六个可复用的工程工作流

这是一组可以直接复制、再按项目替换占位内容的 Pi 工作流。它们共享同一个原则：先让任务可验证，再让 Agent 自主执行。

一条好任务的四个部分

范围：允许读取或修改什么
结果：用户最后应该看到什么
验证：用什么命令或证据证明完成
禁止：哪些动作不能执行

“帮我优化一下项目”缺少边界，也没有完成标准。更好的写法是：

任务骨架替换尖括号中的内容

 只处理 <目录或文件>。 
目标：<可观察的结果>。 完成后运行 <检查命令>，并汇报通过项、失败项和未验证项。
不要修改 <排除范围>，不要执行发布、部署或数据迁移。

如果任务可能造成外部状态变化，把“真正执行”改成“先准备草稿或计划，等我确认”。

1. 理解陌生项目

第一次进入仓库时，先保持只读。目标不是让 Pi 读取所有文件，而是找到入口、约束和真实验证命令。

陌生项目体检首轮保持只读

 先不要修改文件，也不要安装依赖。 
阅读 README、项目说明、包管理文件、主要入口和测试配置，回答：
这个项目解决什么问题？
主要模块和数据流是什么？
本地开发、类型检查、测试和构建分别运行什么命令？
当前工作树有哪些已有修改或风险？
每个结论注明来源文件。最后给出下一步建议，不执行修改。

检查结果至少应包含：

• 项目入口与主要目录。
• 使用哪一种包管理器，是否已有 lockfile。
• 构建、测试、格式化和类型检查命令。
• 当前分支与未提交修改。
• 需要登录、网络、数据库或外部服务的步骤。

2. 完成一个小而完整的修改

把第一项写操作限制在一个功能或一组相邻文件。Pi 可以自行定位相关实现，但不能悄悄扩大范围。

小范围实现适合文档、UI 或单模块改动

 实现 <具体能力>。 
允许修改：<目录或文件>。 完成标准：
<用户可见结果 1>
<用户可见结果 2>
相关错误路径有明确反馈
修改前先检查现有实现和约定。修改后运行 <测试命令> 和 <构建命令>。 保留已有未提交改动；不要升级依赖、改 CI 或执行部署。

完成后不要只看总结。自己运行：

git status --short
git diff --check
git diff --cached --check
git diff
git diff --cached

git diff 与 git diff --cached 分别覆盖未暂存和已暂存修改；git status 中标为 ?? 的未跟踪文件还要逐个检查。再执行项目约定的检查命令。构建通过只能证明“可以构建”，不能替代具体行为验证。

3. 调查一个难复现的问题

排错任务先要求证据和根因，再讨论修复。这样可以避免 Agent 根据错误信息表面猜测。

根因调查默认不修改代码

 调查这个问题：<现象、错误信息、触发条件>。 
先不要修改代码。请：
建立最小复现或找到最接近的现有测试。
沿调用链定位第一个错误状态出现的位置。
区分根因、连带症状和无关告警。
给出能推翻当前判断的反证。
最后输出：根因、证据、影响范围、推荐修复和回归测试。证据不足时明确写“尚未证实”。

确认根因后，再单独发出修复任务：

按刚才确认的根因实施最小修复，并加入能在修复前失败、
修复后通过的回归测试。不要顺手重构无关代码。

4. 审查已有改动

审查的目标是发现会影响用户或维护者的问题，不是复述 diff。

变更审查按影响排序

 审查当前分支相对 <基线分支> 的改动。 
重点检查：
功能错误、状态遗漏和边界条件
安全、凭据与权限变化
并发、取消、重试和幂等问题
测试是否真正覆盖改动
文档和配置是否与行为一致
只报告可操作的问题，按严重程度排序。每项给出文件位置、触发方式、用户影响和建议修复。 如果没有发现问题，说明实际检查过哪些路径和仍未覆盖的风险。

审查前确认比较基线。功能分支通常使用：

git status --short
BASE=$(git merge-base main HEAD)
git diff --stat "$BASE"
git diff "$BASE"

这会把从共同祖先到当前工作树的已提交、已暂存和未暂存修改放进同一次审查。git status 中标为 ?? 的未跟踪文件仍需单独读取。如果仓库默认分支不是 main，替换为实际分支名。

5. 更新文档而不制造过期内容

文档任务应从实现和测试反推，而不是从旧 README 继续扩写。

文档更新先核对事实，再写

 为 <功能或模块> 更新文档。 
先阅读实现、类型、测试和现有文档，列出公开入口、默认值、限制和常见失败路径。 然后补齐：
新手第一次成功的教程
完成常见任务的操作指南
精确的参数或命令参考
非显然设计选择的解释
所有命令和代码示例必须来自当前版本并可验证。更新目录、导航和交叉链接，最后运行文档构建。

避免在文档里长期复制易变的模型 ID、价格或供应商清单。优先链接事实来源，并标注校对版本。

6. 做发布前检查，但不发布

发布、打 tag、上传包和部署都会改变外部状态。先让 Pi 生成发布判断和草稿。

发布准备只检查，不发布

 检查当前分支是否具备发布条件，但不要发布、打 tag、推送或修改远程状态。 
请核对：
工作树、版本号和 changelog 是否一致。
必要测试、类型检查和生产构建是否通过。
是否包含调试代码、测试凭据、生成文件或意外的大文件。
相对上一版本是否存在破坏性变更或迁移步骤。
README、升级说明和发布摘要是否同步。
输出 blockers、warnings、ready 三组结论，并生成一份发布说明草稿。

只有人工确认结果后，再发出独立、明确的发布指令。发布动作和准备动作拆开，能显著降低误操作成本。

如何让这些工作流成为团队资产

使用频率决定放在哪里：

使用方式	放置位置
每次都应遵守的项目约束	AGENTS.md
固定文本、手动调用	.pi/prompts/<name>.md
有步骤、脚本或参考资料的按需流程	.pi/skills/<name>/SKILL.md
需要事件、工具或 UI 能力	.pi/extensions/<name>.ts

下一步可以把最常用的工作流做成第一个 Skill，需要代码级能力时再写第一个 Extension。不确定边界时，回到配置与扩展。