# AI Coding Practice

## 核心要点

明确预期，过程控制，充分验证，保持干净。

## 七条最佳实践（完整）

1. 完整描述问题场景  
给完整报错栈和日志，需求文档尽量完整。需求不清时先让模型提问，再进入实现。

2. 分步执行  
先有完整大纲，再按最小可验证闭环逐步完成。每一步都能单独验收、回滚。

3. 保持干净的工作现场  
代码不可用或结构明显变差就回滚。连续尝试不收敛时，不要在坏方向上继续堆改动。

4. 提供空桩  
用函数、类、文件入口约束模型思考路径，而不是只给抽象目标。

5. 不要纠缠  
改 Bug 多轮不收敛就开新会话并回滚。经验上 3 轮是常见上限。

6. 做好事后清洁  
提交前删掉无意义 log、注释、校验代码。保留真正有价值的背景信息和修复原因。

7. 清晰上下文  
给绝对路径、入口函数、必要行号和相关文件，提升检索速度和改动准确性。

## 从 0 到 1（Step by Step）

1. 拆解需求  
把原始需求转成技术文档，明确改动点、接口、数据流和边界。

2. 逐步实现  
基于技术文档生成 Todo，逐步实现并逐步验证。每个节点结束后人工验收。

3. 最终优化  
全部通过后先做人审，再做小范围优化。优化效果不佳时，宁可回滚不强推。

## 改线上 Bug（Step by Step）

1. 现场还原  
优先确认复现步骤、日志证据和重点文件。已知原因可直接按小需求处理。

2. 诊断迭代  
找不到原因就先补可观测信息，再用新日志开新会话继续分析。

3. 举一反三  
修复后排查同类问题，但只保留人审后有价值的防御代码。

4. 信息沉淀  
把修复背景、原因和结论写回需求或技术文档，作为后续搜索与重构参考。

## 多模型配合（完整）

- Claude：擅长“想清楚”，用于拆问题、理逻辑、生成 PRD 与结构化任务描述。  
- Codex：擅长“干活”，用于执行指令、改代码、跑环境、做迭代。  
- Gemini：擅长长上下文与多模态，用于复杂前端、视觉理解和长链路分析。  

## 模型使用原则

先用 Claude 把需求翻译清楚，再把结构化任务交给 Codex 执行，复杂视觉或超长上下文再由 Gemini 补位。  
核心目标是减少来回拉扯和无效 token 消耗，提升一次实现成功率。