マスタ宣言
本ガイドは、受託開発における工程別ドキュメント運用の推奨モデルです。正本を Git 上の Markdown / OpenAPI / ADR に集約し、レビュー用 HTML・ゲート判定・トレーサビリティで品質と速度を両立します。詳細は各章、配布は本章と第0章を PDF 化する想定です。
成果物マップ（全工程）
提案 baseline-agreements.md · 提案サマリー.html
要件 REQ-xxx.md · review/*.html · glossary
設計 design.md · adr/ADR-xxx.md · C4.mmd
API openapi/**/*.yaml · bundled · Redoc
実装 AGENTS.md · docs/sop/ · DESIGN.md · .agents/skills/ · PR
テスト TestDesignDoc.md · traceability.csv
運用 runbooks/*.md · CHANGELOG
PM open-items.md · gate-decision.md
索引 knowledge/*.yaml · schemas/ · reports/（MD 正本の構造化索引）
変更時の同時更新マトリクス
| 変更イベント | 必ず更新するもの | 確認するもの | ゲート影響 |
|---|---|---|---|
| 要件追加・変更 | REQ-xxx.md, open-items.md, レビュー用HTML | ADR, OpenAPI, TestDesignDoc | 基本設計着手可否 |
| 用語変更 | glossary, REQ, レビュー用HTML | 画面文言、帳票、API名 | 合意再確認 |
| API仕様変更 | OpenAPI YAML, 生成型, API HTML | 実装、テスト、外部IF資料 | 破壊的変更なら承認必須 |
| 設計判断変更 | ADR, design.md | REQ, OpenAPI, テスト観点 | 技術責任者レビュー |
| テスト観点変更 | TestDesignDoc, traceability | REQ, 障害票, 受入条件 | QAレビュー |
| 障害・本番問い合わせ | runbook, CHANGELOG, ADR必要性 | TestDesignDoc 観点, REQ | 運用引継ぎ確認 |
| AGENTS.md変更 | AGENTS.md | 関連スキル、README | 新チャット・再読込推奨 |
| SOP / スキル変更 | docs/sop/*.md または .agents/skills/ | AGENTS.md Rules、CI | 新チャット推奨 |
| REQ / 未決更新 | REQ-xxx.md · open-items.md | starter_kit/knowledge/*.yaml · traceability | ゲート · AI 索引整合 |
変更は単一ファイルで完結しない。変更イベントごとに同時更新対象を決め、差分レビューで漏れを防ぐ。
ロール別最短ルート
| 立場 | ルート |
|---|---|
| 経営 | 00 → 07 → 08（本章） |
| PM | 00 → 07。ゲート前は 01・05・06 |
| SE | 01 → 02 → 03 → 05。引き継ぎ 06 |
| PG | 03 → 04 |
週次 PM チェックリスト
- 未決事項を open-items から更新
- 要件・議事録の drift チェック（AI支援可）
- レビュー用 HTML の差分を共有（必要時のみ）
- ゲート判定：基本設計着手可否
- 障害後は Runbook / ADR / CHANGELOG の反映確認と TestDesignDoc 観点への還流確認（第5・6章）
- AI運用ログの理由分類を確認し、改善候補を正本・ADR・rules・FAQ・承認ルールへ反映
AI運用ログから正本へ改善を還流する
Human Gateで止めた理由を週次レビューし、改善先を正本・ADR・rules・FAQ・承認ルールへ戻す。 着想元は Qiita: AI運用ログを週次レビューし、FAQ・CRM・承認ルールへ戻すGAS実装。GASは必須ではなく、PoC初期は手動記録でよい。
Human Gate / AI利用 → 理由を4項目で記録 → 週次で分類・件数確認 → 改善候補を人間が選択 → Git正本 / ADR / rules / FAQ / 承認ルールへ反映 → 次週のログで効果確認
| 項目 | 用途 | 例 |
|---|---|---|
gate | どの確認点で止まったか | requirements / PR / release |
human_review_reason | 人間へ戻した理由の分類 | missing_context / low_confidence / approval_rule |
blocked_reason | 止まった事実を短く記録 | 対象外範囲が未確定 |
improvement_target | 改善候補 | REQ / FAQ / CRM / ADR / rule / template |
正本境界: ログと確定した改善はGit上のMarkdown/YAMLへ置く。スプレッドシートは一時集計に限り、顧客名・問い合わせ本文・機密情報を保存しない。
自動化条件: 最初の1〜2週間は手動。分類が安定してから集計だけを自動化する。改善チケットの自動起票や未入力による強制ブロックはPoC段階では行わない。
RACI / 承認マトリクス
| 判断対象 | R: 実行 | A: 承認責任 | C: 相談 | I: 共有 |
|---|---|---|---|---|
| 要件正本の更新 | SE / PM | PM | 依頼者側担当、設計担当 | PG / QA |
| レビュー用HTMLの配布 | PM | PM | SE、依頼者側担当 | 関係者 |
| 基本設計着手ゲート | PM / SE | プロジェクト責任者 | QA、アーキテクト | 開発チーム |
| OpenAPI破壊的変更 | SE / API担当 | 技術責任者 | PG、QA、依頼者側担当 | PM |
| ADR追加・変更 | アーキテクト / SE | 技術責任者 | PM、PG | QA / 運用 |
| AGENTS.md変更 | 技術リード | 技術責任者 | セキュリティ、PM | 開発チーム |
| AI利用ルール変更 | PM / 技術リード | プロジェクト責任者 | 情シス、法務、セキュリティ | 利用者 |
「誰が更新するか」「誰が承認するか」を明文化し、正本運用が属人化しないようにする。
ゲート判定の入力
| 成果物 | 用途 |
|---|---|
| baseline-agreements.md | 合意済み / 未決の索引 |
| open-items.md | 確認待ち |
| traceability-matrix | REQ↔設計↔テスト |
| knowledge/*.yaml | MD 正本の構造化索引（source_refs · related） |
| semantic-drift-audit | 版間の意味逸脱検出 |
KPI 測定定義（要約）
| KPI | 定義 | 測定 |
|---|---|---|
| 手戻り工数 | 基本設計以降の仕様変更による再作業人日 | チケット rework |
| 仕様確認往復 | 同一 REQ の確認コメント往復 | PR / レビュー事項 |
| AI参照可能資産 | REQ-ID MD + OpenAPI カバー率 | リポジトリスキャン |
| REQ-ID付与率 | 対象要件のうち ID 付き正本に登録された割合 | リポジトリスキャン |
| 未決滞留日数 | open-items に残る確認待ちの滞留日数 | open-items 更新履歴 |
| ゲート未通過着手件数 | ゲート判定前に設計・実装へ進んだ件数 | PM 週次チェック |
| OpenAPI同期率 | API 実装と OpenAPI 定義が一致している割合 | CI / schema diff |
数値（-30% 等）は事例レンジ。導入前に baseline を取得すること。下段は運用遵守率として導入効果とあわせて追う。
導入フェーズ・中止条件（要約）
- Phase 0: テンプレ・AGENTS.md・骨格
- Phase 1: 新機能から REQ-ID + MD 正本
- Phase 2: 既存 Excel 段階移行
中止・縮小: PM が週次更新できない / レビュー用 HTML の確認ができない / ゲートなし設計着手が常態化
エージェント文書の3層（要約）
| 層 | 例 | 要点 |
|---|---|---|
| グローバル | ~/.codex/AGENTS.md | 個人横断。非コミット |
| リポジトリ | AGENTS.md | Commands / Rules / Done。32 KiB 以内を意識 |
| 参照 | SOP · DESIGN · REQ · スキル | Rules でパス参照（symlink より方法 A）。仕様正本は REQ / OpenAPI |
工程別 AI ツール（要約）
| 要点 | 内容 | 参考 |
|---|---|---|
| 原則 | 「最強1つ」ではなく役割で組む | note |
| 実装4役割 | Cursor · Claude Code · Codex · Composer | 第4章 |
| 工程マトリクス | 要件=起草+監査 · 設計=推論 · API=整合 · 実装=4役割 · テスト=観点 · 運用=Runbook · PM=ゲート | 各章カード |
| 3段ゲート | 決定的 / AIレビュー / 人間承認（ASDLC） | ASDLC |
エージェント運用3原則
- 薄い AGENTS.md — 常時は短く。手順は
docs/sop/、UI はDESIGN.md、ワークフローはスキルへ - タスク単位コンテキスト — 対象 REQ / path のみ渡す。全要件一括投入しない
- 推測禁止 — UNRESOLVED・open-items は確認待ち。仕様を決め打ちしない
配布用: 本章 + 第0章 経営層向け をブラウザ印刷（背景のグラフィックをオン）。
Knowledge 索引 — マスタ対応表
変更イベント時は Markdown 正本に加え、必要に応じ knowledge/*.yaml を更新する。索引はゲート入力・AI コンテキスト・抜け漏れレポートに使う。
| 変更イベント | Markdown 正本 | YAML 索引（starter_kit） |
|---|---|---|
| 要件追加・変更 | REQ-xxx.md · open-items.md | requirements.yaml · open_questions.yaml · traceability.yaml |
| 業務ルール確定 | REQ 内 BR 表 | business_rules.yaml |
| ゲートでリスク検出 | findings · open-items | risks.yaml |
| 意思決定 | docs/adr/ | decisions.yaml |
| ガイド章更新 | notes/*.md | knowledge/chapters.yaml · practices.yaml（パック本体） |
ガイド notes/ → knowledge/chapters.yaml · practices.yaml
実案件 docs/requirements/ → starter_kit/knowledge/requirements.yaml
検証 tools/validate_knowledge.md · reports/knowledge_review_checklist.md
索引だけを更新し Markdown 正本を更新しない運用は禁止。正本が先、索引は半自動抽出＋人間レビュー。
関連リンク
| リンク | 用途 |
|---|---|
| 経営 | PDF配布ペア |
| Knowledge マスタ | 章索引 |
| 実装 | AGENTS・AI役割 |
| 全章目次 | 詳細へ |
| スターター | 導入15分 |
