repo-health

repo-health

リポジトリの基盤となるスキルです。あらゆるコードリポジトリの立ち上げに必要なコミュニティ健全性に関するファイルの標準を定めます。

• README.md — リポジトリの入り口（Standard Readme 仕様）。
• LICENSE — 法的な契約（choosealicense.com に案内します。doc-master がライセンスを選ぶことはありません）。
• CONTRIBUTING.md — 外部のコントリビューターが変更を提案する方法。
• CODE_OF_CONDUCT.md — 行動規範（デフォルトは Contributor Covenant 3.0、代替として 2.1）。
• SECURITY.md — 脆弱性の報告ポリシー。
• SUPPORT.md — ユーザーがサポートを受ける場所（小規模なリポジトリでは省略できることがよくあります）。
• .github/ のテンプレート — Issue／PR／CODEOWNERS／FUNDING／CITATION。
• REUSE 3.3 + SPDX — ファイルごとの著作権およびライセンスのメタデータ。

各基盤ファイルには、その構成、よくある失敗、振り分けに関する注意事項をまとめたリファレンスファイルがあります。この SKILL.md は簡潔なエントリーポイントです。必要に応じてリファレンスを読み込んでください。

まず診断 — 自動作成しないでください

doc-master は、各基盤ファイルの作成を推奨する前に、4 つの質問による診断を行います。

1. 対象者 — 誰が、どのような状況で読みますか？（通りすがりのコントリビューター？ セキュリティ研究者？ 困惑しているユーザー？ コンプライアンス監査担当者？）
2. すでに存在していますか？ — 多くのリポジトリには、別の名前や場所で同等のものがすでにあります。まず見つけてから、作成してください。
3. どこに置きますか？ — トップレベル、.github/、docs/ のどれですか？ 各基盤ファイルには慣例的な配置場所があります。
4. 誰が管理しますか？ — 氏名が明記された人、またはエイリアスを指定してください。「チーム」では管理者になりません。管理責任が重要だからこそ、CODEOWNERS があります。

どれかの答えが「いいえ」または「わかりません」であれば、まだファイルを作成しないでください。 多くの小規模なリポジトリでは、SUPPORT.md も FUNDING.yml も、ファイルごとの REUSE ヘッダーも必要ありません。基盤ファイルを形だけ整えても、誰にも読まれず、誰にも更新されないドキュメントが生まれます。これは ADR に適用される、内容を水増ししないというルールと同じです。

デフォルトで推奨するもの

発足元のチーム以外にも公開されているコードリポジトリでは、次を推奨します。

基盤ファイル	デフォルト
README.md	はい — 必須です。Standard Readme の構成を使用してください。references/readme-canon.md を参照してください。
LICENSE	はい — 再利用されるコードには必須です。doc-master は choosealicense.com に案内しますが、ライセンスは選びません。references/license-routing.md を参照してください。
CONTRIBUTING.md	外部からのコントリビューションを受け付ける場合ははい。リポジトリが読み取り専用の場合は省略してください。references/contributing-canon.md を参照してください。
CODE_OF_CONDUCT.md	外部からの参加を受け付ける場合ははい。デフォルトは Contributor Covenant 3.0、現在も有効な旧バージョンを使う場合は 2.1 です。references/code-of-conduct-canon.md を参照してください。
SECURITY.md	信頼できない入力を処理する、シークレットを扱う、本番環境にリリースする、またはユーザーに見える攻撃対象領域がある場合ははい。references/security-canon.md を参照してください。
SUPPORT.md	ほとんどの小規模なリポジトリではおそらく不要です。Issue トラッカーがサポートに関する質問で誤用されている場合に限り追加してください。references/support-canon.md を参照してください。
Issue／PR／CODEOWNERS／CITATION／FUNDING	ケースバイケースです。 それぞれに明確な追加のきっかけがあります。references/templates-canon.md を参照してください。
REUSE 3.3／SPDX ヘッダー	複数のライセンスのコードを集約するリポジトリ、SBOM が必要な環境にリリースするリポジトリ、または機械検証可能なライセンスメタデータを必要とするリポジトリでははい。references/reuse-spdx-canon.md を参照してください。

ブートストラップまたは監査の実行方法

ユーザーからリポジトリのドキュメントを整備するよう依頼された場合：

1. すでに存在するもの（README*、LICENSE*、CONTRIBUTING*、CODE_OF_CONDUCT*、SECURITY*、SUPPORT*、.github/）を一覧にします。
2. 中核となる各ドキュメントについて、4つの質問による診断を実施します。
3. 1ファイルずつ、作成・統合・現状維持のいずれかを提案します。一括生成はしません。
4. 作成すべきファイルについては、対応するリファレンスを読み込み、ユーザーが記入するプレースホルダーを含む草案を作成します。メンテナー名、連絡先の別名、ライセンスの選択、SLA の期間を決して作り上げてはいけません。
5. ライセンスの選択は適切な窓口に案内するだけで、選択はしません。このスキルでは一般的な既定候補（MIT、Apache-2.0、BSD-3-Clause、GPL-3.0、MPL-2.0）を挙げ、choosealicense.comを案内します。選択するのは人間です。

