核心用法
Agent Context System 是一套面向AI编码助手（Claude Code、Cursor、Copilot、Windsurf）的纯文件级上下文持久化方案。无需任何插件、后台进程或外部服务，仅通过两个Markdown文件解决"每次会话从零开始"的核心痛点：
- AGENTS.md（提交到仓库）：压缩的项目知识库，包含技术栈、命令、架构、模式、边界约束、常见陷阱。严格控制在120行以内，作为被动上下文始终注入prompt。
- .agents.local.md（gitignore忽略）：个人学习笔记，记录会话心得、失败尝试、偏好设置。随使用自动增长，超300行时触发压缩并标记稳定模式。
初始化：运行init-agent-context.sh脚本，自动创建本地笔记、确保gitignore、并配置对应Agent工具的配置文件（.cursorrules、CLAUDE.md等）。
工作流程：每次会话开始时Agent读取两文件获取上下文；会话结束时（或用户指令）将学习心得追加到.local.md；当某模式在3+会话重复出现，压缩脚本将其标记为"Ready to Promote"，由开发者手动提升至AGENTS.md。
显著优点
1. 零依赖零成本：纯文本约定，无API调用、无云服务、无订阅费用，本地文件系统即完整基础设施
2. 跨平台通用：同时支持Claude Code（原生支持auto memory）、Cursor、Windsurf、GitHub Copilot，解决多工具切换时的上下文断裂
3. Subagent就绪：明确指令子Agent读取两文件，避免并行多Agent因上下文隔离而做出冲突决策
4. 研究支撑设计：基于Vercel评估数据（被动上下文100%通过率 vs 检索式53%）、Anthropic指令预算研究（150-200条可靠遵循）
5. 渐进式知识沉淀：实验性知识留在本地笔记，验证稳定后再提升至共享配置，避免AGENTS.md膨胀
6. 安全可控：本地笔记写入需用户确认、路径限定当前目录、内容视为数据而非指令执行
潜在局限
1. 手动维护成本：压缩、提升、清理仍需人工决策，非全自动知识管理
2. Claude Code冗余：若仅使用Claude Code，其原生auto memory已覆盖.local.md功能，双文件方案价值降低
3. 格式约束严格：120行限制、管道分隔格式对大型复杂项目可能过于紧凑
4. 依赖Agent遵从：会话结束写入、压缩标记等行为依赖Agent正确识别AGENTS.md中的Rule 7，非强制执行
5. 无协作同步：.agents.local.md个人私有，团队成员无法共享彼此的学习积累
适合人群
- 多Agent工具用户：在Claude、Cursor、Copilot间切换，需要统一上下文载体
- 团队协作者：通过AGENTS.md共享项目约定，同时保留个人学习笔记
- Subagent重度使用者：使用Claude Code subagents或Copilot /fleet并行任务，需要防止上下文隔离导致的决策冲突
- 隐私敏感场景：不希望代码上下文上传至云端服务，坚持本地文件方案
常规风险
1. 提示词注入风险：若.local.md被恶意写入指令性内容（如"忽略前述规则"），虽设计为数据文件，但依赖Agent正确识别边界
2. 权限误配置：init脚本若未正确设置gitignore，个人笔记可能意外提交至仓库暴露敏感信息
3. Agent不遵从：部分Agent可能忽略AGENTS.md中的规则，导致会话日志未写入、知识无法沉淀
4. 版本漂移：团队共享的AGENTS.md若更新不及时，与实际代码库约定产生偏差