多 Agent 项目为什么越做越乱？用 Piyaz 把任务依赖、执行记录与 PR 审核接成一条链
把 Claude Code、Codex 或 Cursor 同时放进一个仓库，最先失控的通常不是生成代码的速度，而是项目状态：谁正在改哪一块？某个决定为什么做出？上游接口已经变了吗？PR 虽然开了，是否真的满足验收条件？如果答案散落在聊天记录、Issue、终端滚屏和人的记忆里，第二个 Agent 很容易从过期前提出发，造成重复劳动或把冲突带回主分支。
Piyaz 把这个问题当成项目图谱而不是待办清单来处理。它是一个带 Web 应用的 MCP 服务：任务、依赖边、决策和执行记录落在同一个项目图中；编码 Agent 则通过插件和 MCP 读写这些状态。项目同时提供托管服务，也可按 AGPL-3.0 自托管。
本文不把它当作“再多一个看板”，而是从一个多 Agent 常见失败场景出发，看看怎样把计划、实施、审查和人工合并连接起来。
失败场景：两个任务各自正确，组合后却不正确
设想你要给已有 CLI 增加“按 Conventional Commits 生成 changelog”的能力，并支持 monorepo。一个 Agent 在实现解析与分组；另一个 Agent 在增加配置和输出格式。若两者只收到自然语言任务，它们可能各自写出能跑的代码，却对以下事实没有共同认知：
- 输出格式的选择会影响解析层暴露的数据结构；
- 配置任务应等待解析任务确定接口后再开始；
- 解析任务如何处理 breaking change，必须作为下游可见的决策留下来；
- 代码完成并不等于可以合并，仍要把 diff 与验收条件逐项对照。
Piyaz 的核心单位不是孤立卡片，而是带依赖关系的任务图。官方文档说明，在分解阶段每个任务可以包含动词式标题、简短描述、两到四条可测试的验收条件、分类以及依赖边。这样“配置输出格式”不是仅写着“做配置”，而是显式依赖“定义解析结果”。当上游尚未完成，下游不会被当成 ready work 分发。
从想法到可执行图：先把模糊需求压缩成可验证任务
在 Claude Code 中安装插件后，可以用 /piyaz 触发规划流程。下面的输入来自官方文档中的工作方式；它不是 shell 命令，而是交给已连接 Piyaz 的 Agent 的自然语言任务。
/piyaz I want a cli that generates changelogs from conventional commits, with monorepo support
随后 Piyaz 会先通过聚焦问题补齐用户、功能、技术方向与约束，等待确认后再分解任务。这里最值得保留的不是“自动拆任务”本身，而是把验收条件写成二元判断。例如可以要求：解析层能识别 conventional commit 类型与 breaking change；monorepo 仅汇总指定包的提交；输出测试覆盖空提交和跨包提交。这样后续审查不必猜测“差不多完成”是什么意思。
任务创建时将边和任务一起保存，也减少了先建一堆卡片、再靠口头补依赖的窗口。项目恢复时，Agent 可以先询问关键路径与 ready 集合，而不是从仓库里猜哪个文件最急。
执行时记录“事实”，不要只记录状态
真正让多 Agent 协作可续接的是执行记录。Piyaz 的执行文档要求 Agent 在完成任务后写回三类内容：做了什么（含函数、文件和实现模式）、关键技术决策及其原因、创建或修改的文件。下游任务读取上下文时，能获得上游的执行记录、依赖边说明与状态，而不是只看一个模糊的“已完成”。
因此，开始工作时可以给 Agent 一个带核查要求的提示：
MET-1. Read the task, then explore the codebase and the current library docs before you claim it. Validate the plan against what shipped and flag anything stale. No speculative decisions: search and read first.
这里的关键顺序是“先读当前代码与文档，再 claim”。它能避免任务写下后库版本、接口或项目约定已变化，Agent 仍按旧计划直接动手。执行开始后任务进入 in_progress，减少其他 Agent 同时领取同一工作；完成代码、测试和 PR 后，任务进入 in_review，而非自动变为 done。
审核门：把“Agent 完成”与“允许合并”拆开
Piyaz 的 human-on-the-loop 模型刻意把审查门放在 in_review。审查 Agent 会针对安全性、性能、可靠性、可观测性和代码库规范给出带文件引用的结论，并在 approve、request-changes、block 三者中选择一个。它不会自行把任务改成完成，也不直接修改工作树。
可以要求审查 Agent 先读 diff 再下结论：
review MET-1. File-cited, do not rubber-stamp. Read the diff first, then reason across security, performance, reliability, observability, and codebase standards.
这样做的收益是职责边界清楚：实现 Agent 负责提交可验证的变更和执行记录；审查结论负责暴露是否偏离计划；人负责是否合并，以及 in_review 到 done 的最终状态转移。对于想减少交互的团队，Piyaz 的 Composer 还提供 research → plan → implement → CI gate → review 的任务流水线，并将修复循环限制为最多两轮；合并策略仍需由操作者在会话开始时选择。
图谱不是聊天摘要：它应保存哪些不可替代的信息
很多团队已经会在 PR 描述里写“做了什么”，但这不足以让下一个 Agent 安全接手。PR 描述通常面向一次变更，任务图则需要面向依赖传播。一个有用的执行记录至少要回答三个问题：实现事实是什么、约束为何存在、哪些下游假设因此改变。
仍以 changelog CLI 为例。解析任务完成后，记录不应只写“支持 monorepo”，而应明确：提交先按包路径筛选，再按类型分组；breaking change 从提交 footer 与 ! 标记中识别；哪些文件定义了解析结果；输出任务依赖哪一个字段。这样，当另一个 Agent 以后要增加 GitHub Release 输出，能够从图谱看到它应复用的结构，而不是重新扫描整仓库后猜测。
这也是任务依赖边有别于普通优先级的地方。优先级只说明“先做哪个”，依赖边说明“为什么不能独立做”。前者帮助排队，后者让 Agent 在读取上下文时获得正确的因果关系。若上游决策改变，例如把输出模型从扁平数组改成按包分组的对象，负责人应检查 downstream 任务，并相应更新描述或边的说明，而非只在聊天里补一句通知。
托管与自托管：先确认数据边界再接入 MCP
Piyaz 的托管 MCP 端点使用 HTTP 与 OAuth；官方文档也提供了本地运行路径。自托管需要 Bun、Docker 提供的 PostgreSQL，以及 Linux、macOS 或 WSL2 环境。文档中的初始化命令会启动数据库、建立认证与行级安全对象并应用迁移：
bun run db:setup
之后构建并启动服务：
bun run build bun run start
这不是“把数据库跑起来就结束”。如果把实例放在反向代理之后，应按官方指南设置代理相关配置；数据库凭据也不应为了省事让所有连接共用超级用户。对包含客户代码、路线图或内部决策的团队，先做数据驻留、备份、访问控制与 OAuth 账户边界的评估，再决定使用托管服务还是自托管，会比事后迁移项目图谱稳妥得多。
何时值得引入，何时不必
如果项目只有一个人和一个短会话 Agent，维护任务图的成本未必划算；简单的 issue 加 PR 已足够。但当你有并行编码 Agent、跨天任务、依赖链，或需要追踪“这个实现为何这样做”时，图谱与执行记录就比聊天摘要可靠得多。
落地时建议从一个小项目开始：只为关键路径任务写验收条件和依赖；要求每次 PR 前补全执行记录；把 in_review 作为唯一合并入口。等团队习惯“决策与代码同样需要可追溯”后，再开启 Composer 或扩展到多个项目。这样 Piyaz 才不是替你制造更多流程，而是让更多 Agent 在同一份可检查的项目事实之上工作。