agent-context-system

核心用法

Agent Context System采用极简的双文件设计解决AI编程助手"每次会话从零开始"的痛点。用户只需维护两个Markdown文件：：AGENTS.md（提交到版本控制，包含项目架构、命令、模式、边界等压缩知识，限制120行以内）和.agents.local.md（gitignored的个人笔记，记录会话日志、死胡同、偏好设置）。初始化脚本init-agent-context.sh自动配置各主流工具（Claude Code通过CLAUDE.md软链接、Cursor通过.cursorrules、Windsurf通过.windsurfrules、Copilot通过copilot-instructions.md）。会话开始时Agent自动读取双文件获取上下文，结束时追加Session Log；当本地笔记超过300行时触发压缩，重复3次以上的模式会被标记到"Ready to Promote"区域，由用户决定是否提升到AGENTS.md。

显著优点

跨平台兼容性是最大亮点，同一套文件系统同时支持Claude Code、Cursor、Windsurf、GitHub Copilot四大主流工具，特别适合多Agent并行的团队场景。Vercel评估数据显示，被动上下文（始终加载）实现100%通过率，远超需要主动检索的53%，该系统正是将关键知识置于"无法错过"的位置。知识演化机制设计精巧：Session Log → 压缩整理 → 模式识别 → 人工审核 → 项目级知识，形成闭环。对于Claude Code用户，其原生auto memory功能可与该系统互补——auto memory处理会话学习，该系统提供结构化提升路径。子Agent支持尤为关键，随着Claude Code subagents和Copilot /fleet推出，并行Agent不再继承对话历史，共享的AGENTS.md成为防止冲突决策的唯一知识源。120行限制和管道分隔的压缩格式（pattern | where-to-see-it）确保指令预算高效利用。

潜在缺点与局限性

依赖用户自律：系统 effectiveness 高度依赖用户主动编辑AGENTS.md和定期执行模式提升，若缺乏维护会退化为普通笔记。工具支持不均：Claude Code目前不原生读取AGENTS.md，需通过CLAUDE.md软链接 workaround，且auto memory与scratchpad存在功能重叠可能让用户困惑。压缩与提升脚本未实现：文档中compress.sh、promote.sh、validate.sh标记为"Not yet implemented"，当前依赖Agent按指令执行或用户手动操作，可靠性存疑。会话结束钩子缺失：多数工具（Copilot Chat、Cursor、Windsurf）没有原生会话结束回调，依赖AGENTS.md中的Rule 7被Agent"看到并执行"或用户主动说"log this session"，存在遗漏风险。行数限制的双刃剑：120行限制虽保证加载效率，但对复杂项目可能迫使过度压缩，损失关键细节。

适合的目标群体

多Agent工具用户：在Claude、Cursor、Copilot间切换的开发者，需要统一的项目上下文。团队协作场景：AGENTS.md作为共享知识库，配合个人scratchpad，平衡标准化与个性化。子Agent重度用户：使用Claude Code subagents或Copilot /fleet进行并行任务分解的开发者，急需防止上下文隔离导致的冲突决策。追求可解释性的用户：相比黑盒的auto memory，该系统提供完全透明、可审计、可手动干预的知识管理。开源项目维护者：MIT许可证和模板化设计便于fork定制，publish-template.sh支持快速创建组织级模板仓库。

使用风险

信息泄露风险：尽管.agents.local.md默认gitignored，但用户可能误配置或强制提交，导致个人笔记（含潜在敏感信息）进入版本控制；publish-template.sh虽检测.env、.pem等敏感文件，但无法覆盖所有场景。内容质量依赖：系统不验证写入内容，若Agent误解指令可能记录错误模式，经多次会话后被错误提升为项目知识。性能与存储：长期运行的项目scratchpad可能膨胀，300行触发压缩的阈值对高频使用者可能过于保守。工具演进风险：Claude Code auto memory持续迭代，可能未来原生支持类似功能导致该系统部分价值被稀释；各Agent工具对AGENTS.md标准的采纳程度不一，存在碎片化风险。迁移成本：已有成熟笔记系统的团队需投入成本迁移到该双文件架构。