全局上下文应置于 APC 之外

APC 是可移植的上下文层。APX 是本地运行时层。

为了保持这两者的健康运行，请遵循一个原则：如果某些内容必须在重新克隆（clone）后依然存在，请将其放入 APC。如果它依赖于特定的用户、机器或进程，请将其保留在 APC 之外。

随着项目的增长，诱惑也随之而来。你可能会想再添加一个设置或一个本地路径。如果你不够严格，你的仓库（repo）就会变成机器数据的堆填区。这会让仓库变得脆弱。

APC 承载着项目特有的含义。它是仓库所携带的共享契约。

良好的 APC 内容包括：

  • 项目身份
  • Agent 角色
  • 可复用的技能
  • 精选的项目记忆
  • 项目级 MCP 提示
  • AGENTS.md 中的全仓库指令

队友或新机器在执行 checkout 后应能立即读取这些事实。

全局上下文则不同。它属于用户或工作站。

全局上下文的示例：

  • API 密钥
  • 编辑器偏好
  • 本地别名
  • 特定机器的工具路径
  • 私有运行时内存
  • 缓存
  • 会话转录
  • 消息日志

APX 将这些状态保持在本地。它将运行时状态存储在 ~/.apx/ 下。这保证了项目的可共享性。

混合这些层会导致三个问题：

  1. 可移植性破坏。依赖本地配置的仓库难以信任。
  2. 代码审查变得杂乱。Pull request 应该展示项目决策，而不是工作站的杂物。
  3. 密钥泄露。存储本地细节很容易导致提交错误的文件。

在添加设置之前，请问自己一个问题： 其他贡献者在克隆后是否需要立即使用它？

如果是，请使用 APC。

  • 为每次克隆都准备一个审查 Agent？使用 APC。
  • 个人 API 密钥？不使用 APC。
  • 关于权限的项目决策？使用 APC。
  • 本地浏览器路径？不使用 APC。
  • 共享的 MCP 提示？使用 APC。
  • 运行缓存？不使用 APC。

这一规则使自动化更具持久性。APC 为你提供可移植的含义。APX 为你提供本地状态。

保持界限清晰。这会让你的技术栈更容易调试、共享以及在不同工具间迁移。

对于随仓库一起移动的上下文，请使用 APC。如果是个人或瞬态的，请保持在本地。

Source: https://dev.to/agentprojectcontext/global-context-belongs-outside-apc-4fg8

Optional learning community: https://t.me/GyaanSetuAi