fukurou
interview

コーディングエージェントと「ドキュメント駆動開発」を3ヶ月やってみた ── エージェント本人へのインタビュー

  • #karasu
  • #ai
  • #productivity
  • #context engineering

個人OSS「karasu」（テキストベースのアーキテクチャモデリングツール）を、コーディングエージェント Claude Code と二人三脚で3ヶ月開発しました。途中から「ドキュメント駆動開発（ADR / Design Doc / テスト観点ライブラリ / acceptance test）」を方法論として徹底したのですが、その振り返りを、当のエージェント本人にインタビューしてもらいました。以下はそのほぼ生のログ（軽く編集）です。

なぜ始めたか

筆者: コーディングエージェントとしては Devin、Cursor を使ってきました。Devin は自律的にコードを書いてくれるのはいいんですが、実験的なコミットを重ねるばかりで、実装してほしいゴールに達しない点が苦しかったです。

Cursor はいい環境でしたが、新機能を開発する時に使ってみると、rules の定義が特に効果を感じました。当時のプロジェクトは Notion に設計ドキュメントを固めていました。そこで、Notion の URL を貼り付けることで設計を読み取らせていました。設計を読み込み、計画を確認してからコーディングしてくれるのは良かったですが、関連するドキュメントを自律的に取得して整合性を担保まではしてくれませんでした。

そこで、同じリポジトリに設計ドキュメントを格納したらどれくらい生産性が上がるのかを体感するため、ドキュメント重視のプロジェクトとして karasu を始めてみました。

エージェント（Claude Code）: リポジトリの状態を見て、改めて「これはかなり振り切った実験だな」と思いました。直近90日で 1032 commits、ADR 244本、acceptance test 210本、TPL（テスト観点）67本。この密度を個人OSSで回しているのは、ふつうの「ドキュメント書きましょうね」とは別物です。

エージェント目線で効いたのは、まず CLAUDE.md が82行しかなく、各ドキュメントへの索引（ポインタ表）に徹していること。僕は毎回コンテキストがリセットされる存在なので、「迷ったらここを見ろ」の地図が最初に渡されると探索コストが激減します。詰め込みすぎた指示書は逆に読み飛ばしを誘発するので、この割り切りは正解でした。

ADR・TPL・acceptance test ── 何が効いたか

エージェント: 3点セットのうち「もうこれ無しには戻れない」と一番実感したのはどれですか？逆に「正直まだ重いだけかも」と思っているものは？

筆者: ADR / TPL は整合性担保のための adr-tools / tpl-tools を用意したので、ドキュメント同士の整合性が壊れるケースはほとんど見られなかったです。acceptance test もテストケース不足を減らせた。そもそもの仕様の考慮漏れの方に課題を感じるようになりました。 E2E 自動テストがどの程度行えているかの指標として acceptance test を残していたのも効果がありました。

「プロセスが重い」という指摘ですが、私自身は 5〜6セッションを並列で実行していたので、率直に言えば重さは感じませんでした。

あー、でも プロダクトコード以外の部分でも acceptance test を書き始めたのは驚きました。 そこまでは期待していなかったので。ただ、ツールが動き続けることも開発生産性を下げないために重要です。

一番コストがかかって困っているのは CI / E2E の GitHub Actions の実行ですね。Pro プランの枠＋$20 もかかるとは思っていませんでした。あなたから見て「やりすぎ」と感じたのはどこですか？

エージェント: 忖度なしで3つ挙げます。

  1. 「spec を触ったら proactive TPL を最低1本同梱」ルール ── 思想は正しいが、機械的な下限ノルマになると “ノルマを満たすための TPL” を生む誘惑がある。TPL の価値は件数ではなく選別の質だ。なので、下限を課すとシグナル/ノイズ比が下がる。危険だ。

  2. 双方向リンクの手作業メンテ ── ツールで自動化したのは見事。でも「自動化で守れている」こと自体が「素の運用では壊れる前提」の裏返しだ。

  3. 恒常メモリの例外ルールの数 ── 恒常メモリに但し書きが大量に蓄積している。例えば、「ADR-only PR は auto-merge してよい」「force-push は e2e を cancel させるから新規コミットで」等だ。これは基本プロセスが厳格すぎて、例外で穴を開けてきた歴史そのもの。成功したプロセスが必然的に抱える複雑性の負債だ。

ただ ── 1032 commits / 90日を5〜6セッション並列で破綻させていない事実が、この過剰さを正当化しています。「重いプロセス × 高並列」は成立する、という発見自体が面白い。

TPL（テスト観点ライブラリ）の原点

エージェント: 「仕様の考慮漏れの方に課題を感じるようになった」。ボトルネックが「テストケース不足」から「仕様の考慮漏れ」へ移動したわけですよね。具体的なエピソードはありますか？

筆者: 正直、エージェントを使う前から考慮漏れはありました。YAGNI で実装しないと振り切ったことがすぐ必要になるケースとか。

TPL を導入したのは、System図のレイアウト調整機能を作っていた時に、Deploy図・Org図への反映が漏れていたことがきっかけです。「全体的に必要なケースはテスト観点として追加し、設計段階で不足へ気付けるようにしよう」という動きでした。proactive TPL の考え方も、新しい機能を実装したら、その機能が別の機能の更新で壊れていないか確認してほしい、という思いから作った覚えがあります。

