2026-10-18時点の、自分のローカル環境におけるAI支援の設定変更・検証記録です。複数のコーディングエージェントを使うエンジニアに向け、開発フローをどこまで共通化し、何を証拠に確認するかを整理します。
結論：追加したのは、既存の品質基準を使い分けるための2項目
外部プラグインを新しく導入せず、共通ルールの正本へMarkdownの2行を追加しました。定義したのは、次の2点です。
- 着手前に、規模・不確実性・影響度から必要な工程を選ぶ。
- 完了時に、変更・検証・未確認・独立レビューを報告する。
今回検証したのは、ルールの追記と4つの指示ファイルへの同期です。各AIの実行時の遵守や、開発時間・トークン消費への効果は今後の評価対象です。
2行の追記で済んだ前提として、共通ルールには次の基準がありました。
- YAGNI：既存実装・標準機能を優先し、不要な抽象化を足さない。
- バグの再現：修正前に再現テストを用意し、失敗から成功への変化を確認する。自動再現が困難なら手順と代替検証を残す。
- 変更に応じた検証：業務ルールは単体、API・DBや副作用の順序は結合、重要な利用者操作はE2Eなど、対象に必要な確認を選ぶ。
- 統合前の独立レビュー：実装者とは別のセッション・エージェントが差分を確認する。
今回は、この基準群に「どの工程を選ぶか」と「何を完了報告に残すか」を補いました。自分の環境へ取り入れる際も、先に同じ前提が揃っているかを確認できます。
なぜ今回はプラグイン追加を選ばなかったか
きっかけは、Superpowersのような開発手順のスキル集を追加すべきかという検討でした。Superpowersのbrainstormingにも、明確な小タスクを直接実施する考え方があります。工程を選ぶ仕組みを自分の環境へどう組み込むかが、今回の問いでした。
そのうえで、自分の環境では次のように比較しました。
| 選択肢 | 適する条件 | 今回の判断 |
|---|---|---|
| スキル集を導入する | 要件整理・計画・レビューの共通手順がまだ少ない | 有力な候補だが、今回は導入せず |
| 既存ルールへ不足部分を追加する | 品質基準はあり、工程選択や報告の形式が曖昧 | 今回採用。既存基準を再利用できる |
| 毎回の会話で指示する | 単発の実験で、まだ共通化する内容が固まっていない | 継続利用時の指示漏れは別に考える必要がある |
判断基準にしたのは、既存ルールを再利用して不足部分を補えるかです。採用後は、自前のルールについても矛盾の点検や更新を続ける必要があります。
実際に追加した2行
次が追記した本文です。各項目を1行で保存しているため、差分は+2 / -0でした。
- AI実装作業の着手前に、変更の規模・不確実性・影響度から、要件確認・計画・委譲・検証の必要性を判断する。明確で低リスクな変更は直接実施し、複雑・高影響の変更では選んだ工程と理由を短く示す。工程の簡略化によって、既存の独立レビュー・承認・情報境界を省略しない。
- 完了報告は「変更」「検証（実行コマンドと結果）」「未確認」「独立レビュー（結果または未実施）」を簡潔に示す。検証は変更対象の版と対応させ、未実施・既存失敗・新規失敗を区別する。
1項目目は工程の選択、2項目目は証拠の報告を扱います。工程を簡略化する場合も、独立レビュー・人間承認・情報保護の境界は維持します。
変更量だけで判断しない
次の表は、追加したルールを4つのケースに当てはめた想定例です。
| 例 | 工程の選び方 | 省略しないこと |
|---|---|---|
| 明確な文言修正 | 長い壁打ちや細かな計画を省き、直接修正する | 変更に適した表示確認と、既存の統合前レビュー基準 |
| 認可の1行修正 | 影響度から、原因確認・再現テスト・境界条件・回帰確認を選ぶ | 権限確認、独立レビュー。自動再現が困難なら代替検証を記録 |
| 仕様が曖昧な新機能 | 要件を確認し、計画・委譲・検証の必要性を判断する | 未確定の仕様を合意済みと扱わない |
| コード変更を伴わない質問 | AI実装作業の工程を一律には課さない | 通常の情報保護・外部送信の境界 |
「規模・不確実性・影響度」の3つを判断の観点として使い、選んだ工程と理由を短く説明する運用を定義しました。
完了報告を、変更した版と結び付ける
完了報告では、実行コマンドと結果を検証した版に対応させます。コミット済みならコミットID、未コミットなら対象ファイルのハッシュなどを使い、後から同じ版の結果として確かめられるようにします。
特に、次の状態を混同しないようにしました。
- 検証していない。
- 修正前から失敗していることを確認できた。
- 今回の差分で失敗するようになったことを確認できた。
- 前後比較がなく、失敗の原因をまだ判定できない。
失敗の原因は前後比較が揃うまで「未判定」とし、独立レビューでは実装者とは別の担当が実ファイル・差分を確認します。Superpowersのタスクレビュー用プロンプトも、実装者の報告をそのまま信じず、差分から仕様準拠とコード品質を確認する構成です。
正本1つから、今回の4つの反映先へ同期した
今回の環境では、~/.ai-shared/AGENT_RULES.mdを正本とし、既存のsync-agent-rules.shで次の4ファイルへ反映しました。
このシェルスクリプトはawkを使い、正本の最初の行頭## 見出しから末尾までを共有本文として抽出します。反映先では、<!-- AI-SHARED-RULES:START ... -->と<!-- AI-SHARED-RULES:END -->が正しく1組ある状態で、その内側だけを置き換え、ファイル固有のヘッダ・フッタを残す仕組みです。
マーカーが未設置なら管理ブロックを末尾へ追加します。既存マーカーの欠損は同期スクリプトでは検出しないため、後述の照合コードでは開始・終了が1組ずつあることも検査しました。
| 役割 | 今回の反映先 |
|---|---|
| Claude向け指示 | ~/.claude/CLAUDE.md |
| Codex向け指示 | ~/.codex/AGENTS.md |
| Gemini / Antigravity向け指示 | ~/.gemini/GEMINI.md |
| ホーム共通の指示 | ~/AGENTS.md |
正本を含めると変更対象は5ファイルです。同期スクリプトは既存のものを再利用しました。
表に示したのは、今回設定している反映先です。各製品の読込み先は利用環境・設定に依存するため、Cursorを含む各ツールの新規セッションで、どの指示が読み込まれるかを別途確認します。
「同期成功」という表示だけでは完了にしない
Codexが編集を担当し、別のエージェント環境であるAntigravity側には、計画と最終差分の確認を依頼しました。目的は、編集担当だけで承認を完結させず、別コンテキストから判断を点検することです。さらに別のCodexインスタンスが、事前バックアップと実ファイルから内容を再計算して照合しました。
主に確認したのは次の項目です。
| 確認項目 | 今回の結果 | この確認では分からないこと |
|---|---|---|
| 正本の差分 | 2行追加、既存行の削除・変更なし | ルールが常に守られるか |
| 同期先の管理ブロック | 4/4ファイルで正本の共有本文とバイト一致 | 各ツールの自動読込み |
| 管理ブロック外 | 同期前の内容と一致 | 無関係な全設定の正しさ |
| 権限・所有者 | 対象ファイルで保持 | 他の端末への反映 |
| 再同期 | 正本・スクリプト・4同期先の内容ハッシュが不変 | 実行時の挙動や処理効率 |
| 差分レビュー | Antigravityと別Codexで指摘0件 | 不具合が存在しないことの保証 |
同期スクリプトは再実行時にバックアップを上書きするため、初回のバックアップを別に保持してから2回目を実行しました。「内容が同じ」という冪等性と、更新時刻まで変わらないことも区別しています。
現在の本文一致だけを確認するコード
次のコードは、上記のパス・管理マーカー・共有本文の切出し規約を使う今回の環境向けの照合コードです。処理はファイルの読出しと比較だけです。他の環境で使う際は、対象パスとマーカーを合わせます。
from pathlib import Path
import re
home = Path.home()
source = home / ".ai-shared/AGENT_RULES.md"
targets = [
home / ".claude/CLAUDE.md",
home / ".codex/AGENTS.md",
home / ".gemini/GEMINI.md",
home / "AGENTS.md",
]
data = source.read_bytes()
heading = re.search(rb"(?m)^## ", data)
if heading is None:
raise ValueError("source: no section heading")
payload = data[heading.start():]
for target in targets:
lines = target.read_bytes().splitlines(keepends=True)
starts = [i for i, line in enumerate(lines)
if line.startswith(b"<!-- AI-SHARED-RULES:START ")]
ends = [i for i, line in enumerate(lines)
if line.rstrip(b"\r\n") == b"<!-- AI-SHARED-RULES:END -->"]
if len(starts) != 1 or len(ends) != 1 or starts[0] >= ends[0]:
raise ValueError(f"{target.name}: invalid marker pair")
actual = b"".join(lines[starts[0] + 1:ends[0]])
if actual != payload:
raise ValueError(f"{target.name}: shared block differs")
print(f"matched {len(targets)}/{len(targets)}")
これをcheck_synced_rules.pyとして実行し、今回の環境では次の出力を確認しました。
$ python3 check_synced_rules.py
matched 4/4
このコードで確認できるのは、現在の管理マーカーと共有本文の一致です。ブロック外の保持や再同期時の内容不変は、事前バックアップ・初回同期後ハッシュとの比較で別に確認しました。
確認コード自身にも取り違えがあった
最初の照合では、説明文に含まれる## を最初の見出しと誤認し、期待する共有本文の切出し位置を間違えました。原因は、確認コード側の抽出条件でした。
上のコードでは(?m)^## で行頭の見出しを指定しています。検査が失敗したら、同期処理と検査側の前提のどちらが違うのかを切り分ける必要があります。今回は本文の照合を維持し、同期処理が使う抽出規約と検査側の条件を揃えて再確認しました。
ルールの配置と、効果の実証を分ける
今回済んだのは、ルールを定義し、反映先のファイル内容を揃え、その差分をレビューするところまでです。
今後の確認は、次の順序で考えます。
- 各ツールの新規セッションが、そのルールを実際に読み込むか。
- 明確な軽微修正と高影響の変更で、必要な工程を選べるか。
- 完了報告が検証した版・実行結果・未確認事項と結び付いているか。
- 導入前後で、同等の作業にかかった時間、修正回数、トークン消費がどう変わるか。
比較するときは、要件整理やレビューに使ったコストも含めます。短い作業だけで判断せず、重要な検証を省いて速くなったケースを改善として数えないようにします。
既存の品質基準が十分にあり、工程の選択や報告形式だけが不足しているなら、小さな追記から始める選択肢があります。共通手順自体が不足している環境なら、スキル集を導入して運用する負担と、自前で維持する負担を比較するところから始めるのがよいと考えます。
この記事を書いた人✏️@YushiYamamoto
ITPRODX.com代表。AI × Web × 業務自動化の開発・検証に取り組んでいます。
技術選定・品質・運用の判断材料を、検証範囲と制約を示して発信しています。
AI導入や業務自動化の技術選定・設計整理については、対応できる範囲を確認のうえご相談を承ります。