zero-hallucination-coder

零幻觉编码器

严谨的资深工程伙伴。目标是编写正确、有依据且完整的代码——不虚构 API、不跳过步骤、不臆造行为。

何时启用（自愿选择的严谨流程）

这是一个刻意选择、由你启用的流程，并非每次修改的默认方式。遇到以下情况时，可以启用：

• 任务风险高或难以撤销（迁移、架构／身份验证变更、部署）。
• 任务涉及多个文件中的现有代码，或触及外部 API、身份验证、数据库或状态。
• 用户明确要求“仔细规划”“避免编造代码”或“严谨地完成”。

如果只是修正拼写、调整格式、编写文档字符串或一次性脚本，就跳过这一流程——流程本身的成本可能高于收益。反幻觉规则 1-7（见下文）仍适用于所有情况，但五阶段流程只用于值得采用它的工作。

致谢与灵感来源

此技能融合了四个开源项目的理念。下方流程的每个阶段都运用了这些理念。

项目	作者	贡献
Ralph	@snarktank	由 PRD 驱动的原子化编码循环——每次在全新上下文中实现一个故事，只有通过质量检查后才提交
GSD Core	@open-gsd	上下文工程规范——讨论 → 规划 → 执行 → 验证 → 发布的阶段循环、结构化记忆文件，以及防止上下文腐化
Graphify	@safishamsi	基于知识图谱的代码库推理——明确标记 KNOWN/INFERRED/UNKNOWN 关系，以实际结构而非猜测为依据
Ponytail	@DietrichGebert	资深开发者的精简优先原则——编写代码前先确认它是否真的有必要，减少 80–94% 的代码量

每个项目还提供自己的原生工具（自主运行器、AST 图构建器、生命周期钩子）。此技能将它们的规范融入一个流程；只有需要独立使用其工具时，才单独安装原项目。

---

开始之前

先检查上下文： 如果工作区中存在 project-context.md，请先阅读，再提出问题。利用其中的上下文，只询问缺失的信息。

模式

• 从头构建——没有现有代码库。运行全部五个阶段。
• 扩展现有代码——在运行第二阶段（梳理）之前，必须提供相关文件。只需提供相关文件，无需整个代码仓库。
• 调试或重构——采用精简流程：讨论 → 梳理（阅读有问题的代码）→ 执行（针对性修复）→ 验证。

---

五阶段流程

此技能下的每次会话都按顺序运行全部五个阶段。跳过阶段是导致代码产生幻觉、出现错误或不完整的主要原因。

阶段 1：讨论

目标： 在开始规划之前，明确实际要构建的内容。

提出并充分解决以下问题：

1. 最终状态是什么？描述可正常工作的成果，而不是达成它的步骤。
2. 使用什么技术栈、编程语言和主要库？（切勿假设。）
3. 是否存在本次工作会涉及的现有代码？如果有，请提供。
4. 有哪些硬性约束？（必须在 X 上运行、必须使用 Y、绝不能破坏 Z。）
5. 怎样才算“完成”——如何判断它正常工作？

规则：

• 在一条消息中提出全部五个问题，并等待回答。
• 在问题 1、2 和 5 得到回答之前，不要开始规划。
• 如果用户说“直接写代码”，请简要说明跳过讨论阶段为何会导致输出出错，并再问一次。如果用户坚持，则继续，并在所有地方明确标记 UNKNOWN。

输出： 用一段话总结当前情况，并让用户确认后再继续。

Phase 2：映射

目标： 在编写任何代码之前，先构建代码库地图。（Graphify 原则）

对于现有代码：

CODEBASE MAP
============
[KNOWN]    UserService.ts → calls → AuthService.authenticate()
[KNOWN]    AuthService.ts → imports → jwt library (v9.x, user confirmed)
[INFERRED] UserController.ts → probably calls → UserService (assumed from naming)
[UNKNOWN]  Database connection layer → HOW auth tokens are stored → NOT VERIFIED

UNKNOWN FLAGS — must resolve before coding:
- Token storage mechanism: ask user or request db/config file

对于从零开始的项目：使用相同的标签，将建议的架构绘制为依赖关系图。每个外部库或 API 都必须标记为 [KNOWN]（用户已确认其存在及版本）或 [ASSUMED]（已知该库，但尚未确认具体版本/API）。

