---
name: project-workflow
description: 持久化编排大型代码仓库的模块重建、新增、多 Agent 开发、跨会话接力和中断恢复；按证据限制读取、开发、审查与测试范围，不用于普通问答或单文件小改。
---

# 大型仓库模块开发编排

用原生 Agent 实施任务，用 `scripts/workflow.py` 保存任务、占用、检查和接力状态。控制器不是模型调度器、权限系统或全仓质量审计器；本 Skill 不授权高风险业务操作、依赖安装或发布。

默认采用最短闭环：**局部范围化 → 最小实现 → 差异自审 → 最小充分验证 → 一次性收口**。只有出现明确风险证据时才扩大范围，仓库规模本身不是增加读取、开发、审查或测试的理由。

## 1. 局部范围化

先遵循项目 `AGENTS.md` 和长期规则，读取 Git 状态及已有 `.workflow/state.sqlite3`。保护用户原有修改，只确定目标模块、功能入口、公开接口、核心实现和一层直接依赖。图谱可用时优先用 Scout 做少量正向定位；首轮通常不超过 3 次图查询和 5 个关键源码文件。达到“知道从哪里进入、修改哪里、结果从哪里输出、直接影响谁”的证据后立即停止读取。

只有公共接口、共享类型、数据库迁移、高扇出组件、跨模块错误或现有证据不足时才升级 Verify 并向外扩展。Auditor 仅用于用户明确要求的审计、穷尽或否定结论。查找字符串、错误消息、配置、非代码文件或覆盖缺口时，才对明确路径局部使用 `rg`；不得把查询 miss 自动升级为全仓扫描。图谱只是范围化工具，关键结论仍需回读对应源码。

## 2. 最小实现与调度

每项修改必须对应功能目标、必要兼容或验收标准。先解决根因并完成一个端到端纵向切片，不顺带清理技术债、统一风格、重构附近模块或为理论需求增加抽象。验收标准已由代码满足，继续修改只改善风格或假设中的扩展性时立即停止。

Root 按依赖拆分可独立验收的 Task，并亲自承担一个当前可执行任务。只有至少两个范围互不冲突的独立交付单元，且并行收益明显高于交接与复核成本时才创建子 Agent；不能仅因文件多而拆 Agent。领取后绑定真实 Agent 标识，传递目标、读写和禁止范围、依赖、验收标准与停止条件。子 Agent 不修改账本、不继续派生 Agent；共同文档由 Root 独占。

控制器合同见 [编排操作说明](references/编排操作说明.md)。脚本使用 Python 3.12+ 标准库，所有调用从 Skill 目录定位脚本并显式传 `--root`，不安装依赖。任务状态变化时只在有新信息时输出一次简洁看板。

## 3. 差异自审

实现稳定后由 Root 一次核对实际 diff、声明范围、修改文件关键上下文、直接依赖和验收标准。默认不创建独立 Reviewer。只有公共接口、权限安全、数据库迁移、高扇出基础组件、大量删除替换或多 Agent 集成等高风险证据出现时，才安排一次独立只读 Review。

Reviewer 只回答是否满足验收、是否破坏直接依赖、是否存在明确可复现问题；不评价无关风格，不扩大为全项目审计。没有阻断验收的实质问题时停止审查；只有实质修复使原证据失效时才复查受影响部分。

## 4. 最小充分验证

`required_checks` 只声明能为本次改动提供新信息的检查。优先运行一个最小且最相关的定向验证，覆盖核心成功路径、真实失败路径或关键回归；已有证据足以支持结论后立即停止。只有共享接口、直接依赖、数据格式或跨模块行为发生变化时才增加一个契约或直接依赖检查。全量测试必须有明确风险依据并先获得用户确认。

自动化测试不适合文档、配置、纯视觉或人工行为时，不为门禁强行补测试。用户明确不测试时跳过自动测试并标记未验证。不得重复运行无法提供新信息的已通过测试，不以测试数量体现质量。

## 5. 按条件更新图谱与收口

`codebase-memory` 不是所有写任务的固定检查。只有新增、删除、移动代码文件，函数、类、路由或调用关系发生实质变化，后续任务依赖新图谱结构，或项目明确要求同步时，才在代码稳定后调用一次 `detect_changes`、增量 `index_repository` 和 `index_status`，并对本轮实际证据路径调用一次 `check_index_coverage`。样式、文案、注释、文档及不改变结构关系的小改可跳过。全量索引仅用于首次建立、索引损坏、用户明确要求或增量更新无法恢复。

接口、操作流程、行为或重要决策变化时才同步文档；产生可复用知识时才更新知识库及 `knowledge/INDEX.md`。checkpoint 只在关键里程碑、实际中断、跨会话接力或 `pressure` 达到 soft/hard 时保存，不在每个普通阶段重复保存；不得保存完整聊天、密钥或原始业务数据。

最终交付只需说明：改了什么、执行了什么、验证了什么、什么未验证、剩余风险。不得把源码已写入说成已确认有效，也不得把模拟、上传或公开数据说成真实线上结果。

## 接力与安装

自动 handoff 仅在保存了用户明确授权引用后启用。hard 信号出现时由 Root 调用平台工具创建后继任务、prepare，后继核验后 accept；脚本不能自行创建任务。收到 accept 前旧任务仍负责，双方不得同时调度同一范围。

安装、复制或修改本 Skill 后，运行 `scripts/validate_skill.py` 做自包含结构校验。它只校验结构和引用，不代表业务行为已经验证。