tidy-code

根据 16 个 tc-* 结构质量类别审查代码库，并制定一份整合计划，供下游 Agent 或人员执行。审查只读。状态文件仅作为你自己的续接草稿，不供人工审阅。按照宿主 todo 工具中的四个阶段执行。

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

• 绝不修改源文件。 此技能只会写入状态文件和最终计划。
• 仅限显式调用。 通过 /tidy-code 运行；绝不因自然语言请求自动激活。
• 对每项发现进行分类：FALSIFIABLE（引用可由 Grep 确认的特定行上的具体代码片段）或 OPINION（证据属于解释性判断）。
• 在将任何可证伪引用纳入草稿前，先用 Grep 验证。 若无匹配，或匹配出现在不同的行，则删除该发现。
• 深度为 1。 恰好进行一轮对抗式审查。审查者不得重新执行文件审查环节。
• 单一输出文件。 最终计划是唯一面向用户的产物；仅提供其路径。

排除路径

跳过以下路径的发现和审查：

• 点目录：.git/、.venv/、.agents/、.claude/、IDE/Agent 脚手架
• node_modules/、vendor/、bower_components/、任何 */third_party/* 或 */vendor/*
• 构建产物：dist/、build/、target/、out/、coverage/、__pycache__/、.next/、.cache/
• 非源文件：配置文件（JSON/YAML/TOML）、Markdown、锁文件、压缩资源、图片、字体
• 生成的代码（@generated、DO NOT EDIT 等）、迁移文件、.d.ts 文件、少于 20 行的脚本
• .gitignore 中的所有内容——将其视为权威依据

状态文件

工作状态保存在 .agents/local/state/tidy-code-YYYY-MM-DD.md（日期取自 date +%Y-%m-%d）。若当天文件已存在且所有事项均已检查，则追加 -2，然后是 -3。此文件是你自己的草稿——被 git 忽略，绝不向用户展示，也绝不提交。

开始时： 如果 .agents/local/state/ 不存在，则创建它，然后匹配 .agents/local/state/tidy-code-*.md。如果最新文件仍有未检查事项，则从该文件恢复；否则创建新文件。删除该文件即可强制重新运行。

# tidy-code — 2026-07-17

## Batch 1
- [ ] src/auth/session.ts
- [ ] src/auth/token.ts (test)

## Findings draft
- [tc-05] Silent Failure — src/auth/session.ts:88 — sev:high — grep:`except:` — bare except hides auth failures → raise or log explicitly

每当工作者返回结果时，将文件标记为 [x]。工作者绝不写入状态文件——并发写入会导致文件损坏。

阶段 1 — 发现（机械操作，不使用子 Agent）

使用 Glob 或 shell 列表工具直接枚举源文件——优先使用 rg --files，不可用时依次回退到 fd --type f，再到普通的 find . -type f——同时遵守上述排除项。将每个文件标记为应用文件或测试文件（测试文件包括 *.test.*、*.spec.*、*_test.*、test_* 及语言对应的形式；/tests/ 下非测试文件，如工厂、夹具和辅助文件，视为应用文件）。若没有剩余的应用文件，则以面向用户的错误信息停止；若超过 1000 个，则先请用户限定审查范围（例如指定子目录）。

将文件分成每个工作者 8–12 个文件的批次（应用文件少于 20 个的仓库合并为一个批次），将检查清单写入状态文件，然后立即进入阶段 2——不要停止、总结或询问。

阶段 2 — 审查（按批次并行）

每批分派一个工作子代理——最多同时运行 5 个，并在一条消息中发出同一轮的所有 Agent 调用，以便并行执行。工作代理：subagent_type: general-purpose，model: haiku（宿主提供的低成本模型别名——绝不指定固定版本）。向每个工作代理说明其文件列表（标注 app/test）、下面的发现项格式，以及内联保护要求：**只读——绝不修改任何文件；仅报告发现项。**工作代理从用户的项目根目录运行，因此在分派前，请将其说明中的每个 references/… 路径扩展为该技能目录下的绝对路径。

每个工作代理：

1. 首先读取 references/principles-quick-ref.md；仅当出现某个 ID 的候选项时，才加载对应类别的参考资料；分类严重程度时加载 references/severity-rubric.md。
2. 使用并行工具调用读取其批次文件，并根据全部 16 个类别审查 app 文件。Test 文件只检查 tc-09、tc-03 和 tc-13——跳过其余类别。
3. 使用自己的 Grep 调用执行可证伪性检查：FALSIFIABLE 发现项应附带已验证的模式；无法验证的引用应舍弃，不要报告。
4. 验证每条建议的改写都能解决违规问题，且不会引入新问题。允许尝试修订一次；如果仍无法验证，建议修复内容改为哨兵文本 [Suggested rewrite could not be verified — manual rewrite required]。
5. 以精简的单行项目符号形式返回发现项（OPINION 发现项省略 grep:）：

- [tc-05] Silent Failure — src/api/client.py:88 — sev:high — grep:`except:` — bare except hides auth failures → raise or log explicitly

如果工作代理失败或未返回可解析的内容，则重新分派其批次一次；若再次失败，则将其文件留作未检查，并在完成时注明。

你（协调者）将每个工作代理的发现项追加到状态文件的草稿中，并勾选其文件。追加时去重：同一文件同一行的相同类别只保留一条；当一条证据支持多个类别（同时违反 tc-04 和 tc-09 的 UserManager），则保留严重程度较高的发现项，并在该条中注明其他类别。

按类别划分的参考资料：tc-01 composition-over-inheritance.md · tc-02 dependency-injection.md · tc-03 guard-clauses.md · tc-04 single-responsibility.md · tc-05 fail-fast.md · tc-06 least-surprise.md · tc-07 tell-dont-ask.md · tc-08 immutability.md · tc-09 naming.md · tc-10 functional-core-imperative-shell.md · tc-11 magic-numbers.md · tc-12 duplicate-logic.md · tc-13 comment-debt.md · tc-14 type-escape.md · tc-15 query-in-loop.md · tc-16 unsafe-sink.md（均位于 references/ 下）。

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

使用宿主的默认模型分派一个审查子代理，并提供完整的发现项草稿、仓库根目录，以及 references/adversarial-review-prompt.md 中的提示词。审查者会自行重新运行引用的 grep，质疑误报、严重程度夸大和无法执行的改写，标记遗漏的发现项，并返回 KEEP/REVISE/DROP 判定列表。

由你自行将判定应用到草稿中：删除 DROP 项，整合 REVISE 项，并追加经 grep 验证的新增项。审查深度为 1——无论判定结果如何，都绝不分派第二轮。

阶段 4 — 报告

加载 references/final-plan-format.md，并将审查后的发现项写成一份完整的计划：

1. 如果仓库根目录存在 docs/ → docs/YYYY-MM-DD-tidy-code-plan.md。
2. 否则 → 在仓库根目录创建 YYYY-MM-DD-tidy-code-plan.md。

仍带有哨兵文本的发现项放入 <manual_review>。回复用户时只写这个路径——绝不提及状态文件或任何中间细节。

需要避免的失误

• 不要对测试文件应用完整目录清单——仅适用 tc-09/tc-03/tc-13。tc-02 和 tc-10 标记的是在测试中很常见的副作用设置。
• 不要将 /tests/ 中的工厂函数、测试夹具或辅助工具视为测试文件——它们属于应用代码，适用完整目录清单。
• 不要将注释相关问题交由其他技能处理。注释是否存在以及 TODO/FIXME/HACK/XXX 标记均由本技能负责（tc-13；允许的情况：文档注释、linter 指令、解释非显而易见原因的注释）。
• 不要报告跨文件的重复逻辑——这不在范围内（参见 principles-quick-ref.md § 范围边界）。
• 不要将影响超过 5 个文件的跨文件重命名标记为安全——将问题标记为 blast radius: N files — confirm before applying（tc-09）。
• 不要添加置信度、难度或风险评分——此技能报告问题，不对其进行评级。
• 不要为了显得全面而凑数。文件没有问题时，零条发现也是有效结果。

完成

当状态文件中的每个复选框都已勾选且计划已写入时，任务即告完成。回复计划路径，并用一行总结各严重级别的问题数量。不要提交任何内容，不要运行构建或测试命令，也不要删除状态文件。