repo-readme

README の基準と手順を持つ。目的は README を一律のテンプレートに揃えることではなく、各リポの README をそれぞれ筋の通った1本の主張にすること。筋が通っているとは、コアメッセージ（ひとことで何のリポか）→ ターゲット（誰に向けるか）→ アウトライン（それが最も伝わる H2 構成）が一直線につながっていること。固定の必須セクションは置かず、種別ごとの下限だけを決める。

公開パイプラインの固定順: repo-standardize → guarantee-audit → repo-readme → readme-i18n → repo-publish → repo-about。本 Skill は第3。足場とコアメッセージは repo-standardize が、保証台帳は guarantee-audit が先に作る（README が台帳へリンクするため）。中身（アーキテクチャ・技術選定・判断）が固まった publish 前に走らせる。この順は都度再判断しない。

考える順序は次のとおり。下限は満たすべき観点であって、H2 の並びや名前を固定しない。

種別判定（Type A / B / C）
   └─ 下限：必ず満たす観点（順序を持たない）
        └─ コアメッセージ ＋ ターゲット（リポごとに決める）
             └─ アウトライン（H2 の順序・命名・厚み）

1. 素材を集め、種別を判定する

README は創作でなく既にあるものの集約。書く前に読む。

• リポのコード・ディレクトリ構成（実際の構造・データフロー）
• PLAN.md / JUDGE.md（あれば。統合ソースで、後で削除する。§6）
• context/structure.md / context/conventions.md（設計の意図。残す）
• .github/workflows/（CI/Deploy バッジ・デプロイ方式）
• 既存 README（あれば差分更新。良い記述は壊さない）

種別を判定する。

使わせる？ ── yes → Type B（利用保証型）
   └ no（読ませる）
      証拠はコード？数字？ ── コード → Type A（実証型）
                            └ 数字 → Type C（実験型・Lab）

	Type A: 実証型	Type C: 実験型（Lab）	Type B: 利用保証型
性格	「やってみた／移行を実践した」サンプル・ポートフォリオ	問いと実測結果が本体の実験リポ	第三者が導入して使えると保証されたツール／ライブラリ
主張の型	「作れた」	「分かった」	「使える」
読者の既定	コードと設計判断を読む人	結果と方法を読む人（追試する人は第二読者）	動かして組み込む人
再現性	不要（見れば分かる）	生命線（シード・素材固定が主張の担保）	保証の一部
構成の論理	課題 → 解決 → 判断の根拠	問い → 方法 → 結果 → 考察 → 追試	導入 → 使い方 → 設定 → 制約

A と C で迷ったら次で決める。結果の数字を全部消してもリポの価値が残るなら A、残らないなら C。 結論が作る前から分かっていたなら A、測るまで分からなかったなら C。

2. 下限を満たす

順序なしのチェックリスト。すべて満たせば、H2 の切り方・並べ方・命名は自由。

Type A

• コアメッセージが H1 直下に1文である
• 動かす手順がある（コピペで動く）
• 実証の本体が「課題 → 解決」で語られている
• 技術選定に Why がある
• スコープが明示されている（何に特化し／何をやらないか）

Type B

• コアメッセージが H1 直下に1文である
• 導入手順（Installation / Quick Start）と最小の使用例（Usage）がある
• 設定・API など使うための参照情報がある
• スコープが明示されている（対応範囲／非対応）

Type C

• コアメッセージ（問い）が H1 直下に1文である
• 結果が README 本文にある（表・数値。リンク先送りにしない）
• 方法の要約がある（全文は docs/ へ退避してよい）
• 追試手順がある。保証は「同じ手順・シード・素材版で同じ数字が出ることは設計している。それ以外は保証しない」と書く。台帳（docs/guarantees.md）があればリンクする
• スコープが明示されている（何を測り、何を測らないか）

Type C には課題→解決ナラティブも、技術選定の Why の本文掲載も要らない（測定装置の選定理由は docs/ で足りる）。

3. コアメッセージとターゲットを決める

コアメッセージは README 全体の背骨になる1文。

• 主語は「このリポは」（または相当する主部）
• 「何を解決する／実証する／問う」＋「どういう手段で」を含める
• 自慢の形容詞（"高速""モダン"）と機能の単純列挙を使わない
• そのまま H1 直下の概要1〜2行に一致させる

例（Type A）：「レガシーな WinForms 業務アプリを .NET 8 + React へ段階的に移行し、AI 自然言語インターフェース追加までの解体・再構成プロセスを実践するサンプル」 例（Type C）：「冒頭の定義文を消された Wikipedia 記事がどの記事名に対応するかを、係数固定の数式・再学習する GBDT・LLM 再判定の組み合わせで解き、コーパスを引き直しても当て続けられるかを実測するベンチマーク」

ターゲットは1つ選ぶ。下限は変えず、何を厚く・何を先頭に・どう命名するかのレバーとして効く。

軸	例	構成への効き方
習熟度	ジュニア／ミドル／シニア	Quick Start の丁寧さ、前提の省略可否
職種・レイヤー	フロント／バック／インフラ／特定ドメイン	Architecture と Tech Stack のどちらを厚くするか
技術利用者	技術を使う人向けか、成果物を使う人向けか	利用例・API を出すか、設計思想を出すか

4. アウトラインを組んで書く

下限を満たしたうえで、コアメッセージとターゲットから H2 を選ぶ。H2 の順序・命名・分割は固定しない。

