ln-014-agent-instructions-manager

パス： すべてのファイル参照は skills リポジトリのルートからの相対パスです。

エージェント指示管理

タイプ： L3 ワーカー
カテゴリ： 0XX 共通

不足している指示ファイルを作成し、品質、一貫性、ベストプラクティスの観点から監査します（AGENTS.md、CLAUDE.md）。AGENTS.md を内容の唯一の正規ソースとし、CLAUDE.md は制約されたハーネス固有の差分を含む薄い @AGENTS.md インポート用スタブとします。このスキルは、指示ファイルの作成と MCP ツール設定の挿入または置換を一元的に担当します。

必読： references/coordinator_summary_contract.md、references/environment_worker_runtime_contract.md、references/worker_runtime_contract.md を読み込んでください。
必読： references/mcp_tool_preferences.md を読み込んでください。
必読： references/agent_instructions_writing_guide.md を読み込んでください。@AGENTS.md インポートパターン、サイズ予算、アンチパターンの根拠となる正規ガイドです。以下の監査項目はすべて、このガイドに基づいています。

入力／出力

方向	内容
入力	プロジェクトのコンテキスト、dry_run フラグ、省略可能な runId、省略可能な summaryArtifactPath
出力	payload.status が completed／skipped／error のいずれかとなる構造化サマリーエンベロープ、および changes／detail 内の作成済みファイル、監査結果、警告

summaryArtifactPath が指定されている場合は、同じサマリー JSON をそのパスに書き込みます。指定されていない場合は、サマリーをインラインで返し、完全に単独で実行できる状態を保ちます。runId が指定されていない場合は、サマリーエンベロープを出力する前に、単独実行用の run_id を生成します。

ランタイム

ランタイムファミリー：environment-worker-runtime

フェーズプロファイル：

1. PHASE_0_CONFIG
2. PHASE_1_DISCOVER_FILES
3. PHASE_2_CREATE_MISSING_FILES
4. PHASE_3_TOKEN_BUDGET_AUDIT
5. PHASE_4_PROMPT_CACHE_SAFETY
6. PHASE_5_CONTENT_QUALITY
7. PHASE_6_IMPORT_PATTERN_COMPLIANCE
8. PHASE_7_WRITE_SUMMARY
9. PHASE_8_SELF_CHECK

ランタイムルール：

• summary_kind=env-instructions を出力する
• 単独実行では独自の run_id を生成し、ワーカーファミリーのデフォルトアーティファクトパスに書き込む
• 管理対象の実行では runId と summaryArtifactPath の両方が必須であり、指定された正確なパスにサマリーを書き込む
• 終端結果を出す前に、検証済みのサマリーアーティファクトを必ず書き込む

出力コントラクト

以下に従って、構造化された env-instructions サマリーエンベロープを必ず作成します。

• references/coordinator_summary_contract.md
• references/environment_worker_runtime_contract.md

ペイロードのフィールド：

• files_found
• files_created
• quality_findings
• token_budget
• prompt_cache_safety
• import_pattern_status
• status

使用するタイミング

• 指示ファイルを編集した後
• MCP サーバーまたはフックを追加／削除した後
• リリースまたは公開の前
• セッションの品質が低下したとき（コンテキスト肥大化の兆候）
• プロジェクトの初回セットアップ時（指示ファイルがない場合）

フェーズ 1：ファイルの検出

対象プロジェクト内の指示ファイルを特定します。

エージェント	主要ファイル	正規ソース	フォールバック
Claude Code	CLAUDE.md	@AGENTS.md 経由で AGENTS.md をインポート	.claude/settings.local.json
Codex / Cursor / Amp / Factory	AGENTS.md	正規ソース	.codex/instructions.md

報告内容：存在するファイル（found／missing）、および AGENTS.md を直接共有するハーネスとインポート経由で共有するハーネス。

フェーズ 1b：プラグインの競合チェック

スキップ条件： 設定に enabledPlugins がない、またはすべてのプラグインが @levnikolaevich-skills-marketplace である。

