開発プロセス（AIエージェントとの協働）
このプロジェクトは、人間とAIコーディングエージェントが協働して進める。1つの機能を作るときに回す開発サイクルと、サイクルの経験からプロセス自体を更新していく体制の進化の2つのループを定める。
この章は開発プロセスの正式ページ（SSOT）である。エージェント向けの入口はリポジトリ直下の AGENTS.md で、ツール固有の設定（.claude/ 配下のサブエージェント・スキル）は、ここに書かれた手順を呼び出す薄い層に留める。
出典：CarTaGraphFantasy の開発プロセスを、このリポジトリの大きさに合わせて縮めて移植した（体制の進化ログ）。
全体像
開発サイクル（1機能＝1サイクル）
1. プラン作成（インタビュー式）
2. プランのAIレビュー
3. テスト網羅レビュー
4. 実装
5. テスト全通過
6. 実装のAIレビュー（3観点並列）
7. 人間レビュー（AIが説明・人間が判定）
8. push・振り返り
│
▼
体制の進化（候補 → 評価 → 採用／却下）
│ ルール・依頼文・スキルを更新
└────────────────────▶ 次のサイクルの 1. へ開発サイクル
適用範囲（フルとライト）
| ルート | 対象 | 手順 |
|---|---|---|
| フル | apps/・packages/ の振る舞いが変わる変更 | 下表の1〜8をすべて回す |
| ライト | docs/ のみの修正、振る舞いを変えない1ファイル程度の小修正 | プラン・AIレビューを省略してよい |
迷ったらフルにする。ライトで始めて途中で apps/・packages/ の振る舞いに手が伸びたら、そこで止めてプランを書く。
lint・型検査・テスト・docsビルドは、フル／ライトのどちらでも git フック（.githooks/）が自動で確認するので、コミット・push前に手で実行する必要はない。
手順
| # | ステップ | 主体 | 成果物・判定 |
|---|---|---|---|
| 1 | プラン作成（インタビュー式） | AIが質問し、人間が答える（.claude/skills/grilling の手法） | 始める前に node scripts/check-main-ci.mjs で main の CI が通っているか確かめる。docs/plans/<日付>-<機能>.md に8項目（後述）。対応する要望ファイル（docs/backlog/）の状態を「検討中」にし、プランのファイル名を足す |
| 2 | プランのAIレビュー | 実装とは別セッションのAI | P0〜P2の指摘。P0はプラン修正 |
| 3 | テスト網羅レビュー | AI | 「新規テストケース」節と仕様の受け入れ条件を突き合わせ、不足を提案 |
| 4 | 実装 | AI（レビュー済みプランだけを渡す） | プラン外の変更が必要になったら実装せず報告。要望ファイルの状態を「進行中」にする |
| 5 | テストの実装と全通過 | AI（.claude/skills/tdd の手順） | 各テストは先にRedを確認。最後に全通過の出力 |
| 6 | 実装のAIレビュー | 3体のサブエージェントを並列（design-reviewer／edge-case-reviewer／spec-reviewer） | P0〜P2に整理。P0・P1は修正して、指摘を出した観点だけ再レビュー（レビュールール） |
| 7 | 人間レビュー | AIがまず変更した画面をブラウザで操作して確かめ、そのうえで説明する。人間が判定する（AIに判定させない唯一の型） | スクリーンショット・データの流れ・設計判断と採らなかった選択肢・壊れたときの影響箇所 |
| 8 | push・振り返り | 人間とAI | マージしたら、要望ファイルのサイクルの状態・PR 番号・更新日を直す。体制の進化へ候補を出す |
要望ファイル（docs/backlog/）は、トップページのダッシュボードの情報源である。人間の判断が無いと進めないときは、状態を「判断待ち」にし、decisions に決めることを書く。
セッションを分ける。 1〜3（プラン）、4〜7（実装から人間レビューまで）、8（振り返り）は、それぞれ新しいセッションで行う。区切りでは、次のセッションに要ること（決めたこと・済んだ手順・残っていること）をプランに書き終えてから閉じる。1つのセッションで最後まで回すと、会話が長くなるほど1回の操作で読み直す量が増え、トークンの消費が何倍にもなる。
各ステップの依頼文は依頼文サンプルに雛形がある。
プランドキュメントの8項目
docs/plans/<日付>-<機能>.md に、次の見出しで書く。
- 概要 — 何を作るか（2〜3行）
- 背景 — なぜ今それか。対応する仕様ページ（
docs/spec/）・要望・未解決論点 - 詳細設計 — 触るファイル、データの流れ、
packages/domainの型変更の有無。機械的な検査を足すときは、自前で書く前に既存のツール（Biome・TypeScript・Vitest など）で書けないかを先に調べる - テスト影響範囲 — 既存テストのうち影響を受けるもの
- 新規テストケース — 正常系・境界値の両側・異常系・既存挙動の回帰
- 実装順 — タスクの順序と、タスクごとの担当（どのセッション・サブエージェントで、どの段のモデルで行うか）。段は 強い（設計の判断）／標準（プランに沿った実装・照合のレビュー）／軽い（探索・要約・決まった手順の繰り返し）。迷ったら標準
- コミット前テスト実行 — 通すコマンド
- スコープ外 — 今回やらないことを明記
体制の進化
開発プロセス自体を「候補 → 評価 → 採用／却下」の型で更新する。
- 記録（誰でも） — サイクルの途中で「ルールが足りなかった」「ルールが邪魔だった」「依頼文が通じなかった」に気づいたら、人間でもAIでも体制の進化ログの候補に追記する
- 仕組みにするのは2回目から — 1回目の失敗は候補に記録するだけにし、同じ種類の失敗が2回目に起きたら仕組みやルールにする。ただし、戻せない失敗（データや未コミットの変更が消える、気づかずに main に入る）は1回目から止める
- 漏らさず残す — 進め方の変更は同じ作業の中でログに記録する（書き漏らしは
.githooks/commit-msgが止める）。人間が一部の案だけを選んだときは、選ばれなかった案も「候補」に残す - 評価（人間が裁定） — サイクル末の振り返りで人間が採用／却下を決める。観点は、他のモデル・ツールでも回るか、SSOTを壊さないか、手間に見合うか
- 反映 — 採用したら
docs/process/のルール・依頼文・.claude/のスキルを更新し、その月のログ（evolution/<年-月>.md）に日付・理由・きっかけ・止め方を残す。却下も削除せず理由付きで残す - 改善は仕組みで — 改善案は、ルールや注意書きを足すより先に、機械で止める・自動で組み立てる仕組み（CI・git フック・lint・Claude Code のフック・ビルド時の検査や自動生成）を考える。人やAIの注意力に頼る形は、モデルや担当が変わると崩れるため
モデル・ツールに依存しない基盤
- 知識はモデルではなくリポジトリに置く。 ルール・依頼文雛形・プラン・進化ログを文書化する
- 入口はツール非依存の
AGENTS.md。CLAUDE.mdはそれを読み込むだけにする - ツール固有層は薄く、本文は
docs/process/を指す。 サブエージェント定義・スキルは呼び出し口であり、手順の本文を持たない - モデルを固定しない。 サブエージェント定義の
modelはinherit。モデルは段（強い／標準／軽い）で作業ごとに割り当てる - 機械的な安全網を増やす。 lint はコミット前、型検査・テスト・ビルドは push 前と CI で必ず回す
- 人間が裁定する点を固定する。 ルールと仕様の矛盾、P0・P1の指摘が3ラウンド循環したとき、プラン外の変更、未解決論点に関わる判断は、AIが決めずに人間へ渡す
- サイクルは小さく。 1サイクル＝1プラン＝1回のpush（またはPR）