ユーザーからリポジトリのドキュメントを監査するよう依頼された場合：

1. 同じように一覧を作成します。
2. 存在する中核ドキュメントごとに、規範に照らして内容を比較し、逸脱・欠落しているセクション・古い日付・単独メンテナーの連絡先行を指摘します。
3. 存在しない中核ドキュメントごとに、4つの質問による診断の結果、作成が必要になるかを確認します。「不足している」SUPPORT.mdやFUNDING.ymlのほとんどのケースでは、作成せずに不足したままにします。
4. KEEP / REWRITE / CREATE / DELETE の番号付きリストを作成します。一括で書き換えてはいけません。

厳格なルール

• doc-master はライセンスを選びません。choosealicense.comへの案内は必須です。このスキルでは一般的な既定候補を挙げますが、選ぶのは人間です。
• 行動規範の連絡先には共有エイリアスを使い、個人のメールアドレスは使いません。[email protected]、community@…、モデレーションチームなどを使います。個人の受信トレイは使いません。バス係数が1である場合は拒否の条件です。
• SECURITY.md の連絡先には共有エイリアスまたは連携された窓口を使います（GitHub Security Advisories、指定されたプログラム、security@…など）。単独メンテナーのメールアドレスは拒否します。
• **水増しは禁止です。**推奨するファイルはすべて、4つの質問による診断に合格する必要があります。4つの質問に答えられない場合、そのファイルは存在すべきではありません。
• **1回のやり取りにつき指摘は1件です。**監査では、adr-critique / markdown-style と同様に、行番号を示し、原文をそのまま引用し、ルール名を明記し、書き換え案を提示して、指摘ごとに承認を得ます。

担当範囲外のものへの案内

• Markdown の形式 — 中核ドキュメントができたら、markdown-style（/doc-lint）でリントします。
• アーキテクチャ上の決定に関する ADR — doc-diagnostic / adr-draftingを使います。「REUSE を採用した」は ADR に該当する可能性がありますが、ファイルごとの REUSE ヘッダー自体は該当しません。
• 変更履歴 — ../doc-diagnostic/references/changelog-canon.md。
• ランブック / 事後分析 / 未解決事項の一覧 — ../doc-diagnostic/references/{runbook,postmortem,open-questions}-canon.md。
• AI エージェントのコンテキストに関する AGENTS.md — ../doc-diagnostic/references/agentic-docs-canon.md。

例

オープンソースプロジェクトを始めたばかりです。リポジトリのルートにはどのドキュメントが必要ですか？ opensource.guide の4ファイルの基本セットは、README.md、LICENSE、CONTRIBUTING.md、CODE_OF_CONDUCT.md です。コードが信頼できない入力を処理する場合は、SECURITY.md を追加してください。新しいプロジェクトでは、通常 SUPPORT.md は過剰です。`repo-health` を読み込みます。4つの質問による診断を使って、ファイルを1つずつ確認します。ライセンスの選定先は choosealicense.com です。私が選ぶことはありません。 「Contributor Covenant 3.0 を採用した」という ADR を書くべきですか？ いいえ。それは ADR ではなく、CODE_OF_CONDUCT.md の採用です。Contributor Covenant 3.0（4段階の Enforcement Ladder）をデフォルトとし、2.1 は引き続き有効な旧版の代替とします。連絡先には、単一のメンテナーではなく共有エイリアスを指定する必要があります。`repo-health` のリファレンス `code-of-conduct-canon.md` を読み込みます。 コミュニティ関連のファイルを監査してください。 `repo-health` を読み込みます。まず一覧を作成し、次にファイルごとに4つの質問による診断を行い、その後、番号付きの KEEP / REWRITE / CREATE / DELETE リストを作成します。SECURITY.md / CODE_OF_CONDUCT.md の連絡先が単一メンテナーの場合、拒否条件として指摘します。 CITATION.cff は必要ですか？ リポジトリが研究用ソフトウェアである場合、または学術的な引用を想定している場合は、必要です。CITATION.cff が統一された形式です。それ以外の場合は不要です。スキーマについては `references/templates-canon.md` を参照してください。

リファレンス

• references/readme-canon.md — Standard Readme 仕様。標準の9つのセクション。
• references/license-routing.md — 一般的なライセンスのデフォルトと振り分けルール（doc-master は選定しません）。
• references/contributing-canon.md — CONTRIBUTING.md の構成、Conventional Commits 1.0、DCO。
• references/code-of-conduct-canon.md — Contributor Covenant 3.0 をデフォルトとし、2.1 を代替とする方針、Enforcement Ladder、共有エイリアスのルール。
• references/security-canon.md — SECURITY.md のセクション、非公開の報告経路、対応期間の最低基準。
• references/support-canon.md — SUPPORT.md の連絡経路、大半のリポジトリで省略できる場合。
• references/templates-canon.md — .github/ISSUE_TEMPLATE/*.yml、PULL_REQUEST_TEMPLATE.md、CODEOWNERS、FUNDING.yml、CITATION.cff。
• references/reuse-spdx-canon.md — REUSE 3.3 のファイルごとのヘッダー、LICENSES/ フォルダー、REUSE.toml、.license サイドカー、SPDX 識別子カタログ。