4. 実装

AGENTS.md：PGの入口（Commands / Rules / Done）

AGENTS.md はプロンプトの置き場ではなく、検証可能な開発契約です。Codex は既定 32 KiB まで連結読込するため、短い入口＋参照パスが効きます（Zenn: AGENTS.md + SOP + DESIGN 分離、agents.md 標準）。

# AGENTS.md（リポジトリ入口・抜粋）

## Commands
- Install: `npm ci`
- Test: `npm test`
- Lint: `npm run lint`

## Rules
- 仕様正本: docs/requirements/REQ-*.md（HTMLは生成物）
- 手順: docs/sop/engineering.md を全変更で参照
- UI作業前: docs/design/DESIGN.md（フロント案件のみ）
- ワークフロー: .agents/skills/（例: requirements-definition-gate）
- NEVER: 当事者識別情報・接続情報・open-items 未解消の仕様確定

## Done
- `npm test` と `npm run lint` が通る
- 関連 REQ / OpenAPI / docs を PR に同梱

3層のエージェント文書（Codex / Cursor）

推奨ディレクトリ

your-repo/
├── AGENTS.md                 # 短い入口（Codex / Cursor が読む）
├── docs/
│   ├── sop/
│   │   ├── engineering.md    # PR・レビュー・セキュリティ
│   │   └── python.md         # 言語別（必要時）
│   ├── design/
│   │   └── DESIGN.md         # UI・トークン（フロント案件）
│   ├── requirements/         # REQ 正本
│   └── adr/
├── .agents/skills/           # ワークフロー（ゲート・議事録等）
└── openapi/

プロジェクトへの当てはめ（例）

工程別：役割で組む AI ツール

「いちばん強いモデル1つに全部任せる」構成は、モデル停止・規制・性能低下のときに開発全体が止まるリスクがあります。2026年6月には高性能モデルが外部要因で無期限停止された事例もあり（note: かい氏の役割分担ガイド）、「最強1つ」への最適化はリスクの集中になります。

本ガイドではツール名より役割の枠を先に決め、中身のモデルは入れ替え可能にします。実装フェーズの核は個人・小規模チームで検証されている4役割体制です。

なぜ「役割で組む」か（note 記事の要点）

• 消えるリスク — 規制・障害・サービス終了でアクセスごと断たれる
• 落ちるリスク — モデルは残るが半年で2〜3番手に後退しうる
• 比較地獄からの脱出 — 役割の枠が固定なら中身のモデル交代で体制は維持
• アンサンブル — 実装モデルとレビューモデルを分け、意見が割れた箇所だけ人が判断

本ガイドの工程 × AI 役割マトリクス

外部事例（スクレイピング・調査で取り込んだパターン）

PMO AIPC — 社内ノウハウ蓄積地（Hermes + Ollama · MCP Server）

結論: Hermes は Cursor/Codex の代替ではなく、セキュアゾーンに置く記憶・整流レイヤーとして扱う。開発 PC 直置きの常時稼働 Hermes は blast radius が大きいため、個人検証に限定する。

参考: Hermes Agent · Ollama × Hermes

Agent-native CI/CD — スキル・プロンプト変更のゲート

エージェントの挙動はコードだけで決まらない（Zylos 2026）。.agents/skills/ · システムプロンプト · MCP ツール定義 · モデル版をagent bundleとして Git 管理し、従来 CI に次を足すと精度保証と標準化の効果が大きい。

作業タイプ別の振り分け（実装中心）

導入メモ

• Codex プラグイン: /plugin marketplace add openai/codex-plugin-cc（Claude Code + Codex CLI + Node 18.18+ · ChatGPT $20 等）
• 個人参考コスト（note 実数）: Claude Code 上位 ~$200 + Cursor Pro $60 + ChatGPT $20 ≒ 月$280。チームはライセンス×人数＋正本運用で試算
• 2026年傾向: ボトルネックは「書く」→「レビュー・検証」（MetaCTO · Thinkia AI-SDLC）
• MCP: Issue・CI・ドキュメントをエージェントへ JIT 接続する de facto 層になりつつある

役割分担導入後に変わったこと（note 記事より）

• 1つが落ちても手が止まらない — 他役割で継続
• 別の目で品質が上がる — 割れた箇所を潰す習慣
• 「今の最強」に振り回されない — 枠は固定、中身だけ交代

AIチケット起点開発ループ

いきなり「実装して」と依頼せず、チケット品質確認 → インタビュー → 計画 → Handoff → 実装を標準化する。AI開発の品質は実装プロンプトよりチケットの質（目的・受入条件・非対象・影響範囲）に左右される。

AI開発メニュー

全体フロー

```mermaid
flowchart TD
  M[AI開発メニュー] --> B[既存チケット対応]
  M --> C[新規起票]
  M --> D[再整理]
  M --> E[PR指摘対応]
  B --> Q{品質 A/B/C/D}
  Q -->|A/B| P[計画 → 承認 → Handoff → 実装]
  Q -->|C/D| X[調査分離 or 差し戻し]
  C --> T[起票] --> B
```