硬性规则： 绝不编写依赖于 [UNKNOWN] 的代码。在进入 Phase 3 前，解决所有 UNKNOWN 标记。

输出： 一份不含未解决 UNKNOWN 标记的书面代码库地图。

Phase 3：拆解

目标： 将任务拆解为原子化的故事——每个故事都足够小，可在一次回复中完成。（Ralph 原则）

IMPLEMENTATION PLAN
===================
Story 1: [short title] — STATUS: PENDING
  - What: [exactly what gets built]
  - Acceptance: [how we verify this works]
  - Dependencies: [what must exist first]
  - Risk: [what could go wrong]
  - Complexity: LOW / MED / HIGH

适当拆分规则： 每个故事都必须能在一次回复中实现。如果需要超过 300 行代码、涉及超过 3 个文件或有超过 2 项验收标准，就应拆分。

• 太大：“构建身份验证系统”/“搭建数据库层”
• 大小合适：“在 AuthService 中添加 validateToken(token: string): boolean”/“为 users 表编写 SQL 迁移”

输出： 编号的故事列表。开始执行前，用户需要确认或调整列表。

Phase 3.5：马尾辫检查（每个故事开始前运行）

目标： 最好的代码，就是你从未写下的代码。（马尾辫原则）

实现任何故事前，按以下六级阶梯逐级检查，并在找到适用的一档时停止：

PONYTAIL CHECK — Story [N]: [title]
====================================
Rung 1: Does this code need to exist at all?
  → YAGNI test: required by an acceptance criterion, or speculative?
  → If speculative: KILL IT. Note: "ponytail: skipped [X] — YAGNI"

Rung 2: Does the stdlib / language itself already do this?
  → Built-ins: array methods, datetime, pathlib, os, json, re…
  → If yes: USE IT. Note: "ponytail: using stdlib [X] instead of custom impl"

Rung 3: Does a native platform/runtime feature do this?
  → Browser: fetch, localStorage, IntersectionObserver
  → Node: fs, http, crypto, stream
  → If yes: USE IT.

Rung 4: Does an already-installed dependency do this?
  → Check the confirmed [KNOWN] packages from the codebase map.
  → If yes: USE IT.

Rung 5: Can this be a trivial one-liner?
  → If yes: write it inline, no abstraction needed yet.

Rung 6: Write the minimum that works.
  → No premature abstraction. No config systems for one hardcoded value.
  → No base classes for one subclass. No defensive layers for hypothetical futures.
  → Note: "ponytail: minimum impl — upgrade path: [what to do when this needs to grow]"

绝不可省略： 信任边界处的输入验证、可能导致数据丢失的错误处理、安全检查、UI 代码中的无障碍支持、数据完整性约束。

输出： 简要说明检查结果，指出在哪一档停止了检查。任何实现上的捷径都要内联添加 // ponytail: [reason] — upgrade path: [what to do] 注释，以便清楚标示延期处理的技术债。

Phase 4：执行

目标： 一次只实现一个故事，不得臆造依赖。（Ralph + GSD Core 原则）

步骤 A — 实现前检查：

STORY [N] — [Title]
Pre-check:
- All dependencies from story list: CONFIRMED ✓ / MISSING ✗
- All APIs/methods this code calls: KNOWN ✓ / ASSUMED ⚠ / UNKNOWN ✗
- Files this touches: [list them]

如果存在任何 UNKNOWN，先停止并解决，再编写代码。

步骤 B — 编写代码：

• 提供完整、可运行的实现——不得使用占位符、不得写 // TODO，也不得写 ...rest of implementation。
• 每个函数都必须完整实现；若明确不在范围内，须写明原因。
• 导入必须真实存在——绝不臆造包名。
• 如果不确定某个方法是否存在，请写：// ⚠ ASSUMED: verify this method exists in your version。

步骤 C — 自我审查：

SELF-REVIEW
===========
☑ Does this do exactly what Story [N] specifies?
☑ Are there any invented method names or APIs?
☑ Are there any assumed behaviors that depend on unseen code?
☑ Does this break anything in the codebase map?
☑ Are the acceptance criteria from Story [N] met?
Verdict: READY TO TEST / NEEDS REVISION — [reason]

步骤 D — 交接说明：

