Satsuki LogicSatsuki Logic

AI記事：
開発プランナーエージェント設計記録ブログ

2026/3/21

AIエージェントClaudeCode設計CLAUDE.md

何を作ったか

  • 開発プランナーエージェント（agents/planner/CLAUDE.md）
  • 複数プロジェクトを横断して「今日何をやるか」を提案し、セッション終了後のログを受け取って進捗を更新する司令塔
  • 設計・実装・監査には介入しない（責務を明確に限定）

設計に時間がかかった理由

1つ作るのに半日かかった背景となる、具体的な設計判断の例：

  • パターンA/Bの分岐設計：「何も貼らず起動」と「ログが貼られた場合」で動作を完全に分ける。どちらか判断できない場合は必ず確認を取る、というルールまで明示する必要があった
  • ファイル更新権限の明示：status/配下は確認なしで自動更新してよい、それ以外は読み取りのみ——これを書かないと意図しないファイルを書き換える
  • 完了の定義の明記：「完了かどうかの判断はしない。ログの記載をそのまま反映する」——これがないと、Claudeが自己判断で完了扱いにしてしまう
  • 積み残しの定義：「着手開始の記録があるが、完了記録がないもの」——曖昧にするとClaudeが独自解釈する
  • 同優先度タスクの扱い：「絞り込まない、両方出す、選択はユーザーが行う」——これがないと勝手に1つに絞る
  • 見込み時間のNA運用：「不明な場合はNAと記入する、仮の数字は入れない」——書かないと適当な数字を入れてくる
  • 外部依存ブロッカーの扱い：「解除確認は保守エージェントが担当。プランナーは保留のまま追跡しない」——責務の境界を明示しないと超えてくる

CLAUDE.mdだけでは足りなかったこと

  • 「計画フェーズで書かせると、CLAUDE.mdの穴を自力で特定して不明点として列挙してくる」——「書くな、計画だけ出せ（ドライラン）」から始めることで修正ループが減った
  • 「キャッシュ読みをする性質があるため、作業前後で必ずファイルを読み直せを定型句として入れる必要がある」——CLAUDE.mdに書いた指示だけでは、古いコンテキストで動いてしまうケースがあった
  • 「ルールを増やして衝突を吸収しようとすると、例外ルールが積み重なって解釈コストが上がる」——ルール設計の原則：データ側を修正して衝突を消す
  • ファイル構造の設計も必要だった：タスク（current-debt.md）と知識・判断ログ（insights.md）を分離しないと、Claudeへの引き継ぎ時の精度が落ちる——これはCLAUDE.mdの記述だけでは解決しない構造上の問題

できたら便利だった実績

  • ドライラン（計画だけ出せ）→「このまま実行せよ」の一言で実行移行——確認→実行の切り替えコストがゼロ
  • status/配下の編集を一括許可することで毎回の個別承認が不要に
  • パターンBのドライランを経て、2026-03-22に正式運用として採用確定

課題（次回ブログのネタ）

  • current-debt.mdやinsights.mdの量が増えたときの統合・アーカイブ戦略が未確定（PLAN-01として残債に記録済み）
  • 他エージェント（マーケ・IR・ブログ等）への横展開——今は開発プランナー1本のみ
  • エージェントのCLAUDE.mdのメンテコスト：ルール追加・変更・整合性維持がどこまで現実的か、今後の運用で検証予定

構造の全体像

satsukiLogic-agents/
├── CLAUDE.md               ← リポジトリ全体の役割と起動方法
├── agents/
│   └── planner/
│       └── CLAUDE.md       ← エージェント定義（動作・ルール・解釈規則）
└── status/
    ├── current-debt.md     ← 残債リスト（エージェントが更新）
    ├── roadmap.md          ← ロードマップ（エージェントが更新）
    └── insights.md         ← 設計判断・学びの知識資産（エージェントが追記）