de-bloat 至简
用于任何会产生或修改代码的任务:写代码、新增功能、加接口、改代码、重构、修 bug、写脚本,涉及 C++、Go、Java、Python、Node.js 时同样适用。用户说「简单点」「别过度设计」「复用已有的」「抽一下公共方法」「按官方规范写」「至简」「de-bloat」「YAGNI」,或代码里出现重复造轮子、复制粘贴的相似代码、层层 try-catch、空兜底、为未来预留的抽象时,即使没有点名也应使用。
de-bloat 至简
先找再写;只写当前需要的;只改该改的;安全守底线;有证据才说完成。
自包含的编码 skill,不依赖其他流程或纪律类 skill,也不依赖特定 agent 或工具。下文只描述要完成的动作;用当前环境里能完成该动作的工具即可:
- 列目录、读文件:任何文件浏览或读取工具,或
ls、find。 - 文本搜索:任何代码内容搜索工具,或
rg/grep。 - 文件名搜索:任何按文件名或模式找文件的工具,或
find/rg --files。 - 广域探索:环境支持子代理(sub-agent)时,交给子代理做跨目录、跨命名约定的搜索,只取回路径与证据;不支持时,用上面的文本搜索与文件名搜索逐项完成,范围不缩小。
流程
[0 结构速览与目标] -> [1 找复用] -> [2 节俭实现] -> [3 安全底线] -> [4 交付验证]
修 bug 先走 2.2,要不要抽象看 2.3
上一步没有结论,不进入下一步。
小改动(单文件、几行、不新增函数)可走简版:结构速览只看改动文件所在目录,跳过第 1 步的广域探索;第 0 步的成功标准和第 4 步的验证不能省。
0. 结构速览与目标
-
结构速览:列出根目录与主要源码目录,读构建文件(如
go.mod、pom.xml、package.json、pyproject.toml、CMakeLists.txt),仓库较大时用广域探索;在回复里给出不超过 5 行的结构图:text 语言与构建: <go.mod / pom.xml / package.json ...,声明的语言版本> 分层与模块: <如 api -> service -> repo,或按领域划分的目录> 公共代码: <utils / common / shared 等目录的实际路径> 惯例: <命名、错误处理、日志的既有写法,各举一个文件为证> 测试: <测试目录、命名方式与运行命令>新代码放在哪、第 1 步去哪搜复用、2.3 抽象到哪一层,都以这张图为准。图里每一项都要有路径为证,查不到就写「未发现」,不凭印象补。
-
读改动涉及的文件、接口与调用方,确认影响范围。
-
把任务改写成可验证的成功标准:
任务 成功标准 加校验 非法输入的测试先失败,实现后通过 修 bug 复现原始症状的测试先失败,修复后通过 重构 改动前后同一组测试都通过 新功能 列出可观察的行为,每条写明怎么检查 -
列出不能破坏的行为。
-
在回复里写明采用的关键假设。需求有多种解读且会得出不同实现时,列出这些解读:影响正确性的先问用户,只影响偏好的(命名、结构、排版)选一种并说明,不停工追问。
-
发现比用户要求更简单的方案时,直接提出来。
-
多步任务先给简短计划,每步带验证:
1. 步骤 -> 验证:检查项。
1. 全局梳理,先找复用
动手前必须扫全局,不能只读手边文件。
- 用广域探索问:所需的函数、类、工具方法、模式在项目里是否已存在,要求给出绝对路径与证据。
- 用文本搜索按中英文关键词搜符号名、方法名、领域词;用文件名搜索找 helper、util、service、adapter。
- 对每个候选记录:路径、符号、能力、改造成本。
- 三选一:直接复用 / 小改造复用 / 确实没有才新建。新建要能回答「为什么现成的不行」。
- 找到的是「相似但不完全相同」的代码,或本次要写的逻辑在项目里已有一份内联实现时,按 2.3 判定是否抽象,不复制一份再改。
搜索策略与可复用判定见 references/reuse-discovery.md。
2. 节俭实现
- YAGNI:只实现被要求的行为,不为假想需求加参数、配置、抽象层或扩展点。
- 粒度刚好:一个函数做一件事,不拆成空壳,也不塞成上帝函数。
- 不兜底:缺失值代表异常时直接报错,不用
or {}、or []、if not x: return None静默填值,不 try-catch 后pass。只有业务上「无值合法」才用默认值,并写明理由。 - 批量优先:底层支持批量时一次批量调用,不在循环里逐个请求;也不为批量硬塞单元素数组。
- 最短路径:数据与控制流不为「看起来规范」加中间层。
- 精准修改:diff 的每一行都能追溯到本次需求。不顺手改相邻代码、注释、格式,不重构没坏的代码(按 2.3 提取重复实现除外)。因本次改动变成无用的导入、变量、函数要删掉;原本就存在的死代码只在回复里提及,不删。
- 命名、格式与惯用法按 2.1。
改写方式见 references/over-defense-patterns.md。
2.1 语言规范自适应
按改动文件的语言加载对应参考;多语言项目按文件判定,只加载本次涉及的语言。
| 语言 | 识别依据 | 官方规范 | 参考 |
|---|---|---|---|
| C++ | .cpp .cc .cxx .h .hpp,CMakeLists.txt | ISO C++ Core Guidelines | references/lang/cpp.md |
| Go | .go,go.mod | gofmt、Effective Go、Go Code Review Comments | references/lang/go.md |
| Java | .java,pom.xml / build.gradle(.kts) | Oracle Java Code Conventions、Javadoc 指南 | references/lang/java.md |
| Python | .py,pyproject.toml / requirements.txt | PEP 8、PEP 257、PEP 484 | references/lang/python.md |
| Node.js | .js .mjs .cjs .ts,package.json | Node.js 官方 API 文档与 Learn 指南 | references/lang/nodejs.md |
优先级从高到低:
- 语言强制工具(如
gofmt),无条件执行。 - 项目的规范配置:
.clang-format/.clang-tidy、Checkstyle / Spotless、Ruff / Black、ESLint / Prettier、.editorconfig。它由团队决定、CI 执行,排版以它为准。 - 官方规范:上述配置没覆盖的部分。
- 语言版本以项目声明为准(
CMAKE_CXX_STANDARD、go.mod、maven.compiler.release、requires-python、engines.node),不用超出版本的特性。
规范只作用于本次改动的代码(见 2 第 6 条)。规范与「不兜底」「YAGNI」冲突时以本 skill 为准。
2.2 修 bug:先根因,后修复
- 读完整报错与堆栈,稳定复现。复现不了就继续收集证据,不猜。
- 沿数据流回溯到坏值的源头,在源头修。在症状处补默认值等于兜底。
- 写出一句假设:「根因是 X,因为 Y」。用最小改动验证,一次只改一个变量;不成立就换假设,不在失败的修法上叠加。
- 先写复现测试并看到它失败,再修复并看到它通过。
- 同一问题已试 3 种修法仍失败:停止再试,向用户说明现象,讨论设计本身是否有问题。
2.3 抽象判定:以现有调用方为依据,不以未来为依据
只按下表判定,表里没有的情况不抽象。
| 现状(第 1 步的搜索证据) | 做法 |
|---|---|
| 项目已有一份语义相同的实现(函数或内联代码),本次要写第二份 | 提取为一个函数,放到两个调用方最近的共同模块(按第 0 步结构图里的公共代码位置),原调用方改为调用它 |
| 已有 2 处以上只在少数值上不同的相似代码,本次要写下一处 | 合并为一个带参数的函数,参数只覆盖已出现的差异 |
| 已有函数只差一点就能满足本次需求 | 按第 1 步「小改造复用」,在原函数上改,不另起一份 |
| 只有一个实现,或只有一个调用方 | 不抽象:不建接口、基类、工厂、策略、泛型 |
| 代码长得像,但业务含义不同、会各自独立变化(偶然重复) | 不合并,各自保留;合并会把两个领域绑在一起 |
| 抽象的理由是「以后可能用」「更灵活」 | 不抽象 |
判断语义是否相同:问「这两处中的一处因业务调整需要修改时,另一处是否一定要跟着改」。一定要跟着改才算相同。
提取时:
- 改动原调用方属于本次需求,在回复里写明改了哪几处调用;只替换重复的那段,不顺手整理原文件的其他代码。
- 原调用方的行为不能变:已有测试本轮跑通;没有测试的,先补一条覆盖原行为的测试再提取。
- 提取出的函数名用业务语义命名(如
validate_email),不用helper、util1、common_func。
3. 安全底线之上的克制
必须做:
- SQL 参数绑定,不拼接
- XSS 按输出上下文转义
- 权限与资源归属校验(AuthZ)
- 外部请求做目标白名单与内网地址拦截(SSRF)
- 不可信数据用安全的反序列化方式
- 密钥、token 只从环境变量读取
不要做: 对内部可信契约重复校验;为不可能的输入写分支;层层 try-catch 吞错或静默降级;每个函数入口都防御性拷贝与全量 null 检查;以安全为名引入与风险不匹配的抽象。
判定:外部输入必校验,内部契约直接信任;失败要显式可见。 细则见 references/security-floor.md。
4. 交付验证:有证据才说完成
本轮没有运行验证命令并读到输出,就不能说「完成」「已修复」「测试通过」。
- 找出能证明结论的命令:测试、构建、2.1 对应语言参考里的校验命令、复现脚本。
- 完整运行。
- 读完输出,看退出码与失败数。
- 输出支持结论才下结论;不支持就如实报告实际状态。
| 结论 | 需要的证据 | 不算证据 |
|---|---|---|
| 测试通过 | 本轮测试输出 0 失败 | 之前的结果、「应该能过」 |
| 构建成功 | 构建命令退出码 0 | lint 通过 |
| bug 已修复 | 原始症状复现后消失 | 改了代码 |
| 需求已满足 | 第 0 步成功标准逐条核对 | 测试通过 |
| 子代理已完成 | 实际 diff | 子代理的自述 |
无法运行(缺工具、缺环境、无权限)时,写明哪些没验证、为什么,不用「应该没问题」代替。
交付前逐项核对,任一项不通过就回到对应步骤:
- 第 0 步的成功标准逐条有证据?
- 回复里给出了结构速览,新代码放在结构图对应的位置?
- 新建的函数、类、模块确实没有现成实现?
- 没有留下与已有代码语义相同的第二份实现;做过的抽象都能对应 2.3 表中的一行?
- 没有为「以后可能用」预留的参数、配置或抽象?
- 没有吞错、空兜底或静默降级?
- 没有把可批量的调用拆成循环里的逐个请求?
- 六条安全底线全覆盖,且没有多余的防御层?
- 符合语言规范与项目配置,校验命令已运行(没运行写明原因)?
- diff 的每一行都能追溯到需求,没有顺手改动,没破坏第 0 步列出的行为?
红旗:出现这些念头就停下
| 念头 | 实际 | 回到 |
|---|---|---|
| 「项目里应该没有现成的」 | 没搜就不知道 | 第 1 步 |
| 「新文件放这里就行」 | 没对照结构图,可能放错层 | 第 0 步第 1 条 |
| 「把那段复制过来改两行」 | 制造第二份实现 | 2.3 |
| 「先抽个接口 / 基类,结构更清晰」 | 只有一个实现就是空壳 | 2.3 |
| 「这两段长得一样,合并掉」 | 可能是偶然重复 | 2.3 语义判断 |
| 「加个默认值防止报错」 | 掩盖了坏值的来源 | 2 第 3 条 / 2.2 |
| 「先留个参数,以后好扩展」 | 现在没人用就是负担 | 2 第 1 条 |
| 「顺手把这个文件格式化一下」 | 超出需求,放大 diff | 2 第 6 条 |
| 「为了安全,每层都校验一遍」 | 边界校验一次即可 | 第 3 步 |
| 「大概是 X,先改了试试」 | 没有根因就是猜 | 2.2 |
| 「再试一种修法」(已失败 3 次) | 可能是设计问题 | 2.2 第 5 条 |
| 「应该能跑」「看起来没问题」 | 没有证据 | 第 4 步 |
维护
改动本 skill 后:用 evals/evals.json 做加载与不加载(或旧版本)两组对比,用 evals/trigger_evals.json 检查 description 的触发;再检查 frontmatter 只含合法 YAML、name 为小写字母数字与连字符、description 不超过 1024 字符。
- Downloads
- 100All time
- Security audit
- Pass
- Last updated
- 4d ago
- Current version
- v1.5.1
- License
- MIT-0
