repo-health

リポジトリの健全性

GitHub リポジトリの健全性をワンコマンドで監査します。スコア付きレポートを生成し、優先度順に修正を提案します。

インストール

claude skill add --from https://github.com/thatrebeccarae/claude-marketing/skills/repo-health

使用する場面

• 新しいリポジトリをセットアップし、必要なものが揃っているか確認したいとき
• アクティブなリポジトリを定期的に健全性チェックするとき
• プライベートリポジトリをオープンソース化する前に、追加が必要なものを確認するとき
• 状態を把握するために、なじみのないリポジトリに参加するとき
• リリース前に整理するとき

使用方法

/repo-health [repo-path]        # Full audit with scored report
/repo-health [repo-path] --fix  # Audit + generate missing files

repo-path を省略した場合、デフォルトでは現在の作業ディレクトリが使用されます。

---

手順

各ステップを順番に実行してください。ステップを省略しないでください。

ステップ 1：リポジトリのパスを検証する

1. repo-path が指定されている場合は、絶対パスに解決します。省略されている場合は、現在の作業ディレクトリを使用します。
2. パスが存在し、ディレクトリであることを確認します。
3. .git ディレクトリが含まれていること（Git リポジトリであること）を確認します。

検証に失敗した場合：

Error: {repo-path} is not a git repository.
Provide a path to a git repo or run from within one.

停止します。

ステップ 2：パブリック／プライベートを判定する

リポジトリの公開範囲を判定します。

1. リポジトリのルートに .public-repo マーカーファイルがあるか確認します。あればパブリックです。
2. リモート URL に「public」が含まれているか確認します。含まれていればパブリックです。
3. gh が利用可能な場合は gh repo view --json isPrivate -q '.isPrivate' を実行し、結果を使用します。
4. 上記のいずれでも判定できない場合は、ユーザーに確認します。

結果を repo_visibility（public または private）として保存します。パブリックリポジトリは、スコアリングでより厳しい基準が適用されます。

ステップ 3：ファイルの有無を確認する

各標準ファイルを確認します。結果を PRESENT または MISSING として記録します。

ファイル	必須（パブリック）	必須（プライベート）
LICENSE	はい	いいえ
README.md	はい	はい
.gitignore	はい	はい
SECURITY.md	はい	いいえ
CONTRIBUTING.md	はい	いいえ
CODEOWNERS	推奨	いいえ
.editorconfig	推奨	推奨
.github/pull_request_template.md または .github/PULL_REQUEST_TEMPLATE.md	推奨	いいえ
.github/ISSUE_TEMPLATE/ ディレクトリ（または .github/ISSUE_TEMPLATE.md）	推奨	いいえ
CHANGELOG.md	推奨	いいえ
CODE_OF_CONDUCT.md	推奨（パブリック）	いいえ

ステップ 4：GitHub の設定を確認する

gh CLI を使用して、リポジトリのメタデータを取得します。gh が利用できない場合は、このカテゴリをスキップし、レポートにその旨を記載します。

gh repo view --json description,repositoryTopics,hasWikiEnabled,defaultBranchRef,homepageUrl

各項目を確認します。PASS または FAIL として記録します。

チェック	基準
説明の設定	description が空ではない
トピックの設定	repositoryTopics にトピックが 3 つ以上ある
ホームページ URL	プロジェクトにサイトがある場合、homepageUrl が設定されている
デフォルトブランチ名	defaultBranchRef.name が main（master ではない）
ブランチ保護	gh api repos/{owner}/{repo}/branches/main/protection が 200 を返す（パブリックリポジトリのみ）
ソーシャルプレビュー	gh api repos/{owner}/{repo} を実行し、カスタムの Open Graph 画像があるか確認する（参考情報のみ）

ステップ 5：ドキュメントの品質

README のチェック：

1. README.md が存在する（ステップ 3 の結果）
2. README の長さ：50 行未満の場合は WARN（短すぎます）、500 行を超える場合は INFO（分割を検討してください）
3. 最初の 5 行にプロジェクトの説明がある（H1 または太字のテキスト）
4. インストール／セットアップの手順がある（「install」、「getting started」、「setup」、「usage」を検索）
5. ライセンスへの記載がある（「license」、「LICENSE」を検索）
6. /github-readme スキルが利用可能な場合は、/github:readme audit でより詳細な README 監査を実行できる旨を記載する

CHANGELOG のチェック：

1. CHANGELOG.md が存在する（ステップ 3 の結果）
2. 存在する場合：Keep a Changelog 形式に従っている（## [ バージョンヘッダーを検索）
3. 最新のエントリーが過去 90 日以内にある（古い場合は WARN）

ステップ 6：コードの衛生状態

古いブランチ：

git branch -r --merged main | grep -v main | grep -v HEAD
git for-each-ref --sort=committerdate --format='%(refname:short) %(committerdate:relative)' refs/remotes/

• 90 日を超えてコミットがないブランチを古いブランチとして判定します
• 古いブランチの合計数を数えます

追跡対象のシークレット／環境ファイル：

git ls-files | grep -E '\.env$|\.env\.|credentials|secrets'

• .env、.env.*、credentials.*、secrets.* ファイルが Git で追跡されている場合は、FAIL とします

大きなバイナリファイル：

git ls-files | while read f; do
  size=$(wc -c < "$f" 2>/dev/null)
  [ "$size" -gt 5242880 ] && echo "$f ($size bytes)"
done

• 5 MB を超えるファイルが Git LFS なしで Git に追跡されている場合は、WARN とします
• 大きなバイナリファイルがある場合は、LFS パターンを含む .gitattributes があるか確認します

