工程別ドキュメント運用ガイド

正本を Git 上の Markdown / OpenAPI / ADR に集約し、レビュー用 HTML・ゲート・トレーサビリティで品質と速度を両立するための読み物と実運用テンプレです。入口は本ページ（index.html）のみです。

オンボーディング研修: 受講者は onboarding_index.html · 研修計画

v1.3: リスト・権限統制（端末 allow/deny · KEEL-LST）— 調査メモ · 第4章コース C 追補 · starter_kit/.cursor/permissions.json

このパックの構成

入口は **index.html** のみ。ここから各章・スターターキットへ分岐します。
パス	内容
index.html	本ページ — 読み方・目次・実運用導線
notes/	Obsidian 用 Markdown（章別・正本）
knowledge/	章・施策の YAML 索引（Markdown 正本 + 索引）
starter_kit/	実運用テンプレ（AGENTS · SOP · スキル · knowledge）
09 参考リンク	外部読み物・同梱物索引
`articles/`	Qiita/Zenn向け公開記事

実運用を始める（15分）

starter_kit/ をプロジェクトルートへコピー
AGENTS.md の Commands を編集
REQ-TEMPLATE から起票
Cursor: dev-docs-ssot.mdc を有効化 · permissions.json を配置
ゲート前: python scripts/scan_ambiguous_words.py docs/requirements reference（スターター内パス）
スキル: $dev-docs-gate-lite · $requirements-definition-gate · $doc-pr-gate

詳細は starter_kit/README.md と第4章実装

スターターキット同梱物

種別	パス
エージェント入口	`starter_kit/AGENTS.md`
SOP	`starter_kit/docs/sop/`
Cursorルール	`starter_kit/.cursor/rules/dev-docs-ssot.mdc`
端末リスト	`starter_kit/.cursor/permissions.json`
スキル	`dev-docs-gate-lite` · `requirements-definition-gate` · `doc-pr-gate` 等
構造化索引	`starter_kit/knowledge/` · `schemas/` · `tools/`
スクリプト	`starter_kit/scripts/`

Markdown 正本 + YAML 構造化索引

