trellis-check

代码质量检查

对近期编写的代码进行全面的质量验证。结合规范合规性、跨层安全性和提交前检查。

---

步骤 1：确定变更内容

git diff --name-only HEAD
git status

步骤 2：阅读任务资料和适用规范

按顺序阅读当前任务资料：

• prd.md
• design.md（如果存在）
• implement.md（如果存在）

python3 ./.trellis/scripts/get_context.py --mode packages

对于每个发生变更的包／层，阅读规范索引并遵循其中的 Quality Check 部分：

cat .trellis/spec/<package>/<layer>/index.md

阅读索引中引用的具体指南文件——索引只是指引，不是最终目标。

步骤 3：运行项目检查

运行项目的 lint、类型检查和测试命令。继续之前，先修复所有失败项。

步骤 4：依据清单进行审查

代码质量

• Linter 是否通过？
• 类型检查器是否通过（如适用）？
• 测试是否通过？
• 是否清除了所有调试日志？
• 是否没有屏蔽警告或绕过类型安全？

测试覆盖

• 新增函数 → 是否添加了单元测试？
• 修复 Bug → 是否添加了回归测试？
• 行为发生变化 → 是否更新了现有测试？

规范同步

• .trellis/spec/ 是否需要更新？（新增模式、约定或经验教训）

“如果我修复了一个 Bug，或发现了不显而易见的问题，是否应该记录下来，以免未来的自己再次踩坑？”→ 如果是，请更新相关规范文档。

范围控制

• 是否整理了任务不要求改动的代码？
• 是否为尚不存在的情况添加了抽象、配置或扩展点？
• 是否为不可能出现的状态添加了推测性的回退逻辑？
• 是否改动了验收标准未提及的文件？
• 是否在调用方添加了变通方案，而不是修复行为实际所在的位置？

步骤 5：跨层维度（如适用）

如果变更仅限于单层，请跳过此步骤。

A. 数据流（变更涉及 3 层或更多层）

• 是否正确追踪读取流：Storage → Service → API → UI
• 是否正确追踪写入流：UI → API → Service → Storage
• 类型／Schema 是否在各层之间正确传递？
• 错误是否正确传递给调用方？

B. 代码复用（修改常量、创建工具函数）

• 创建新代码之前，是否搜索过现有的类似代码？

  grep -r "pattern" src/
  

• 如果同一个值重复出现，它是否代表一个稳定的概念，且所有调用方都必须同步变更？只有这种情况下才提取——两个字面值今天碰巧相同，仍应保持独立。
• 批量修改后，是否更新了所有出现的位置？

C. 导入／依赖（创建新文件）

• 导入路径是否正确（相对路径与绝对路径）？
• 是否没有循环依赖？

D. 同层一致性

• 使用相同概念的其他位置是否保持一致？

---

步骤 6：报告并修复

报告发现的每一处违规，然后：

• 机械性且局部的问题（lint 小问题、缺少类型、导入错误、无效分支、断言失败）→ 就地修复，然后重新运行项目检查。
• 设计或判断类问题（共享概念的命名、移动模块边界、更改公共接口、重新确定行为所在位置）→ 记录证据和建议，然后停止。不要擅自静默改写。

如果修复需要改动当前任务范围之外的文件，请说明并停止，不要扩大变更范围。