依存関係の最新性（該当する場合）：

• package.json が存在する場合：package-lock.json があるか確認します
• requirements.txt が存在する場合：バージョンが指定されているか確認します
• インストールコマンドを実行したり、何かを変更したりしないでください

ステップ 7：採点とレポート

採点カテゴリ

カテゴリ	配点	対象
標準ファイル	30%	LICENSE、SECURITY.md、CONTRIBUTING.md、CODEOWNERS、.gitignore、.editorconfig、テンプレート
GitHub 設定	15%	説明、トピック、ブランチ保護、デフォルトブランチ
ドキュメント	25%	README の品質、CHANGELOG の有無と最新性
コードの衛生状態	20%	古いブランチ、追跡対象のシークレット、大きなバイナリ
コミュニティ	10%	CODE_OF_CONDUCT、Issue テンプレート、PR テンプレート、CONTRIBUTING.md

カテゴリごとの採点

各カテゴリは、そのカテゴリ内で合格したチェックに基づいて 0～100 点で採点されます。完全な採点基準については REFERENCE.md を参照してください。

評価

スコア	評価
90-100	A
80-89	B
70-79	C
60-69	D
0-59	F

レポート形式

=== Repo Health Report: {repo-name} ===
Visibility: {public | private}
Overall Score: {score}/100 (Grade: {letter})

--- Standard Files (30%) --- Score: {n}/100
  [PASS] .gitignore
  [PASS] LICENSE (MIT)
  [MISS] SECURITY.md
  [MISS] CONTRIBUTING.md
  [PASS] CODEOWNERS
  ...

--- GitHub Config (15%) --- Score: {n}/100
  [PASS] Description: "One-command repo health audit..."
  [FAIL] Topics: none set
  [PASS] Default branch: main
  [FAIL] Branch protection: not enabled
  ...

--- Documentation (25%) --- Score: {n}/100
  [PASS] README.md (142 lines)
  [WARN] No install/setup instructions found in README
  [MISS] CHANGELOG.md
  ...

--- Code Hygiene (20%) --- Score: {n}/100
  [PASS] No tracked .env files
  [WARN] 3 stale branches (>90 days)
  [PASS] No large binary files tracked
  ...

--- Community (10%) --- Score: {n}/100
  [MISS] CODE_OF_CONDUCT.md
  [MISS] Issue templates
  [PASS] PR template
  ...

=== Prioritized Fixes ===
1. [HIGH] Add SECURITY.md — required for public repos. See template in REFERENCE.md.
2. [HIGH] Enable branch protection on main — prevents force pushes and requires reviews.
3. [HIGH] Add repository topics — improves discoverability. Suggest: {topic1}, {topic2}, {topic3}.
4. [MED]  Add CONTRIBUTING.md — guides external contributors.
5. [MED]  Add CHANGELOG.md — tracks releases for users.
6. [LOW]  Clean up 3 stale branches.
7. [LOW]  Add CODE_OF_CONDUCT.md — signals welcoming community.

優先度：

• HIGH：セキュリティ、法務（LICENSE／SECURITY.md）、または保護に関する問題
• MED：使いやすさに影響するドキュメントやコミュニティの不足
• LOW：クリーンアップや、あると望ましい項目

ステップ 8：修正モード（--fix）

--fix フラグが渡された場合：

1. 自動生成できる MISS および FAIL 項目の一覧を提示します
2. 作成するファイルをユーザーに確認します（番号付きリストを表示し、カンマ区切りの選択または「all」を受け付けます）
3. 確認されたファイルごとに、適切なデフォルトを使用して生成します：
   • SECURITY.md：標準的な脆弱性報告テンプレート
   • CONTRIBUTING.md：コードスタイルに関する注記を含む、フォーク／ブランチ／PR のワークフロー
   • CODE_OF_CONDUCT.md：Contributor Covenant v2.1
   • .editorconfig：検出された技術スタックに適したデフォルト設定
   • CODEOWNERS：オーナーパターンをユーザーに確認します
   • Issue／PR テンプレート：YAML フォーム形式のテンプレート（REFERENCE.md を参照）
4. 既存のファイルを上書きしないでください
5. 書き込む前に、生成したすべての内容に infra/PII のスクラブを実行します

---

主要な原則

• デフォルトでは読み取り専用です。 --fix が明示的に渡されない限り、監査によってファイルが変更されることはありません。
• 公開リポジトリには、より高い基準を適用します。 プライベートリポジトリでは、コミュニティおよび一部の設定チェックを省略します。
• 実行可能な内容を優先します。 すべての指摘に、具体的な修正方法が含まれます。
• 不要な緊急性を煽りません。 推奨項目は必須項目より低く採点されます。レポートでは、必須の修正と、あると望ましい項目を区別します。
• 既存の作業を尊重します。 修正モードでは上書きせず、不足しているファイルのみを作成します。
• Infra/PII への配慮。 生成されるファイルはすべて、書き込む前に標準の PII スクラブを通過します。

アンチパターン -- してはいけないこと

• 標準の監査中（--fix フラグなし）にファイルを変更する
• インストールコマンド（npm install、pip install など）を実行する
• 変更をプッシュしたりコミットを作成したりする -- コミットするタイミングはユーザーが決めます
• リポジトリのメタデータを捏造する -- gh と git が報告する内容を使用します
• ローカルでアクセスできないリポジトリを評価する -- これはローカル監査ツールです
• 修正モードでファイルを生成する際に、PII スクラブを省略する