こんにちは、バックエンドエンジニアのユンです。

現在あるプロジェクトで、AIコーディングエージェントをフルに使って開発を進めています。その中で、作成・修正などの触るファイル数が増えてくると、AIの記憶力は目に見えて低下してました。細かい指示をせずに任せた結果、アーキテクチャルールを無視してControllerがUseCaseを経由せずRepositoryを直接呼び出したり、まだ存在しないメソッドを平気で呼び出したり。命名もUserRepositoryとuserRepoなど混在し、テストは「後で書きます」のコメントだけ、もしくはテストが落ちて修正を振り返るとセッション内のコンテキストを使い切りセッションを切り替えることになったり……といったことが頻繁に起こっていました。

後から直すコストは膨大で、人が最初から時間を掛けてプロンプトを細かく書いた上で指示を出すよりもはるかに手間がかかりました。そこで辿り着いたのが、Spec（設計書）をSingle Source of Truthにして、フェーズごとにAIの文脈を外部化するというやり方です。Spec-Driven Development（SDD）の発想をベースにしています。

解決策の概要

うまく回る形はこうでした。

設計書（Spec）を唯一の信頼できる情報源にする
実装は呼び出される側から順にフェーズ分割する
各フェーズの終わりにChecklist と Session Notes を更新して、次回の"復帰点"を作る

この3点を運用として固定し、毎回同じ型で回せるようにしました。
また今回はClaude CodeのSkills*1を利用して上記の解決策をシステム化しました。

全体フロー

実際のワークフロー

Step 1: /plan-feature（Spec生成）

まず /plan-feature で、曖昧な要件を仕様（Spec）として落とし込みます。

たとえば、口頭（チャット）で「重複処理しないで」と頼むだけでは忘れてしまいますが、これを docs/plans/<feature>/01_DOMAIN_MODEL.md に「冪等性キー生成ロジック」として明記しておくと、実装の前提が揃いやすくなります。

出力されるドキュメント群（Spec）:

docs/plans/<feature>/
├── 00_OVERVIEW.md
├── 01_DOMAIN_MODEL.md
├── 02_DATA_ACCESS.md
├── ...
└── 05_API_INTERFACE.md

これが以降の唯一の正解（Single Source of Truth）になります。

Step 2: /init-impl（Checklist生成）

設計が決まったら/init-implで実装用ファイルを生成します。

Specだけでは「何を作るか」は決まっても「どの順で作るか」が曖昧です。ここでSpecを読み込み、呼び出される側から順にフェーズ分割とチェックリストを自動生成します。

出力されるもの：

実装チェックリスト（フェーズ別）
フェーズごとのスラッシュコマンド（/feature-phase1など）
プロジェクト固有ルール（lint/命名/レイヤ規約など）の参照

チェックリストには各フェーズのゴール、作業項目、テストコマンド、Session Notes欄が含まれます。詳細は次のセクションで説明します。スラッシュコマンド（/feature-phase1など）は、該当フェーズのSpecとChecklistを読み込んだ上で実装を進めるためのショートカットです。プロジェクト固有ルールを参照させておくと、AIが勝手にルールを逸脱するのを防げます。毎回説明する手間が省けるのはこのおかげです。

Step 3: フェーズ実行

呼び出される側から順に実装を進めます。

Domain（Phase 1）：ビジネスルールの芯を作る
Data Access（Phase 2）：データの出入り口を作る
UseCase（Phase 3,4）：1と2を使って処理を組み立てる
規模が大きい場合は主要フローと副次フローに分割する。一度に実装するとコンテキストが膨らみやすいため
Interface / API（Phase 5）：外部I/Oを実装する

この順序にすると、未定義の関数呼び出し（幻覚）が起きにくくなります。

Checklist & Session Notesの運用

/init-implが生成するチェックリストは、ただのToDoではありません。"次のセッションで復帰するための状態"まで含んだものです。

以下は運用例です。

# Feature Checklist: <Feature Name>

## Current Progress
- Current Phase: Phase 3 (UseCase - Primary)
- Last Update: 2026-01-20
- Next Task: Phase 4 (UseCase - Secondary)
- Overall: 2/5 phases completed

---

## Phase 1: Domain Model
Status: ✅ Completed

### Checklist
- [x] コアとなる型/ルールを定義
- [x] 重要な境界条件を明文化
- [x] ユニットテスト通過

### Testing
```bash
go test ./... -run TestDomain -v
```

### Session Notes
2026-01-20
- Done: ドメイン型とID生成の方針を確定
- Next: データアクセス層のI/Fとトランザクション境界を設計
- Risks/TODO: 冪等性キーの運用（再実行/重複排除）の最終決定が必要

なぜ効くのか