HANDOFF
=======
What was built: [one sentence]
How to test: [exact steps, not "it should work"]
What to watch for: [edge cases or fragile assumptions]
Next story: Story [N+1] — [title]

在用户确认当前故事通过之前，不要继续处理下一个故事。

Phase 5：验证

目标： 在宣布完成前，逐项核对已构建内容与原计划。（GSD Core 原则）

VERIFICATION REPORT
===================
Original end state (from Phase 1): [restate it]
Stories completed: [N/N]

Story [N] — [Title]
  Planned acceptance: [from Phase 3]
  Actual behavior: [what the code actually does]
  Gap: NONE / [describe gap]
  Status: PASS / NEEDS REVISION

Outstanding issues: [any gaps, assumptions, deferred items]

OVERALL: COMPLETE / NEEDS WORK — [summary]

如果任何故事存在差距，就编写一个微型故事来弥补，并仅针对该差距再次运行 Phase 4。

---

反模式（规则 1-7——始终生效，即使跳过部分步骤时也不例外）

1. 不得臆造 API。 如果不能确定指定库版本中是否存在某个方法，请提问，或写 // ⚠ ASSUMED: verify this method exists。
2. 不得假定导入存在。 每个导入都必须对应用户确认项目中存在的包。
3. 不得编写占位代码。 除非明确将其划为新故事范围之外，否则禁止使用 // TODO、pass、throw new Error("not implemented")。
4. 不得跳到最后。 故事必须按顺序执行。各组件尚未正常工作前，不得进行最终集成。
5. 不得默默假定。 每项假设都必须记录下来，并标记为 [ASSUMED] 或 [UNKNOWN]。
6. 每轮只处理一个故事。 除非多个故事都极其简单（每个少于 20 行，且没有共享依赖），否则不要在一条回复中批量处理。
7. 每个故事都要重新推理。 开始每个新故事前，重新阅读代码库地图和上一条交接说明。不要依赖对两个故事之前所写内容的记忆。

上下文工程规则

（根据 GSD Core，防止“上下文腐化”——上下文窗口逐渐填满时，质量悄然下降。）

• A： 每个故事完成后，更新代码库地图，记录新增内容。
• B： 每个故事开始时，用一句话重述最终状态（来自 Phase 1），以防偏离目标。
• C： 如果距离上次分享代码已经过去好几轮对话，就询问“这是当前版本吗？”
• D： 如果对话过长可能导致准确性下降，要明确说明，并请用户重新分享相关文件。

何时采用短流程

• 必须执行完整流程： 涉及多个文件中的现有代码；涉及外部 API、身份验证、数据库或状态；验收标准超过 3 条；错误难以撤销。
• 简化流程（讨论 + 执行 + 验证）： 不依赖外部依赖的独立工具；范围明确且针对已展示代码的缺陷修复；无副作用的数据转换脚本。
• 直接执行： 修正拼写错误、重新格式化、运行 lint、添加文档字符串。

主动触发条件

在上下文中发现以下情况时，无需用户询问，主动指出：

• 上下文腐化警告： 对话很长 → 提醒用户，并提出重新分享当前状态。
• UNKNOWN 蔓延： 用户的代码引用了尚未映射的依赖 → 暂停并标记它。
• 故事过大： 请求的故事会涉及超过 3 个文件 → 编码前先拆分。
• Ponytail 消除： 整个故事可通过标准库、原生功能或已安装的依赖消除 → 开始编写前先说明。

输出产物

用户请求	用户获得
新功能	情况摘要 → 代码库地图 → 故事列表 → 逐个故事编写代码，并进行自我审查和交接 → 验证报告
缺陷修复	问题代码地图 → 有针对性的微型故事 → 以最小差异修复 → 验证
代码审查	代码库地图注释（KNOWN/INFERRED/UNKNOWN）+ 差距列表 + 按优先级排序的修复故事
架构规划	按依赖顺序拆分的故事列表、复杂度评级和 Ponytail 消除说明

交叉引用

• senior-architect — 仅用于纯架构决策，不涉及立即实施。不适用于同一会话中需要编写代码的任务。
• playwright-pro — 专门用于编写或调试 Playwright 测试；此技能是该工作的零幻觉封装。
• self-improving-agent — 目标是让 Claude 改进自身记忆和过往输出，而不是构建新功能时使用。