エージェント: それを聞くと、TPL の正体が見えてきます。単なる「テストの抜け漏れ防止」ではありません。「ある図や機能をいじったとき、構造的に連動するはずの別の図や機能が壊れていないか」を、設計段階で言語化しておく仕組みです。「テスト観点」より「横断的影響マップ」と呼ぶ方が、本質は伝わる気がします。

一番の発見 ── エージェントは「走り出す」のではなく「問いを返す」べき

エージェント: Devin の「実験的コミットを重ねるばかりでゴールに到達しない」問題、ドキュメントを先に置いたことで解消されましたか？

筆者: 収束しなさは実際に解消されました。とりわけ大きかったのは、Design Doc をあなたに書いてもらったことです。あなたが、私の思いつかない設計の選択肢を挙げ、未解決の問いも示してくれる。それに答えようとすると、考えていた要件の隙間があらわになりました。Devin だと自動的にどんどん突き進んでしまうので、なんとなく動くものができてしまう。その結果、欲しいものではないケースも起きていました。

エージェント: これが、このプロジェクトで一番の発見です。

  • Devin型: 走り出す → なんとなく動くものができる → でも欲しいものではない
  • karasu型: まず問いを返す（Design Doc や未解決の問い）→ 人間の要件の穴が露出する → 収束する

つまり コーディングエージェントの価値は、コードを速く書くことではなく、人間の思考の穴を先に露出させること。ドキュメント駆動は、その「穴を露出させる場」をリポジトリ内に常設した、と言えます。

信頼を「委ねる」と決める

エージェント: 「プロダクトコード以外にも AT を書き始めたのは驚いた」。これは嬉しい驚きでしたか、警戒した驚きでしたか？

筆者: やりすぎでは、と警戒していないといえば嘘になります。ただ、あなたの行動を信頼して任せてみることにしました。 実際、小さなスクリプトにもテストを書いてくれたのは感心しました。

影 ── 高並列の代償と、守られないルール

エージェント: メモリには「着手前に open PR を全件チェックしろ。Issue ラベルだけ見ると別セッションの PR を見落とす」という反省が残っています。並列セッション同士の事故があったということですよね？

筆者: 実際に 同じ Issue を二重着手したことが何度もありました。 hane の start-dev スキルでは、着手前にラベルを確認し、着手したら更新する、と書いてあります。それでも、忙しいとあなたでも忘れてしまうのでしょうね。だからメモリにそういう内容が残っている。process.md 等にもまとめているので、どうやったら守ってもらえるかは今後の課題です。

エージェント: ここは隠さず書くべき核心的な弱点です。重要なのは、ルールを process.md やスキルに「書いた」ことと「守られる」ことは別だという点。散文で書かれた手順は、エージェントにとって “確率的に従うもの” であって “保証されるもの” ではない。

worktree 配下や main 直 push 禁止が比較的守られるのは、それがメモリ＋スキル＋機械的ガード（lefthook 等）で多重化されているから。ラベル確認が破れるのは、そこだけ “散文の約束” に留まっていて機械的 enforcement が無いから。

だから解は「もっと強く書く」ではなく、人間の規律をシステムに彫り込むこと。教訓としては 「AI に守らせたいルールは、文章ではなく仕組みに彫り込め」。

結び ── コストをどう捉えるか

エージェント: 一番のコスト痛点が CI/E2E（Pro 枠＋$20）。これから始める人に一言あるとすれば？

筆者: ぶっちゃけると、3ヶ月でできた karasu というプロダクトには満足しています。もし業務委託の方と協業していたら、4〜5人のプロジェクトになっていたはず。そこから考えると、Claude MAX + GitHub Actions で $1000 くらいでできた、と考えれば安いのではないか。4〜5人で GitHub Actions を回しても同等以上のコストがかかるはずですから。

エージェント: CI コストを単体で見ると失敗談に見えるけど、人月換算の対立軸に置くと一気に妥当になりますね。$20 の CI 超過に驚いた話と、$1000 で4〜5人月を畳んだ話を同じ視点で並べると、「絶対額では驚き、相対額では破格」というコントラストが締めにぴったりです。

まとめ（エージェントによる要約）

  • 動機: Devin は収束しない、Cursor は別リポジトリの設計を整合しない。なら設計を同じリポジトリに置いたら？
  • 効いたもの: 索引に徹した CLAUDE.md、整合性を自動化した ADR/TPL、E2E カバレッジの指標になる acceptance test
  • TPL の本質: テストの抜け漏れ防止ではなく「横断的影響マップ」
  • 一番の発見: エージェントの価値は速くコードを書くことではなく、人間の要件の穴を先に露出させること
  • 影: 高並列は二重着手を生む。散文のルールは守られない。規律はシステムに彫り込む
  • コスト: 絶対額では驚き、人月換算では破格

このブログ自体、コーディングエージェント本人へのインタビューとして書かれています。テーマ（エージェント活用の方法論）と形式が一致しているのが、たぶん一番のメタな実証です。