Portable Agent Project Operating Protocol — Documentation skill for Claude Code

Portable Agent Project Operating Protocol v5.0.0

[English](README_EN.md) · [为什么要用状态机](docs/WHY.md) · [状态机怎样工作](docs/HOW.md) · [安装指南](docs/INSTALL.md) · [从旧版迁移](docs/MIGRATION.md)

PAPOP 是一套给 Agent 使用的工作规则和项目状态机。

这里的 **Agent**，就是能读取文件、修改内容、运行命令并连续完成任务的 AI；**Harness** 是承载 Agent 的工具，例如 Codex、Claude Code、OpenCode、ZCode 或 DeepSeek Harness。

普通聊天主要依靠当前对话里的上下文。对话变长、发生自动压缩、换模型或隔几天继续时，细节可能丢失。PAPOP 把最终目标、计划、用户决定、当前状态和历史证据写入项目文件，使 Agent 能从磁盘恢复，而不是猜测自己上次做到了哪里。

**你需要做什么**

安装只做一次。日常使用时，你真正需要做的是下面这些事：

1. 开始项目时说清最终想得到什么。 Agent 会和你讨论需求。一个 Task 就是一个项目；同一项目换对话继续时，应当继续原来的 Task，不要重复创建。
2. 选择适合你的工作方式。 想逐个把关就使用 Strict Approval；愿意把整个任务交给 Agent 就使用 Autonomous。模式会写进 Task，不能因为后来替换规则文件而静默改变。
3. 严格审批模式下，认真处理四个审查点。 你需要依次确认需求、审批 goal.md、阅读并审批当前阶段的 plan.md、查看真实交付物后决定是否验收。不要只回复“继续”；要明确说哪里正确、哪里要改、是否批准当前版本。
4. 自主推进模式下，先说清授权边界。 Agent 可以在这个边界内连续工作，但关键决定、具体外部动作、不可逆操作、你设置的关卡以及最终目标变化，仍然会停下来等你决定。
5. 主动管理上下文。 如果 Harness 能显示上下文占用，建议在大约一半时准备压缩；即使看不到占用，也建议在一个 Stage 完成并落盘后压缩。先让 Agent 保存检查点，并确认脚本输出 CHECKPOINT_COMMITTED，再手动压缩。不要等自动压缩先发生，因为尚未落盘的细节可能丢失。
6. 压缩、更换模型或换一次新对话后，先核对恢复结果。 Agent 必须重新读取 goal.md 和当前状态，并向你复述最终目标、当前阶段、已有批准、未完成事项和下一步。复述不对就立刻纠正，不要让它带着错误继续施工。
7. 验收时看实际产物和机器证据。 测试、脚本和 diff 负责验证；Agent 不能靠一句“已经完成”证明结果正确。AGENT_COMPLETION=COMPLETE 只表示 Agent 做完了自己的部分，不等于你已经验收。
8. 随时给文件，但保留原件。 你引用当前 Task 外的文件时，Agent 会把它复制到该 Task 的 UserInput/。工作区外的源文件只复制、不询问删除；工作区内但在 Task 外的源文件，复制并验证后才会询问你是否删除。
9. 自己备份整个 Task。 .agent-state/ 默认被 Git 忽略，PAPOP 不提供自动备份、同步或导出。备份或迁移时必须复制完整 Task 目录，并确认隐藏的 .agent-state/ 也在其中。

日常主流程如下。更完整的状态、账本和恢复说明见 [HOW.md](docs/HOW.md)。


先选择一个发布包

PAPOP v5 提供三个 ZIP。只安装其中一个，不要把两种状态机同时放进同一工作区。

发布包	适合谁	Agent 如何工作
GlobalRules Only	只想规范 Agent，不需要项目状态机	约束证据、权限、Git、.gitignore、.venv、依赖、代码修改、验证和外部动作
Strict Approval	希望重要阶段都由人确认	需求确认 → Goal 审批 → Stage Plan 审批 → 施工和验证 → Delivery 验收
Autonomous	愿意把整个 Task 委托给 Agent	在授权范围内持续推进，遇到关键决定、具体授权或