stream-coding

Stream Coding v3.5：文档优先开发

⚠️ 关键重构：这是一种文档方法论，而非编码方法论

目标： 面向 AI 的文档。文档足够清晰时，代码生成便会自动完成。

洞察：

“如果文档足够好，AI 就能编写代码。真正艰巨的工作是编写文档。代码不过是打印出来的结果。”

v3.5 核心新增内容：

1. 阶段 2.5 对抗性审查——在执行前由持怀疑态度的批评者对规格进行压力测试。新的时间分配：40/40/5/10/5。
2. 将内部 13 项检查清单重命名为 Spec Gate（确保结构完整，以便生成代码）

双关卡流水线——了解两者的区别：

• Spec Gate（13 项，本技能）→ “AI 能否无需提问就执行？”
• Clarity Gate（9 个要点，独立工具）→ “AI 会不会把假设误当成事实？”

Spec Gate → Clarity Gate → 对抗性审查 → 已验证规格 → 执行

---

更新日志

版本	更改
3.0	Stream Coding 方法论初始版本
3.1	术语更清晰，Spec Gate 设为必需
3.3	根据文档类型决定内容位置（在实现文档中列出反模式、测试用例和错误处理）
3.3.1	修正时间分配（40/40/20），新增阶段 4，新增分歧规则
3.4	完整的 13 项 Spec Gate、带权重的评分标准、自评问题、4 个必需的章节模板，以及集成到阶段 1 的文档审计
3.5	新增阶段 2.5 对抗性审查。新的时间分配：40/40/5/10/5。将内部 13 项检查清单从“Clarity Gate”重命名为“Spec Gate”。记录双关卡流水线：Spec Gate（结构性）+ 独立的 Clarity Gate（认知性）。

---

Stream Coding 的真相

Messy Docs → Vague Specs → AI Guesses → Rework Cycles → 2-3x Velocity
Clear Docs → Clear Specs → AI Executes → Minimal Rework → 10-20x Velocity

为什么大多数“AI 辅助开发”会失败：

• 人们给 AI 提供杂乱的文档
• AI 基于假设生成代码
• 代码不符合意图
• 反复修改，没完没了
• 结果：只比手动编码快一点

Stream Coding 为何能实现 10–20 倍效率：

• 首先理清文档
• AI 不会遇到任何歧义
• 代码一次就符合意图
• 修改次数极少
• 结果：编写文档所需的时间 + 自动代码生成

---

文档类型架构

规则： 并非所有文档都需要包含所有章节。在战略文档中加入实现细节会破坏单一事实来源。

“如果 AI 必须自行判断去哪里查找信息，你就已经失去了速度优势。”

文档类型

类型	用途	示例
战略文档	做什么以及为什么	总体蓝图、PRD、愿景文档、商业案例
实现文档	如何实现	技术规格、API 文档、模块规格、架构文档
参考文档	查阅信息	Schema 参考、术语表、配置

章节位置矩阵

章节	战略文档	实现文档	参考文档
深层链接（引用）	✅ 必需	✅ 必需	✅ 必需
反模式	❌ 仅提供指引	✅ 必需	❌ 不适用
测试用例规格	❌ 仅提供指引	✅ 必需	❌ 不适用
错误处理矩阵	❌ 仅提供指引	✅ 必需	❌ 不适用

这为何重要

错误（破坏单一事实来源）：

Master Blueprint
├── Strategy content
├── Anti-patterns ← WRONG: duplicates Technical Spec
├── Test Cases ← WRONG: duplicates Testing doc
└── Error Matrix ← WRONG: duplicates Error Handling doc

正确（单一事实来源）：

Master Blueprint (Strategic)
├── Strategy content
└── References
    └── Pointer: "Anti-patterns → Technical Spec, Section 7"

Technical Spec (Implementation)
├── Implementation details
├── Anti-patterns ← CORRECT: lives here
├── Test Cases ← CORRECT: lives here
└── Error Matrix ← CORRECT: lives here

---

4 阶段方法论

时间分配

