AI補助開発を安全に進めるための運用設計ガイド

1. なぜこの運用が必要なのか

AIは、短い説明からコードのたたき台を作る、ログを分類する、ドキュメントの下書きを作る、といった作業では非常に速く動きます。一方で、既存リポジトリ、運用中のサーバー、複数の設定ファイル、過去の判断、公開済みドキュメントが絡むと、単に「いい感じに直して」と頼むだけでは危険です。

問題は、AIが必ず間違うことではありません。問題は、作業範囲が広いまま進むと、どの情報が正本で、どのファイルを変更してよく、何を検証したのかが曖昧になることです。曖昧なまま会話を続けるほど、説明は増えるのに成果物が進まない状態に入りやすくなります。

1. 目的を1つに絞る
2. 変更範囲を決める
3. 正本を確認する
4. 検証する
5. 記録して閉じる

2. 対象読者と対象外

ここで紹介するのは、AIを現場で活用するために私が試してきた方法の一例です。必要な部分だけを、それぞれの環境に合わせて利用してください。

3. AI補助開発の6原則

私の環境では、次の6つを意識すると、AIの出力を実際の成果物につなげやすくなりました。すべてを同じ形で導入する必要はありませんが、承認、変更範囲、正本、検証、記録をつなげて考える点は役立ちました。

4. 小さい承認単位

AIに大きな目的をそのまま渡すと、調査、実装、検証、ドキュメント更新、公開作業が一つの会話に混ざります。混ざった作業はレビューしにくく、失敗したときに戻しにくくなります。

そこで、承認は「今回やること」と「今回やらないこと」が明確になる大きさに分けます。たとえば、read-only 調査、docs-only 更新、実装、runtime 変更、公開作業は、それぞれ別の承認に分けます。

悪い例

この機能を公開できるところまで全部やって。

良い例

今回は docs/NOW.md と docs/CHANGELOG.md だけを更新する。
目的は、前回の検証結果を記録し、次の SINGLE_ACTION を明確にすること。
サーバー、Nginx、DNS、mail、deploy 設定には触らない。

5. 明示的な write set

write set は、今回の作業でAIが編集してよいファイル一覧です。これを決めずに「必要なところを直して」と頼むと、AIが善意で周辺ファイルまで編集することがあります。

write set は、単なる作業指示ではなく、安全境界です。どのファイルが変更されるべきかを先に決めることで、Git diff の確認が短くなり、想定外の副作用も見つけやすくなります。

Approved write set:
- docs/NOW.md
- docs/CHANGELOG.md

