agents-md

管理 AGENTS.md

AGENTS.md 为编码 Agent 提供范围明确、内容最新且针对特定仓库的指引。它不是 README、运行手册、架构文档、变更日志、教程或证据记录。优质指引有证据支撑、简洁明了、适用于该文件所在目录树的范围，并且能指导行为：告诉 Agent 在此仓库中应如何调整做法。

适用场景

• 创建、更新、审查、拆分、移动或修复仓库中的 AGENTS.md。
• 记录已验证的本地命令、仓库约定、路径归属或 Agent 经常犯的错误。
• 将仓库证据转化为供未来 Agent 遵循的规则。

不适用场景

• 独立技能、提示词、全局指引、README、架构文档、变更日志或运行手册。
• 将 AGENTS.md 并非明确交付物的广泛文档重写。
• 缺乏当前仓库证据支持的理想化流程指引。

模式

• patch：小型文本修正、拼写错误、过时路径或范围有限的规则变更。仅检查受影响的章节和相关证据。
• create：不存在合适的 AGENTS.md。运行分析器，抽样查看源文件、配置和文档，然后起草最精简实用的文件。
• update：现有文件需要新增或修正指引。保留有效规则，移除过时或重复的内容，只添加有证据支持的变更。
• split/move：范围边界正在变化。检查现有根目录和嵌套文件，然后参照 references/topology-and-handoff-guidance.md。
• review：除非有人要求，否则不要编辑。按严重程度列出发现，并提供证据及剩余风险。
• exhaustive：适用于单体仓库、契约密集型仓库、安全敏感型指引、运维交接、重大拓扑变更或证据不明确的情况。

工作流

1. 选择模式和目标范围。阅读最近的现有 AGENTS.md、可能存在范围重叠的嵌套 AGENTS.md，以及可用时的 git status --short。
2. 对于 create、update、split/move 或 exhaustive 模式，运行 python <skill-root>/scripts/analyze_project.py --repo-root <target-repo> --format json。将其视为抽样指南，而非权威依据。
3. 有关常规编写细节，请参阅 references/normal-authoring.md。只检查支撑所述主张所需的来源。
4. 从 references/template-selection.md 中选择最精简且适用的模板起草。除非仓库明显需要专用模板，否则优先使用 assets/agentsmd-minimal.md。
5. 将证据保存在工作笔记或最终摘要中。仅当仓库已有证据文件，或用户提出要求时，才添加证据文件。
6. 使用 python <skill-root>/scripts/validate_agentsmd.py --repo-root <target-repo> --agents-file <target-agents-file> --mode <quick|standard|exhaustive> 和 python <skill-root>/scripts/semantic_check_agentsmd.py --repo-root <target-repo> --agents-file <target-agents-file> 进行验证。

规则质量标准

仅保留符合以下条件的规则：

• 具体：指出实际路径、命令、约定或本地规范。
• 当前有效：有现存文件或用户提供的当前事实作为支持。
• 范围明确：适用于此 AGENTS.md 所涵盖的目录树。
• 指导行为：能改变 Agent 应采取的做法。
• 有证据支持：可追溯至已检查的仓库证据。
• 安全：避免涉及机密、未授权访问、破坏性命令和生产环境执行。
• 不重复：不复述全局指引、语言基础知识或 README 内容。
• 简洁：足够精炼，便于日常编码时快速浏览。

升级矩阵

仅在任务需要时加载额外参考资料：

触发条件	阅读
工具、CLI、MCP、API、生成文件、迁移、架构或公共契约指南	references/contract-bearing-agentsmd.md
拆分、移动、嵌套作用域、过时拓扑或所有权交接	references/topology-and-handoff-guidance.md
实时操作、工具降级、手动分派、停止状态或环境重置	references/degraded-tool-surface.md、references/evidence-invalidation.md
子 Agent 或委派式审查工作流	references/subagent-coordination-patterns.md
Python、TypeScript、其他技术栈、Databricks/Spark 或 ML 专属证据提示	references/language-specific/python-guidance.md、references/language-specific/typescript-guidance.md、references/language-specific/other-stack-guidance.md、references/domain-specific/databricks-spark.md、references/domain-specific/ml-projects.md
仅审查或需要大量判断的审计	references/manual-audit.md

最终回复

对于编辑模式，请列出更改的文件、新增/更改/删除的规则、抽查的证据来源、验证命令及结果，以及剩余风险。

对于审查模式，按严重程度排序列出发现的问题。每项发现都需指出受影响的 AGENTS.md 章节或行、支持性仓库证据、问题的重要性以及建议的修复方案。随后列出待解问题、测试/验证缺口，最后再简要总结。

确定性工具

工具	用途
scripts/analyze_project.py	技术栈、配置、测试、路径和建议清单
scripts/validate_agentsmd.py	结构验证
scripts/semantic_check_agentsmd.py	路径、命令、链接和示例验证
scripts/check_agentsmd_templates.py	技能模板和指南规范检查
scripts/run_agentsmd_fixture_checks.py	验证器变更的已知夹具行为检查

参考资料

• references/tool-contracts.md 和 references/template-selection.md - 辅助 CLI 契约、模式和模板
• assets/agentsmd-minimal.md、assets/agentsmd-contract-bearing.md、assets/agentsmd-operational.md、assets/agentsmd-full.md - 起始模板
• assets/example-validated-agentsmd.md、assets/example-contract-bearing-agentsmd.md、assets/example-operational-agentsmd.md、assets/writing-tips.md - 简明示例