Knowledge
AI-DLC Workflows を Claude Code で使う ― フェーズ・ステージ・エージェント・スコープの仕組みと実際の流れ
AWS の開発手法 AI-DLC を Claude Code で動かす OSS「AI-DLC Workflows」の、5フェーズ・33ステージ・14エージェント・11スコープの分け方を整理し、読書記録の CLI を要件から実装・テストまで作らせました。かかった時間と、重すぎる場面も実測で確かめます。
AI-DLC(AI-Driven Development Life Cycle)は、AWS が提唱している「AI と一緒にソフトウェアを作るときの進め方」です。AI-DLC Workflows は、それを Claude Code・Codex CLI・Cursor・Kiro などのエージェントの中で実際に動かせるようにした OSS です。/aidlc 作りたいもの と頼むと、やりたいことの確認 → 要件 → 実装 → テストを、人の承認を挟みながら順に進めます。
AI-DLC の肝は、開発の流れをフェーズ・ステージ・エージェント・スコープの4つに分けて組み立てているところです。この記事では、まずその分け方を定義ファイルとドキュメントから整理し、そのあと AI-DLC Workflows 2.11.4 を Claude Code で使って「読んだ本を記録する小さなコマンドラインツール」を作らせ、どのステージでどのエージェントが動いたかを実際のログで追います。AI-DLC を使わずに作らせた場合との違いと、かかった時間も比べました。
こんな場面で役立つ
- AI に「作って」と頼むと、確認なしに実装まで進んでしまうとき。言語・保存形式・並び順などを AI が勝手に決めてしまい、あとで「そうじゃない」と直すことが多い場合に、先に質問させる流れを作れます。
- 何をどういう理由で決めたかを、あとから見返せるようにしたいとき。質問への答え、要件、レビューの指摘、承認の記録が Markdown のファイルとしてリポジトリに残ります。
- 作るものの大きさに合わせて、手順の重さを変えたいとき。試作なら数ステージ、本番の機能なら全ステージ、と「スコープ」を選ぶだけで通る段階が変わります。
- チームや別のエージェントでも、同じ進め方をそろえたいとき。設定をリポジトリに入れておけば誰が使っても同じ段階と承認を通り、Codex CLI・Cursor・Kiro・opencode・GitHub Copilot にも同じ仕組みで入れられます。
前提・検証環境
- 確認日:2026年11月17日
- AI-DLC Workflows 2.11.4(2026年11月13日公開の安定版)
- Claude Code 2.1.322 / macOS / Node.js 23.9.0
- 一次情報:Introduction、Phases and Stages、Scopes, Depth, and Test Strategy、Agents、GitHub のリリース、インストールされた 2.11.4 の定義ファイル(
.claude/aidlc-common/stages/・.claude/agents/・.claude/scopes/)
AI-DLC Workflows の仕組み
ドキュメントでは、AI-DLC を「AI を使ったソフトウェア開発を、繰り返せて追跡できるフェーズに構造化する方法論」と説明しています。全体は次の4つの部品でできています(数字は2026年11月時点、Introduction の Key Numbers)。
| 部品 | 数 | 役割 |
|---|---|---|
| フェーズ | 5 | 開発全体の大きな区切り。順番に進む |
| ステージ | 33 | フェーズの中の1つ1つの作業。それぞれ成果物と承認がある |
| エージェント | 14 | 各ステージを担当する役割(プロダクト担当・開発担当・レビュー担当など) |
| スコープ | 11 | 33ステージのうち「今回どれを通るか」の組み合わせ。作業の大きさで選ぶ |
つまり、スコープで通るステージが決まり、ステージごとに決まったエージェントが動き、ステージはフェーズ順に進む、という関係です。ライセンスは MIT-0(MIT No Attribution)で、無料で使えます。
フェーズ(5つ)
フェーズは上から順に進みます。Initialization 以外のフェーズの境目では、成果物どうしのつながり(要件に対応する設計や実装があるか、など)を自動で確かめる検証ゲートが入ります(Phases and Stages)。
| フェーズ | 番号 | 目的 | ステージ数 |
|---|---|---|---|
| Initialization(準備) | 0.1〜0.3 | 作業用フォルダと状態ファイルを作る。承認なしで自動で終わる | 3 |
| Ideation(構想) | 1.1〜1.7 | やりたいことを捉え、実現性と範囲を確かめ、進めてよいかの承認を得る | 7 |
| Inception(立ち上げ) | 2.1〜2.9 | 要件を詰める。既存コードの分析、要件、設計、作業単位(Unit)への分割、実行計画 | 9 |
| Construction(構築) | 3.1〜3.7 | 設計・実装・テストを、確認できる単位ごとに進める | 7 |
| Operation(運用) | 4.1〜4.7 | デプロイの仕組み、環境、監視、障害対応、改善のループを作る | 7 |
ステージ(33)
各ステージは定義ファイル(.claude/aidlc-common/stages/<フェーズ>/<ステージ>.md)で、主担当のエージェント、作る成果物、スコープに入っていれば必ず実行するか(ALWAYS、表では「必ず」)、条件付きか(CONDITIONAL)が決められています。条件付きのステージは、スコープに入っていても条件に合わなければ飛ばされます(例:既存コードの分析は、既存コードがあるときだけ)。Initialization の3つ(作業フォルダの作成・ワークスペースの判定・状態の初期化)は自動なので、残りの30を表にします。
| 番号 | ステージ | 主担当 | 実行 |
|---|---|---|---|
| Ideation(構想) | |||
| 1.1 | 意図の確認(Intent Capture & Framing) | product | 必ず |
| 1.2 | 市場調査(Market Research) | product | 条件付き |
| 1.3 | 実現性と制約(Feasibility) | architect | 条件付き |
| 1.4 | 範囲と優先順位(Scope Definition) | product | 必ず |
| 1.5 | チーム編成(Team Formation) | delivery | 条件付き |
| 1.6 | ラフなモックアップ(Rough Mockups) | design | 条件付き |
| 1.7 | 承認と引き継ぎ(Approval & Handoff) | delivery | 必ず |
| Inception(立ち上げ) | |||
| 2.1 | 既存コードの分析(Reverse Engineering) | developer | 条件付き |
| 2.2 | 開発の慣習の把握(Practices Discovery) | pipeline-deploy | 条件付き |
| 2.3 | 要件分析(Requirements Analysis) | product | 必ず |
| 2.4 | ユーザーストーリー(User Stories) | product | 条件付き |
| 2.5 | 詳細なモックアップ(Refined Mockups) | design | 条件付き |
| 2.6 | ドメイン設計(Domain Design) | architect | 条件付き |
| 2.7 | 作業単位への分割(Units Generation) | architect | 必ず |
| 2.8 | 契約(API など)の設計(Contract Design) | architect | 条件付き |
| 2.9 | 実行計画(Delivery Planning) | delivery | 必ず |
| Construction(構築) | |||
| 3.1 | 機能設計(Functional Design) | architect | 条件付き |
| 3.2 | 非機能要件(NFR Requirements) | architect | 条件付き |
| 3.3 | 非機能の設計(NFR Design) | architect | 条件付き |
| 3.4 | インフラ設計(Infrastructure Design) | aws-platform | 条件付き |
| 3.5 | コード生成(Code Generation) | developer | 必ず |
| 3.6 | ビルドとテスト(Build and Test) | quality | 必ず |
| 3.7 | CI の構築(CI Pipeline) | pipeline-deploy | 条件付き |
| Operation(運用) | |||
| 4.1 | デプロイの仕組み(Deployment Pipeline) | pipeline-deploy | 条件付き |
| 4.2 | 環境の用意(Environment Provisioning) | aws-platform | 条件付き |
| 4.3 | デプロイの実行(Deployment Execution) | pipeline-deploy | 条件付き |
| 4.4 | 監視の設定(Observability Setup) | operations | 条件付き |
| 4.5 | 障害対応と手順書(Incident Response) | operations | 条件付き |
| 4.6 | 性能の検証(Performance Validation) | quality | 条件付き |
| 4.7 | フィードバックと改善(Feedback & Optimization) | operations | 条件付き |
「主担当」はエージェント名の aidlc- と -agent を省いたものです。多くのステージには補助のエージェントも付きます(例:意図の確認は product が主担当で architect が補助)。
エージェント(14)
エージェントは、Claude Code のサブエージェント定義(.claude/agents/aidlc-*.md)として置かれます。ドキュメントの言い方では「専門エージェント11、レビュー担当2、組み立て役1」です。役割は各定義ファイルの説明から要約しました。
| エージェント | 人にたとえると | 主に担当するステージ |
|---|---|---|
| 専門エージェント(11) | ||
| product | プロダクトマネージャー | 意図の確認、市場調査、範囲、要件分析、ユーザーストーリー |
| design | UX/UI デザイナー | ラフ・詳細なモックアップ |
| delivery | エンジニアリングマネージャー | チーム編成、承認と引き継ぎ、実行計画 |
| architect | ソリューションアーキテクト | 実現性、ドメイン設計、作業単位、契約、機能設計、非機能要件と設計 |
| aws-platform | AWS のアーキテクト | インフラ設計、環境の用意 |
| compliance | 規制・コンプライアンス担当 | 実現性などの補助のみ(主担当はない) |
| devsecops | セキュリティエンジニア | 非機能要件・インフラ設計・ビルドとテストなどの補助 |
| developer | シニア開発者 | 既存コードの分析、コード生成 |
| quality | QA リード | ビルドとテスト、性能の検証 |
| pipeline-deploy | CI/CD・リリース担当 | 開発の慣習の把握、CI、デプロイの仕組みと実行 |
| operations | SRE | 監視、障害対応、改善 |
| レビュー担当(2):作らずに、成果物を読んで指摘だけする | ||
| product-lead | シニアのプロダクトリーダー | 要件・ストーリー・UX の成果物をレビュー |
| architecture-reviewer | シニアのアーキテクト | 設計・コードの成果物をレビュー |
| 組み立て役(1) | ||
| composer | 進め方の設計者 | 依頼内容から「どのステージを通るか」を組み立てて提案する |
ステージの定義には実行のしかた(mode)も書かれています。inline のステージは Claude Code 本体がそのエージェントになりきって進め、subagent のステージは別のサブエージェントとして起動されます。今回のツールでは、意図の確認・要件分析・ビルドとテストが inline、コード生成が subagent でした。レビュー担当の2つは、定義ファイルでモデルが sonnet に指定されています。
スコープ(11)
スコープは「33ステージのうち、今回どれを通るか」の組み合わせで、それぞれ詳しさ(depth:成果物にどこまで書き込むか)と、レビューや確認の手続きの既定値を持っています。ステージ数は Initialization の3つを除いた数で、新しいプロジェクトでは既存コードの分析(2.1)が飛ばされるので、さらに1つ減ります(Scopes, Depth, and Test Strategy)。
| スコープ | 向いている場面 | ステージ数 | 詳しさ |
|---|---|---|---|
| enterprise | 規制のある企業向け機能。監査の記録を完全に残す | 30(全部) | Comprehensive |
| feature | 本番アプリの新機能。全ステージを実用的な詳しさで | 30(全部) | Standard |
| workshop | 研修・ワークショップ | 23 | Standard |
| mvp | ゼロから作る最小限の製品。運用フェーズを飛ばす | 20 | Standard |
| classic | Inception と Construction だけの従来型。何も指定しないときの既定 | 15 | Standard |
| infra | インフラの変更(環境・CDK など) | 12 | Standard |
| express | 要件 → 実装 → テスト → (必要なら)デプロイの最も軽い道。設計とレビュー担当なし | 7 | Minimal |
| refactor | 動きを変えないコードの整理 | 7 | Minimal |
| security-patch | CVE・脆弱性への対応 | 7 | Minimal |
| bugfix | 決まったバグの修正とデプロイ | 6 | Minimal |
| poc | 実現できるかを素早く確かめる試作 | 5 | Minimal |
今回の実行で提案された express は「7 − 既存コードの分析 = 6ステップ」(要件分析、コード生成、ビルドとテスト、デプロイの仕組み、デプロイの実行、監視の設定)、最終的に選んだ poc は「5 − 1 = 4ステップ」(意図の確認、要件分析、コード生成、ビルドとテスト)でした。どちらも表の下のほう、軽い側のスコープです。ただし手続きの中身は違い、express はレビュー担当を呼ばず、回答の要約確認(summary confirmation)もオフ、poc はレビューが1回ずつ入り、要約確認もオンです。
スコープの選ばれ方
スコープは自分で指定もできますが(/aidlc poc 〜 など)、作りたいものを書くだけでも決まります。ドキュメントによると流れは次のとおりで、今回のログでもそのとおりに動きました。
| ドキュメントの説明 | 今回のログ |
|---|---|
| 依頼文と、各スコープの説明・キーワードをもとに、エージェントが合いそうなスコープを1つ提案する。人は「そのまま進める/別のスコープ/作業に合わせて組み立てる」から選ぶ | 「express(6ステップ、承認6回)」が提案された |
| 「組み立てる」か、合うものがないときは composer エージェントが、意図のあいまいさ・コードの不確かさ・検証の難しさ・リスク・未解決の前提の5つを見積もり、足りる最小限のステージの組み合わせを提案する。既存のスコープと一致すればそのスコープになる | 「デプロイは要らない、小さなプランに」と答えると composer が起動し、poc(4ステップ、承認4回)を提案した |
| 提案には、レビューや確認の手続きの設定も付き、承認前なら変えられる。承認するまで何も始まらない | 「Guard Policy: off」「sensors on、learnings on、summary confirmation on、plan approval off…」と表示され、承認してから始まった |
何も選ばれないときの既定は classic(AWS_AIDLC_DEFAULT_SCOPE で変更可) | aidlc config が置いた .claude/settings.json にも AWS_AIDLC_DEFAULT_SCOPE: classic が入っていた |
手順
1. インストールする
公式のインストーラーは、シェルスクリプトを1つ実行する形です。ダウンロードして中身を確認してから実行しました。スクリプトは、リリースのチェックサムと署名(GitHub の attestation)を確かめてから本体を置きます。
置き場所は、標準では本体が ~/.local/share/aidlc、コマンドが ~/.local/bin/aidlc です。今回は試すだけなので、環境変数 AIDLC_INSTALL_ROOT・AIDLC_BIN_DIR で検証用のフォルダに入れました(シェルの設定ファイルは、--profile を付けない限り書き換えられません)。
curl -fsSL -o install.sh https://github.com/awslabs/aidlc-workflows/releases/download/v2.11.4/install.sh
less install.sh # 中身を確認する
# 検証用フォルダに入れる場合(普段使いなら環境変数なしで sh install.sh --version 2.11.4)
D=$PWD/aidlc-test
AIDLC_BIN_DIR=$D/bin AIDLC_INSTALL_ROOT=$D/share/aidlc sh install.sh --version 2.11.4
実行結果(パスは省略)
Downloaded version.json
Downloaded checksums.txt
Downloaded aidlc-release.intoto.jsonl
Downloaded aidlc-darwin-x64
Downloaded aidlc-runtime-2.11.4.tar.gz
PASS installed AI-DLC 2.11.4 with all harness runtimes
Plugin marketplace for Claude Code and Codex: …/share/aidlc/plugins (add it once; updates keep it current)
Add AI-DLC to PATH for this shell:
export PATH="…/bin:$PATH"
Then run: aidlc config
2. プロジェクトに設定する(aidlc config)
作業するリポジトリで aidlc config --harness claude を実行すると、Claude Code 用の設定一式が置かれます。今回は README だけの空のリポジトリ yomu-memo で試しました。
cd yomu-memo
aidlc config --harness claude
実行結果(パスは省略)
configured …/yomu-memo for Claude Code 2.11.4; next: open Claude Code in this project (if it is already open in this folder, exit it and start it again) and run `/aidlc --doctor`
一言で終わりますが、置かれるファイルはかなり多いです。空のリポジトリで aidlc config --harness claude --dry-run を実行すると「create=398」(398ファイルを作る)と出ました。上で説明した部品は、次の場所に置かれます。
.claude/aidlc-common/stages/:33ステージの定義(フェーズごとのフォルダ).claude/agents/:14エージェントの定義.claude/scopes/:11スコープの定義.claude/skills/:/aidlc本体を含むスキル42個.claude/settings.json:フック(ツール実行前後・セッション開始時などに AI-DLC のチェックを走らせる)と、許可するコマンドの一覧aidlc/:作業の記録(質問・要件・レビュー・承認の履歴)を置くフォルダ
続けて aidlc doctor で状態を確かめます。
aidlc doctor
実行結果
AI-DLC doctor
Machine
ok all 11 checks passed
Project (.claude, Claude Code)
warn AIDLC hooks have not run in this project yet
fix: This is expected before your first Claude Code chat in this folder. …
warn Workspace records: 8 uncommitted change(s) under aidlc/ (advisory - …)
ok 44 checks passed
Framework integrity
ok all 12 checks passed
0 problems, 2 warnings.
2つの warn は「まだ Claude Code を一度も起動していない」「記録をコミットしていない」というもので、問題ではありません。設定をコミットしてから Claude Code で作業を始めると、どちらも消えて 0 problems, 0 warnings. になりました。
3. /aidlc で依頼し、スコープを決める
Claude Code で、作りたいものを普通の言葉で伝えます。
/aidlc 読んだ本を記録する小さなコマンドラインツールを作りたい。本のタイトル・著者・読み終えた日・ひとことメモを追加して、一覧で見られるようにしたい。
最初に返ってきたのは、実装ではなくスコープの提案でした。
実行結果(Claude Code の返答)
「読んだ本を記録する…」には「express」プランを使うつもりです。6 ステップあり、各ステップの終わりにあなたの承認をいただきます(承認は計 6 回)。このプランで進めますか? 別のプランを使うことも、この作業に合わせてプランを組み立てることもできます。
1. Go ahead with the "express" plan(express プランで進める)
2. Use a different plan(別のプランを使う)
3. Tailor a plan to this task(この作業に合わせてプランを組み立てる)
4. Other(その他:希望を書いてください)
express にはデプロイ側のステージ(4.1・4.3・4.4)が含まれます。手元で使うだけのツールなので、「デプロイは要らない、要件の整理・実装・テストまでの小さなプランにしてほしい」と答えました。ここで composer エージェントがサブエージェントとして起動し、poc を提案しました。
実行結果(抜粋)
手元のパソコンだけで使う新しい個人用ツールで、既存のコードはなく、失敗しても影響はほとんどありません。そのため小さな流れをおすすめします。「やりたいことの確認 → 要件の整理(使う言語や保存形式もここで決めます)→ 実装 → テストして動作確認」の順で、デプロイや CI は含めません。
プラン: poc(4 ステップ、承認 4 回)
承認すると、Initialization(0.1〜0.3)が自動で終わり、状態ファイル aidlc-state.md に「通るステージ」と「飛ばすステージ」が記録されました。
生成されたファイル(aidlc-state.md の抜粋)
- **Scope**: poc
- **Stages to Execute**: 0.1 (workspace-scaffold), 0.2 (workspace-detection), 0.3 (state-init), 1.1 (intent-capture), 2.3 (requirements-analysis), 3.5 (code-generation), 3.6 (build-and-test)
- **Depth**: Minimal
- **Test Strategy**: Minimal
以降は、どのステージも「質問 → 回答の要約の確認 → 成果物の作成 → レビュー → 人の承認」の順で進みます。
4. 意図の確認(1.1):Ideation フェーズ
主担当は product エージェントです(inline なので Claude Code 本体が担当になりきって進めます)。選択式の質問が4つ、aidlc/spaces/default/intents/<作業名>/ideation/intent-capture/ に Markdown で置かれ、チャットで答えても、ファイルに直接書き込んでもかまいません。
生成されたファイル(intent-capture-questions.md の抜粋)
## Q1. [プロダクト] このツールで一番かなえたいこと
A. 読んだ本を忘れないよう、記録を手元に残しておきたい
B. どれくらい読んだか(冊数など)を後で振り返りたい
C. 書いたひとことメモを、後で読み返したい
D. まだ決めていない(まずは作って使ってみたい)
## Q3. [プロダクト] 「できた」と言える目安
A. 1冊分を1回のコマンドで追加でき、一覧で全件を確認できる
B. A に加えて、読み終えた日の順に並んで表示される
## Q4. [プロダクト] 最初の版に含めないもの(select all that apply)
A. 登録した記録の編集・削除
B. タイトルや著者での検索・絞り込み
C. ファイルへの書き出しや、他のサービスからの取り込み
答えると要約の確認を挟んで intent-statement.md(やりたいことの整理)と stakeholder-map.md(関係者)が作られ、続いてレビュー担当の product-lead エージェントがサブエージェントとして起動し、指摘を出しました。
実行結果(レビューの指摘・抜粋)
| ID | Severity | Where | Status |
|---|---|---|---|
| R-01 | Minor | intent-statement.md > Success Metrics | New |
| R-02 | Minor | intent-statement.md > Success Metrics「一覧の並び順」 | New |
| R-03 | Minor | intent-statement.md > Problem Statement | New |
> R-02 Finding: 「読み終えた日の順」が昇順か降順か書かれていない。読み終えた日が空の場合や同じ日の本の扱いも未記載。
「読み終えた日の順」としか答えていなかったので、新しい順か古い順かが決まっていない、という指摘です。承認するときに「新しい順にして」と伝えると、次のステージに引き継がれました。
5. 要件分析(2.3):Inception フェーズ
主担当は再び product エージェント、レビューは product-lead です。言語・保存先・必須項目・同じ日の並び順を質問され、「素の JavaScript(Node.js 20 以上)」「ホームフォルダの JSON ファイル、環境変数 YOMU_MEMO_FILE で変更可」「タイトル・著者・日付は必須」「同じ日は後から追加したものを上」と答えました。できあがった requirements.md には、要件ごとに Given/When/Then 形式の受け入れ条件が付き、前のステージのレビューで決めた並び順(R-02)も反映されていました。
生成されたファイル(requirements.md の抜粋)
### FR2 記録の一覧表示
- **FR2.2** 読み終えた日が新しい順に並べる(R-02)。読み終えた日が同じ記録は、後から追加したものを上にする(Q4)。
受け入れ条件:
- Given 読み終えた日が `2026-01-10`、`2026-03-05`、`2026-02-01` の 3 件 When 一覧を表示する Then `2026-03-05`、`2026-02-01`、`2026-01-10` の順に 3 件すべて表示される
- Given 読み終えた日が同じ 2 件を A、B の順に追加済み When 一覧を表示する Then B が A より上に表示される
このステージのレビューでも「空白だけのタイトルをどう扱うか」「保存先に書き込めないときにどうするか」など4点の指摘が出ました。そのうち2点は「実装に含めて」と伝えて承認しました。
6. コード生成(3.5)とビルドとテスト(3.6):Construction フェーズ
コード生成の主担当は developer エージェントで、このステージは subagent なので別のサブエージェントとして起動しました。poc ではコードの計画の承認(plan approval)がオフなので、計画を書いたらそのまま実装に入ります。このステージが最も時間がかかりました(承認から完了まで約8分)。
実行結果(Claude Code の返答・抜粋)
# 💻 Code Generation Complete
- 読んだ本の記録ツール `yomu-memo` を作りました。素の JavaScript で書いていて、Node.js 20 以上で動き、ビルドも外部パッケージも要りません。
- 前回お願いされた 2 点も入れました。空白だけの入力はエラーにします(R-01)。書き込めないときは終了コード 1 で止まり、保存は一時ファイルに書いてから置き換えるので、既存のファイルは壊れません(R-02)。
- テストは 29 件で、すべて成功しました。書いたのに実行していないテストはありません。
コードのレビューは architecture-reviewer エージェントが担当し、「権限がなくて書けない場合のテストがない」「保存ファイルだけが読み取り専用でも、置き換えで追加が成功してしまう」など4点を指摘しました。今回は個人用ツールなので、残ったリスクとして受け入れて承認しています。
最後のビルドとテスト(3.6)は quality エージェントが主担当(inline)です。構文チェックとテストの実行、要件と実装・テストの対応表の確認を行い、レビュー担当は付きませんでした。これを承認してワークフローは完了です。
できたツールを、自分でも動かしてみました。
node bin/yomu-memo.js add --title "こころ" --author "夏目漱石" --date 2026-10-20 --memo "先生の手紙が重かった"
node bin/yomu-memo.js add --title "走れメロス" --author "太宰治" --date 2026-11-02
node bin/yomu-memo.js add --title "檸檬" --author "梶井基次郎" --date 2026-11-02 --memo "短いのに色が残る"
node bin/yomu-memo.js list
node bin/yomu-memo.js add --title " " --author "x" --date 2026-11-01
node bin/yomu-memo.js add --title "a" --author "b" --date 2026-02-30
実行結果
追加しました: 2026-10-20 『こころ』 夏目漱石 ― 先生の手紙が重かった
追加しました: 2026-11-02 『走れメロス』 太宰治
追加しました: 2026-11-02 『檸檬』 梶井基次郎 ― 短いのに色が残る
2026-11-02 『檸檬』 梶井基次郎 ― 短いのに色が残る
2026-11-02 『走れメロス』 太宰治
2026-10-20 『こころ』 夏目漱石 ― 先生の手紙が重かった
エラー: 必須項目が足りません: タイトル
エラー: 読み終えた日の形式が正しくありません: "2026-02-30"(YYYY-MM-DD 形式の実在する日付を指定してください。例: 2026-11-17)
一覧は新しい順で、同じ 11月2日の2冊は後から追加した「檸檬」が上に来ています。空白だけのタイトルや、存在しない日付もエラーになりました。質問とレビューで決めたとおりの動きです。npm test も 29件すべて成功しました。
実行結果(npm test の末尾)
ℹ tests 29
ℹ suites 0
ℹ pass 29
ℹ fail 0
今回動いたフェーズ・ステージ・エージェントをまとめると、次のとおりです。
| フェーズ | ステージ | 主担当(実行のしかた) | レビュー | 主な成果物 |
|---|---|---|---|---|
| Initialization | 0.1〜0.3 | 自動 | なし | aidlc-state.md |
| (スコープの決定) | ― | composer(subagent) | ― | プランの提案 |
| Ideation | 1.1 意図の確認 | product(inline) | product-lead | intent-statement.md ほか |
| Inception | 2.3 要件分析 | product(inline) | product-lead | requirements.md・traceability.json |
| Construction | 3.5 コード生成 | developer(subagent) | architecture-reviewer | コード5ファイル、テスト4ファイル(29件) |
| Construction | 3.6 ビルドとテスト | quality(inline) | なし | test-results.md ほか |
作業の記録は、ステージごとに次のファイルとして残りました(抜粋)。
aidlc/spaces/default/intents/261117-reading-log-cli/
├── aidlc-state.md … どのステージを通り、どれを飛ばしたか
├── ideation/intent-capture/
│ ├── intent-capture-questions.md … 質問と答え
│ ├── intent-statement.md … やりたいことの整理
│ └── reviews/review-01.md … レビューの指摘
├── inception/requirements-analysis/
│ ├── requirements.md … 要件と受け入れ条件
│ └── reviews/review-01.md
└── construction/
├── code-generation/code-summary.md … 作ったファイルと実装の判断
└── build-and-test/test-results.md … テスト結果
7. 比較:AI-DLC なしで「作って」と頼んだ場合
別の空のリポジトリで、同じ文章を /aidlc なしで Claude Code に頼みました。
| AI-DLC あり(poc) | AI-DLC なし | |
|---|---|---|
| 質問 | スコープの確認と、選択式の質問が2ステージで計8問 | なし(すぐ実装) |
| 人の返答の回数 | 11回(承認・質問への答え・確認) | 0回 |
| Claude Code の処理時間 | 合計 約19分 | 約50秒 |
| 言語 | JavaScript(質問で指定) | Python(AI が選んだ) |
| 一覧の並び | 読み終えた日が新しい順(指定) | 古い順(AI が選んだ) |
| 読み終えた日 | 必須(指定) | 省略すると今日の日付(AI が選んだ) |
| テスト | 29件 | 8件(すべて成功) |
| 決めたことの記録 | 質問・要件・レビュー・承認がファイルで残る | 最後の返答の説明だけ |
実行結果(AI-DLC なしで作られたツールの一覧表示)
# 読了日 タイトル 著者 メモ
- ---------- ---------- ---------- --------------------
1 2026-10-20 こころ 夏目漱石 先生の手紙が重かった
2 2026-11-02 走れメロス 太宰治
3 2026-11-02 檸檬 梶井基次郎 短いのに色が残る
合計 3 冊
AI-DLC なしでも、ツールとしてはきちんと動き、表の見た目はむしろ整っていました。違いはコードの出来よりも、言語・並び順・必須項目といった「決めること」を、AI が黙って決めたか、人に聞いてから決めたかにあります。
要件を固めるのは良いが、毎回だと重い
実装の前に要件を詰めてくれる点は、上の比較のとおり効いていました。一方で、小さなツールにも同じ手続きを毎回通すと、時間とやりとりが大きく増えます。今回いちばん軽い部類の poc を選んでも、次のようになりました。
| 場面 | 人の返答 | Claude Code の処理時間 |
|---|---|---|
| スコープの提案と決定(composer を含む) | 3回 | 約2分 |
| 1.1 意図の確認(質問 → 要約の確認 → レビュー → 承認) | 3回 | 約3分半 |
| 2.3 要件分析(質問 → 要約の確認 → レビュー → 承認) | 3回 | 約3分 |
| 3.5 コード生成(レビュー → 承認) | 1回 | 約8分 |
| 3.6 ビルドとテスト(→ 承認して完了) | 1回 | 約2分 |
| 合計 | 11回 | 約19分 |
(人の返答の11回には、対話なしで実行したために許可を求められた1回を含みます。時間は Claude Code が応答にかかった時間の合計で、人が考えている時間は含みません。)同じ依頼を AI-DLC なしで頼むと、約50秒・返答0回でした。
ドキュメントでも、スコープによって手続きの量は「桁違い」だとしていて、たとえば feature は新しいプロジェクトでも29ステージ・承認29回になります。重さを抑える方法として、ドキュメントには次のものが挙がっています(Scopes, Depth, and Test Strategy)。
- 小さく、内容の分かっている変更は express(既知のバグなら bugfix)から始める。express はレビュー担当を呼ばず、回答の要約確認と「次回のために覚えますか」の質問もオフです。デプロイ側のステージは、デプロイするものがなければ自動で飛ばされると説明されています。今回は express を提案されたものの、デプロイを含むと思って poc を選びましたが、レビューと要約確認がある分、poc のほうがやりとりは多くなっていました(express は今回試していません)。
- 必要なステージだけ足す。feature で全部を通すより、
/aidlc express --add functional-design 〜のように軽いスコープに1つだけ足す使い方が勧められています。 - 確認の手続きを減らす。
--summary-confirmation offで回答の要約確認を、--learnings offで学びの記録の質問を省けます。今回の11回のうち2回は要約確認でした。ただし、各ステージの質問と承認そのものはなくなりません。
それでも、ステージごとの質問と承認は残ります。1行の修正や、言語・仕様を自分がもう決めている小さな作業なら、AI-DLC を通さずに具体的に頼んだほうが速い場面が多いはずです。逆に、決めることが多い、関わる人が多い、決めた理由をあとで説明する必要がある、といった作業ほど、この手間が見合うと考えられます。
つまずきポイント
- 以前のバージョンが入っていると、古いほうが使われることがある。今回のマシンには以前入れた AI-DLC 2.9.0 があり、最初に
aidlc configしたプロジェクトは 2.9.0 の設定で作られました。aidlc doctorがProject runtime stamp: 2.9.0; selected engine: 2.11.4と警告して気づけます。今回は既存の環境を変えないよう、環境変数AIDLC_INSTALL_ROOTを検証用フォルダに向けてから設定し直しました。普段使いなら、doctor の案内どおりaidlc updateなどで1つの版にそろえるのが素直です(今回は試していません)。 - 許可していない操作があると、最初の一歩で止まる。
claude -p(対話なしの実行)で試したところ、最初のaidlc engine orchestrate next …が「This command requires approval」で実行されず、何も始まりませんでした。--allowedTools "Bash(aidlc engine:*)"を付けて続けると進みました。普段の対話画面では、ここで許可を求める確認が出ます。 - 設定したら Claude Code を起動し直す。AI-DLC はフックで動くので、Claude Code を開いたまま
aidlc configした場合は、いったん終了して起動し直す必要があります(config の出力にもそう書かれています)。 - 記録のファイル名にマシン名が入る。承認などの履歴は
audit/<マシン名>-<ID>.mdというファイルに書かれ、.gitignoreの設定上コミットされる側に入ります。公開リポジトリで使う場合は、ファイル名にマシン名が出ることを知っておいたほうがよいです。 - 最後の返答だけ英語になった。途中はずっと日本語でしたが、ワークフロー完了時のまとめだけ英語で返ってきました。
まとめ
- AI-DLC Workflows は、開発を 5フェーズ・33ステージに分け、ステージごとに 14エージェントの誰が担当しレビューするかを決め、11スコープで「今回どのステージを通るか」を選ぶ仕組みです。定義はすべて
.claude/の下の Markdown として置かれます。 - スコープは依頼文からエージェントが提案し、人が変えられます。今回は express が提案され、「デプロイ不要」と伝えると composer が poc を組み立てました。
- poc では、意図の確認(product)→ 要件分析(product)→ コード生成(developer)→ ビルドとテスト(quality)と進み、レビュー担当(product-lead・architecture-reviewer)が並び順のあいまいさや入力チェックの抜けを実装前に指摘しました。
- その代わり、小さなツールでも約19分・返答11回かかりました(AI-DLC なしは約50秒)。小さな作業では express や
--summary-confirmation offで軽くするか、AI-DLC を通さないほうが合う場面もあります。
試してみて考えたことは、記事「AI-DLC は「ある程度の規模」の開発で使いたい」に書きました。