阶段	时间	重点
阶段 1：战略思考	40%	构建什么、为什么重要
阶段 2：AI 就绪文档	40%	如何构建（规范要清晰到让 AI 无需做任何决定）
阶段 2.5：对抗性审查	5%	在执行前，让持反对意见的审查者对规范进行压力测试
阶段 3：执行	10%	代码生成 + 实现
阶段 4：质量与迭代	5%	测试、完善、防止偏离

原理： 前期投入 5% 的时间来找出规范的问题，可以节省超过 5% 的阶段 3 返工时间。如果通过对抗性审查让文档无懈可击，执行会更快，而不是更慢。

---

阶段 2.5：对抗性审查（占总时间的 5%）

何时执行

规范关卡通过（9+/10）后、生成任何代码之前。

原则： 编写规范的 AI 和你有着同样的盲点。另一个模型，或受指示进行挑错的人类，能发现你看不到的问题。

“代码出错时，修复规范，而不是代码。阶段 2.5 会在代码出错之前发现规范的问题。”

流程

1. Spec Gate passes (9+/10) → proceed to adversarial step
2. Submit specs to DIFFERENT AI model (Gemini, GPT-4, Perplexity)
   OR trusted human reviewer
3. Use the adversarial prompt below
4. Categorize findings: CRITICAL / HIGH / MEDIUM / LOW
5. Fix ALL CRITICAL issues → return to Spec Gate → re-score
6. Document HIGH issues with explicit accept/defer decision
7. Gate: zero CRITICAL remaining → proceed to Phase 3

为什么要用不同的模型： 生成或审查文档的 AI 已经接受了你的假设。不同的模型没有上下文，不会善意解读，也不会宽容以待。它能发现你的主力 AI 已经习以为常的漏洞。

对抗性提示词模板

You are a skeptical senior developer and hostile critic reviewing 
this specification before it goes to an AI agent for execution.

## Your Mission
Find every flaw. Assume problems exist — your job is to find them.
Do not be helpful. Do not suggest minor improvements. Attack the spec.

## What to Look For

### 1. LOGICAL CONTRADICTIONS
- Claims that conflict with each other within the spec
- Numbers that don't add up
- Requirements that are mutually exclusive

### 2. CREDIBILITY RISKS  
- Overclaims ("zero bugs", "always", "never", "guaranteed")
- Unverifiable statements with no measurement method
- Claims a hostile reader would immediately challenge

### 3. IMPLICIT DEGREES OF FREEDOM
- Points where the AI agent must CHOOSE between valid interpretations
- Anything where two different developers would implement differently
- Edge cases that are mentioned but not fully specified

### 4. MISSING CONSIDERATIONS
- Error states that have no specified handling
- Concurrency or race conditions not addressed  
- External dependencies with no fallback specified
- Security assumptions not made explicit

### 5. DEFENSIBILITY GAPS
- "What would a hostile HN commenter use to debunk this?"
- "What would a junior developer get wrong from this spec?"
- "What happens when the happy path fails?"

## Output Format

For each issue found:
**[SEVERITY]** — Issue title  
Location: Where in the spec  
Problem: What exactly is wrong  
Fix: Specific rewrite needed  

Severity:
- **CRITICAL:** Execution will fail or produce wrong output without this fix
- **HIGH:** Significant risk of incorrect implementation  
- **MEDIUM:** Minor ambiguity, lower risk
- **LOW:** Polish, not blocking

## Success Criteria

