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の最小構成です。
- スターターキット:
- 開発ドキュメント運用の無料診断: