SuperAPI AI 工具集

doc-gardening

智能体与模型

查看项目

更新于 10-15 23:42

技能介绍

用途:在由智能体管理的仓库中,AGENTS.md 与 README 往往是合并冲突最集中的文件,因为每次改动都会经过它们。该技能的目标是少写、多删,并把保留内容放到只有相关改动才会触及的位置。

主要能力与原则:AGENTS.md / CLAUDE.md 只放“伤疤”和“不变量”。伤疤指开发中付出代价才得到的非显然约束,例如反复出现的缺陷类型、每次会话都被重新争论的设计问题、智能体不被告知就会踩的坑;不变量指必须成立的规则。不要写工作状态(状态、进度日志、TODO、正在实现 X),不要写索引或复述(子命令列表、命令帮助输出、文件清单、目录树、依赖列表),这些用 glob 或 --help 几秒即可发现,写下来只会过时。用户文档(README、指南)面向人和智能体说明如何使用产品,按任务组织,讲概念、工作流和用户必须做的决策,同样不要复述工具已报告的内容。

可发现性测试:写入任何事实前先问,新智能体能否用一次 grep、一次 glob 或一次 --help 在一分钟内得知?能则不写,已存在则删除。只写无法被发现的内容:意图、约束,以及为什么显而易见的方法会失败。

修剪:每次编辑指令文件都应寻找可删除的内容。过时条目比缺失条目更糟,因为缺失会被查证,过时会被信任。工作状态腐烂最快,PROGRESS.md 式文件、已实现部分和清单在状态变化一周后即成错误信息,发现即删,先把持久教训转为伤疤。当伤疤背后的约束消失时,应在移除约束的同一次改动中删除该伤疤。

分片:根 AGENTS.md 或 CLAUDE.md 保存不变量、伤疤,以及每个模块最多一行指向该模块自身文档的链接。模块细节放在模块文档中。功能改动更新其模块文档;根文件仅在模块出现或消失、或不变量变化时改动,从而把根文件移出每次提交的影响范围。若根文档为每个模块写了段落级架构条目并重复模块文档,应缩为一行加链接,把独有内容移入模块文档。

限制:资料未提供具体安装命令、平台支持、收费或价格信息。