开源项目渐进式披露：精简AGENTS.md提升AI Agent效率

背景

随着 AI 辅助编程的普及，AGENTS.md 文件已成为许多开发者与 AI 代理（Agent）交互的核心配置文件。它通常用于定义 AI 的行为准则、项目结构、编码规范以及常用工作流。然而，随着项目复杂度的增加，AGENTS.md 往往变得臃肿不堪，包含大量细枝末节的指令和上下文信息。

这种“大而全”的文件带来了显著的问题：

1. 上下文窗口浪费：AI 模型在处理请求时，需要加载整个 AGENTS.md 内容，导致宝贵的上下文窗口被大量非关键信息占用。
2. 维护成本高：随着项目迭代，修改单一规则可能需要重新审视整个文件，容易引入冲突或遗漏。
3. 检索效率低：AI 难以从海量文本中快速定位到当前任务所需的具体规范。

在此背景下，LINUX DO 社区用户提出了一种名为“渐进式披露”（Progressive Disclosure）的策略，旨在通过重构 AGENTS.md 的结构，解决上述痛点。

核心内容

该方案的核心思想是将 AGENTS.md 从“全能说明书”转变为“精简入口”，并配合专项文档目录（docs/）实现信息的按需加载。具体实施步骤如下：

1. 工具引入

通过安装开源 Skill agents-progressive-disclosure 来辅助重构。安装方式支持直接通过 npx 命令执行：

npx skills add Caph-dev/agents-progressive-disclosure

或者直接将项目链接发送给 AI Agent，让其自动完成安装。

2. 重构流程

使用上述 Skill 对现有的 AGENTS.md 进行自动化重构，主要动作包括：

• 精简入口文件：保留 AGENTS.md 中的核心指令、全局配置和关键路径指引，移除过于详细的技术细节和特定场景的长篇幅说明。
• 建立专项文档：将剥离出的详细技术规范、特定流程说明、API 参考等内容，整理并存放至项目根目录下的 docs/ 文件夹中，形成结构化的专项文档。

3. 人工校验与调整

自动化重构完成后，开发者必须进行人工审查。重点检查以下问题：

• 颗粒度是否合理：当前的分类是否过于细致，导致文档碎片化？
• 高频流程的处理：某些常用且简单的流程是否真的有必要放入 docs/ 下？如果某些指令使用频率极高且简短，保留在 AGENTS.md 中可能更高效。

4. 实际效果示例

重构后的全局 AGENTS.md 示例显示，文件长度大幅缩减，仅保留核心导航和关键约束，而详细的技术实现细节则通过链接或指引指向 docs/ 中的具体文件。

关键要点

• 按需加载机制：技术文档可以写得非常详细，因为只有在 AI 处理特定任务时，才会根据 AGENTS.md 中的指引去加载对应的 docs/ 文件。这类似于将技术文档提炼为独立的 Skill，既保持了主文件的精简，又保留了信息的完整性。
• 上下文优化：通过移除冗长的非关键信息，显著节省了 AI 模型的上下文窗口（Context Window），降低了 Token 消耗，并提高了响应速度和准确性。
• 维护性提升：将不同模块、不同技术栈的规范分散到独立的文档中，使得单一规则的修改不再牵一发而动全身，降低了长期维护的成本。
• 人机协作必要性：自动化重构仅是第一步，开发者必须亲自检查重构结果，确保分类逻辑符合项目实际，避免过度拆分或遗漏关键指令。
• 开源合规性：该项目遵循 LINUX DO 社区的开源推广要求，代码完全开源，且 AI 生成/润色内容已按规定公示，接受社区监督。

意义与影响

这一实践标志着 AI 辅助开发工作流从“粗放式配置”向“精细化工程”的演进。

1. 提升 AI 协作效率：通过结构化信息，让 AI 更快速地理解当前任务所需的上下文，减少因上下文过载导致的幻觉或指令遵循偏差。
2. 标准化项目结构：为大型 AI 驱动的项目提供了一种可复用的文档组织范式，即“核心指令精简 + 详细规范模块化”。
3. 降低使用门槛：对于新手开发者，清晰的文档结构比堆砌在单一文件中的长文本更易于理解和遵循。
4. 推动 Skill 生态发展：该方案鼓励将特定功能或规范封装为独立的 Skill 或文档模块，丰富了 AI 工具链的可组合性，符合模块化软件工程的趋势。

总之，“渐进式披露”不仅是一种文档管理技巧，更是一种优化人机交互体验的工程哲学，值得在复杂的 AI 辅助开发项目中推广使用。