自分の `.claude/` を磨く 7 日間

コース構成

このコースで学ぶこと

1. 01

   Day 1：CLAUDE.md を 200 行で書く

   プロジェクトの前提を 200 行以内に絞って文書化。コードを読めばわかることは書かない。

   CLAUDE.md は毎セッションで Claude が最初に読むファイル。ここに書いた内容は「常に意識される」前提知識になります。

   コツは「コードを読めばわかること」は書かないこと。書くべきは『触ってはいけないもの』『暗黙のルール』『過去の事故から学んだこと』など、コードに現れない暗黙知。

   markdown

   # このプロジェクトの前提
   
   - パッケージマネージャは **pnpm** 固定（npm/yarn 禁止）
   - DB マイグレーションは `pnpm db:migrate` 経由のみ
   - `apps/legacy/` は触らない（凍結中、別チーム管轄）
   
   ## テスト
   - 統合テストは **Postgres に接続**する（モック禁止：過去にズレで本番事故）
   - `pnpm test:int` で実行
   
   ## デプロイ
   - main へ merge 後、自動で staging に出る
   - prod は Slack の #release で手動承認

   手を動かす

   0 / 4

   • プロジェクトディレクトリで `/init` を実行
   • 200 行以内に絞る（長くなったら Skill に切り出す）
   • 「コードを読めばわかること」を削除
   • 「触るな」「過去の事故」を追加

   Lv.3 — メモリと CLAUDE.md

   理解度チェック

   1. Q1.CLAUDE.md を 200 行以内に絞る基本方針として正しいのは？

      A全 API ドキュメントをコピペするBコードを読めば分かることは書かず、暗黙知（触らない領域・過去の事故）を中心に書くC毎ターン Claude が編集して肥大化させるD依存ライブラリのバージョン履歴を書く
   Day 2：最初の Skill を 1 個作る
2. 02

   Day 2：最初の Skill を 1 個作る

   繰り返し打っていたプロンプトを Skill 化する。description が良ければ自動発動する。

   Skill は `.claude/skills/<name>/SKILL.md` というファイル。フロントマターに `description` を書いて、Claude が「これに合う状況だ」と判断したら自動でロードされます。

   手で `/<name>` と呼び出すこともできます。

   markdown

   ---
   name: release-notes
   description: |
     git log からリリースノートを下書きする。
     ユーザーが「v1.x のリリースノート作って」「リリースノートを生成して」
     と頼んだときに使用する。
   ---
   
   # 手順
   1. `git log <from>..<to> --oneline` を取得
   2. Conventional Commits でカテゴリ分け（feat / fix / chore / docs）
   3. `RELEASE_NOTES.md` に書き出す（fix → feat → chore の順）
   4. ユーザーに見せて、削るべきものを確認

   手を動かす

   0 / 4

   • 過去 1 週間で 3 回以上打ったプロンプトを 1 つ思い出す
   • .claude/skills/<name>/SKILL.md を作る
   • description を「いつ使うか」を 3 例書いて厚くする
   • /<name> で手動呼出してテスト

   Skill Builder で組み立て

   理解度チェック

   1. Q1.Skill の description を“厚く”書く（使用シーンを 3 例書く）と何が変わる？

      AAnthropic から認定 Skill バッジがもらえるBClaude が状況に合う Skill を自動で選びやすくなり、手動呼び出しなしで発動する確率が上がるCSkill 本文の読み込み時間が短くなるDSkill ファイルサイズが小さくなる
   Day 1：CLAUDE.md を 200 行で書くDay 3：Hook を 1 個書く
3. 03

   Day 3：Hook を 1 個書く

   PostToolUse で自動フォーマット、または Stop でデスクトップ通知。決定論的な拡張を体感する。

   Hook は「Claude のループの特定の瞬間に必ず走るコード」。Skill が Claude の裁量で動くのに対し、Hook は **決定論的に毎回必ず動く**のが違いです。

   最初は「編集後に自動フォーマット」がおすすめ。コードベースが常に綺麗な状態に保たれます。

   json

   {
     "hooks": {
       "PostToolUse": [
         {
           "matcher": "Edit|Write",
           "command": "biome format --write ${FILE} 2>/dev/null || prettier --write ${FILE}"
         }
       ],
       "Stop": [
         {
           "command": "osascript -e 'display notification \"Claude が完了しました\" with title \"Claude Code\"'"
         }
       ]
     }
   }

   手を動かす

   0 / 3

   • PostToolUse の format hook を追加
   • Stop hook でデスクトップ通知を追加（macOS は osascript）
   • Claude にダミー編集をさせて、フォーマットが走るか確認

   Hooks 完全版（29 イベント）

   理解度チェック

   1. Q1.Skill と Hook の役割分担として正しいのは？

      ASkill は決定論的、Hook は判断ありBSkill は Claude の判断で動く（柔軟）、Hook は決定論的に毎回必ず動くC両者は同じ機能DHook は判断、Skill は記録のみ
   Day 2：最初の Skill を 1 個作るDay 4：MCP を 1 個繋ぐ