本ガイドおよび実案件では、Markdown を人間向けの正本として維持しつつ、AI・ツール・ゲート向けに knowledge/*.yaml で構造化索引を持ちます。YAML は正本の代替ではなく、出典（source_refs）・確度（confidence）・状態（status）を付けた索引層です。

やらないこと: Markdown を YAML に置き換える · 出典なしで confirmed にする · AI が推測した内容を確定情報として登録する。

パック内の索引レイヤ（用途別）
パス	正本	索引の内容
notes/	章ノート MD	chapters.yaml · practices.yaml · deliverables.yaml
starter_kit/	REQ-*.md · open-items	requirements.yaml · open_questions.yaml · traceability.yaml
`schemas/` · `tools/` · `reports/`	—	キー揺れ防止 · 抽出手順 · レビューレポート

更新タイミング: Markdown 正本を追加・更新したとき · ゲートで未決・リスクが見つかったとき · PM が週次で open-items を更新したとき。

読み方 — 立場別ルート

必要な章だけ読んでください。

経営層: 00 → 07 → 08 サマリー
PM: 00 → 07。ゲート前は 01・05・06
SE: 01 → 02 → 03 → 05。運用引き継ぎは 06
PG: 03 → 04（3層エージェント文書 · 4役割 · Agent-native CI/CD）
AI運用・エージェント: 04 実装（IDE内4役割）→ 06 運用 → 10 Hermes / PMO AIPC → 11 Quality Signals Loop
初回の外部リンク: 09 参考リンク

配布用 PDF は 08 サマリー + 00 経営 をブラウザ印刷（「背景のグラフィック」をオン）。

章別目次

各章の概要と、資料内で扱う技術名・正本パスの目安。詳細は章本文へ。

0. 経営層向け品質×効率の ROI。Before/After・KPI 定義・PoC baseline・ゲート判断の3分サマリー。SSOT · KPI · gate-decision · open-items · PDF配布経営 · PM 1. 要件定義REQ-ID 付き Markdown 正本。Mermaid 分岐・曖昧語ゲート・依頼者向けレビュー HTML（非正本）。REQ-*.md · Mermaid · open-items.md · requirements-definition-gate · 二層（MD+HTML）経営 · PM · SE 2. 基本設計・ADR技術選択の理由を ADR に残す。C4 / 状態遷移・却下案の記録で手戻りを減らす。adr/ADR-*.md · design.md · C4 · Mermaid · v0（UIたたき台）PM · SE 3. API・OpenAPI契約の正本は分割 YAML。CI で bundle・schema diff・型生成の整合を取る。OpenAPI 3.x · paths/components · bundle · Orval · openapi-diff · Swagger UISE · PG 4. 実装AGENTS.md + SOP + スキルの3層。AI役割設計（知識蒸留）· 既存CI/CD×AI · Agent-native CI/CD。AGENTS.md · docs/sop/ · Copilot instructions · Jenkins/GHA · PR-Agent · 品質定義テンプレPG · SE 5. テストTestDesignDoc と traceability.csv で REQ↔TC 網羅。障害・変更から観点を還流。TestDesignDoc.md · traceability.csv · REQ-ID · LLM-as-a-Judge（補助）SE · PM 6. 運用Runbook MD 正本。PMO AIPC · BTS（Redmine）判断履歴 · CI/CD×AI連携の運用記録。runbooks/ · PMO AIPC · Redmine REST · CI結果追跡 · 週次 PMSE · PM 7. PM・共有週次 PM・着手ゲート・版間意味逸脱監査。合意索引と open-items の鮮度維持。gate-decision.md · semantic-drift-audit · weekly PM · baseline-agreements経営 · PM 8. マスタサマリー全工程1枚。RACI・変更マトリクス・週次チェック・AI 役割要約。経営配布用。RACI · 変更マトリクス · 週次チェックリスト · 4役割要約経営 · PM · 全員 9. 参考リンク外部読み物・スターターキット索引。note / MetaCTO / ASDLC / Hermes / Zylos 等。note · MetaCTO · ASDLC · ai-requirements-factory · Hermes · Agent-native CI/CD全員 10. Hermes / PMO AIPCHermes を社内ノウハウ蓄積 MCP Server として扱うかの限定採用判断。開発PC直置き非推奨・ADR未決を明示。Hermes Agent · Ollama · MCP Server · PMO AIPC · allowlist · draft/approvedPM · SE · PG 11. Quality Signals LoopPR・CI・eval・週次レビューを接続し、人の記録漏れだけに依存せず問題を検知する。Required Checks · eval · DORA · postmortem · observabilityPM · SE · PG · QA

2026-06 追記 — エージェント運用（調査反映）

Web 調査でメリットが大きいと判断したパターンのみ追記。詳細・デメリットは各章を参照。

入口からの読み順
トピック	内容	章
IDE 内4役割	Cursor · Claude Code · Codex · Composer（実装≠レビュー）	第4章
PMO AIPC	セキュアゾーン内 MCP Server — 社内ノウハウ蓄積地（Hermes+Ollama）	第4章 · 第6章
Agent-native CI/CD	スキル/プロンプト bundle · ゴールデン eval · コストゲート	第4章 · 第5章
CI/CD × AI 協調	既存パイプライン + AIログ要約/PRレビュー · Redmine判断履歴	第4章 · 第6章 · ai_quality 第7章
AI役割設計（ワークフロー）	品質定義蒸留 · AGENTS.md · 既存WF 10例	第4章 · ai_quality 第17章
品質アンカー	ADR/5層 · PoC仮説（Gram Anchoring比喩） · カリキュラム順	第2章 · 第4章 CI/CD×AI
Hermes（開発PC直置き）	非推奨 — blast radius。個人検証のみ	—

理念: Hermes = 記憶・整流 · Cursor = 実装 · Codex = レビュー。Cursor 契約内 LLM の外部プロキシ化は期待しない（社内調査 2026-06-22）。

ねらい：「品質のために時間がかかる」のではなく、正本を1か所に集約することで品質と速度が同時に上がることを、各章の Before/After で示します。

リンク	用途
09 参考リンク	外部読み物
オンボーディング研修	コース A〜E
Knowledge 索引	章・施策 YAML
スターターキット	実運用テンプレ
Obsidian	ノート版目次
マスタサマリー	配布1枚