agents-progressive-disclosure

Agent 指令渐进式披露

使用此技能，将冗长的 Agent 指令文件转换为高信号入口文件，并将其路由到聚焦的文档文件。目标是在减少始终加载的上下文的同时保留规则。

核心模型

将根指令文件视为路由器，而不是规则仓库。

• 入口文件只保留高频、长期有效且始终必须遵循的规则。
• 将详细的任务特定规则移至 docs/ 文件。
• 入口文件应包含清晰的“何时阅读此文档”索引。
• Agent 只应加载与当前任务相关的文档。

工作流

1. 找出目标指令文件。

   • 除非用户指定其他文件，否则优先选择当前目录中的 AGENTS.md。
   • 同时支持 CLAUDE.md、GEMINI.md 或项目特定的同类文件。
   • 如果存在多个候选文件，且用户未指定其中之一，应报告这些候选文件，并选择当前 Agent 配置中使用范围最广的文件；只有在无法明确判断或选择存在风险时才询问用户。

2. 检查现有结构。

   • 完整阅读目标文件。
   • 列出已有的 docs/ 文件（如有）。
   • 编辑前检查是否存在备份。

3. 分类前检测矛盾。

   • 检查是否存在相互冲突的风格规则、包管理器选择、测试命令、安全边界、优先级声明，或措辞不同的重复规则。
   • 尽可能依据用户明确指示、指令文件的优先级顺序或清晰的本地证据解决矛盾。
   • 只有当矛盾会影响重构，且无法根据现有证据解决时，才询问用户。

4. 将规则分类。

   • 保留在入口文件中：语言默认设置、安全边界、工具优先级、冲突优先级，以及关键的始终必须遵循的规则。
   • 移至文档：命令目录、搜索策略、框架特定指令、包管理器规则、环境设置、Git 工作流、部署、测试、文档风格、领域术语、长篇示例。

5. 设计文档映射。

   • 优先采用项目现有的 Agent 文档约定；否则，默认使用 docs/，以便跨 Agent 通用。
   • 现有约定可能包括 .claude/、.claude/rules/、.cursor/rules/ 或其他 Agent 文档目录。
   • 如果现有文档名称合适，就沿用；否则，根据源规则类别拟定聚焦的名称。
   • 保留平台特定的文件格式、必需的 frontmatter、导入项、路径 glob 和文件扩展名。
   • 只有在有助于浏览多个文档时，才创建 docs/README.md。

6. 谨慎编辑。

   • 替换目标文件前，在同一目录中创建一个不会覆盖现有文件的备份。
   • 将入口文件改写为精简的路由器，包含：
     • 范围说明；
     • 核心原则；
     • 按需查阅的文档索引；
     • 始终生效的安全和工具规则；
     • 优先级规则。
   • 将详细规则移至文档，同时保持其原意不变。
   • 避免在多个位置重复相同的长篇规则。

7. 验证内容保留情况。

   • 创建一份简短的保留情况清单，将原有的每个规则类别映射到其新位置、一个验证关键词或标题，以及通过/未通过结果。
   • 将清单视为临时验证工作；除非用户要求，或项目已有迁移说明约定，否则不要将其写入仓库。
   • 比较编辑前后的行数。
   • 在新的入口文件和路由指向的文档或规则文件中搜索原文件中的清单关键词。
   • 确认入口文件说明了未来的 Agent 在何种情况下应阅读每份文档。
   • 检查文档是否与入口文件存在矛盾。

建议的入口文件结构

# Agent Instructions

> Scope: This file is the entrypoint. It keeps only always-on rules; task details live in docs/.

## Core Principles

- [language/default behavior]
- [safety boundary]
- [primary tool or evidence policy]
- [this file is a router, not a warehouse]

## Read-On-Demand Index

| Task type | Read first | Trigger |
| --- | --- | --- |
| [rule cluster] | `[focused-doc]` | [when to read it] |
| [rule cluster] | `[focused-doc]` | [when to read it] |

## Always-On Rules

- [short critical rules]

## Priority

1. User's current explicit instruction.
2. Nearest project instruction file.
3. This file.
4. Routed docs details.

验证命令

使用与当前环境兼容的命令，并将占位符替换为实际的目标文件、路由后的文档/规则文件，以及保留清单关键词。以下示例使用 POSIX 风格的 Shell 命令；如有需要，请针对 Windows 或其他 Shell 进行调整。

find <docs-dir> -maxdepth 1 -type f -print | sort
wc -l <target-file> <routed-docs...>
rg -n '<checklist-keyword>|<another-checklist-keyword>' <target-file> <routed-docs...>
sed -n '1,180p' <target-file>

从源文件中选择清单关键词，而不是从此模板中选择。

防护措施

• 不要仅仅因为规则冗长就删除它们；应将其移至合适的文档中。
• 不要只在路由后的文档中放置安全关键规则。
• 不要创建许多职责重叠的零散小文档。
• 除非用户提出要求，否则不要添加源文件中未提及的项目特定意见。
• 除非确实将技能复制或安装到当前启用的技能目录中并进行了验证，否则不要声称已将其安装到 Codex 中。