04 - AI 协作原则
从 Sice 项目开发总结的与 AI 协作开发的经验和原则。
基本原则：你是决策者，AI 是执行者
核心观点：
- 你来：需求分析、架构设计、技术选型、方案决策
- AI 来：编写代码、生成文档、帮你搜索、发现问题
AI 很强大，但 AI 不会告诉你需要做什么和应该怎么做。
高效协作经验
1. 先思考，再让 AI 干活
❌ 不好：
帮我做一个 AI 文档处理应用✅ 好：
帮我实现这个功能：
- 目标：实现 Agent 认证模块
- 接口：需要提供 FastAPI 依赖，验证 Authorization header 中的令牌
- 令牌存在 ~/.sice/agent-state.json
- 无效令牌返回 401
- 请参考这个项目现有的代码风格经验：给 AI 的指令越具体，结果越符合预期。
2. 分而治之，一次做一件事
不要让 AI 一次性实现整个应用，分模块一次做一块：
- 第一天：架构设计和项目初始化
- 第二天：配置模块
- 第三天：认证模块
- 第四天：API 路由
- ...
好处：
- 每个模块 AI 能完整理解上下文
- 你能每个模块验证，错了及时修正
- 不会因为上下文太长导致质量下降
3. 充分利用工具，不依赖记忆
规则：遇到 API 问题，一定要查最新文档。
- Deep Agents/LangChain/LangGraph 问题 → 使用
mcp__docs-langchain__search_docs_by_lang_chain - 第三方库问题 → 使用 Context7 MCP 查询
- 网页内容抓取 → 使用 Tavily
不要：相信训练数据里的 API，随时可能过时。
4. 设计文档先写，代码后写
任何功能开写之前，先写设计文档：
- 记录背景和问题
- 记录设计决策和理由
- 记录权衡对比
- 明确目录和文件结构
好处：
- 你自己想清楚了，AI 才能做对
- 后续回来能快速找回上下文
- 新人能快速理解为什么这么设计
5. 计划跟踪进度
大任务拆成计划，按 Chunk 跟踪：
markdown
| Chunk | 状态 |
|-------|------|
| 项目初始化 | ✅ 完成 |
| 配置模块 | ✅ 完成 |
| 认证模块 | ⏳ 进行中 |
| API 路由 | ⏳ 待开始 |好处：
- 清楚知道做到哪了
- 中断后回来能快速恢复
- 预计完成时间更准确
常见陷阱和避免方法
陷阱 1：AI 说能做，就信了
AI 经常会「假装」能做，但实际写出来的代码有问题。
避免方法：
- 每个 Chunk 写完必须验证
- 不要因为是 AI 写的就不测试
- 跑不起来就立刻让 AI 修
陷阱 2：追求完美设计一开始
想要一步到位设计出完美架构，结果卡很久开不了工。
避免方法：
- 先做简单能跑的
- 验证思路可行再逐步完善
- 重构随时可以做
陷阱 3：不停让 AI 重写，越来越乱
AI 写不好，就让 AI 一遍一遍重写，结果代码越来越乱。
避免方法：
- 一两遍还不对，停下来自己分析问题出在哪
- 把问题拆小，分步骤让 AI 改
- 问题描述清楚，不要只说「不对，重写」
陷阱 4：忽略安全问题
AI 能生成访问文件系统和执行命令的代码，容易出安全问题。
避免方法：
- 安全设计从一开始就要考虑
- 权限控制一定要做
- 敏感操作必须要求用户确认
Claude Code 特定技巧
1. 充分使用 Skills
Claude Code 有很多现成的 Skills，直接用：
superpowers:brainstorming→ 头脑风暴，探索方案superpowers:writing-plans→ 写实现计划superpowers:executing-plans→ 执行计划superpowers:systematic-debugging→ 系统化调试
2. 使用 todo list 跟踪
TodoWrite 工具跟踪进度，清楚当前在做什么。
3. 并行启动多个 Agents
多个独立任务可以并行启动多个 Agents 探索：
python
Agent(subagent_type=Explore) # 探索代码
Agent(subagent_type=Plan) # 做计划节省时间。
文档规范
为什么要写文档？
- 几个月后回来，你需要找回上下文
- 别人学这个项目需要知道设计决策
- AI 也需要文档理解整体架构
文档分类存放
docs/
├── 01-design/ # 产品设计、技术架构 → 设计阶段
├── 02-dev/ # 开发说明、环境搭建、故障排除 → 开发阶段
└── 10-archived/ # 过期文档归档 → 不要删除，留着参考更新记录
技术文档要保留更新记录：
markdown
| 日期 | 更新内容 |
|------|----------|
| 2026-03-26 | 创建文档 |
| 2026-03-27 | 确认架构 |
| 2026-04-01 | 更新实现进展 |总结：AI 协作格言
- 你做决策，AI 写代码 → 方向对了，结果才对
- 分而治之，逐个验证 → 小步快跑，比大跃进靠谱
- 先设计，后编码 → 想清楚再动手
- 充分利用工具 → API 问题查官方文档，不猜
- 持续沉淀 → 经验记录下来，下次更快
AI 是生产力放大器，你越会用，效率越高。