前回の記事（AIコーディングツールの設定をdotfilesで共通化した）で、AI支援ツール（Cursor / Claude Code / codex / Gemini CLI）の設定を dotfiles に集約し、複数プロジェクトを並行で回すための“共通インターフェース”を作った。
その次のステップとして、Claude の公式ベストプラクティスを根拠にパターンを削り、“かなり賢い前提”で動くように形を整えた。
要点（今回の判断基準）
- Claude は基本かなり賢い前提で設計する
「背景知識の講義」「念のための説明」を増やすほど、トークン消費が増えて判断が鈍る。 - Skill は“知識”ではなく“成功させるための設計図（ガードレール）”
壊れやすい/順序が命のタスクは自由度を下げる。レビューや方針決めは縛りすぎない。 - name/description が最重要
起動時にまず読まれるのは “名前と説明” なので、「何をするか」だけでなく「いつ使うか」を書く。 - Progressive Disclosure
最初から全部読ませず、必要になった瞬間だけ参照する。参照の参照は増やさない（1段で止める）。 - 一発成功前提にしない（実行→検証→修正を組み込む）
変更点（dotfiles側で実際に変えたこと）
1) /fix を “チェックリスト” に寄せた
長文の手順説明をやめて、進行管理しやすいチェックリストにした。 各ステップで、達成してほしいことを明確にし、一定のガードレールとしてエージェントへの移譲やスキルの示唆は残す
-
- Setup
-
- Understand（必要なら公式調査だけ subagent に委譲）
-
- Plan（複雑な場合のみ）
-
- Implement（TDD）
-
- Docs
-
- Pre-PR Check（lint/test/build/e2e を並行で実行）
-
- Push & PR
-
- Post-PR Check（CI/レビュー監視を並行で実行）
2) “ログが太りがち” を subagent に隔離した
メインのコンテキストを汚しやすい作業を subagent に切り出し、返ってくるのは「要点＋問題解決に必要なログ抜粋」だけにした。
setup-checker: 初期セットアップを「整うまで」完了させて要約だけ返すlinter-runner/tester-runner/builder-runner/e2e-tester: Pre-PR の検証を並行実行して要約を返すci-debugger/review-checker: PR後の監視を並行実行して要約を返すofficial-researcher: 公式ソース限定で技術調査し、要約とURLだけ返す
3) 汎用のSkill は 自分独自の定型手順 に絞った
PRやテスト方針など、自分なりに守りたいものだけに絞った。 基本は Claude Code をメインに使い、レビュー/振り返りのように文章量が増えがちな作業は codex に移譲できるよう、移譲用のスキルも用意している。
- skills（ガードレール）
tdd-guide: TDD（Nested TDD含む）の 手順の型だけを提供（プロジェクト固有はAGENTS.mdを正）push-pr: push〜PR作成の定型手順（rebase など意図判断が必要な箇所はメインでやる）subagent-review: PRレビューを subagent（Codex/Gemini）に委譲するための呼び出し手順subagent-retrospective: セッションの振り返りを subagent（Codex）に委譲するための呼び出し手順
4) 冗長な“共通エージェント”を削った
汎用エージェントを整理した。2)の要件で明確に切り出したいものだけに絞った。
command / skill / subagent の役割分担（今の結論）
- command: 共通の入口。チェックリストで進行と合流点を作る（SSOTはプロジェクト側）
- skill: 失敗しやすい作業の “型/ガードレール”。短く、参照は1段で止める
- subagent: ログが多い/並行実行したい/ツール制約で隔離したい作業を担当し、要約だけ返す
次にやること（運用の改善ループ）
- 引き続き、各セッションのレトロスペクティブのログから改善のサイクルを回す運用でやってく。