ln-014-agent-instructions-manager

路径： 所有文件引用均相对于 skills 仓库根目录。

Agent 指令管理器

类型： L3 工作器
类别： 0XX 共享

创建缺失的指令文件，并审查这些文件（AGENTS.md、CLAUDE.md）的质量、一致性和最佳实践。AGENTS.md 是内容的唯一规范来源；CLAUDE.md 是精简的 @AGENTS.md 导入存根，仅包含范围受限的运行框架专属差异。此技能是创建指令文件以及插入或替换 MCP Tool Preferences 的唯一负责人。

必须读取： 加载 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：发现文件

在目标项目中查找指令文件：

Agent	主要文件	规范来源	回退方案
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/* 下查找匹配的插件或 marketplace
   • 从该安装位置读取当前启用的 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 个 → safe
5. CONFLICT："CONFLICT: {plugin} overlaps with ln-* pipeline ({signals}). Disable?" → AskUserQuestion → 如果选择是，则在 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，且总行数 ≤50
5. 不要将 AGENTS.md 中的任何内容复制到 CLAUDE.md — @ 导入会在会话加载时处理

步骤 2e：报告创建结果

列出每个已创建文件及其来源（模板 agents_md_template.md、模板 claude_md_template.md 存根）。

阶段 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）。

阶段 4：提示词缓存安全

检查每个文件是否包含会破坏基于前缀的提示词缓存的内容：

#	检查项	模式	严重级别
1	不含时间戳	grep -E '\d{4}-\d{2}-\d{2}.\d{2}:\d{2}'	WARN
2	内容中不含日期	`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

阶段 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	Compact Instructions 部分简洁	AGENTS.md 中存在包含保留优先级的 ## Compact Instructions	缺失——会话在 /compact 时会丢失决策
6	MCP 工具偏好	AGENTS.md 中的规范策略部分与 references/mcp_tool_preferences.md 一致	缺失或过时——Agent 会使用次优工具
7	不含工具输出示例	不含大型代码块或命令输出	发现相关内容——会使每轮内容膨胀

检查项 #1–#6 仅评估 AGENTS.md，因为 CLAUDE.md 通过 @AGENTS.md 导入继承该内容。增量本身的检查见阶段 6。

阶段 5b：自动修复可修复的问题

对于阶段 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	缺失或多行 — FAIL
2	CLAUDE.md 差异范围受限	文件总行数 ≤50	>50 行 — FAIL，并提供偏差报告
3	内容没有重复	AGENTS.md 中没有任何章节或规则在 CLAUDE.md 中再次出现	发现重复 — FAIL，并指出具体重叠行

偏差处理规则： AGENTS.md 是权威来源。对于每项不一致：

• (a) 如果 AGENTS.md 缺少某项内容，但 CLAUDE.md 中有 → 将其移至 AGENTS.md，然后从存根中删除。
• (b) 如果 CLAUDE.md 重复了 AGENTS.md 的内容 → 替换为一行 @AGENTS.md 导入语句。
• (c) 如果存根差异超过 50 行 → 将真正特定于运行环境的内容拆分到 .claude/rules/*.md；其他所有内容移至 AGENTS.md。

不要根据内容量「建议哪个文件是权威来源」——AGENTS.md 始终是权威来源。

如果 .hex-skills/environment_state.json 报告 agents.codex.discovery_violation=true，请发出 WARN，说明 Codex 技能发现机制已发生偏差；在 ln-013-config-syncer 修复 marketplace/plugin 对齐问题之前，不得将陈旧缓存中的重复技能计数作为指令审计的证据。

如果 .hex-skills/environment_state.json 报告 agents.codex.permissions_default_ready=false，请发出 WARN，说明 Codex CLI 启动权限已偏离受管默认设置；在 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

跨 Agent 说明： Codex CLI 0.120（2026-04-11）现在支持 SessionStart hook，可区分 /clear 与全新启动／恢复会话，与 Claude Code 的行为一致。

完成定义

• 已发现所有指令文件
• 已创建缺失文件（先根据模板创建 AGENTS.md；再创建作为 @AGENTS.md 导入存根的 CLAUDE.md）
• Token 预算在限制范围内：AGENTS.md ≤200 行、CLAUDE.md ≤50 行、AGENTS.md 命令式指令数 ≤150
• 未发现提示词缓存失效因素（或已作为 WARN 报告）
• AGENTS.md 内容质量检查已通过（或已报告问题）
• 已解决 AGENTS.md 中可自动修复的问题（Compact Instructions、MCP Tool Preferences），若为 dry_run 则已报告
• 已验证导入模式合规性：CLAUDE.md 恰好包含一行 @AGENTS.md，且未重复 AGENTS.md 的内容
• 已生成报告，包含创建日志、偏差发现和可执行建议
• 未检测到冲突的外部插件（或用户已确认保留）
• 已返回结构化摘要
• 已将摘要产物写入受管或独立运行时路径

关键规则：非破坏性文件编辑。 自动修复仅在已验证的位置插入章节。切勿重写整个指令文件。保留插入章节之外的所有现有内容。

版本： 2.2.0 最后更新： 2026-03-25