実装可能性判定（A/B/C/D）

チケット品質ゲート · Handoff

• 品質ゲート: 目的・背景、対象、期待状態、受入条件、非対象、影響範囲、テスト観点
• Handoff で渡す: 採用方針、変更対象/可不可、受入条件、テスト、禁止事項、参考実装
• 渡さない: 却下案、迷いの長文、未採用仮説、関係ない調査ログ

エージェント役割（論理分離）

AIを既存開発に馴染ませる — 役割設計

正本: tools/dev_docs_guide_pack/references/ai_role_design_for_existing_dev_workflow.md

CI/CD×AI 協調（第4章 · ai_quality 第7章）が接続の仕方なら、本章はもう一段上の運用設計 — 既存ワークフロー・作業ルーティンの中で AI をどの役割として差し込むかを扱う。

AIを開発ワークフローや作業ルーティンの中で、
どのような役割として既存開発に馴染ませるか。

基本方針

品質定義・設計思想・禁止事項・完了条件が明文化されていないと、AIは一般論として正しいが現場期待とズレる結果を出しやすい。

蒸留先マップ

ワークフロー組み込み事例（10例）

効果別導入パターン

効果の大きさで見る導入パターン

メリット · デメリット

AI向け品質定義テンプレート（作業前に最低限）

## このプロジェクトで重視する品質
- 正確性 / 保守性 / 可読性 / セキュリティ / 性能 / テスト容易性 / 運用容易性

## 設計思想
- レイヤー構造 · 依存方向 · 禁止依存 · 例外処理 · ログ方針

## コーディングルール
- 命名 · フォーマット · null扱い · DB/外部APIアクセス · エラー処理

## テスト方針
- 必須テスト · 変更時コマンド · 追加観点 · テスト不要条件

## AIに任せてよいこと / 任せないこと / 人間が確認すること
（ログ要約·PR要約 / 仕様最終判断·本番デプロイ / 影響範囲·セキュリティ）

starter_kit: docs/sop/ai-usage.md · AGENTS.md に落とし込む。詳細は正本 references/ai_role_design_for_existing_dev_workflow.md §8。

5層運用: ルール · スキル · アンカー（ADR/REQの判断構造）· 評価（CI/eval）· ログ（PR/BTS）。品質アンカーはPoC仮説として 第2章 を参照。

BTS記録テンプレート — 「人間が何を判断したか」を残す

## AI利用メモ
### 事実 — 対象PR · commit · CI job · 変更ファイル
### AIによる整理 — 原因候補 · 影響範囲 · 修正案（推測と事実を分離）
### 人間判断 — 採用 · 見送り · 見送り理由 · 判断者 · 判断日
### 最終結果 — CI/CD · Quality Gate · レビュー · マージ/リリース可否

第6章 BTS連携 · CI/CD協調 第4章 と併用。

運用チェックリスト（要約）

• AI向けルール: README · 設計思想 · TESTING · REVIEW_GUIDE · AGENTS.md/CLAUDE.md/Copilot instructions のいずれか · 任せる/任せないの明記
• CI/CD·Git·BTS·セキュリティ: CI/CD×AI協調 のチェックリストと共通

参考: Copilot repository instructions · Codex AGENTS.md · Atlassian Rovo Dev · AGENTS.md効果分析 (arXiv) · RovoDev Code Reviewer (arXiv)

PRフロー（品質ゲート）

エージェント運用：コンテキスト設計

• 読み込み順: AGENTS.md（常時）→ 対象 REQ の md のみ → 必要時 openapi の該当 path
• 一括投入しない: 全要件・全 OpenAPI を毎プロンプトに貼らない（コンテキスト枯渇・忘却）
• 推測禁止: open-items / UNRESOLVED を仕様確定させない。不足は確認待ちと明記
• スキル vs 正本: スキルはワークフロー（例: requirements-definition-gate）。仕様の正本は REQ / OpenAPI
• セッション境界: AGENTS.md・スキル・常時ルール更新後は新チャット推奨
• NEVER 拡張: 当事者識別情報・接続情報・人事・エンゲージメント系をエージェントに渡さない

## エージェントに渡す順
1. AGENTS.md
2. docs/requirements/REQ-042.md のみ
3. openapi/paths/orders.yaml（該当時）

## やらせないこと
- open-items 未解消の仕様確定
- レビュー用 HTML の手編集（MD から再生成）

AIへ渡してよい情報 / 渡さない情報

既存 CI/CD と AI の協調動作

定着フェーズでは、エージェント文書（AGENTS.md · スキル）に加え、既存パイプラインへ AI を差し込むことで品質の底上げと維持が可能。正本: tools/dev_docs_guide_pack/references/ci_cd_ai_collaboration_guide.md。

本節の主旨: AIを開発の自動操縦役にせず、既存の CI/CD · Git · Redmine 等と連携し、人間が判断可能な形で品質情報を整理する補助レイヤーとして使う。