Session Notes（文脈の外部化）：セッション終了時に追記する。次はこのファイルだけ読めば復帰できる。
Testing（検証の具体化）：実行すべきコマンドを固定する。検証範囲が曖昧にならない。

実際、チャットで長文説明していた頃は解釈ズレで修正が頻発していましたが、Spec参照に切り替えてからはブレがほぼなくなりました。セッションを跨ぐたびに説明し直していたのも、今はNotesを読み込むだけで済んでいます。

復帰時のダッシュボード

/statusのようなスキルを用意しておくと、現在の進捗を一覧表示できます。

📊 Implementation Status: <Feature Name>

Overall Progress
██████████████░░░░░░ 67% (2/3 Phases completed)

Phase 1: Domain Model        ✅ Done
Phase 2: Data Access         🔄 Active (86%)
Phase 3: UseCase             ⏳ Pending

現在のフォーカス: Repository実装

Checklistを読み込んで進捗率を計算し、次のアクションまで提示します。週明けの「どこまでやったっけ？」がこれで解消されます。

運用上の注意点

実践してみて、ここを外すと崩れるなと感じたポイントがあります。

Specの更新ルール（Truthの守り方）

SpecがTruthなら、仕様変更時は必ずSpec更新 → 実装の順にします。"チャットでの会話で決めた"は無効とし、書いたものだけがTruthとします。

Session Notesの最低品質

Notesが雑だと復帰できません。「やったこと」「次にやること」「リスク/未解決」の3点は必ず残すようにしています。

まとめ

振り返ると、うまく回ったポイントはこの3つでした。

Specを唯一の情報源にする
呼び出される側から順にフェーズ分割する
Checklist & Session Notesで文脈を外部化する

体感として一番効いたのは「復帰コスト」と「ルール逸脱の手戻り」の削減でした。日をまたいでも、週末を挟んでも、Checklistを見るだけで実装に戻れます。

「AIにコードを書かせる」ではなく「AIと一緒に設計し、実装プロセスを管理させる」。この視点の転換が、大規模開発を安定させる鍵だと感じています。

Appendix：テンプレート活用ガイド

Skills定義ファイルを使わなくても、以下の手順で同じワークフローを再現できます。

Quick Start

Checklistファイルを作成
docs/plans/<feature>/CHECKLIST.md
下のテンプレートをコピペして、機能名・フェーズを埋める
AIに以下の3ステップで指示するだけ
- 開始時：「このChecklistを読んで、現在のPhaseから作業を始めて」
- 作業中：「Phase N の Checklist に沿って実装する。終わったら Checklist を更新して」
- 終了時：「今までの作業をSession Notesに追記して」

これで、セッションを跨いだ復帰がスムーズになります。

Checklistテンプレ（最小）

# Feature Checklist: <Feature Name>

## Current Progress
- Current Phase:
- Last Update:
- Next Task:
- Overall:

---

## Phase N: <Phase Name>
Document: <Spec Path>
Status: ⬜ Not started / 🟨 In progress / ✅ Completed

### Goal
- ...

### Checklist
- [ ] ...
- [ ] ...

### Testing
# run commands

### Session Notes
YYYY-MM-DD
- Done:
- Next:
- Risks/TODO:

シーン別プロンプト例

Spec生成時（/plan-feature相当）

<機能名>の設計をしてください。

以下の観点でヒアリングしながら進めてください：
- コア目標（整合性／冪等性／監査性など）
- ユースケースと境界条件
- データストレージ設計
- 失敗時の挙動

出力は docs/plans/<feature>/ に以下の構成で：
- 00_OVERVIEW.md
- 01_DOMAIN_MODEL.md
- 02_DATA_ACCESS.md
- 03_USECASE.md
- 04_API_INTERFACE.md

Checklist生成時（/init-impl相当）

docs/plans/<feature>/ のSpecを読んで、実装用Checklistを生成してください。

- フェーズ分割は呼び出される側から順に実装する（Domain, Repository, UseCase, API）
- 各フェーズにGoal、Checklist、Testing、Session Notesセクションを含める
- 出力先: docs/plans/<feature>/CHECKLIST.md

セッション再開時

docs/plans/<feature>/CHECKLIST.md を読んで、現在の状況を把握してください。

- Current Progressを確認
- 最新のSession Notesを確認
- 次にやるべきタスクから作業を再開してください

セッション終了時

今までの作業内容をSession Notesに追記してください。

- Done: 完了したこと
- Next: 次にやること
- Risks/TODO: 未解決の課題や懸念点

Checklistの完了項目も [x] に更新してください。

We are hiring!

ミラティブではエンジニアを絶賛募集中です。日本全国どこからでもフルリモート勤務が可能です。ご興味のある方はお気軽にご連絡ください！

www.mirrativ.co.jp

mirrativ.notion.site

speakerdeck.com

*1:Claude Code Skills Documentation