Trellis Debug Systematic Zh
当 Trellis 子任务实现/验证过程中测试该绿不绿、或自检命令失败时,用一段不可偏离的刚性脚本做系统化根因定位与最小修复。用于 Codex / Claude Code 等驱动 qwen3.6 35b 这类小参数模型调试时——小模型一旦自由发挥就会到处乱改,本技能用"一次只改一处、改完必重跑、禁止猜"的铁律把它锁在窄路径上,并带防御性回归检查。
Install
npx skills add coldwateryi/trellis-skills --skill trellis-debug-systematic-zhgit clone --depth 1 https://github.com/coldwateryi/trellis-skills.git /tmp/trellis-skills
mkdir -p ~/.claude/skills
cp -r /tmp/trellis-skills/trellis-debug-systematic-zh ~/.claude/skills/trellis-debug-systematic-zhPersonal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.
From the SKILL.md
# Trellis 系统化调试(刚性脚本)
## 概览
接管一次失败的测试或自检命令,按固定的 4 步把它修绿:固定失败信号 → 定位 → 单一假设验证 → 最小修复 + 回归。本技能存在的意义是**防止(尤其是小模型)在调试时乱改、越改越坏**——所以它是一段**编号脚本 + 铁律**,不是建议。
触发:`trellis-implement-tdd-zh` 的红绿循环里某测试该绿不绿,或 `prd.md` 自检命令失败,且原因不显然。
调试轨迹固定写入任务目录下的 `<task-dir>/debug-report.md`。第一次进入调试时从 `references/debug-report-template.md` 创建,后续每次新的调试事件在同一个文件里追加一个 session 块;不要改 skill 目录里的模板文件。
## 约束(铁律)
- **一次只改一处**。改完立刻重跑那个失败命令,再决定下一步。
- **改完必重跑原失败命令**。不重跑就不算验证。
- **禁止猜**。定位只用"读栈 / 二分注释 / 加一行日志"三招缩小范围,不靠想象改代码。
- **不动文件清单 / 禁止事项之外的文件**。怀疑根因在范围外时,停下来报告,不擅自扩散修改。
- **修不对就回滚**。一处修改重跑仍失败,先回滚这次改动再换假设,不要在错误改动上叠加。
- **不 commit / push / merge**。
- 超过 3 轮"假设→修复→重跑"仍未绿 → 停止,升级给强模型或回报人工,不无限烧 token。
## 工作流
### 1. 固定失败信号(不复现不动手)
- 把失败的**原文**贴出:报错堆栈 / 失败断言 / 命令非零退出码及输出。
- 确认能稳定复现:记下复现命令(取自 `prd.md` 自检命令或测试命令)。
- 复现不了就先解决"不稳定复现",不要对着偶发现象瞎修。
- 把复现命令、失败原文和是否稳定复现写入 `<task-dir>/debug-report.md`。
### 2. 定位(只用三招,缩小到具体行)
按代价从低到高,命中即停:
1. **读栈**:报错堆栈/断言指向的文件与行,直接看那一处。
2. **二分注释**:对可疑代码段二分注释/短路,看失败是否消失,缩小范围。
3. **加一行日志**:在缩小后的范围打印关键变量的实际值,对比期望值。
输出:把范围缩小到"具体文件 + 具体行/变量",不再泛泛说"哪里有问题"。
### 3. 单一假设(先验证真假,再谈修)
- 写一句话假设:`我认为根因是 X(具体到变量/分支/契约)`。
- 先用最小手段**验证假设真假**(看变量实际值、查契约、跑一个更小的探针),确认了再修。
- 假设被证伪 → 回到步骤 2 换一处,不要带着错假设去改。
### 4. 最小修复 + 回归
- 只针对已验证的根因改**一处**。
- 重跑原失败命令 → 绿则继续;仍红则回滚本次改动,回步骤 3 换假设。
- 绿之后跑 `prd.md` 自检命令全集,确认没引入新的红(无回归)。
- **防御性收尾**:回答一句"这个 bug 还能从别的入口再发生吗?"
- 能 → 在 `check.jsonl` 记一条回归点(`{"file":"<回归测试或风险点>","reason":"<它保护的行为>"}`),并考虑补一个回归测试。
- 不能 → 在调试记录里写明"已局部封闭"。
### 5. 退出Details
- Skill name
trellis-debug-systematic-zh- Repository
- coldwateryi/trellis-skills
- Path
trellis-debug-systematic-zh/SKILL.md- License
- MIT
- Repo updated
- 3 July 2026
FAQ
What does the Trellis Debug Systematic Zh skill do?
当 Trellis 子任务实现/验证过程中测试该绿不绿、或自检命令失败时,用一段不可偏离的刚性脚本做系统化根因定位与最小修复。用于 Codex / Claude Code 等驱动 qwen3.6 35b 这类小参数模型调试时——小模型一旦自由发挥就会到处乱改,本技能用"一次只改一处、改完必重跑、禁止猜"的铁律把它锁在窄路径上,并带防御性回归检查。
How do I install the Trellis Debug Systematic Zh skill?
skills CLI (Claude Code, Cursor, Codex and more): npx skills add coldwateryi/trellis-skills --skill trellis-debug-systematic-zh. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.
Is Trellis Debug Systematic Zh popular?
It lives in coldwateryi/trellis-skills, which has 44 GitHub stars and 1 forks.
Related skills
Trellis Debug Systematic
44coldwateryi/trellis-skills
When a test should be green but stays red, or a self-check command fails during Trellis subtask implementation/verification, use this non-deviable rigid script for systematic root-cause pinpointing and minimal fix. Used when Codex / Claude Code drives a small-parameter model like qwen3.6 35b—small models quickly spiral out of control when debugging freely; this skill uses "one change at a time, must re-run after change, no guessing" iron rules to lock it on a narrow path with defensive regression checks.
Trellis Delivery Controller
44coldwateryi/trellis-skills
Trellis requirements-to-delivery entrypoint and workflow controller. Use when the user wants to invoke one Trellis skill that detects the current stage and routes work across requirements analysis, MVP task planning, post-MVP gap audit, delivery loop, TDD implementation, systematic debugging, two-stage review, and final acceptance. Coordinates trellis-zero-to-mvp, trellis-mvp-to-delivery, trellis-implement-tdd, trellis-debug-systematic, and trellis-review-twostage while enforcing safety gates.
Trellis Delivery Controller Zh
44coldwateryi/trellis-skills
Trellis 需求交付总入口和流程控制器。用于用户希望只调用一个 Trellis skill 自动判断当前阶段,并在需求分析、MVP 任务规划、MVP 后差距审计、交付 loop、TDD 实现、系统调试、双阶段评审和最终验收之间进行路由、推进和安全门控制的场景。适合基于 trellis-zero-to-mvp-zh、trellis-mvp-to-delivery-zh、trellis-implement-tdd-zh、trellis-debug-systematic-zh 和 trellis-review-twostage-zh 形成端到端交付闭环。
Trellis Review Twostage Zh
44coldwateryi/trellis-skills
在 Trellis 子任务自检全绿、标记完成之前,做两阶段代码评审:先机械核对规范符合(对照 PRD 验收标准/决策表/禁止事项/文件清单/挂载点),再做代码质量评审(对照 .trellis/spec/guides 的工程规范与设计纪律)。用于 Codex / Claude Code 等团队协作场景,尤其当实现由 qwen3.6 35b 小模型完成时——小模型评审自己的代码不可靠,Stage 2 应升级到强模型;critical 问题阻断完成。
Trellis Zero to Mvp Zh
44coldwateryi/trellis-skills
从完整需求文档创建 Trellis MVP 任务树。用于 Codex 收到产品说明、需求文档、PRD、从 0 到 MVP 的新项目需求、大型能力建设请求,或已经手工实现了一部分功能的项目时,先做只读分析,分配稳定 REQ/AC 编号,生成需求追踪矩阵和项目契约,识别已有实现证据,通过渐进式批次规划和子代理协作形成完整 MVP 父子任务树、PRD、设计/实现产物计划,并在用户确认后创建 Trellis 任务;不编写应用代码。
Backstage Backend Plugin
23rothenbergt/backstage-agent-skills
Build Backstage backend plugins and modules with createBackendPlugin: DI, httpRouter, secure-by-default auth, Knex DB, scheduler, testing, extension points. Use for APIs, modules, and background jobs.
Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.