AIに全部任せるのではない。
CI/CDが事実を検出し、
AIが読み解き、
Redmine/Gitに経緯を残し、
人間が判断する。

推奨アーキテクチャ

事例一覧（16件）

導入優先: ★5=既存CIを壊さず効果が見えやすい · ★4=PoC第2段 · ★3=閉域/ベンダー縛りあり。正式導入時は各公式ライセンス・データ送信範囲を再確認。

実装パターン

パターンA — CI失敗 → AI要約 → BTS追記

1. Jenkins / GHA / GitLab CI が失敗
2. Webhook → n8n / Lambda / 自前Bot
3. ログ末尾 · 失敗ステージ · commit · PR番号を取得（秘密情報マスク）
4. AIが要約: 原因候補 · 該当ステージ · 関連ファイル · 次に見る箇所 · 暫定対応案
5. Redmine APIで既存チケットへコメント追記
6. Slack/Teams通知
7. 人間が「対応」「保留」「誤検知」「別チケット化」を判断

パターンB — PR/MR → AIレビュー → 品質ゲート → 人間承認

1. Redmine番号つきブランチ/PR作成
2. CI: build / test / lint / SAST / coverage
3. AIがPR差分を一次レビュー（参考情報）
4. SonarQube / Qodana / Semgrep の Quality Gate で客観判定
5. AI指摘はPRコメント · 対応/見送り理由を記録
6. 人間レビュアーが最終判断
7. BTSに「対応経緯」「CI結果」「判断理由」を残す

パターンC — 品質ゲート中心（AI生成コード向け）

導入優先度

セキュリティ・運用

セキュリティ境界

運用チェックリスト

品質アンカー — AI協調CI/CDでの劣化防止

AI協調CI/CDでは、ADRを単なる設計判断の記録ではなく、後続のAI作業・レビュー・CIが参照する品質アンカーとして扱う。AIは全体として自然な成果物を生成できる一方、作業が長期化・多段化すると、過去に合意した局所的な設計意図や品質基準を失いやすい。重要な設計判断・例外条件・非対象範囲・責務分離・品質ゲートをADRに固定し、PR、CI、AIレビュー、handoffから継続的に参照する。

AIに長く・多段に作業させると、過去に合意した設計意図・例外条件・命名規則・責務分離・非対象範囲を見落とす可能性がある。本ガイドでは、判断構造を参照点（アンカー）としてADRへ記録し、PR・CI・AIレビュー・handoff から継続参照する運用をPoC仮説として扱う。

• 作業順序: チケット/REQ → 関連ADR読込 → スキル実行 → PR（ADR欄必須）→ CI → 人間判断
• カリキュラム: いきなり実装させず、品質定義・ADR・受入条件を先にアンカー化（チケットループ）
• 評価ループ: CI失敗・PR指摘・BTS記録を次のルール/スキル/ADR更新に還流

設計仮説の正本: research/quality_anchor_ai_ops.md · ADRテンプレ: 第2章 2.0b

コーディング品質管理・規約チェック

Javaを含む主要言語向けに、品質・価格・導入難度・MCP対応・「すり抜けしないレベル」を整理した実務ガイド。AIエージェント時代はAIレビュー単体ではなく、静的解析・型チェック・テスト・CI品質ゲート・MCP連携の多層防御が現実解。

5段階評価の定義

主要ソリューション比較

価格は相対評価（5=低コスト/OSS中心）。正式導入時は各公式のライセンスを再確認。

Java案件の推奨構成

推奨パイプライン：
Formatter → Checkstyle → SpotBugs/PMD/Error Prone → Unit/Integration Test
→ Semgrep → SonarQube Quality Gate → PRレビュー → MCP経由でAI修正支援

PRパイプライン（詳細）

MCPでの実現

価格帯別構成

導入実績・証跡

社内標準化ルール

参考: SonarQube · Semgrep · CodeQL · 評価は2026-06時点の公開情報ベース。

エージェントと Knowledge 索引

AGENTS.md の Rules 9 に索引パスを追加。REQ 更新後は knowledge/ を同期し、ゲート前に reports/knowledge_review_checklist.md で抜け漏れを確認する。

成果物サンプル一覧

実際のプロジェクトではファイル名・パスをテンプレに合わせてください。以下は掲載可能な具体イメージ（HTML/CSS埋め込み）です。

オンボーディング — 実装コース C（AGENTS.md ハンズオン）

講師配布の 研修環境設定 のリポジトリで実施。所要 45〜60分。

ハンズオン手順

確認テスト（5問）

オンボーディング — リスト・権限（コース C 追補）

LLM ゲートウェイの外側で、端末のシェルとエージェントの自動実行を統制する。正本はリポジトリの .cursor/permissions.json（雛形は starter_kit）。設計の全体像は 調査メモ · LLM GW 第9章。

ハンズオン Step 5（15分）

確認テスト（3問）

関連リンク