zero-hallucination-coder 快速入门

这是什么？适合谁？

zero-hallucination-coder 是 alirezarezvani/claude-skills（24.5k 星的 Claude 技能库）engineering 目录下的一个防幻觉编码 Skill：它用一条严格的五阶段循环—Discuss -> Map -> Decompose -> Execute -> Verify—把代码锚定在已核实的代码结构上：不发明 API、不假设 import、不写占位代码，并叠加一条”懒惰资深工程师”的 YAGNI 阶梯，在代码写出来之前先删掉不必要的代码（作者称可减少 80-94% 代码量）。它是四个开源项目纪律的合成：Ralph 的 PRD 原子编码循环、GSD Core 的上下文工程、Graphify 的知识图谱推理（KNOWN/INFERRED/UNKNOWN 标注）、Ponytail 的懒惰层级。

适合人群：用 Claude Code/Codex 等编码 Agent 做高风险改动（迁移、认证、数据库 schema、多文件特性）的开发者；被 Agent”发明不存在的 API”坑过的人；想在团队里推行严格编码纪律的技术负责人。 使用前提：使用支持 Agent Skills 的编码工具（Claude Code 等）；任务值得这份仪式感—改错别字、一次性脚本不需要全循环。

快速上手（3 步）

第一步：安装 Skill

zero-hallucination-coder 随 alirezarezvani/claude-skills 仓库分发（.claude-plugin 插件形态或直接复制 skill 目录）：

git clone https://github.com/alirezarezvani/claude-skills
# 按仓库 INSTALLATION.md 指引启用 engineering/zero-hallucination-coder

第二步：在一个高风险任务上显式调用

用 zero-hallucination-coder 纪律处理这个任务：
把用户表的认证从 session 迁移到 JWT，涉及 auth 中间件与刷新令牌存储。

Skill 是opt-in管道：显式点名调用才会跑完整五阶段。

第三步：走完第一个循环

• Phase 1 DISCUSS：Agent 一次问清 5 个问题（终态/技术栈/现有代码/硬约束/完成判据），等你回答
• Phase 2 MAP：输出 CODEBASE MAP，每条关系标注 [KNOWN]/[INFERRED]/[UNKNOWN]—有未解决 UNKNOWN 就不写码
• Phase 3 DECOMPOSE：拆成一次响应能装下的原子故事
• Phase 4 EXECUTE：逐故事实现，只依赖已验证结构
• Phase 5 VERIFY：按 Phase 1 的”完成判据”验证

首个任务的预期产出：一份你确认过的 Situation Summary、一张无未解 UNKNOWN 的代码库地图、一份原子实施计划、逐故事交付的代码与验证结果。

初级用法

• 三种模式选对：Build from scratch（全五阶段）/ Extend existing code（Phase 2 前必须共享相关文件，只要相关文件不要整个仓库）/ Debug or refactor（缩略循环：Discuss -> Map -> Execute -> Verify）。
• context 复用：工作区有 project-context.md 就先读再问，只问缺口，避免重复盘问。
• 七条反幻觉规则全程有效：即使跳过五阶段循环（小改动），不发明 API/不假设 import 等规则仍然适用。

高级玩法

1. 迁移前哨：把 Phase 2 的 KNOWN/INFERRED/UNKNOWN 地图当作迁移可行性评审材料—UNKNOWN 数量就是风险清单，强制在写码前变成 KNOWN（问人/读配置）。
2. YAGNI 阶梯当需求过滤器：让 Agent 在 DECOMPOSE 前先跑 Ponytail 式删除：这个功能需要存在吗？用户会用到吗？砍掉 80-94% 的计划代码量再开工。
3. 团队纪律模板化：把五阶段循环的输出格式（Situation Summary/CODEBASE MAP/IMPLEMENTATION PLAN）固化为团队 PR 模板，评审人先查地图再看 diff。

常见踩坑（5 条）

踩坑 1：小任务也跑全循环

• 现象：改一行文案等了五轮问答
• 原因：把 opt-in 纪律当默认行为
• 解决：Skill 自己就声明”错别字/一次性脚本不需要循环”；小改动直接让 Agent 按 7 条反幻觉规则干活

