AIが参照する「仕様」が一つに決まらない

AIコーディングエージェントへ「この仕様で実装して」と依頼しても、参照先が議事録、表計算、チャット、Wikiへ分散していると、正しい文脈を安定して渡せません。

かといって、情報を巨大なMarkdownへ集約すると、更新箇所が分からなくなります。必要なのは一枚岩の仕様書ではなく、「この種類の情報はここが正しい」と言える配置です。

編集するファイルと、見るためのファイルを分ける

最初に決めたいのはファイル形式より更新元です。たとえばレビュー用HTMLが見やすくても、HTMLを直接直し始めるとMarkdownとの二重管理になります。

種類	例	更新方法
要件の正本	`docs/requirements/REQ-*.md`	人間がレビューして更新
設計判断の正本	`docs/adr/ADR-*.md`	判断時に追記
APIの正本	`openapi/*.yaml`	API変更と同じPRで更新
未決事項	`docs/open-items.md`	担当・期限・状態を更新
閲覧用HTML	`dist/review/*.html`	正本から再生成
AI検索用索引	`knowledge/*.yaml`	正本から抽出して検証

HTMLや索引は捨てられる生成物にしておきます。直すのは正本、表示が必要なら再生成。この順序を崩さないだけでも、AIが古い記述を拾う事故は減ります。

小さく始めるならこの程度

repository/
├── AGENTS.md
├── docs/
│   ├── requirements/
│   │   ├── REQ-001.md
│   │   └── REQ-002.md
│   ├── adr/
│   │   └── ADR-001.md
│   ├── testing/
│   │   └── TST-001.md
│   └── open-items.md
├── openapi/
│   └── root.yaml
├── knowledge/
│   ├── requirements.yaml
│   └── traceability.yaml
└── scripts/
    ├── build-review-html.sh
    └── validate-docs.sh

AGENTS.md に規約本文を詰め込むと、すぐに長くなります。ここは入口に限定し、コマンド、参照先、完了条件だけを置きます。

# AGENTS.md

## Commands
- Test: `npm test`
- Lint: `npm run lint`
- Docs: `./scripts/validate-docs.sh`

## Rules
- 要件正本は `docs/requirements/REQ-*.md`
- API正本は `openapi/`
- 未決事項を推測で確定しない
- 仕様変更と関連文書を同じPRで更新する

## Done
- テストとLintが成功している
- 関連する要件、ADR、OpenAPI、テスト文書が更新されている

ファイル名とは別に要件IDを持つ

ファイル名と見出しだけでは、変更時の追跡が不安定です。要件に変更されない識別子を付けます。

---
id: REQ-042
status: approved
owner: product-owner
---

# CSVエクスポート

## 目的

検索結果をCSVとして取得できるようにする。

## 受入条件

- UTF-8で出力される
- 現在の検索条件が反映される
- 権限のない項目は含まれない

## 対象外

- 定期実行
- 100万件を超える出力

## 未決事項

- 最大出力件数は確認待ち

実装内容より、対象外 と 未決事項 の方が効くことがあります。書かれていない部分をAIが自然に補ってしまうためです。「最大件数は確認待ち」と書いてあれば、勝手な上限値を仕様に混ぜにくくなります。

変更漏れはマトリクスで拾う

要件変更時に確認する文書を、簡単なマトリクスとして定義します。

変更	必須更新	影響確認
受入条件	REQ、テスト設計	API、画面仕様
API項目	OpenAPI、生成型	REQ、実装、テスト
設計判断	ADR	REQ、運用手順
用語	用語集、REQ	UI文言、API名
未決事項の解消	REQ、open-items	ADR、テスト

この表はAIにも渡せます。差分を見て更新候補を挙げてもらい、担当者が要否を決めます。「関連しそうな全文書を探して」と頼むより結果を評価しやすくなります。

内容以前の壊れ方はCIで止める

文書にも機械検査を追加できます。

#!/usr/bin/env bash
set -euo pipefail

npx prettier --check "docs/**/*.md"
npx @redocly/cli lint openapi/root.yaml
python scripts/check_duplicate_ids.py docs/requirements
python scripts/check_local_links.py docs
python scripts/check_traceability.py

内容の妥当性はレビューが必要ですが、次のような構造上の不備はスクリプトで拾えます。

要件IDの重複
ローカルリンク切れ
OpenAPIの構文と参照
承認済み要件に担当者があるか
要件とテストの対応漏れ
未決事項が消えずに追跡されているか

YAML索引に本文を書かない

AIが検索しやすいように、要件の要約をYAMLへ抽出する方法があります。

requirements:
  - id: REQ-042
    title: CSVエクスポート
    status: approved
    source_refs:
      - path: docs/requirements/REQ-042.md
    related:
      tests:
        - TST-018

索引は検索と欠落検査には便利です。ただし要約を詳しくしすぎると、こちらがもう一つの仕様書になります。source_refs から正本へ戻れることを優先し、本文はMarkdown側に残します。

導入順

既存資料を全部移行する必要はありません。変更が入る要件からIDを付ける、未決事項を一か所へ集める、AGENTS.md に正本の場所を書く、リンク切れをCIで見る。この4点なら、今の開発フローを大きく変えずに試せます。

15分で試せる最小スターター

この記事の構成をそのまま試せるテンプレートを準備しています。要件、ADR、OpenAPI、テスト、未決事項、トレーサビリティ、AGENTS.mdの最小構成です。

スターターキット:
開発ドキュメント運用の無料診断: