tidy-project

审核代码库的项目结构——文件和目录的布局、放置位置与命名，以及配置、依赖和构建规范——并制定一份合并后的批量执行计划。执行至完成，全程无需用户交互：各阶段之间不停顿，不请求确认，不提供中间报告。计划文件是交付物；状态文件仅供你恢复执行，不供人工审阅。使用宿主的待办工具，按四个阶段组织任务。

不可妥协的要求（请先阅读）

• 对源代码只读。 除状态文件和最终计划路径外，不得创建任何内容。
• 提案只能在保持行为不变的前提下提出。 每项提议的更改都必须保留原有功能。
• 保留基础设施。 第 1 阶段识别出的语言、框架、托管平台、数据库和运行时环境，在整个审核过程中均保持不变。
• 不得替换依赖项，除非能明确证明该依赖项未使用，或可用约 10 行标准库代码替代。
• 不得重写——仅允许合并、删除、扁平化、重命名和提取（字面量 → 环境变量读取）。
• 不得查看 Git 历史。 证据仅限已跟踪文件列表（git ls-files）、清单文件和文件树——不得使用提交日期或代码变更量。若某项发现的唯一证据是“已有 N 个月未改动”，则舍弃。
• 可证伪性门槛。 将每项发现分类为 FALSIFIABLE（引用可通过 Grep 或 git ls-files 确认的路径、已跟踪文件条目或字符串）或 OPINION（结构性判断）。将发现纳入草稿前，必须通过新执行的 Grep 或 git ls-files 调用核实每条可证伪引用；若无匹配，即为虚构引用，必须舍弃。
• 框架要求的结构不在检查范围内。 绝不得将第 1 阶段识别出的框架所要求的文件或目录（src/pages/、app/、settings.py、.github/workflows/、Dockerfile、package.json、tsconfig.json、Makefile 等）列为发现项。

范围边界

每个 tp-* 类别（tp-01..tp-11，定义见 references/categories-quick-ref.md）都可根据文件树、git ls-files、清单文件和有针对性的 Grep 检查作出判断。本技能不负责：

• 代码语义——死代码、跨文件逻辑重复、过早抽象、耦合、导入循环。不得阅读代码以理解其含义。
• 单文件问题——标识符命名、函数长度、魔法数字、文件内重复。证据完全位于单个文件中的发现不在范围内。
• 测试内部细节——仅从结构层面审核测试文件（是否存在、放置位置、组织方式、过时脚手架）；测试函数内部逻辑不在范围内。

排除路径

跳过对以下内容的遍历：任何点目录（.git/、.venv/、.next/、.cache/、.turbo/、.agents/、.claude/、.vscode/、.idea/、.github/ 等）、node_modules/、vendor/、dist/、build/、__pycache__/、target/、coverage/、生成的代码和二进制资源。

注意： 跳过遍历不等于跳过取证——tp-02/tp-03 仍可通过 git ls-files 标记已提交的 dist/ 或 vendored 库；这项检查成本低，且在范围内。不得读取锁文件，但每个清单文件旁是否存在锁文件，是 tp-02 的判断依据。

状态文件

.agents/local/state/tidy-project-YYYY-MM-DD.md（如果目录不存在，则创建该目录）。如果今天的文件已存在且已完成，则依次追加 -2、-3。启动时：使用 glob 匹配 .agents/local/state/tidy-project-*.md；如果最新文件中有未勾选项，则从该文件恢复执行；否则创建新文件。删除该文件即可强制重新运行。格式——按阶段分组的 Markdown 复选清单，每个区域一项，并在其下方追加发现草稿：

# Tidy Project — 2026-07-17
- [ ] Phase 1 — inventory
- [ ] src/
- [ ] docs (drift)
- [ ] Phase 3 — adversarial review
- [ ] Phase 4 — plan written

只有你可以写入状态文件。工作者在回复中提供发现；他们不得触碰状态文件。

第 1 阶段 — 清点（机械操作，不使用子 Agent）

在此处直接完成清点 — 不要为此派发子 Agent：

1. 技术栈。 查找清单文件（package.json、pyproject.toml、requirements.txt、go.mod、Cargo.toml、composer.json、Gemfile）并阅读，了解所用框架。记录框架要求的（禁止修改的）路径、入口点和配置范围。
2. 目录树和区域。 使用 git ls-files 并进行两层目录遍历。列出顶层区域及其源文件数量；标记用途不明确的文件夹。
3. 卫生检查 grep — 这些检查本质上适合用 grep 执行；现在运行并将命中项作为候选项交给对应区域的工作者：git ls-files '*.env' | grep -v example（已跟踪的环境文件）、每个清单文件旁的锁文件、git ls-files dist build out 和 git ls-files '*.min.*'（已提交的构建产物）、git ls-files '*.log'（日志产物）、find . -name .git -mindepth 2 -not -path './.git/*'（嵌套代码库）。

将清点摘要和区域检查清单写入状态文件，然后直接进入第 2 阶段 — 不要停下或总结。

第 2 阶段 — 区域分析（并行）

使用 references/adversarial-review-prompts.md 中的 Area Analyst 提示词派发工作者 — 每个顶层区域派发一个工作者，另派一个文档工作者负责文档区域（README、docs/、Agent 指令文件）；该工作者还需加载 references/docs-code-drift.md，并以相同的单行格式返回偏移发现。将源文件少于 10 个的区域合并给同一工作者。并发工作者最多 5 个，每轮的所有 Agent 调用都放在一条消息中；区域较多时，分 5 个一轮执行 — 绝不要为了满足上限而跳过区域。

工作者使用主机的廉价模型别名（类似 model: haiku — 绝不要使用固定版本）。向每个工作者提供其文件列表和清点摘要（技术栈、禁止修改的路径、入口点、相关卫生检查命中项）。工作者从用户的项目根目录运行，因此派发前须将简报中的每个 references/… 路径展开为该技能目录下的绝对路径。工作者需加载 references/solo-dev-lens.md、references/categories-quick-ref.md 和 references/severity-and-difficulty.md；对于 tp-10 候选项，还需加载 references/hardcoded-environment.md；对于 tp-11 候选项，还需加载 references/convention-drift.md；使用各自的 Grep/git ls-files 调用执行可证伪性门槛检查，并返回单行发现。

跨区域综合器 — 仅当顶层区域数 ≥ 4 时启用；少于 4 个则跳过。所有区域工作者返回后，派发一个综合器（使用相同参考资料及其专属提示词），并提供汇总后的发现及仓库读取权限，以找出跨区域重复项、跨区域分散的内聚问题、相互冲突的建议和术语漂移。最多列出 10 条发现。

每个工作者返回结果后，将其发现追加到状态文件中的草稿，并勾选对应复选框。

发现格式

每条发现占一行。OPINION 类型的发现省略证据字段；其他字段均为必填 — 第 4 阶段的公式会使用 sev、diff、risk 和 blast。

- [tp-10] Hardcoded environment — src/config/db.ts:4 — sev:high diff:easy risk:MEDIUM blast:1 — grep:`postgres://[^ ]*@db\.internal` — committed connection string, not deploy-portable → replace with process.env.DATABASE_URL and add a .env.example entry

sev 为 low|medium|high · diff 为 easy|medium|hard · risk 为 LOW|MEDIUM|HIGH · blast = 受影响文件数（最少为 1）。证据格式为 grep: 或 git-ls-files:，后接可精确重新运行的模式。必须一起落地的发现使用相同的 group:tag 标记，并置于证据字段之前。仅当发现与特定行有关时，才为路径标注行号（:line）。

第 3 阶段 — 对抗性审查（一轮）

派发一个 Findings Reviewer（使用默认模型，提示词见 references/adversarial-review-prompts.md），并提供完整的发现草稿及仓库读取权限。该审查者会自行重新运行所有引用的 grep 和 git ls-files，删除虚构的引用，质疑错误的遗留项判断、错误的硬编码环境判断及有风险的重命名，确保安全路径的严重性达到最低要求，指出遗漏的发现，并为每条发现返回 KEEP/REVISE/DROP 判定。将判定应用于草稿。深度 = 1 — 绝不要派发第二轮。

阶段 4 — 排序并编写计划（不使用子 Agent）

加载 references/ranking-formula.md；为每条保留的发现评分，按照分组规则合并带有 group 标签的发现，并排序。将排序后的发现编排成原子批次——每批规模尽可能小，且批次之间仓库都能正常运行；每批均可独立提交，按依赖顺序排列，并附带具体可运行的 Verification: 命令。任何涉及环境变量、CLI 标志、DB 架构、已部署 URL、cron/webhook/队列处理程序或身份验证的批次，都标记为 boundary_crossing: true。然后加载 references/final-plan-format.md 并编写计划：

• 仓库根目录存在 docs/ → docs/YYYY-MM-DD-tidy-project-plan.md
• 否则 → 在仓库根目录创建 YYYY-MM-DD-tidy-project-plan.md

仅显示计划路径。 你的结束回复只写合并后的计划路径，不得包含其他内容——切勿显示状态文件、工作线程输出或中间草稿。只有用户明确询问时，才透露状态文件位置。

应避免的失败模式

• 将框架要求的结构标记为过度设计。
• 将“几个月来都没动过”视为证据——只看结构证据，不看 git 历史。
• 将必需的已检入文件（锁文件、夹具、构建所用的生成文件输入）视为 tp-03 提交产物。
• 将跳过的目录视为不可审查——其已跟踪状态仍可通过 git ls-files 作为证据。
• 允许工作线程返回段落，而不是单行发现——重新分派该区域，并重申格式要求。
• 在各阶段之间暂停等待确认，或输出逐阶段摘要。应直接执行到底。

完成

所有复选框均已勾选，计划也已写入。报告计划路径——仅此而已。不要提交，不要删除状态文件，也不要运行构建或测试命令。