用途:把项目共享知识放在第二位读者能触及的地方,包含术语表、决策记录和研究文档三类记录,各有格式说明位于 references/ 目录。
主要能力与存放位置:术语表放在根目录 GLOSSARY.md,或按 GLOSSARY-MAP.md 列出的每个上下文各一份,格式见 references/glossary-format.md;决策记录放在 docs/adr/NNNN-slug.md,格式见 references/adr-format.md;研究文档放在 docs/research/<date>-<question>.md,或 docs/agents/conventions.md 指定的路径,格式见 references/research-document.md。文件按需创建:首个术语确定时建术语表,首个决策符合条件时建 docs/adr/,某个来源教会了东西时建研究文档。
规则:DECIDE-1,只为难以逆转、令人意外且无真正替代方案的权衡写记录,三者须同时成立,一段话即可;DECIDE-2,术语表术语有主张且不含实现细节,一个概念一个术语,其余列入 avoid,用一两句话说明是什么;DECIDE-3,术语表、研究文档和计划表格使用固定列并写明校准,每行校准必须写出(如 unverified),不得留空,决策记录是散文例外;DECIDE-4,记录不写人名,只写系统与角色;DECIDE-5,一个主题一个文件,不覆盖非本次会话创建的文件,新日期文档放在旧文档旁;DECIDE-6,与记录冲突要显式提出,而非静默覆盖。
使用方式:设计前先读 GLOSSARY.md 和 docs/adr/ 下相关记录;术语与术语表冲突时立即指出;术语含糊或过载时提出规范术语;用具体场景压力测试关系;陈述与代码不符时指出矛盾;术语确定后立即写下,不要批量更新。
适用场景:架构形态、上下文间集成模式、有锁定风险的技术选型、边界与范围决策、对明显路径的有意偏离、代码中不可见的约束、非显而易见的被拒替代方案。
限制:资料未提供具体安装命令、收费、平台或效果信息。