Claude Code のプロジェクト設定を最小構成から育てる
一言まとめ
新規リポの `.claude/` は CLAUDE.md(200 行以下)+ `settings.json`(permissions と hook 2 つ)+ skill 1 本に絞り、必要になった trigger で足す。自作のコマンド群やサブエージェントを最初から積まない。hook は検証コマンド(lint / typecheck / test)が決まってから入れる。
調査時点: 2026-08〜09。公式ドキュメント(best-practices / memory / skills / hooks / settings)を引いて個人開発の PWA 数本に適用した構成。推奨は変わるので、半年以上経ったら引き直す。
Claude Code は、ファイル操作やコマンド実行を行う Anthropic の AI 開発支援ツール。CLAUDE.md はプロジェクトごとの作業指示、skill は再利用する手順、hook は所定のイベントで処理を実行する設定を指す。
方針
- 中身の無いリポに運用機構だけ先に積むと、CLAUDE.md が膨らんで肝心の指示が埋もれる。
- 組み込み機能(plan mode、
/code-reviewなど)で足りるものを自作すると保守先が増える。古いリポの自作 dev-loop コマンド群やサブエージェントは流用しない。 - カスタムコマンドは skills に統合されているので、コマンドではなく skill として置く。
初期構成
| 要素 | 内容 |
|---|---|
CLAUDE.md | 200 行以下。検証コマンド(lint / typecheck / test)を「検証」節に書く。scaffold 前なら「これから定義する名前」の宣言でよい |
.claude/settings.json | permissions と hook |
| skill | 決定を ADR として記録する /decide のような、そのリポで繰り返す手順を 1 本 |
.claude/README.md(任意) | 判断根拠・参照した公式ドキュメントの URL・育て方。2 本目以降のリポは置かず、1 本目を参照する |
hook は 2 つ、テストが書かれてから
| イベント | 内容 |
|---|---|
| PostToolUse(Edit / Write) | 編集したファイルだけフォーマッタ(Biome など)を掛ける |
| Stop | lint → typecheck → test を走らせ、失敗を Claude に返す |
検証コマンドが決まる前に hook を入れると、存在しないコマンドを呼んで止まる。テストが 1 本でも書かれてから足す。
育て方
- 必要になった trigger(同じ指示を 2 回したら、同じ失敗を 2 回見たら)で足す。
- 2 週間前に組んだ構成は、推奨が変わっていなければそのまま次のリポにコピーする。フレームワーク固有の項目だけ削る。
- 配信先・ホスティングのような「Claude がコマンドを打つ前提」に関わる判断は、ADR として残して CLAUDE.md から参照する。
関連
更新履歴
- 2026-08-29: 初版(ローカル調査ノート)
- 2026-10-17: Wiki へ移植、概念ページとして再構成。冒頭に定義を追加