4. 04

   Day 4：MCP を 1 個繋ぐ

   GitHub / Slack / Postgres から 1 つ。外部システムを Claude のツールキットに加える。

   MCP（Model Context Protocol）は、外部システムを Claude にツールとして渡す仕組み。GitHub MCP を繋げば「Issue 一覧を見て」「PR にコメントして」が Claude のツール呼出として動くようになります。

   bash

   # GitHub MCP を追加（最も使われる）
   claude mcp add github -s project -- \
     npx -y @modelcontextprotocol/server-github
   
   # 接続確認
   claude mcp list
   
   # プロジェクト直下に .mcp.json が生成される
   cat .mcp.json

   手を動かす

   0 / 4

   • 業務でよく使う SaaS（GitHub / Slack / Notion 等）を 1 つ選ぶ
   • claude mcp add で追加
   • /mcp で接続状態を確認
   • 実際に試す: 「GitHub の open PR を一覧して」

   MCP 完全版

   理解度チェック

   1. Q1.MCP を追加したあと、接続状態を確認するコマンドは？

      A`/mcp`B`claude --debug`C`claude ping`D`/clear`
   Day 3：Hook を 1 個書くDay 5：Subagent をテンプレ化
5. 05

   Day 5：Subagent をテンプレ化

   「重い検索は別ワーカー」のパターンを Explore / Plan / general-purpose の組合せで身につける。

   Subagent は独自のコンテキストを持つ専門ワーカー。「大量の grep」「大規模リポジトリの探索」のような重い作業を委譲すると、メイン会話の context window を汚さずに済みます。

   返ってくるのは要約だけ。

   組み込みは Explore（読み取り専用）、Plan（編集せず計画のみ）、general-purpose（全ツール使用可）の 3 種。

   • **Explore**: 「どこに X がある？」「Y はどう実装されている？」のような調査
   • **Plan**: 大きな変更前に計画だけ立てる（編集せず）
   • **general-purpose**: 確信のない検索が 3 回以上続きそうなとき

   text

   # 例：認証まわりを調査
   > Explore サブエージェントを使って、ユーザー認証のコードがどこにあるか調べて。
     エントリポイント、ミドルウェア、ハンドラの3層に分けて、各ファイルパスと行数を返して。
   
   # 例：大型リファクタの計画
   > Plan Mode に切替えて、src/api/users.ts の解体案を 3 つ提示して。
     各案の影響範囲・テストへの影響・リスクを比較表で。

   Lv.5 — Subagent への委譲

   理解度チェック

   1. Q1.「同じファイルの場所を 3 回 grep して見つけられない」状況に出会ったとき、最適な対応は？

      Aもう 5 回 grep を続けるBExplore Subagent を呼び、コードベース全体を独自 context で探索させて要約だけ受け取るCファイルを諦めるDClaude を再起動する
   Day 4：MCP を 1 個繋ぐDay 6：権限ルールを整える
6. 06

   Day 6：権限ルールを整える

   deny / ask / allow の三段評価を理解し、自分の作業域に合うルールセットを作る。

   Claude Code は権限ルールに従ってツール呼出を許可・確認・拒否します。評価順は **deny → ask → allow**、最初のマッチが勝ち。

   最低限の deny を最初に置き、頻発する確認を allow に追加すれば、安全かつ快適な作業環境が出来上がります。

   json

   {
     "permissions": {
       "allow": [
         "Bash(git status:*)",
         "Bash(git diff:*)",
         "Bash(pnpm test)",
         "Bash(pnpm lint)",
         "Read(./**)",
         "Edit(src/**)"
       ],
       "ask": [
         "Bash(pnpm:*)",
         "Bash(curl:*)",
         "WebFetch(*)"
       ],
       "deny": [
         "Bash(rm -rf:*)",
         "Edit(.env)",
         "Edit(.env.*)",
         "Edit(secrets/**)",
         "Edit(infra/prod/**)"
       ]
     }
   }

   Lv.4 — 権限とサンドボックス

   理解度チェック

   1. Q1.`.env` を deny に入れているのに、`Edit(src/**)` を allow に書く順番は問題ないか？

      Adeny → ask → allow の順で評価されるので、`.env` への編集試行は deny がマッチして必ず拒否されるB上から書いた順に評価されるので allow が勝つCpermissions は最初の 1 個しか読まれないDJSON のキー順で評価される
   Day 5：Subagent をテンプレ化Day 7：チームに配布する
7. 07

   Day 7：チームに配布する

   .claude/ を Git で共有、settings.local.json は ignore。Marketplace 配布や managed settings も検討。

   個人で磨いた .claude/ をチームに展開するには、リポジトリにコミットするのが最も簡単です。`.claude/settings.local.json` は個人ローカル上書きなので、これだけ .gitignore に入れます。

   text

   # .gitignore に追加
   .claude/settings.local.json
   .claude/cache/
   
   # 共有するもの
   .claude/CLAUDE.md
   .claude/settings.json
   .claude/skills/
   .claude/hooks/
   .claude/agents/
   .claude/rules/
   .mcp.json

   手を動かす

   0 / 4

   • .claude/settings.local.json を .gitignore に追加
   • .claude/ を git add → commit
   • チームに「git pull すれば同じ環境が使える」と告知
   • （社内全体）managed-settings 配布を IT 部門と相談

   Lv.9 — エンタープライズ

   理解度チェック

   1. Q1..claude/ を Git で共有するとき、リポジトリに含めず .gitignore に入れるべきファイルは？

      A.claude/CLAUDE.mdB.claude/settings.json と .claude/skills/C.claude/settings.local.json と .claude/cache/D.mcp.json と .claude/agents/
   Day 6：権限ルールを整える