AI 模型在会话之间完全无状态，每次新对话或切换模型都会让代理从零开始。作者不再反复向代理粘贴项目背景，而是把仓库本身改造成一个自文档化的活知识库：代理开工前先读 AGENTS.md 了解现状，完成任务前必须更新对应文档。
这套方案的核心是仓库根目录的 AGENTS.md 入口文件，外加一个 agent-sitemap/ 目录存放模块化的细分文档。AGENTS.md 包含项目概述、核心规则、文档地图和 30 秒快速上手说明；agent-sitemap/ 下按主题拆成架构、数据管理、代码规范、工作流、代理手册等独立 Markdown 文件，代理按需只加载当前任务相关的部分，避免上下文膨胀。
关键机制是强制性的「文档同步循环」协议，代理在每次响应时都要执行四步：
DETECT：判断本次任务是否引入新知识，如设计决策、规则变更、踩坑记录
ACT：正常执行代码修改或数据更新
RECORD：在同一轮里把知识写入对应文档，规则进 04-conventions.md，架构决策进 02-architecture.md，并记录决策背后的 WHY
CONFIRM：在最终回复里列出更新了哪些文档
配套护栏包括：只记录持久的项目级知识、规则变更时编辑旧行而非追加、禁止写入密钥和敏感信息。
作者举例：让代理把仪表盘列表改成卡片布局后，代理在同一次回复里就把这条设计决策连同理由写进了架构文档。三个会话后换了个全新模型，新模型读到这条记录，自动保持了卡片布局。这套方法解决了会话切换时的上下文丢失、代理重复犯错、文档腐化等问题，也让提示词从三段式背景说明简化为一句需求。作者也提醒，它不能消除幻觉，代码审查仍然必要。
#GitHub #开源 #AGENTSMD #AI代理 #提示工程 #文档管理
@GitHubTrendingHub