素材	内容	向く種別
Overview	目的・背景・デモ URL	A / B / C
Architecture	構成図（Mermaid）・データフロー。文章より図	A / B
Before / After	移行前の課題と移行後の構造	A
Results	実測結果の表・グラフと読み方	C
Method	タスク定義・測定手順の要約	C
Tech Stack	技術名＋選定理由（Reason 列必須）	A / B
Design Decisions	JUDGE.md から統合した選定根拠	A / B / C
Usage / API	使用例・エンドポイント・設定	B
Reproduce	追試手順（シード・素材版の固定）	C
Scope	Focus と Out-of-Scope	A / B / C
Deploy	デプロイ方式の概要のみ	公開アプリのみ
Comparison	姉妹リポ・既存手法との比較	A / C
Directory Structure	ツリー形式。主要ファイルにコメント	A / B

書き方の決まり:

• 言語: 見出し H1〜H3 は英語、本文・H4 以降・表の中身は日本語
• H1 直下: CI バッジ（自動デプロイがあるリポのみ Deploy バッジも）とコアメッセージの概要1〜2行
• 動かす手順: 最短で動く経路を先に書く。前提の少ない経路（依存不要・ワンライナー）を優先し、言語ランタイムの個別導入は Local Development へ分ける。Prerequisites は実際に要るものだけ。Type C では追試手順がこの位置に来る。大きな素材の取得が要るならサイズと取得先を書き、結果だけ読む人が踏まない導線（生成済みデータの Releases 添付など）を用意する
• Tech Stack: | Layer | Technology | Reason | の表で、なぜそれかまで書く
• 図: Mermaid をインラインで埋め、SVG に焼かない。描くかどうかと描き方は mermaid-diagram Skill に従う（Architecture 節を書く前に「描かない判断」を必ず通す）。画像は src/ か docs/ に置いて相対パスで参照し、外部ホスティングに依存しない
• Deploy: デプロイ方式の概要とデモ URL だけ。Secrets 一覧・初回セットアップ・サーバー側設定は書かない（repo-standardize/reference/cicd.md と運用ドキュメントの管轄）
• Secrets: ドメイン実値・Tunnel UUID 等を README に載せない（secrets-agents/ の <PLACEHOLDER> 方針）

5. 妥当性で取捨する

必須節を機械的に足さない。

• 単純な静的サイト・設定リポでは Architecture・Scope 等が過剰になりうる。不要なら省き、省いた旨を一言添える
• 同じ「なぜ」を複数箇所に書かない。Design Decisions は横断的判断の集約先にし、各機能のインライン説明と重複させない
• 筋が通っているかを通読して確かめる。コアメッセージ → H1 直下の概要 → 各 H2 が同じ主張を支えているか。逸れている H2 は、コアメッセージかターゲットのどちらかとズレている

6. JUDGE.md / PLAN.md を統合して消す

どちらも user の作業産物で、公開時に README へ統合したら元ファイルを削除する（統合 = 移設 + 削除。履歴は git にある）。作る側は mvp-docs Skill。

• JUDGE.md … 要点を Design Decisions と Tech Stack の Reason 列へ。全文は docs/design-decisions.md へ（少なければ README に直接統合）。判断基準を創作しない
• PLAN.md … 3つに仕分けてから消す。一括で捨てない
  • 進捗（チェックボックス・完了メモ）… 移設せず削除
  • スコープ … README の Scope へ。Type C では方法の記述を docs/method.md へ
  • 概念定義（エンティティとその境界・処理段の名前・情報ソースの区分）… context/domain.md へ移設し、README には出さない。公開後も実装の骨格として機能追加のたびに参照されるため、「実装済みだから不要」で捨てない

消す手順:

1. リポ内の参照を grep する（grep -rn "JUDGE\|PLAN" --include="*.md"。CLAUDE.md・context/・issues/ が指していることがある）
2. 参照先を README / docs/ / context/ へ書き換える
3. 概念定義が context/domain.md に移っていることを確かめてから削除する

7. docs/ 分離を判断する

分離は README を1本の主張に保つための退避先で、目的ではない。書き終えてから、肥大した節だけ退避する。

• 分離する: その節の全文が深掘り・参照・運用など別の読者モーメントに仕える／README には要点だけあれば足り、全文は読み飛ばされる分量
• 分離しない: 全文でも数行〜十数行／README 側の要約と原本がほぼ同文になる

典型候補（該当分だけ作る。空ファイルを揃えない）:

ファイル	中身	対象
docs/design-decisions.md	判断の全文（何を捨てたか・再検討の境界）	JUDGE.md があるリポ
docs/guarantees.md	保証台帳。README の Scope 節からリンクする（敷設は guarantee-audit）	テストがあるリポ
docs/method.md / docs/reproduce.md	方法・追試の全文	Type C
docs/usage.md	API 表・環境変数・CLI 詳細	Type B / アプリ系
docs/release.md	リリース・publish 手順	レジストリ公開リポ
docs/deploy.md	利用者向けセルフホスト手順（自分用の運用手順は含めない）	clone リファレンス型アプリ

• 分離したら README 側に要点と docs/ へのリンクを残す
• README.en.md があるリポでは docs/*.en.md も対で作り、両ファイル冒頭に言語リンクを置く（英語版だけインライン、の非対称を作らない）
• Type C の結果は分離しない。docs/ へ送るのは方法の全文・生データ・追加のグラフまで

8. 出して止まる

変更はワーキングツリーに残し、追加/削除した節・docs/ 分離の判断・削除したファイルを要約して報告する。コミット/push は user の指示があったときのみ。

.claude/・LICENSE・.gitignore 等の足場は repo-standardize の管轄で、本 Skill は触らない。

_{Acknowledgement — the "core message → target → outline" framing draws on yoshiko-pg's talk at ZennFes 2026: https://yoshiko-pg.github.io/talks/zennfes-2026/. With thanks and respect.}