1. ~/.claude/settings.json を読み込み、enabledPlugins を解析します
2. フィルター：enabled=true かつ publisher ≠ levnikolaevich-skills-marketplace
3. 各外部プラグインについて：
   • まずアクティブなインストールを解決します：~/.claude/plugins/marketplaces/* の下にある、一致するプラグインまたはマーケットプレイス
   • そのインストール先から、アクティブな plugins/*/skills/*/SKILL.md の説明を読み込みます
   • アクティブなインストールが利用できない場合に限り、~/.claude/plugins/cache/{publisher}/{plugin}/*/skills/*/SKILL.md の最新キャッシュスナップショットにフォールバックします
   • キャッシュはフォレンジック用のフォールバックとしてのみ扱います。複数のキャッシュスナップショットを個別のアクティブな競合として数えてはいけません。
   • 競合を示すキーワードを照合します：

シグナル	説明内のキーワード	重複対象
オーケストレーション	"orchestrat", "pipeline", "end-to-end", "lifecycle"	ln-1000 パイプライン
計画	"plan.*implement", "brainstorm", "design.*spec"	ln-300 タスクコーディネーター
実行	"execut.*plan", "subagent.*task", "task-by-task"	ln-400/ln-401 実行ツール
コードレビュー	"code.review.*dispatch", "review.*quality.*spec"	ln-402/ln-310
品質ゲート	"quality.*gate", "verification.*complet", "test-driven.*always"	ln-500 品質ゲート
デバッグ	"systematic.*debug", "root.*cause.*phase"	problem_solving.md
Git 分離	"worktree.*creat", "git.*isolat"	git_worktree_fallback.md

• まずアクティブなインストール先に hooks/session-start ディレクトリがあるか確認します

4. スコア：シグナルカテゴリが 2 つ以上 → CONFLICT。1 つ → WARN。0 → 安全
5. CONFLICT："CONFLICT: {plugin} overlaps with ln-* pipeline ({signals}). Disable?" → AskUserQuestion → yes の場合、settings.json で false に設定します
6. WARN：報告して続行します

フェーズ 2：不足ファイルの作成

スキップ条件： すべてのファイルが存在する、または dry_run == true（作成予定の内容を報告します）。

標準モデル： AGENTS.md をコンテンツの唯一のソースとします。CLAUDE.md は、範囲を限定したハーネス固有の差分を含む @AGENTS.md インポート用スタブです。スタブがすでに存在するファイルを参照するよう、この順序で作成します。

ステップ 2a：プロジェクトコンテキストの検出

フィールド	ソース	フォールバック
PROJECT_NAME	package.json → name	basename(cwd)
PROJECT_DESCRIPTION	package.json → description	[TBD: Project description]
DATE	現在の日付（YYYY-MM-DD）	—
ENABLE_WORKFLOW_PRINCIPLES	呼び出し元の入力（デフォルトは false）	—

ステップ 2b：AGENTS.md の作成（存在しない場合）— 標準ファイル

1. 必須の読み込み： plugins/documentation-pipeline/skills/ln-111-root-docs-creator/references/templates/agents_md_template.md を読み込みます
2. {{PROJECT_NAME}}、{{PROJECT_DESCRIPTION}}、{{DATE}}、および {{DEV_COMMANDS_*}} のプレースホルダーを置換します
3. ENABLE_WORKFLOW_PRINCIPLES=true の場合：{{WORKFLOW_PRINCIPLES_BLOCK}} を plugins/documentation-pipeline/skills/ln-111-root-docs-creator/references/templates/agents_md_workflow_principles.md の全内容に置換します。それ以外の場合は、プレースホルダー行とその先頭の HTML コメントを削除します。
4. 残りの {{...}} を [TBD: placeholder_name] として記します
5. 対象プロジェクトのルートに書き込みます

ステップ 2c：CLAUDE.md の作成（存在しない場合）— インポート用スタブ

1. 必須の読み込み： plugins/documentation-pipeline/skills/ln-111-root-docs-creator/references/templates/claude_md_template.md を読み込みます
2. {{PROJECT_NAME}} のみを置換します
3. 対象プロジェクトのルートに書き込みます
4. ファイルに @AGENTS.md の行が正確に 1 行含まれ、全体が 50 行以下であることを確認します
5. AGENTS.md の内容を CLAUDE.md にコピーしてはいけません。@ インポートによってセッション読み込み時に処理されます

ステップ 2e：作成ファイルの報告

作成した各ファイルと、そのソース（テンプレート agents_md_template.md、テンプレート claude_md_template.md のスタブ）を一覧表示します。

Phase 3: トークン予算の監査

行数の予算は、Anthropic の公式目標（<200 lines per CLAUDE.md file）および IFScale の指示上限に関する調査に沿っています。根拠の詳細については、references/agent_instructions_writing_guide.md を参照してください。

チェック	合格	警告	不合格
AGENTS.md の行数	≤150	151-200	>200
CLAUDE.md の行数（スタブ）	≤20	21-50	>50
AGENTS.md にユーザーが追加した命令文の数	≤100	101-150	>150

命令文のカウント方法： ルールのセクション内で ^\s*- に一致する行に加え、MUST\|NEVER\|ALWAYS\|DO NOT を含む行を数えます。WARN / FAIL メッセージでは、IFScale ベンチマーク（arxiv 2507.11538）を引用してください。

各ファイルについて、行数と命令文の数（AGENTS.md の場合）を表で報告してください。

Phase 4: プロンプトキャッシュの安全性

各ファイルに、プレフィックスベースのプロンプトキャッシュを妨げる内容がないか確認してください。

#	チェック	パターン	重大度
1	タイムスタンプがない	grep -E '\d{4}-\d{2}-\d{2}.\d{2}:\d{2}'	WARN
2	コンテンツ内に日付がない	**Last Updated:** がファイル末尾にある場合を除き、`grep -E '(January	February
3	動的な数がない	grep -E '\d+ skills|\d+ tools|\d+ servers'（ハードコードされた数は変わるため）	WARN
4	絶対パスがない	`grep -E '[A-Z]:\	/home/
5	構造が安定している	条件付きセクション（if X then include Y）がない	INFO

Phase 5: コンテンツの品質

#	チェック	合格	不合格
1	ビルド／テストコマンドがある	AGENTS.md に npm|cargo|pytest|dotnet コマンドがある	ない — 必須コマンドを追加
2	抽象的な原則がない	"write quality code"、"follow best practices" がない	曖昧な指示が見つかった
3	重複するドキュメントがない	API ドキュメントやアーキテクチャの全体説明がない	コードから確認できる内容が見つかった
4	明確な禁止事項がある	AGENTS.md に NEVER|ALWAYS|MUST|DO NOT のルールがある	ない — 明示的な禁止事項が不足
5	簡潔な Instructions セクションがある	AGENTS.md に、保持する優先事項を記載した ## Compact Instructions がある	ない — /compact 時にセッションの決定事項が失われる
6	MCP Tool Preferences がある	AGENTS.md の標準ポリシーセクションが references/mcp_tool_preferences.md と一致している	ない、または古い — エージェントが最適でないツールを使う
7	ツール出力の例がない	大きなコードブロックやコマンド出力がない	見つかった — すべてのターンが肥大化する

チェック #1〜#6 は、CLAUDE.md が @AGENTS.md のインポートによってその内容を引き継ぐため、AGENTS.md のみを評価します。差分自体のチェックは Phase 6 で行います。

Phase 5b: 修正可能な問題の自動修正

Phase 5 で FAIL となった各項目について、報告前に自動修正を試みます。

自動修正で内容を挿入する前に：

1. 挿入位置が存在することを確認します（特定の行に見出しが完全一致で存在すること）。
2. 曖昧な場合（見出しが見つからない場合）は、WARN を出してスキップします（手動修正が必要として報告します）。
3. 挿入後、ファイル内に ## Compact Instructions または ## MCP Tool Preferences セクションが重複していないことを確認します。

#	問題	修正	スキップする条件
5	Compact Instructions がない	AGENTS.md の ## Navigation の前に ## Compact Instructions セクションを挿入	dry_run: true
6	MCP Tool Preferences がない、または古い	references/mcp_tool_preferences.md の内容で AGENTS.md のセクションを挿入または置換	dry_run: true
1	ビルド／テストコマンドがない	WARN のみ（プロジェクト固有のため、自動生成できません）	--
2	抽象的な原則が見つかった	WARN のみ（人間の判断が必要です）	--

Compact Instructions のテンプレート（AGENTS.md の ## Navigation の前、または最後のルールセクションの後に挿入）：

## Compact Instructions

Preserve during /compact: [Critical Rules], [MCP Tool Preferences table],
[Navigation table], [language/communication rules], [hard boundaries (NEVER/ALWAYS)].
Drop examples and explanations first.

CLAUDE.md は @AGENTS.md を参照するため、保持する項目のリストは Claude Code にも引き継がれます。ハーネス固有の用語（/compact とコンテキスト圧縮）は、スタブの差分に記載します。

フェーズ 6：インポートパターンへの準拠

DOC_ROLE メタデータに従い、AGENTS.md を正規の情報源とします。CLAUDE.md は、範囲を限定したハーネス固有の差分を含む、薄い @AGENTS.md インポートスタブでなければなりません。

#	チェック	合格	不合格
1	CLAUDE.md に @AGENTS.md インポートがある	@AGENTS.md の行がちょうど 1 行ある	ない、または複数ある — 不合格
2	CLAUDE.md の差分が上限内	ファイル全体が 50 行以下	50 行超 — 差分レポートを出して不合格
3	内容が重複していない	AGENTS.md のセクションやルールが CLAUDE.md に再掲されていない	重複が見つかった — 重複する行を具体的に示して不合格

差分の解消ルール： AGENTS.md を正規の情報源とします。矛盾がある場合は、それぞれ次のように対応します。

• (a) AGENTS.md にはなく、CLAUDE.md にある内容 → AGENTS.md に移してから、スタブから削除します。
• (b) CLAUDE.md に AGENTS.md の内容が重複している → @AGENTS.md のインポート行 1 行に置き換えます。
• (c) スタブの差分が 50 行を超えている → 本当にハーネス固有の内容は .claude/rules/*.md に分割し、それ以外はすべて AGENTS.md に移します。

内容の量を根拠に「どちらのファイルを正とすべきか提案」しないでください。AGENTS.md は常に正規の情報源です。

.hex-skills/environment_state.json が agents.codex.discovery_violation=true を報告している場合、Codex のスキル検出に差分があるという WARN を出してください。ln-013-config-syncer がマーケットプレイスとプラグインの整合性を修復するまでは、古いキャッシュに基づく重複スキル数を、指示の監査における証拠として使用してはなりません。

.hex-skills/environment_state.json が agents.codex.permissions_default_ready=false を報告している場合、Codex CLI の起動時の権限が管理されたデフォルト設定からずれているという WARN を出してください。ln-013-config-syncer が ~/.codex/config.toml を修復するまでは、指示の監査でフルアクセス起動のセマンティクスを前提としてはなりません。

フェーズ 7：レポート

Agent Instructions Manager:

Created:  (omit section if nothing created)
- AGENTS.md (from template, context from package.json)
- CLAUDE.md (import stub)

Audit:
| File       | Lines | Imperatives | Cache-safe | Quality | Import pattern | Issues |
|------------|-------|-------------|------------|---------|----------------|--------|
| AGENTS.md  | 118   | 47          | OK         | 7/7     | n/a            | OK |
| CLAUDE.md  | 13    | 0           | OK         | 7/7     | OK             | OK |

Import pattern: OK (or N drift issues listed)

Recommendations:
1. Run /init (ln-100) for full context-aware AGENTS.md with project-specific rules

エージェント間の補足： Codex CLI 0.120（2026-04-11）では、SessionStart フックが /clear と、新規セッション／再開の区別をサポートするようになりました。これは Claude Code の動作と一致します。

完了の定義

• すべての指示ファイルを検出した
• 不足しているファイルを作成した（最初にテンプレートから AGENTS.md を作成し、次に @AGENTS.md インポートスタブとして CLAUDE.md を作成）
• トークン予算が上限内：AGENTS.md は 200 行以下、CLAUDE.md は 50 行以下、AGENTS.md の命令形表現は 150 個以下
• プロンプトキャッシュのブレーカーが見つからなかった（または WARN として報告した）
• AGENTS.md のコンテンツ品質チェックに合格した（または問題を報告した）
• AGENTS.md の自動修正可能な問題（コンパクトな指示、MCP ツールの優先設定）を解決した（または dry_run の場合は報告した）
• インポートパターンへの準拠を確認した：CLAUDE.md に @AGENTS.md の行がちょうど 1 行あり、AGENTS.md の内容が重複していない
• 作成ログ、差分の検出結果、実行可能な推奨事項を含むレポートを生成した
• 競合する外部プラグインを検出しなかった（またはユーザーが維持を確認した）
• 構造化された概要を返した
• 管理対象またはスタンドアロンのランタイムパスに概要アーティファクトを書き込んだ

重要なルール：ファイル編集は非破壊的に行うこと。 自動修正では、位置を確認したうえでのみセクションを挿入します。指示ファイル全体を書き換えてはなりません。挿入したセクション以外の既存の内容はすべて保持してください。

バージョン： 2.2.0 最終更新日： 2026-03-25