進化：規約と検証の継続的イテレーション
序章ではharnessの2つの原則、closed-loop controlと持続的進化を定義しました。前の2章ではclosed-loop controlを確立し、規約で意図を定義し、検証で実行結果を確認しました。しかし、2つ目の原則にはまだ踏み込んでいません。
コードは完成した瞬間が終わりではなく、むしろ始まりです。リリース後にはユーザーフィードバックが届き、プロダクト要件が変わり、機能の追加や修正が発生します。最初のバージョンではspecとテストがうまく機能していても、次の要件が来たらどうすればよいのでしょうか。
直感的なアプローチは2つあり、どちらにも問題があります。1つ目はVibe Codingに戻ること、つまりspecを飛ばしてAgentに直接新しい要件を伝える方法です。前の2章で説明した通り、これはうまくいきません。注意力の減衰、意図の喪失、検証のアンカー消失など、すべての問題が再発します。
2つ目はすべてのドキュメントを手動で更新すること、つまり新しい要件の影響をspec、テスト、project-contextに一つずつ反映する方法です。方向性は正しいのですが、specを丁寧に作成していればドキュメント量は膨大になり、機能同士が絡み合っているため、1つのビジネスルールを変更すると3つのモジュールのテストと2つのspecの制約条件に影響する可能性があります。手動メンテナンスのコストはプロジェクト規模とともに急速に増大します。
この章が扱うのは、harnessの2つ目の原則です。閉ループをプロジェクトとともに進化させ、最初のイテレーションで腐敗が始まるのを防ぐ方法を解説します。
なぜspecは必ず陳腐化するのか
Specの陳腐化は怠慢ではなく、構造的な必然です。閉ループの参照基準はspecであり、すべての検証アクションはspecをアンカーとしています。Specが正しければ、閉ループは正しいアウトプットを保証できます。しかしspec自体は自動的に更新されません。
序章でAgentの記憶蓄積なしという特性を議論した際に、この点をすでに指摘しました。Agentのために構築した外部知識体系（規約、テスト、プロセスドキュメント）は、人間が本来持っている業務知識やプロジェクトの記憶を代替するものです。しかし人間の頭の中の知識はプロジェクトの進化とともに自動で更新されるのに対し、ドキュメントは更新されません。モジュールをリファクタリングすれば、そのモジュールに対する理解は同時に更新されます。しかしドキュメントはリファクタリング前のままです。
イテレーションのたびに、specとコードの間にドリフトが生まれます。新機能がシステムの振る舞いを変えても、specはそれを知りません。旧機能のテストは、もう存在しない前提を検証し続けています。数回のイテレーションを重ねると、specとコードの距離はますます広がり、閉ループは保護機能を失うのではなく、誤った目標を保護するようになります。序章で警告したシナリオはまさにこうして発生します。偏差が閉ループの保護のもとで制度化されるのです。
ドキュメントをコードとともに進化させるという課題は、AI時代に新たに生まれたものではありません。従来のソフトウェアエンジニアリングでも数十年前から直面しており、成熟した方法論が存在します。ではこれらの方法論をそのまま持ち込めるのでしょうか。
アジャイルの原則は正しいが、粒度が合わない
アジャイル方法論のイテレーション原則はspecメンテナンスに直接適用できます。小さなステップでのイテレーション、継続的なフィードバック、変化の受容です。しかしアジャイルの実行粒度は人間のチーム向けに調整されており、AI開発にそのまま持ち込むと深刻な効率の逆転が発生します。
BMADフレームワークは、現在のAI開発コミュニティで最も完全なアジャイルの移植です。epicをstoryに分解し、各storyに5種類以上のドキュメントを用意し、12のagent personaが分業協力し、各storyが完全な承認ゲートを通過します。この仕組みにより、すべてのステップにドキュメントがあり、すべてのステップが審査されます。しかし1つのstoryは人間の開発者の数日分の作業量に対応しており、この規模の作業に完全なプロセスを適用するのは、人間のチームではコストとリターンが釣り合います。
Agentの実行単位はそれよりはるかに大きいです。規約の章で確立したcontext容量の概念がこのミスマッチを説明します。1回のAgent sessionが効果的に処理できる情報量は、従来の複数のstory分の作業量をカバーできます。私たちのサンプルプロジェクトAILock-Stepでは、1つのfeatureに完全なspec、task list、checklist、実装、検証が含まれており、規模としてはBMADの複数のstoryに相当します。story単位の作業すべてに完全なアジャイルプロセスを適用すると、プロセス管理に費やす労力がAgentの実行で節約した時間をかえって上回ります。実際の使用では、この効率の逆転は明らかです。数文で説明できる要件が、完全なアジャイルプロセスを通すと丸一日かかることがあります。
根本原因は、実行単位のサイズが変わったのにプロセスの粒度がそれに追随していないことです。アジャイルのイテレーション管理原則は依然として有効であり、再調整が必要なのは各ステップの大きさです。
コードと同じようにドキュメントを管理する
featureを単位としてイテレーションし、各feature内部でspec → implement → verifyの完全な閉ループを実行します。残る問題は、feature間のドキュメントをどう管理するかです。イテレーションのたびに同じspecファイル群を修正し、変更履歴の追跡が必要になり、不整合の検出が必要になります。これらの課題はコード管理が直面する課題と構造的に同じです。コードはマージ後にテストを実行し、specもマージ後に検証を実行します。コードにはバージョン履歴があり、specにもアーカイブが必要です。コード開発前に最新版をpullするように、spec開発前にも一貫性チェックが必要です。
規約の章のOKR事例の続きとして、このフローを見ていきます。
前提状態
最初のfeature（OKR基本CRUD）が完了しています。メインspecには3つのサブ機能（目標管理、KR管理、四半期総覧）、5つのビジネスルール（BR-001からBR-005）、6つのAPIエンドポイントが含まれています。Out of Scopeリストには8つの機能が明示的に除外されており、そのうち1つが「目標アラインメント」です。
プロダクト側から次の要件が来ました。次のバージョンで部門間のOKRアラインメントをサポートし、部門責任者が自部門の目標を上位部門の目標に関連付けられるようにする。これはまさに以前明示的に除外した機能です。
changeパッケージの作成
各変更はユーザーストーリーから受入条件まですべての階層を完全にカバーする、自己完結型のfeatureパッケージです。コードレベルのdiffではなく、specレベルの完全な記述です。
changes/cross-dept-alignment/
├── story.md # ユーザーストーリー
├── design.md # アーキテクチャ影響分析
├── delta-spec.md # メインspecへの増分変更
├── tasks.md # タスク分解
└── checklist.md # 受入チェック項目
story.mdはユーザー価値を記述します。部門責任者が四半期OKRを設定する際に、自部門の目標を上位部門の目標に関連付けられるようにし、組織が会社レベルから部門レベルへの目標アラインメント関係を追跡できるようにします。
design.mdはアーキテクチャへの影響を分析します。alignmentモジュールの新規追加（アラインメント関係テーブル、CRUDインターフェース）、既存の目標クエリインターフェースの修正（アラインメント状態フィールドの返却）、目標詳細ページの修正（アラインメント関係の表示）です。
delta-spec.mdが中核です。ADDED、MODIFIED、REMOVEDの3つのブロックでメインspecへの増分変更を記述し、各requirementに完全なacceptance scenarioを付与します。
## ADDED Requirements
### Feature: 目標アラインメント (Objective Alignment)
**User Story**: As a 部門責任者, I want to 部門目標を上位部門の目標に関連付ける
so that 組織が会社から部門への目標アラインメント関係を追跡できる。
**Acceptance Criteria**:
- [ ] 目標詳細ページに「アラインメント先」フィールドを表示し、上位部門の目標を選択可能にする
- [ ] アラインメント関係が確立された後、四半期総覧ページにアラインメントチェーンを表示する
- [ ] 部門責任者ロールのみがアラインメント関係を設定可能とする
**Business Rules**:
| # | Rule | Condition | Outcome |
|---|------|-----------|---------|
| BR-006 | アラインメント方向 | アラインメント関係設定時 | 上位部門の目標にのみアラインメント可能、同レベルや逆方向は不可 |
| BR-007 | アラインメント任意 | 目標作成時 | アラインメント関係は必須項目ではない |
**API Contract**:
| Endpoint | Method | URL |
|----------|--------|-----|
| アラインメント設定 | POST | /system/okrAlignment |
| アラインメントチェーン照会 | GET | /system/okrAlignment/chain |
## MODIFIED Requirements
### Feature: 目標管理 (Objective Management)
**変更説明**: 目標クエリインターフェースにalignedToフィールドを追加し、当該目標がアラインメントしている上位目標の情報を返却する。
目標一覧ページに「アラインメント状態」列を追加する（アラインメント済み/未アラインメント）。
### Out of Scope
**変更説明**: 「目標アラインメント」の項目を削除する。この機能は今回の開発範囲に含まれる。
## UNCHANGED (明示的宣言)
BR-002（各目標に最大5つのKR）、BR-003（完成率の範囲は0-100）等の既存ビジネスルールは
今回の変更による影響を受けない。
UNCHANGEDブロックは序章で警告したシナリオを防ぐための重要なメカニズムです。「何が変わらないか」を明示的に宣言しなければ、Agentは新機能の実装時に既存のルールを意図せず上書きしてしまう可能性があります。明示的な宣言により、保持すべきルールが暗黙の前提から監査可能なドキュメントへと変わります。
作成時の検証
changeパッケージはコーディングの前に検証を実行します。これが最もコストの低い遮断ポイントであり、問題を発見してもドキュメントの修正だけで済みます。
自動化検証は一貫性レベルの問題をチェックします。delta-specでMODIFIEDとなっている各requirementがメインspecに存在するか。新規追加のAPIエンドポイントと既存エンドポイントにパスの衝突がないか。新規追加のBR-006、BR-007と既存のBR-001からBR-005の間に矛盾がないか。design.mdが宣言した影響範囲のモジュールが、delta-specのすべての変更に関係するモジュールをカバーしているか。
人による審査は意図レベルに焦点を当てます。ユーザーストーリーはプロダクトの意図を正確に反映しているか。アラインメント方向のビジネスルール（上位へのみアラインメント可能）は正しいか。MODIFIEDの範囲は完全か、影響を受けるモジュールの漏れはないか。
審査通過後、changeパッケージはAgentの実行入力となり、ここから規約の章と検証の章で確立した閉ループに入ります。
実行の閉ループ
Agentはdelta-specとtasksに基づいて機能を実装し、checklistとacceptance scenarioに基づいて検証します。この段階は前の2章とまったく同じであり、新しい方法は必要ありません。
マージとマージ後の検証
実装と検証が完了した後、deltaをメインspecにマージします。マージ自体はrequirement粒度の操作です。ADDEDの内容はメインspecの対応モジュールに追加し、MODIFIEDは元のrequirementの内容全体を置き換え、REMOVEDは削除します（ここではOut of Scopeから「目標アラインメント」を削除）。
マージ後にドキュメントレベルの検証を1回実行します。検証の章のテスト基盤と同じ考え方です。マージ後のメインspecに内部矛盾がないかをチェックします。新規追加のアラインメント権限モデル（部門責任者のみ）と既存の目標管理権限（管理者）が衝突していないか。新規追加のアラインメントクエリインターフェースの返却値フォーマットが既存インターフェースと一致しているか。既存のBR-001からBR-005がマージ後も完全に存在しているか。
マージ後にproject-contextを更新します。モジュール一覧にalignmentモジュールを追加し、API一覧に2つのエンドポイントを追加し、Out of Scopeリストから実装済みの項目を削除します。
アーカイブ
changeパッケージ全体をarchive/2026-04-cross-dept-alignment/に移動します。アーカイブ内容には、元のユーザーストーリー、アーキテクチャ分析、delta-spec、task list、checklist、実行結果が含まれます。3か月後にアラインメント機能に問題が発生した場合、このアーカイブが完全な意思決定チェーンを提供します。なぜ実装したか、どう設計したか、どの条件を検証したかです。
アーカイブの原則は、追跡可能であるが現在のワークスペースを汚染しないことです。現在のAgentはメインspecと作業中のfeatureのドキュメントのみを読み込み、過去のアーカイブに埋もれることはありません。
次のfeature前の同期検出
3つ目のfeatureが来ました（例えばOKRスコアリング機能）。開始前にAgentはまずproject-contextを読んで現在のシステム状態を把握し、次にメインspecと照合して一貫性をチェックします。
changeパッケージのフローを厳格に運用しても、不整合が生じる可能性は残ります。実装過程でのAgentの残留ドリフト（検証の章で議論した通り、テストとreviewが大部分を遮断しますがすべてではありません）、またはdeltaマージ時に関連モジュールの更新が漏れるケースです。同期検出はこれらの残留問題のセーフティネットです。
同期検出と作成時検証は閉ループを形成します。作成時検証はchangeパッケージとメインspecの一貫性を検証し、同期検出はメインspecとコードの一貫性を検証します。2つのゲートがspecライフサイクルの両端をカバーします。検出結果には人の判断が必要です。差異が意図的な進化なのか、意図しない漏れなのかを見極める必要があります。
changeパッケージのフローは、ドキュメントの進化を「忘れずに更新する」から再現可能なエンジニアリングアクションに変えます。各変更にはspecレベルの完全な記述があり、2つの検証ゲート（作成時とマージ後）があり、アーカイブが意思決定チェーンを保存し、同期検出が残留ドリフトのセーフティネットとなります。序章が定義した2つ目の原則、持続的進化は、ここで具体的な運用方法を得ました。
Harness Engineering Playbook · AgentsZone Community