Do not edit:
- public/**
- AGENTS.md
- README.md
- server/runtime/DNS/mail/deploy settings

読む範囲 / 変更してよい範囲 / 今回触らない範囲

公開作業やサーバー関連作業では、編集対象だけでなく、読んでよい範囲と触ってはいけない範囲も分けます。

6. Git 正本

AIとの会話は便利ですが、正本には向きません。会話には、途中の仮説、古い前提、失敗した案、未確認の記憶が混ざるためです。

私の環境では、現在の状態を判断するときに、GitHubのremote mainと対応するローカル作業ツリーを基準にしています。作業前後には、HEAD、origin/main、remote refs/heads/main、worktreeの状態を確認します。GitLab、Bitbucket、セルフホストGit、feature branchなどを使う場合は、そのプロジェクトで合意したリモートリポジトリと基準ブランチに読み替えてください。

git fetch origin main
git status --branch --short
git rev-parse HEAD
git rev-parse origin/main
git ls-remote origin refs/heads/main

7. ドキュメントを実装と一緒に更新する

コードだけを直してドキュメントを後回しにすると、次回のAIや人間が古い説明を読み、間違った作業を始めることがあります。私の環境では、実装とドキュメントのずれが、そのまま次回の前提ミスにつながりました。

一方で、ドキュメントは増やせばよいわけではありません。役割を分け、同じ内容を何度も重複させないようにしています。

重要なのは、説明を増やすことではなく、次の作業で迷わないだけの情報を残すことです。

8. 検証ログ

「確認済みです」という一文だけでは、何を確認したのか分かりません。検証ログには、実行したコマンド、確認した対象、得られた結果、確認していない範囲を残します。

Checks run:
- git fetch origin main
- git status --branch --short
- git diff --check
- Markdown fence / HTML comment / Jinja scan
- git rev-parse HEAD
- git rev-parse origin/main

Result:
- PASS
- HEAD == origin/main
- worktree clean

検証ログは、AIの説明を信じるためではなく、後から人間が確認できる状態を残すためのものです。

9. 実装と文書の同時 closeout

closeout は、作業の終わりに状態を閉じる手順です。実装、検証、ドキュメント、commit、次の作業が別々のタイミングで残ると、どれが完了でどれが未完了か分からなくなります。

同時 closeout では、変更内容、変更ファイル、検証結果、未確認事項、commit、次の作業を一つのまとまりとして記録します。

Closeout:
- Result: PASS
- Changed files:
  - app/example.py
  - docs/NOW.md
  - docs/CHANGELOG.md
- Checks run:
  - pytest
  - git diff --check
  - parser-safety scan
- Commit: abc1234
- Final state:
  - HEAD == origin/main
  - worktree clean
- Next single action:
  - R4_PUBLICATION_READONLY_VERIFY

10. 作業の種類と危険度を分ける

軽い文書更新と、本番環境に影響する操作を同じ手順で扱うと、確認が過剰になったり、逆に必要な承認が不足したりします。そこで私は、作業の種類と危険度を見分けやすくするため、R0〜R5（筆者の分類例）という区分を使っています。

この分類は一般規格ではなく、私の運用例です。重要なのはR0〜R5という名前ではなく、「読むだけ」「文書だけ」「実装」「本番操作」など、性質の違う作業を区別して伝えることです。

この区分が役立った点

• 軽い作業に過剰な前処理をかけないため
• 危険な作業を軽い承認で進めないため
• 作業の途中で、AIが勝手に範囲を広げるのを防ぐため
• 他人へ引き継ぐときに、作業の重さを一言で伝えるため

11. 承認テンプレートを作り、同じ形式で使う

依頼のたびに自由な文章だけで指示すると、目的、変更範囲、禁止範囲、確認方法が抜けることがあります。そこで私は、必要な項目をまとめた承認テンプレートを作り、同じ形式で使っています。

以下は私の環境で使っている一例です。項目名や構成をそのまま採用する必要はありません。目的、変更範囲、今回触らない範囲、確認方法、作業を止める条件など、各環境で必要な項目を決めて使うことが重要です。

WORK_ID:
WORK_RANK:
GOAL:
SOURCE_OF_TRUTH:
REQUIRED_READS:
APPROVED_WRITE_SET:
FORBIDDEN_SET:
RESTRICTED_SECRET_MATERIAL:
ALLOWED_COMMANDS:
REQUIRED_CHECKS:
STOP_CONDITION:
DOCS_TO_UPDATE:
COMPLETION_CRITERIA:
OUTPUT_FORMAT:
NEXT_SINGLE_ACTION:

私の環境でのテンプレート例

WORK_ID: R1_DOCS_ONLY_CLOSEOUT_SYNC_YYYYMMDD_01
WORK_RANK: R1_DOCS_ONLY
GOAL: 直近の検証結果を docs/NOW.md と docs/CHANGELOG.md に記録する。
SOURCE_OF_TRUTH: GitHub remote main and matching local worktree.
REQUIRED_READS:
- docs/NOW.md
- docs/CHANGELOG.md
APPROVED_WRITE_SET:
- docs/NOW.md
- docs/CHANGELOG.md
FORBIDDEN_SET:
- public/**
- server/runtime/DNS/mail/deploy settings
- unrelated files
RESTRICTED_SECRET_MATERIAL:
- .env
- SSH private keys
- API keys and access tokens
- files containing passwords, customer data, or personal data
ALLOWED_COMMANDS:
- git status / git diff / git diff --check / git rev-parse
REQUIRED_CHECKS:
- changed files exactly match approved write set
- Markdown parser-safety scan
- final HEAD == origin/main if commit/push is in scope
DOCS_TO_UPDATE:
- docs/NOW.md
- docs/CHANGELOG.md
COMPLETION_CRITERIA:
- verified facts and unverified items are recorded
- NEXT_SINGLE_ACTION is one item only
OUTPUT_FORMAT: closeout summary only
NEXT_SINGLE_ACTION: R2_DIFF_PLAN_FOR_NEXT_CHANGE

効果

• AIが勝手に目的を広げにくくなる
• レビュー対象が明確になる
• 同じ形式で履歴を残せる
• Codexへ渡すプロンプトとして再利用しやすい
• 作業前に、不足している承認や検証条件を見つけやすい

12. Verified / Unverified / Next に分けて記録する

AI補助開発で危険なのは、未確認の推測が、いつの間にか確認済みの事実として扱われることです。これを防ぐには、作業報告の最後に Verified、Unverified、Next を必ず分けて書きます。

Verified:
- docs/NOW.md and docs/CHANGELOG.md were updated.
- Changed files match the approved write set.
- Markdown parser-safety scan passed.
- HEAD == origin/main after push.

Unverified:
- Runtime state was not checked.
- Nginx reload/restart was not performed.
- DNS/mail/server settings were not changed.

Next:
- R2_DIFF_PLAN_FOR_PUBLICATION_ROUTE

分けて記録する理由

この3項目に分けると、観測した事実、確認していない範囲、次の一手が分かれます。結果として、次の作業者が「何を信じてよいか」「何をまだ信じてはいけないか」を判断しやすくなります。

13. 失敗時の撤退とロールバック

AI補助開発では、失敗しない前提ではなく、失敗したときに安全に止める前提が必要です。Verified とした後に問題が出る場合もあるため、撤退手順を先に決めます。

失敗時プロトコル:
1. 追加実装を止める
2. git status と git diff --stat で変更範囲を確認する
3. 必要なら diff を保存する
4. Verified / Unverified / Risks を記録する
5. 破棄・revert・再設計のどれにするか人間が決める
6. HANDOFF_PROMPT.md または closeout 形式で再起動する

14. セッションとコンテキスト管理

会話が長くなると、古い指示、失敗した修正案、途中の仮説が混ざり、AIが現在の承認境界を見失いやすくなります。1つの承認単位が終わったら、必要に応じて新しいセッションへ切り替える前提で運用します。

セッション再起動用の最小情報:
- Source of truth: GitHub remote main + local worktree
- Current HEAD / origin/main
- Approved WORK_RANK and write set
- Verified facts only
- Unverified items
- Next single action
- Forbidden set

15. 機密情報漏えい防止の自動化

「秘密情報を書かない」という注意だけでは不十分です。人間もAIもミスをする前提で、誤コミットや公開前の混入を検出する仕組みを取り入れています。

16. JSON / YAML 承認テンプレート

私のようにテンプレートをツールやスクリプトでも再利用したい場合は、MarkdownだけでなくJSONやYAMLにしておく方法もあります。これは必要な人向けの具体例であり、通常のチャット利用ではMarkdownや文章形式だけでも十分です。

YAML版

work_id: R3_IMPLEMENTATION_EXAMPLE_YYYYMMDD_01
work_rank: R3_IMPLEMENTATION
goal: Implement the approved small change only.
source_of_truth:
  - GitHub remote main
  - Corresponding local worktree
approved_write_set:
  - app/example.py
  - tests/test_example.py
forbidden_set:
  - server/runtime/DNS/mail/deploy settings
  - unrelated files
restricted_secret_material:
  - .env
  - SSH private keys
  - API keys and access tokens
  - files containing passwords, customer data, or personal data
required_checks:
  - pytest
  - git diff --check
  - changed files match approved write set

JSON版

{
  "work_id": "R3_IMPLEMENTATION_EXAMPLE_YYYYMMDD_01",
  "work_rank": "R3_IMPLEMENTATION",
  "goal": "Implement the approved small change only.",
  "source_of_truth": ["GitHub remote main", "Corresponding local worktree"],
  "approved_write_set": ["app/example.py", "tests/test_example.py"],
  "forbidden_set": ["server/runtime/DNS/mail/deploy settings", "unrelated files"],
  "restricted_secret_material": [".env", "SSH private keys", "API keys and access tokens", "files containing passwords, customer data, or personal data"],
  "required_checks": ["pytest", "git diff --check", "write set verification"],
  "closeout_format": ["Result", "Changed files", "Verified", "Unverified", "Risks", "Next"]
}

17. レビュー粒度とアンチパターン

承認単位を小さくすることは有効ですが、小さすぎると人間のレビュー待ちがボトルネックになります。安全性と進捗のバランスを取るため、適切な粒度を決めます。次の15-30分という時間は、私が確認しやすいと感じている目安であり、一般的な基準ではありません。

18. Codexに渡すときの最小プロンプト

CodexやAI開発支援ツールへ渡すプロンプトは、長ければよいわけではありません。必要なのは、正本、承認範囲、禁止範囲、検証、停止条件、出力形式です。

Use the local worktree as the source of truth.
Do not infer current state from chat history.

WORK_RANK: R3_IMPLEMENTATION
GOAL: Implement the approved small change only.
APPROVED_WRITE_SET:
- app/example.py
- tests/test_example.py
- docs/NOW.md
- docs/CHANGELOG.md
FORBIDDEN_SET:
- server/runtime/DNS/mail/deploy settings
- unrelated refactors
RESTRICTED_SECRET_MATERIAL:
- .env
- SSH private keys
- API keys / access tokens
- files containing passwords or personal data
REQUIRED_CHECKS:
- tests for changed behavior
- git diff --check
- changed files exactly match approved write set
- parser-safety scan for edited Markdown
STOP_CONDITION:
- stop if write set must expand
- stop if runtime/deploy operation becomes necessary
- stop if restricted secret material must be read or displayed
CLOSEOUT_FORMAT:
- Result
- Changed files
- Verified
- Unverified
- Risks
- Next

19. 利用上の注意とライセンス

本資料は、AI補助開発を安全に進めるための実務上の考え方を整理した公開版資料です。筆者の経験に基づく観測結果であり、特定の製品、法令、セキュリティ基準への適合を保証するものではありません。

20. まとめ

AI開発で重要なのは、AIを使うか使わないかではありません。重要なのは、AIにどこまで任せ、どこから人間が境界を引くかです。

私の環境では、小さい承認単位、明示的な write set、Git 正本、docs 同期、検証ログ、実装と文書の同時 closeout を意識することで、AIの速さを実際の成果物につなげやすくなりました。

さらに、失敗時の撤退、セッション管理、秘密情報検出、JSON/YAMLテンプレート、レビュー粒度を足すことで、運用を回し始めた後の壁にも対応しやすくなります。