一个文件夹，不等于一个智能体项目。它里面可能有代码、有笔记、有一段好用的提示词，但智能体运行时要把这个文件夹当成可持续推进的工作，还得先回答两个问题：这里适用什么指导？这到底是哪个项目？

APC 和 APX 用两个小文件把答案写死：AGENTS.md 存放共享指令，包括约定、约束、命令和项目专属上下文；.apc/project.json 存放稳定元数据，包括项目名称，以及 APX 管理该项目时的稳定标识 apx_id。

这对文件构成一条实用边界。在 APX 里，apx project add 会同时读取这两个文件。缺任何一个，注册就会停下，而不是去猜某个随便的目录是不是一个完整项目。

为什么一个文件不够

只有 AGENTS.md 而没有元数据，它能说明工作该怎么做，却给不了运行时一个稳定身份来对应本地状态。两份检出可以有相似的指令，运行时仍然需要知道，哪一个本地项目存储属于这一份。

只有 project.json 而没有指令，问题正好相反。它能给项目起名，却没法告诉智能体这个仓库的规则、安全边界和预期工作流。有身份没指导，注册就退化成一个标签，而不是一份可用的契约。

两个文件也把职责分清楚了。APC 是可移植的上下文层：把共享契约随仓库一起提交。APX 是日常使用的运行时：它使用这份契约，同时把会话、对话、消息、缓存、任务日志和机器专属配置放在 ~/.apx/projects/ 下。

一套小而可靠的配置

从这样的仓库根目录开始：

  • my-project/
  • ├── AGENTS.md
  • └── .apc/
  • 　　└── project.json

让 AGENTS.md 专注于队友和兼容工具应当共享的指导。让 project.json 专注于稳定元数据。两个文件都不要放 API 密钥、原始会话日志或私有的运行时记忆。

然后显式注册项目：apx project add .

APX 可以通过 apx_id 把已提交的项目定义链接到本地运行时目录。如果仓库移动了位置，运行时需要重新扫描磁盘上的契约，就用 apx project rebuild。

关键细节不在命令本身，而在于拒绝凭空补出缺失的上下文。一个运行时如果悄悄注册了没有指令的文件夹，本该遵守项目规则的地方可能退化成通用行为；一个运行时如果自己发明身份，就可能把本地历史挂到错误的工作边界上。

可用的规则很简单：在让智能体运行时接手持续进行的工作之前，先给项目配齐指令和身份。AGENTS.md 说明贡献者应当怎么做，.apc/project.json 说明他们是在哪个持久项目定义里做。

这就是分工：APC 让契约保持可移植、可审查；APX 让它在单台机器上运转起来，同时不把私有的运行时状态提交回仓库。