踩坑 2：跳过 DISCUSS 直接要代码

• 现象：用户说”直接写”后幻觉复发
• 原因：问题 1/2/5（终态/技术栈/完成判据）没有答案
• 解决：Skill 会解释为何不能跳并再问一次；坚持跳过则所有依赖处标 UNKNOWN 显式暴露

踩坑 3：MAP 阶段只贴整个仓库

• 现象：地图冗长且 UNKNOWN 一大堆
• 原因：把整个 repo 塞给 Agent 而非相关文件
• 解决：只共享任务触及的文件；Skill 明确”request only the files that matter”

踩坑 4：[INFERRED] 被当成事实用

• 现象：基于”大概这么调用”写出错码
• 原因：混淆 INFERRED（命名推测）与 KNOWN（用户确认）
• 解决：硬规则—绝不写依赖 [UNKNOWN] 的代码；INFERRED 在 EXECUTE 前升级为 KNOWN

踩坑 5：装了 Skill 却发现没生效

• 现象：Claude 没按五阶段走
• 原因：未正确安装/启用，或任务描述未触发
• 解决：按仓库 INSTALLATION.md 检查启用状态；显式点名调用

FAQ（5 个常见问题）

Q1：这个 Skill 收费吗？ A：免费，MIT 协议仓库（alirezarezvani/claude-skills，24.5k 星）分发。

Q2：和直接让 Claude “小心别编造” 有什么区别？ A：提示词叮嘱靠模型自觉；本 Skill 是结构化流程强制—UNKNOWN 不清零不写码、每故事独立验证、YAGNI 删减先行，纪律落在流程里而非语气里。

Q3：只能在 Claude Code 用吗？ A：仓库同时提供 .claude/.codex/.gemini/.hermes 等多套运行时目录，主流编码 Agent 均可启用；核心是 SKILL.md 的流程定义，可移植。

Q4：会拖慢开发吗？ A：会增加前置问答与地图成本，但换来的是高风险任务上更少的返工。设计上就是”高杠杆任务专用”：迁移/auth/数据库/多文件特性用它，小修不用。

Q5：80-94% 代码减少的数据从哪来？ A：来自其所借鉴的 Ponytail 项目的宣称数字，属于方法论声明而非受控实验结论；实际效果取决于任务与团队，建议自测对比。

小技巧（5 条）

1. 先写 project-context.md：把技术栈、关键约束、完成判据常驻工作区，DISCUSS 阶段直接复用，省一轮问答。
2. UNKNOWN 当 TodoList：地图里的 UNKNOWN flags 就是下一步行动清单，逐条消灭后再放行 EXECUTE。
3. debug 模式省时：修 bug/重构用缩略循环（跳过 DECOMPOSE），保留地图与验证两个关键阶段。
4. --kind 式任务归类：给任务打 high-stakes / routine 标签，只有前者进全循环，团队效率与质量两头兼顾。
5. 配套使用原项目：需要自动化运行器/AST 图构建等原生工具时，另装 Ralph/Graphify 等被借鉴项目的独立工具链。

进阶学习建议

• 对比研读被借鉴的四件作品（Ralph 的原子循环、GSD Core 的上下文工程、Graphify 的 KNOWN/INFERRED/UNKNOWN 标注、Ponytail 的懒惰层级），理解每阶段纪律的来源与取舍
• 把 CODEBASE MAP 的三色标注法用到自己的架构评审流程里，练习”区分已验证事实与命名推测”的思维
• 在真实迁移任务上对比”直接让 Agent 写”与”五阶段循环”的返工率，量化防幻觉纪律在自己代码库上的收益
• 浏览 alirezarezvani/claude-skills 的 engineering 目录（migration-architect、zero_downtime_techniques 等姊妹 Skill），组合出覆盖”规划->迁移->验证”全链路的纪律工具箱

参考链接

• alirezarezvani/claude-skills 仓库
• zero-hallucination-coder SKILL.md

本文基于公开资料于 2026-08-18 整理，社区指标反映 GitHub 公开数据。独立实测未进行，功能和配置项可能随版本更新而变化，请以官方文档为准。