実践：AILock-Step Feature Workflow
前のセクションで規約の方法論フレームワークを確立しました。情報の階層化、三つの次元、クロスバリデーション、イテレーションサイクルです。このセクションでは、具体的なワークフローシステムを使って、これらの概念が実践でどう具現化されるかを示します。
AILock-Step Feature Workflowは、私たちのコミュニティメンバーが開発したClaude Codeベースのドキュメント駆動開発フレームワークです。skill（slash command）を使ってfeatureのライフサイクル全体を編成し、要件の投入からコードの納品までをカバーします。このシステムはすでにAI agentプラットフォームのプロジェクトで40以上のfeatureを処理してきました。完全なソースコードはGitHub上で公開されています。
ここで示すのは一つの実装であり、唯一の実装ではありません。重要なのはディレクトリ構造や設定フォーマットをそのまま真似ることではなく、前述のprincipleがどのように実行可能なワークフローに変換されているかを観察することです。
情報階層化の具現化
前述の通り、情報にはvision、アーキテクチャ、feature、taskの四つの階層があり、異なる階層は異なる速度で変化し適用範囲も異なるため、異なるドキュメントで担い、異なる戦略でロードすべきです。AILock-Stepは三種類のドキュメントでこの階層化を実現しています。
CLAUDE.mdは階層をまたぐ強制的な制約を担います。 これはClaude Codeが起動するたびに自動的にロードされるファイルです。その内容はプロジェクトのライフサイクル全体を通じてほとんど変わらないハードルールです。TypeScriptの厳格モードを使用すること、データベースの直接操作を禁止すること、commitメッセージのフォーマット要件、コード内でのハードコーディングの禁止。これらの制約は特定の階層に属するのではなく、すべての階層を横断し、すべてのタスクが遵守しなければなりません。内容が安定しており毎回必要なので、自動ロードの位置に配置されています。
project-context.mdは高層の情報を担います。 これは前述のvision層とアーキテクチャ層に対応します。その内容は以下の通りです。
Technology Stack（技術スタック表）
| Category | Technology | Version | Notes |
| Frontend | React | 18.x | ... |
| Backend | Node.js | 20.x | ... |
| Database | PostgreSQL | 15 | ... |
Directory Structure（ディレクトリ構造）
src/
├── components/ # 共有コンポーネント
├── pages/ # ページルーティング
├── services/ # APIサービス
├── hooks/ # カスタムhooks
└── utils/ # ユーティリティ関数
Critical Rules（重要なルール）
Must Follow:
- すべてのAPIレスポンスは統一されたResponseWrapperフォーマットを使用する
- データベース操作はORM層を経由すること、生SQLは禁止
Must Avoid:
- コンポーネント内でデータベースを直接呼び出さないこと
- utils/にビジネスロジックを配置しないこと
Code Patterns（コードパターン）
命名規約、importスタイル、エラーハンドリングパターン
Testing Patterns（テストパターン）
ユニットテストの配置場所、命名規則、E2Eフレームワーク
Recent Changes（最近の変更）
直近のfeatureの変更と影響
このドキュメントには厳格な制限があります。200行以内です。この制限は前述のcontext制約に直接由来しています。プロジェクトコンテキストは毎回Agentのcontextにロードされるため、長すぎるとspecやコードのための空間を圧迫します。200行は中規模プロジェクトの重要な情報を収容するのに十分ですが、インデックスレベルの内容のみを含め、実装の詳細をすべて書き込まないことが求められます。
このドキュメントは一度書いて終わりではありません。featureが完了するたびに、新しい技術スタックのコンポーネント、新しいコードパターン、新しいディレクトリ構造が導入された場合、project-context.mdは差分更新されます。ドキュメント末尾にはUpdate Logがあり、各更新の内容と日付を記録しています。これは前述の「高層の情報はまれに変化する」に対応しています。
各featureには独自の三つのドキュメントがあります。spec.md、task.md、checklist.md。 これはfeature層とtask層に対応します。これらのドキュメントはAgentがそのfeatureを実行する時にのみロードされ、完了後にアーカイブされます。
この三層構造のロード戦略は明確です。CLAUDE.mdとproject-context.mdは毎回ロードされます（すべてのタスクが必要とする背景情報です）。featureドキュメントは対応するfeatureの実行時にのみロードされます（タスクレベルの情報であり、無関係なfeatureのドキュメントをロードするとノイズを生むだけです）。
Specテンプレートにおける三つの次元の体現
AILock-Stepのspec.mdテンプレートは、前述の三つの次元（意図、受入、制約）を具体的なフィールドに変換しています。
意図の次元は三箇所に体現されています。「要件記述」フィールドは解決すべき問題を自然言語で記述します。「ユーザー価値ポイント」フィールドはこのfeatureに含まれる独立したユーザー価値を列挙し、Agentの分析により生成されます。「ユーザーストーリー」フィールドは標準フォーマットで表現します。[役割]として、[目標]をしたい。[価値]のためだ。
受入の次元はGherkinシナリオに体現されています。テンプレートは各ユーザー価値ポイントに対して少なくとも一つの正常パスシナリオと一つの異常シナリオの生成を要求します。たとえばユーザー登録機能には二つのシナリオがあります。
# シナリオ 1: 登録成功
Given ユーザーが登録ページにいる
When ユーザーが有効なユーザー名 "testuser" とパスワード "Test123!" を入力する
And 登録ボタンをクリックする
Then アカウントが正常に作成される
And ウェルカムメッセージが表示される
# シナリオ 2: ユーザー名の重複
Given ユーザーが登録ページにいる
And ユーザー名 "testuser" がすでに存在する
When ユーザーがユーザー名 "testuser" とパスワード "Test123!" を入力する
And 登録ボタンをクリックする
Then エラーメッセージ "ユーザー名はすでに存在します" が表示される
これらのシナリオは前述の受入の次元そのものです。各シナリオはfeatureの振る舞いが意図と一致しているかを検証しています。正常パスは「すべきことをしたか」を検証し、異常パスは「問題が発生した際の振る舞いが妥当か」を検証します。
制約の次元は「コンテキスト分析」フィールドに体現されており、三つの内容を含みます。参照すべき既存コード（プロジェクト内の再利用可能な既存モジュール）、関連ドキュメント（設計ドキュメント、APIドキュメント）、関連する過去の要件（以前実装した類似機能）。このフィールドはAgentに変更の背景と境界を伝えます。何が利用可能か、何がすでに実装済みか、何に触れるべきでないか。
テンプレートには「技術方針」フィールドもあり、「開発過程で記入」と注記されています。このフィールドはspec生成段階では空であり、Agentが実際の開発時に具体的な実装方針を記入します。これは前述の階層化原則における「低層の情報は必要な時にのみ生成する」という考え方に対応しています。
クロスバリデーションの具現化
spec、task list、checklistの三つのドキュメントの分担は、前述のクロスバリデーションに直接対応しています。
specは一回目の理解です。要件から出発し、意図の記述、受入シナリオ、制約の分析を生成します。
task listは二回目の理解です。specから出発し、具体的な実行ステップに分解します。テンプレートはモジュール/コンポーネント、APIインターフェース、フロントエンドページ、その他の四つのカテゴリでタスク項目を整理し、各タスク項目はチェックボックスです。末尾に進捗記録表があり、Agentが実行過程で更新します。
checklistは三回目の理解です。「どうやるか」から「正しくできたかどうかをどう判断するか」を逆算します。テンプレートは五つの確認カテゴリを含みます。開発完了（すべてのタスクが完了したか、境界ケースは処理されたか）。コード品質（スタイルは規約に準拠しているか、コードの悪臭はないか）。テスト（ユニットテストは作成されたか、通過しているか）。ドキュメント（specの技術方針は記入されたか、関連ドキュメントは更新されたか）。コミット準備（変更はステージングされたか、commitメッセージは準備できたか）。
checklistにspecで言及されていない確認項目が現れた場合、Agentがtask段階でspecがカバーしていない内容を導入したことを意味します。checklistのある項目がspecの記述と矛盾している場合、意図が伝達過程でずれたことを意味します。三つのドキュメント間の一貫性がアラインメントの証拠です。
分割の実際のプロセス
/new-featureというskillが、一つの要件に三つ以上のユーザー価値ポイントが含まれていると分析した場合、システムは分割を提案します。このプロセスはテストで完全に記録されています。
要件を入力します。「ユーザー認証システム。登録、ログイン、権限管理をサポートする。」Agentは三つの独立したユーザー価値ポイントを分析します。ユーザー登録（新規アカウントの作成）、ユーザーログイン（システムへのアクセス）、権限管理（アクセス権限の制御）。ユーザー価値ポイントが3であるため、分割の提案がトリガーされます。
システムが分割方針を提示します。元の要件が三つのサブfeatureに分割されます。feat-auth-register（ユーザー登録。依存なし）、feat-auth-login（ユーザーログイン。feat-auth-registerに依存）、feat-auth-permission（権限管理。feat-auth-loginに依存）。依存関係はシステムが自動的に設定します。
分割を確認すると、システムは各サブfeatureに独立したディレクトリを作成し、各ディレクトリに独自のspec.md、task.md、checklist.mdを含めます。同時にqueue.yamlに三つのサブfeatureのステータス、優先度、依存関係を記録し、全体の進捗を追跡する親要件のエントリも作成します。
実行エンジンはfeatureの開始前にその依存関係が完了しているかを確認します。feat-auth-registerがまだ完了していない状態でfeat-auth-loginを開始しようとすると、システムが「依存関係が未完了」と警告して阻止します。
各サブfeatureは同じイテレーションサイクルに入ります。Agentがspecを展開し、クロスバリデーションを行い、人間がユーザーストーリーをレビューし、収束したら実行します。
一つの要件のウォークスルー
TODO: ここには実際に完了したfeatureのケーススタディが必要です。以下の内容を示す必要があります。記入済みのspec（実際のユーザーストーリーとGherkinシナリオを含む）、対応するtask list（実際のタスク項目を含む）、対応するchecklist（実際の確認項目を含む）、およびイテレーション過程で問題を発見し修正した記録。実際のプロジェクトから素材を取得した後に補充します。
人間の実際の時間投入
ワークフロー全体を通して、開発者が実際に時間を費やすのは一箇所に集中しています。spec生成後のユーザーストーリーとGherkinシナリオのレビューです。Agentが理解した「この機能は誰のどんな問題を解決するのか」が自分の意図と一致しているかを確認します。一致していれば、後続のtask分割、checklist生成、コード実装はAgentに任せます。
これは前述の「イテレーションにおける人間の役割」を裏付けています。意図アラインメントは人間にしかできず、一貫性チェックはAgentに任せられます。開発者の注意力は最もROIの高いチェックポイント（上位層の方向性）に集中し、下位層の一貫性はAgentのクロスバリデーションがカバーします。
完全な実装のソースコードはGitHub上で公開されています（AILock-Step Feature Workflow）。ここで示したのは一つの実装方針に過ぎません。読者が同じツールや同じディレクトリ構造を使う必要はありません。重要なのはその背後にあるprincipleを理解することです。情報を階層的に管理すること、各階層で三つの次元を使って明確に表現すること、クロスバリデーションで階層間のドリフトを検出すること、収束するまでイテレーションすること。どのツールでこれらのprincipleを実装するかは、あなたのプロジェクトとチーム次第です。
本章のまとめ
規約の本質は意図アラインメントです。Vibe Codingの失敗は、意図が対話の中に存在し、対話が膨張し、矛盾し、内容を喪失する媒体であることに起因しています。Agentの有限なcontextと不均一な注意力が、意図アラインメントをコミュニケーションの問題から工学的な問題に変えています。
この工学的問題の解法は二つの基盤の上に成り立っています。情報には自然な階層があり、異なる階層は異なる速度で変化し適用範囲も異なるため、構造化された方法で異なるドキュメントに分割する必要があります。高層は永続的にロードし、タスク層は必要に応じてロードします。各階層では三つの次元（意図、受入、制約）で明確に表現し、中でも受入の次元の核心的な役割は、現在の階層と上位層のアラインメントが失われていないかを検出することです。
specはイテレーションで練り上げるものです。意図を書き、Agentが展開し、クロスバリデーションが問題を露出させ、修正または分割し、収束するまで再検証します。このサイクルの中で、意図が正しくアラインされているかを判断できるのは人間だけです。なぜなら意図は人間の頭の中にのみ存在するからです。サイクルをどの程度の重さで回すかは、間違えた場合のやり直しコストの大きさによって決まります。
規約は「何をするか」の問題を解決します。しかしspecが正しくてもコードが正しいとは限りません。Agentが出力したコードが実際に正しいかどうか、どう検証するかは、次の章で展開します。