Claude CodeでCONTRIBUTING.mdを書き、cloneし直して手順を検証する

CONTRIBUTING.mdの検証とは、書いた手順だけを頼りに、まっさらなcloneの上でビルドとテストを最後まで走らせることです。Claude Codeに手順を書かせるだけなら数分で済みますが、その手順が他人の手元で通るかどうかは、書いた本人の環境では分かりません。この記事では、書く、cloneし直して走らせる、詰まった箇所を直す、という往復を実行例つきで追います。

書いた本人の環境では、なぜ必ず通ってしまうのか

作業中のリポジトリには、gitが追跡していないファイルが残っています。.env、ビルド成果物のdist/、インストール済みの依存、グローバルに入れたコマンドなどです。Claude Codeに「ビルドとテストの手順をCONTRIBUTING.mdに書いて」と頼むと、Claude Codeはこの手元の状態を見て手順を組み立てます。出来上がる手順は、手元では動いて当然の内容になります。

公式のベストプラクティスにも、同じ構造を示す記述があります。worktreeは新しいチェックアウトなので、.envのようなgitignoreされたファイルは存在せず、依存もインストールされていません。cloneも同じ条件です。つまりcloneし直した環境は、新しく参加する人が最初に見る状態を再現する場所になります。

検証用の小さなリポジトリで、抜けを実際に出してみる

仕組みを確かめるため、わざと抜けのあるリポジトリを作りました。Node.js v20.18.0とgit 2.50.1の環境で、構成は次のとおりです。

• scripts/build.jsがsrc/greet.jsをdist/へコピーする(.envが無いとエラー終了する)
• test/greet.test.jsがdist/greet.jsを読んでテストする
• .gitignoreにdist/と.envが入っている
• .env.exampleはコミット済み
• CONTRIBUTING.mdは「cloneする」「npm test」「PRを出す」の3行だけ

作者の手元には.envもdist/もあるので、npm testは通ります。これを別ディレクトリにcloneして、CONTRIBUTING.mdどおりに進めた結果が次の出力です。

git clone origin fresh && cd fresh
ls -a
npm test
npm run build

. .. .env.example .git .gitignore CONTRIBUTING.md package.json scripts src test
not ok 1 - greet
    Cannot find module '../dist/greet.js'
# pass 0
# fail 1
Error: .env not found (copy .env.example)

手順の2行目で、すでに落ちています。dist/が無いためです。ビルドを先に走らせると今度は.envが無いと言われ、.env.exampleをコピーしてからビルドすると、テストは # pass 1 で通りました。CONTRIBUTING.mdに本来必要だったのは、次の順番です。

1. cp .env.example .env
2. npm run build
3. npm test

3行の手順に、抜けが2つ(環境変数ファイルの用意と、テスト前のビルド)ありました。どちらも作者の手元では一度も問題にならなかった点です。

手順1: 初稿を書かせるときに「前提を列挙する」よう指示する

初稿の段階で、抜けの出やすい箇所を先回りして書かせておくと、検証の往復が減ります。リポジトリ直下のCLAUDE.mdに、書かせ方の規約を置く例です(例示であり、公式の定型文ではありません)。

## CONTRIBUTING.md を書くとき・直すとき
 
- 手順は「cloneした直後の空の状態」から始まる前提で書く
- gitignoreされているファイル(.env、dist/、node_modules/)は、
  どのコマンドで作るかを手順に明記する
- 必要なランタイムとバージョンを先頭に書く(Node.js 20 以上、など)
- 各ステップに「成功したらこう見える」という確認出力を1行添える

CLAUDE.mdはセッションの開始時にClaude Codeが読む、プロジェクト共通の指示ファイルです。ここに規約を置けば、CONTRIBUTING.mdを更新するたびに同じ観点で書かせられます。

手順2: 空のディレクトリにcloneして、手順どおりに走らせる

検証は、書いた作業ディレクトリとは別の場所で行います。git cloneの対象にはローカルのリポジトリも指定できるので、未コミットの変更が無いこと(コミット済みの内容がそのまま検証対象になること)だけ先に確かめます。

git status --short            # 空であること
mkdir -p ~/tmp/verify && cd ~/tmp/verify
git clone ~/work/myrepo fresh && cd fresh
claude

起動したセッションで、検証役としての指示を渡します。ポイントは「書かれていないコマンドを実行しない」「詰まったら止まって報告する」の2つです。

このリポジトリは今cloneしたばかりです。CONTRIBUTING.md の手順だけに従って、
ビルドとテストを最後まで実行してください。
 
- CONTRIBUTING.md に書かれていないコマンドは実行しない
- エラーで止まったら、自分で回避せずに、止まった手順番号・コマンド・
  エラー全文を報告する
- 最後に、手順に足りなかった前提を箇条書きにする

「自分で回避しない」の指示が要です。指示が無いと、Claude Codeは.envが無いと分かった時点で.env.exampleをコピーして先へ進んでしまい、抜けは解消しても、CONTRIBUTING.mdには何も残りません。なお、リポジトリ内にCLAUDE.mdがあれば、cloneした環境でもClaude Codeはそれを読みます。CLAUDE.mdにインストールやビルドのコマンドが書かれていると、CONTRIBUTING.mdの抜けをCLAUDE.mdが埋めてしまい、抜けとして現れません。検証の目的が「人が読むCONTRIBUTING.mdの抜け探し」なら、報告の最後に「CLAUDE.mdから補った手順」も列挙させておくと、この見落としを拾えます。