A good adversarial review finds:
- At least 2 CRITICAL issues (if zero, you haven't looked hard enough)
- At least 4-5 HIGH issues
- 10+ total issues across all severities

If you find fewer, state explicitly why the spec is unusually strong.

关卡标准

• 未解决的 CRITICAL 问题为零
• 所有 HIGH 问题均已记录，并明确决定：立即修复 / 接受风险 / 延后处理
• 如果修复了任何 CRITICAL 问题，则重新运行规范关卡（评分可能已变化）

什么算作“不同的 AI”

规则：始终使用不同于主工作流的提供商。同一提供商 = 确认偏误。

此步骤有意采用手动方式——将规范粘贴到另一个聊天中，并应用对抗性提示词。无需 API 密钥或集成。

选项	使用方式	备注
GPT-5.2 / GPT-5.3（ChatGPT）	聊天 — 无需 API 密钥	通用推理能力强；GPT-5.3-Codex 擅长发现代码规范中的漏洞
Gemini 3 Pro / 3.1（AI Studio）	聊天 — 无需 API 密钥	上下文窗口达 1M；擅长发现长篇规范中的逻辑矛盾
GitHub Copilot（IDE 聊天）	编辑器内	使用方便；基于 GPT-5.x；无需切换上下文
o3 / o4-mini（ChatGPT）	聊天或 API	最擅长发现逻辑漏洞和边界情况
Perplexity	聊天	适合核查事实和可信度
可信赖的人类（资深开发者）	—	信息价值最高，投入也最大

切勿使用曾帮助编写文档的同一个 Claude 会话。至少要开启新会话，最好使用不同的模型。

---

阶段 1：战略思考（占总时间的 40%）

决策树：从哪里开始？

Phase 1: Strategic Product Thinking
│
├─ Have existing documentation?
│   └─ YES → Start with Documentation Audit → then 7 Questions
│
└─ Starting fresh?
    └─ Skip to 7 Questions

文档审计（条件性）

如果从零开始，请跳过此步骤。 文档审计仅适用于已有文档的情况，例如之前的规范、继承的文档或累积的笔记。

为什么要清理现有文档？ 因为大多数文档都会积累冗余内容：

• 愿景式陈述（“我们将带来变革……”）
• 推测未来（“到 2030 年，我们或许……”）
• 过时的决策（v3 文档中仍采用 v1 架构）
• 多个文件中重复的信息
• 对实现毫无价值的激励性空话

审计流程：

对所有现有文档应用清晰度测试：

检查项	问题
可执行	AI 能据此采取行动吗？如果只是愿景式内容，就删除。
当前有效	这仍是当前决策吗？如果已变更，请更新或删除。
单一来源	其他地方也有这项内容吗？请整合到一处。
已决策	这已经决定了吗？如果没有，就不要纳入。
适合用于提示词	你会把这段内容放进 AI 提示词吗？如果不会，就删除。

审计清单：

• 删除所有“愿景”和“未来状态”表述
• 删除激励性的结论和前言
• 将重复信息整合到单一来源
• 更新所有过时的架构决策
• 删除当前范围之外的推测性功能

目标： 在不丢失可执行信息的前提下，将文档量减少 40-50%。

清理完成后，继续回答 7 个问题。

---

7 个问题框架

编写任何新文档之前，务必具体回答以下问题。回答含糊，代码也会含糊。

#	问题	❌ 不合格	✅ 合格
1	你要解决的具体问题是什么？	“帮助用户管理任务”	“帮助[特定用户画像]在[特定情境]中实现[可衡量的结果]”
2	成功指标是什么？	“用户节省时间”	数字 + 时间范围：“100 名用户、25% 转化率、3 个月”
3	你凭什么胜出？	“更好的 UI 和功能”	结构性优势：架构、数据护城河、商业模式
4	核心架构决策是什么？	“让 AI 决定”	人类根据明确的权衡分析作出决策
5	技术栈的选择依据是什么？	“因为我喜欢 Node.js”	商业依据：“Node——团队熟悉，交付更快”
6	MVP 功能有哪些？	10 个以上“必备”功能	3-5 个真正必不可少的功能，其余明确推迟
7	你不会构建什么？	“看看用户想要什么再说”	明确列出不包含的内容及其理由

阶段 1 退出标准

• 所有 7 个问题均达到“合格”标准
• 已创建战略蓝图文档
• 已为重大选择编写架构决策记录（ADR）
• 对你要构建的内容没有任何歧义

---

阶段 2：面向 AI 的文档（占用 40% 时间）

4 个必备章节（实现文档）

每份实现文档都必须包含以下 4 个章节。缺少这些内容，AI 就会靠猜测——而猜测会造成速度假象。

1. 反模式章节

原因： AI 需要知道哪些做法不可取。

## Anti-Patterns (DO NOT)

| ❌ Don't | ✅ Do Instead | Why |
|----------|---------------|-----|
| Store timestamps as Date objects | Use ISO 8601 strings | Serialization issues |
| Hardcode configuration values | Use environment variables | Deployment flexibility |
| Use generic error messages | Specific error codes per failure | Debugging impossible otherwise |
| Skip validation on internal calls | Validate everything | Internal calls can have bugs too |
| Expose internal IDs in APIs | Use UUIDs or slugs | Security and flexibility |

规则： 每份实现文档至少列出 5 个反模式。

2. 测试用例规范

原因： AI 需要明确的验证标准。

## Test Case Specifications

### Unit Tests Required
| Test ID | Component | Input | Expected Output | Edge Cases |
|---------|-----------|-------|-----------------|------------|
| TC-001 | Tier classifier | 100 contacts | 20-30 in Critical tier | Empty list, all same score |
| TC-002 | Score calculator | Activity array | Score 0-100 | No events, >1000 events |

### Integration Tests Required
| Test ID | Flow | Setup | Verification | Teardown |
|---------|------|-------|--------------|----------|
| IT-001 | Auth flow | Create test user | Token refresh works | Delete test user |

规则： 每个组件至少包含 5 个单元测试和 3 个集成测试。

3. 错误处理矩阵

原因： AI 需要知道如何处理每种故障模式。

## Error Handling Matrix

### External Service Errors
| Error Type | Detection | Response | Fallback | Logging | Alert |
|------------|-----------|----------|----------|---------|-------|
| API timeout | >5s response | Retry 3x exponential | Return cached | ERROR | If 3 in 5 min |
| Rate limit | 429 response | Pause 15 min | Queue for retry | WARN | If >5/hour |

### User-Facing Errors
| Error Type | User Message | Code | Recovery Action |
|------------|--------------|------|-----------------|
| Quota exceeded | "You've used all checks this month." | 403 | Show upgrade CTA |
| Session expired | "Please sign in again." | 401 | Redirect to login |

规则： 必须说明每项外部服务和面向用户的错误。

4. 深层链接（所有文档类型）

原因： AI 需要跳转到确切位置。“参见技术附录”毫无用处。

## References

### Schema References
| Topic | Location | Anchor |
|-------|----------|--------|
| User profiles | [Schema Reference](../schemas/schema.md#user_profiles) | `user_profiles` |
| Events table | [Schema Reference](../schemas/schema.md#events) | `events` |

### Implementation References
| Topic | Document | Section |
|-------|----------|---------|
| Auth flow | [API Spec](../specs/api.md#authentication) | Section 3.2 |
| Rate limiting | [API Spec](../specs/api.md#rate-limiting) | Section 5 |

规则： 绝不要使用含糊的引用。务必注明文档路径 + 章节锚点。

---

⚠️ 规范门槛（v3.5 - COMPLETE）

⛔ 绝不要跳过此门槛。

这是流式编码与氛围编码的区别。7/10 的规范会生成 7/10 的代码，并需要返工 30%。

13 项规范门槛检查清单

生成任何代码之前，务必确认所有项目均通过：

基础检查（7 项）

#	检查项	问题
1	可执行性	AI 能否对每个部分采取行动？（不含空泛内容）
2	时效性	所有内容是否都是最新的？（不含过时决策）
3	单一信息源	文档之间是否没有重复信息？
4	决策而非愿望	每项陈述都是决策，而非期望吗？
5	可直接用于提示词	你会把每个部分都放进 AI 提示词中吗？
6	不含未来状态	是否删除了所有“最终会”“可能”“理想情况下”等表述？
7	不含冗余内容	是否删除了所有激励性／空泛内容？

文档架构检查（6 项 - v3.3 关键项）

#	检查项	问题
8	已标明类型	是否清楚标明文档类型？（战略、实现或参考）
9	已放置反模式	反模式是否只放在实现文档中？（战略文档提供指引）
10	已放置测试用例	测试用例是否只放在实现文档中？（战略文档提供指引）
11	已放置错误处理	错误处理矩阵是否只放在实现文档中？
12	包含深层链接	所有文档是否都包含深层链接？（不使用含糊的“参见其他地方”）
13	没有重复内容	战略文档是否使用指引，而非重复内容？

门禁执行

- [ ] All 7 Foundation Checks pass
- [ ] All 6 Document Architecture Checks pass
- [ ] AI Coder Understandability Score ≥ 9/10

If ANY item fails → Fix before proceeding to Phase 3

---

AI 编码 Agent 可理解性评分

使用此评分标准评估文档。目标：进入第 3 阶段前达到 9+/10。

6 项标准评分表

标准	权重	10/10 要求
可执行性	25%	每个部分都有实现影响说明
具体性	20%	所有数字都具体，所有阈值都明确
一致性	15%	单一事实来源，文档之间没有重复内容
结构	15%	优先使用表格而非散文，层级清晰，格式可预测
消除歧义	15%	包含反模式（每份实现文档至少 5 项），明确列出边缘情况
参考清晰度	10%	仅使用深层链接，不含含糊的引用

分数解读

分数	含义	操作
10/10	AI 无需任何澄清即可实现	进入第 3 阶段
9/10	需要 1 项小澄清	修正后继续
7-8/10	存在 3-5 处歧义	需要重大修订
<7/10	尚未达到 AI 就绪状态，存在根本性问题	返回第 2 阶段

自我评估问题

进入第 3 阶段前，问自己：

1. 可执行性：“每个部分都准确告诉 AI 要做什么了吗？”
2. 具体性：“是否有任何数字仍然含糊不清？”
3. 一致性：“是否有任何信息在多个地方重复出现？”
4. 结构：“是否可以把某些散文段落转换为表格？”
5. 消除歧义：“每份实现文档是否都至少列出了 5 项反模式？”
6. 参考清晰度：“是否有任何引用只说‘参见其他地方’，却没有给出确切位置？”

如果你对任何本应回答相反的问题答了“否”或“是” → 继续前先修正。

---

AI 辅助规格门禁（元提示词）

使用此提示词让 Claude 为你的文档评分：

**ROLE:** You are the Spec Gatekeeper. Your job is to ruthlessly 
evaluate software specifications for ambiguity, incompleteness, and 
"vibe coding" tendencies.

**INPUT:** I will provide a technical specification document.

**TASK:** Grade this document on a scale of 1-10 using this rubric:

**RUBRIC:**
1. **Actionability (25%):** Does every section dictate a specific 
   implementation detail? (Reject aspirational like "fast" or 
   "scalable" without metrics)
2. **Specificity (20%):** Are data types, error codes, thresholds, 
   and edge cases explicitly defined? (Reject "handle errors appropriately")
3. **Consistency (15%):** Single source of truth? No duplicates?
4. **Structure (15%):** Tables over prose? Clear hierarchy?
5. **Disambiguation (15%):** Anti-patterns present? Edge cases explicit?
6. **Reference Clarity (10%):** Deep links only? No vague references?

**OUTPUT FORMAT:**
1. **Score:** [X]/10
2. **Criterion Breakdown:** Score each of the 6 criteria
3. **Hallucination Risks:** List specific lines where an AI developer 
   would have to guess or make an assumption
4. **The Fix:** Rewrite the 3 most ambiguous sections into AI-ready specs

**THRESHOLD:** 
- 9-10: Ready for code generation
- 7-8: Needs revision before proceeding
- <7: Return to Phase 2

---

第 3 阶段：执行（占用 10% 的时间）

生成-验证-集成循环

1. GENERATE: Feed spec to AI → Receive code
2. VERIFY: Run tests → Check against spec
   - Does output match spec exactly?
   - Yes → Continue
   - No → Fix SPEC first, then regenerate
3. INTEGRATE: Commit → Update documentation if needed

第 3 阶段黄金法则

“代码出错时，修规格，而不是修代码。”

如果生成的代码无法正常工作：

1. ❌ 不要手动修补代码
2. ✅ 问：“我的规格中有哪些内容不够清楚？”
3. ✅ 修正规格
4. ✅ 重新生成

**原因：**手动修改代码会导致规格与实际情况偏离。偏离会不断累积。最终，你的规格会沦为虚构，而你又回到了手动开发。

---

第 4 阶段：质量与迭代（占用 5% 的时间）

偏离规则

每次手动编辑 AI 生成的代码却不更新规格，都会造成偏离。偏离就是技术债务。

偏离的危险之处：

• 如果你修复了代码中的错误，却没有修正规格，就永远无法重新生成该模块
• 后续 AI 迭代会重新引入该错误
• 你破坏了流程

防止偏离

场景	❌ 错误做法	✅ 正确做法
生成的代码有 Bug	手动修复代码	修复规范，重新生成
缺少边界情况	添加代码补丁	在规范中补充，重新生成
性能问题	优化代码	记录约束，重新生成
需要“快速修复”	“就这一次……”	不行。修复规范。

“第二天”的工作流

1. 隔离模块： 针对特定模块，而不是整个应用
2. 更新规范： 添加新的边界情况、需求或修复
3. 重新生成模块： 将更新后的规范提供给 AI
4. 验证集成： 运行测试套件，检查是否有回归问题

这比快速热修复多花 5 分钟，但可以确保文档始终与实际情况一致。

---

触发行为

用户说出以下内容时，将启用此方法：

• “构建 [功能]” → 完整方法（阶段 1-4）
• “创建 [组件]” → 完整方法
• “实现 [系统]” → 检查：是否已有清晰的文档？
• “编写 [项目] 的文档” → 仅阶段 1-2
• “为 [功能] 编写规范” → 仅阶段 1-2
• “整理 [X] 的文档” → 仅进行文档审计

响应流程

1. 检查现有文档：“这个项目是否已有文档？”
2. 如果有现有文档：“我们先进行文档审计，整理好之后再开始构建。”
3. 如果阶段 1 未完成：“开始构建前，我们先明确策略。[提出 7 个问题]”
4. 如果阶段 2 未完成：“开始编码前，我们先确保文档已准备好供 AI 使用。[运行规范关卡]”
5. 如果未通过规范关卡：“文档得分为 [X]/10。我们先修复[具体问题]再继续。”
6. 如果阶段 3 已就绪：“文档已通过规范关卡（9+/10）。正在生成实现……”
7. 如果处于维护阶段（阶段 4）：“这项变更是否符合规范？我们先更新文档。”

---

流式编码契约

你必须：

文档审计（如果已有文档）：

• 对所有现有文档进行清晰度测试
• 删除描述愿景或未来状态的措辞
• 将重复内容合并到单一来源
• 在不丢失可操作内容的前提下，将内容精简 40-50%

阶段 1：

• 按“必答”级别回答全部 7 个问题
• 创建包含实现影响的战略蓝图
• 为重要的架构决策编写 ADR

阶段 2：

• 确定文档类型（战略类、实现类或参考类）
• 在每份实现类文档中加入 4 个必备章节
• 为所有文档添加深层链接
• 在战略类文档中使用指针，而非重复内容

阶段 2.5 — 对抗性审查：

• 将规范提交给不同的 AI 模型或人工审查者
• 使用对抗性提示词模板
• 在进入阶段 3 前修复所有严重问题
• 记录高优先级问题，并注明接受或延期的决定
• 如果已修复严重问题，重新运行规范关卡

规范关卡：

• 通过全部 13 项检查清单
• AI 编码者可理解性评分达到 9+/10
• 正确回答全部 6 个自评问题

阶段 3-4：

• 创建文件前先展示代码
• 运行质量关卡（lint、类型检查、测试）
• 代码失败时：修复规范，重新生成
• 绝不造成偏离（每次更改代码时都更新规范）

你不能：

• ❌ 未先进行文档审计就基于现有文档构建
• ❌ 未准备清晰文档就跳到编码
• ❌ 接受模糊的规范（“适当处理错误”）
• ❌ 跳过规范关卡（即使文档是你自己写的）
• ❌ 在战略类文档中加入反模式、测试用例或错误处理
• ❌ 使用模糊的引用（“参见技术附录”）
• ❌ 在不同类型的文档之间重复内容
• ❌ 问题出在规范中时仍反复修改代码
• ❌ 修改代码却不更新规范（这会造成偏离）

---

文档模板

战略文档模板

# [Document Title] (Strategic)

## 1. [Strategic Section]
[Strategic content]

**Implementation Implication:** [Concrete effect on code/architecture]

## 2. [Another Section]
[Strategic content]

**Implementation Implication:** [Concrete effect on code/architecture]

## N. REFERENCES

### Implementation Details Location
| Content Type | Location |
|--------------|----------|
| Anti-patterns | [Technical Spec, Section 7](path#anchor) |
| Test Cases | [Testing Doc, Section 3](path#anchor) |
| Error Handling | [Error Handling Doc](path#anchor) |

### Schema References
| Topic | Location | Anchor |
|-------|----------|--------|
| [Topic] | [Path](path#anchor) | `anchor` |

*This document provides strategic overview. Technical documents provide implementation specifications.*

实现文档模板

# [Document Title] (Implementation)

## 1. [Implementation Section]
[Technical details]

## N-3. ANTI-PATTERNS (DO NOT)

| ❌ Don't | ✅ Do Instead | Why |
|----------|---------------|-----|
| [Anti-pattern] | [Correct approach] | [Reason] |

## N-2. TEST CASE SPECIFICATIONS

### Unit Tests
| Test ID | Component | Input | Expected Output | Edge Cases |
|---------|-----------|-------|-----------------|------------|
| TC-XXX | [Component] | [Input] | [Output] | [Edge cases] |

### Integration Tests
| Test ID | Flow | Setup | Verification | Teardown |
|---------|------|-------|--------------|----------|
| IT-XXX | [Flow] | [Setup] | [Verify] | [Cleanup] |

## N-1. ERROR HANDLING MATRIX

| Error Type | Detection | Response | Fallback | Logging |
|------------|-----------|----------|----------|---------|
| [Error] | [How detected] | [Response] | [Fallback] | [Level] |

## N. REFERENCES

| Topic | Location | Anchor |
|-------|----------|--------|
| [Topic] | [Path](path#anchor) | `anchor` |

---

快速参考

13 项规范门槛

基础（7 项）：

1. 可执行？2. 是当前状态？3. 是否为唯一信息源？4. 是决策而非愿望？
2. 可直接用于提示词？6. 不包含未来状态？7. 没有废话？

架构（6 项）： 8. 已识别类型？9. 反模式是否放置在正确位置？10. 测试用例是否放置在正确位置？ 11. 错误处理是否放置在正确位置？12. 是否包含深层链接？13. 是否没有重复内容？

评分标准

标准	权重
可执行性	25%
具体性	20%
一致性	15%
结构	15%
消歧	15%
参考清晰度	10%

时间分配

┌─────────────────────────────────────────────────────────────┐
│ Have existing docs? → Documentation Audit (conditional)     │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Phase 1 (Strategy): 40% ──┐                                │
│  Phase 2 (Specs): 40% ─────┼── 80% Documentation            │
│                            │                                │
│  ⚠️ SPEC GATE ─────────────┘                                │
│                            │                                │
│  🔴 Phase 2.5 (Adversarial): 5% ← different AI attacks spec │
│                            │                                │
│  Phase 3 (Code): 10% ──────┼── 15% Code + Quality           │
│  Phase 4 (Quality): 5% ────┘                                │
│                                                             │
└─────────────────────────────────────────────────────────────┘

核心准则

1. “文档就是工作本身。代码只是打印出来的结果。”
2. “代码出错时，修正规范，而不是代码。”
3. “7/10 的规范会生成 7/10 的代码，并需要 30% 的返工。”
4. “如果 AI 还得决定去哪里查找信息，你已经失去速度优势了。”

---

版本： 3.5 相较于 3.4 的变更：

• 新增阶段 2.5 对抗性审查（包含完整章节、流程、提示词模板和门槛标准）
• 更新了时间分配：40/40/5/10/5（原为 40/40/15/5）
• 全文将“清晰度门槛”改名为“规范门槛”（结构完整性，共 13 项）
• 记录了双门槛流程：规范门槛（本技能）+ 清晰度门槛（独立的单独工具，用于评估认知质量）
• 合同章节新增阶段 2.5 检查清单
• 更新了快速参考图
• 核心要点：规范门槛检查完整性。对抗性审查检查正确性。清晰度门槛（独立工具）检查认知偏移。

---

Francesco Marinoni Moretto 的 Stream Coding — CC BY 4.0 github.com/frmoretto/stream-coding

STREAM CODING v3.5 结束