非対話モードで繰り返す

何度も回す検証は、claude -pで非対話にすると繰り返しやすくなります。非対話の実行で許可の確認が出る操作は、何も承認する仕組みが無ければ拒否されます。許可する道具は--allowedToolsで列挙できます。

cd ~/tmp/verify/fresh
claude -p "CONTRIBUTING.md の手順だけでビルドとテストを実行し、\
詰まった手順と足りない前提を報告して" \
  --allowedTools "Bash,Read"

Bashを許可すると、シェルコマンドが確認なしで実行されます。使い捨てのcloneの中でだけ使い、本物の認証情報が置かれた環境では走らせない運用にします。

手順3: 詰まった箇所を、報告から直す

報告を受け取ったら、元の作業ディレクトリへ戻り、報告の内容を渡してCONTRIBUTING.mdを直させます。

cloneし直した環境での検証報告は次のとおりです。
  - 手順2 npm test: Cannot find module '../dist/greet.js'
  - 手順3 npm run build: .env not found
これを受けて CONTRIBUTING.md を直してください。手順の順序も見直して、
各ステップに成功時の確認出力を添えてください。

報告は2種類に分けて読むと直しやすくなります。1つは「手順どおりに実行したがエラーになった」で、コマンドや順序そのものの誤りです。もう1つは「書かれていない操作をしないと進めない」で、前提の書き漏れです。前者は該当の行を直し、後者は前提の節に足します。

検証用リポジトリでは、直したCONTRIBUTING.mdは次の形になりました。成功時の出力を添えてあるので、読む人は自分の画面と見比べて進められます。

# Contributing
 
前提: Node.js 20 以上
 
1. リポジトリをclone する
2. `cp .env.example .env` を実行する(`.env` は gitignore 対象)
3. `npm run build` を実行し、`built` と表示されることを確かめる
4. `npm test` を実行し、`# fail 0` となることを確かめる
5. PR を出す

手順が3行から5行に増えただけですが、抜けていた2つの前提と、各ステップの成否の見分け方が入っています。

直したら、コミットしてから、もう一度新しいディレクトリにcloneして走らせます。報告が「足りない前提なし」になった回が終了の目安です。前の検証で作ったcloneを使い回すと、前回作った.envやdist/が残り、抜けを隠してしまうので、毎回消して作り直します。検証報告の要点をPR説明に残しておくと、どの前提をいつ足したかが後から追えます。

抜けが出やすい場所と、直し方の早見表

検証用リポジトリで出た2つに加え、cloneの直後に存在しない種類のものを表にします。

最後の2行は、検証機が書いた本人の機械と同じである限り、cloneし直しても見つかりません。ここは次の節の限界と重なります。READMEに載せたコード例そのものの古さは、READMEのコードブロックを実行して洗い出す手順で別に確かめられます。

worktreeで代用するときの注意

cloneの代わりにclaude --worktree <名前>で新しいworktreeを作る方法もあります。公式のワークフローの説明では、worktreeは既存のコミットから別ブランチとして切るチェックアウトで、リポジトリに最低1つのコミットが要ります。ただし.worktreeincludeにファイルを列挙している場合、Claude Codeはそれらのgitignoreされたファイルを新しいworktreeへコピーします。.envをここに入れていると、CONTRIBUTING.mdに.envの用意が書かれていなくてもworktreeでは通ってしまい、抜けが隠れます。新しい参加者の状態を再現したいときは、.worktreeincludeを使わないcloneのほうが厳しい検証になります。worktreeまわりの失敗はpartial cloneでworktreeが作れないときの記事にもあります。

この検証で分からないこと

cloneし直す検証には、見つけられない抜けもあります。

• OSの違い: macOSで検証しても、Windowsの利用者が詰まる点は出ません
• 検証機の既存状態: グローバルにインストール済みのツールや、ログイン済みの認証情報は見えたままです。まっさらにするならコンテナや別ユーザーでの実行が必要になります(devcontainerの公式ドキュメントが、隔離された開発環境の用意を扱っています)。コンテナで通す手順はREADMEのセットアップ検証の記事にあります
• ネットワークとシークレット: 社内レジストリへの到達性や、共有された秘密情報の渡し方は、手順書の検証では確かめられません

これらは「検証済み」と書かず、CONTRIBUTING.mdの冒頭に前提として明記しておくほうが、読者にとって正確です。

CONTRIBUTING.mdの検証を、ほかの作業とどう分けるか

新しく入った人への案内を作るなら、/team-onboardingコマンドの紹介がオンボーディングガイドの生成を扱っています。README、JSDoc、変更ログの生成はドキュメント生成の手順の領分です。この記事の検証は、それらで書いたビルドとテストの手順が、cloneした直後に動くことを確かめる工程にあたります。同じ「書いたあとに別の環境で走らせる」型の検証としては、pg_restoreのリストアを検証用DBで確かめる手順も参考になります。

まとめ

CONTRIBUTING.mdは、書いた直後にcloneし直して走らせると、.envやdist/のような作者の手元にしかないファイルへの依存が最初に見つかります。検証役のClaude Codeには「書かれていないコマンドは実行しない」「詰まったら回避せず報告する」の2点を守らせ、報告をそのまま書き直しの材料にします。報告が空になるまで、毎回cloneを作り直して繰り返します。OS差や検証機の既存状態までは見えないので、それは前提として手順書に書いておきます。