####################################
Tutorial 10: 氛围编程最佳实践
####################################
.. include:: ../links.ref
.. include:: ../tags.ref
.. include:: ../abbrs.ref
============ ==========================
**Abstract** 氛围编程的最佳实践总结
**Authors** Walter Fan
**Status** WIP
**Updated** |date|
============ ==========================
.. contents::
:local:
氛围编程原则
============
经过前面的学习，让我们总结氛围编程的核心原则：
.. code-block:: text
氛围编程核心原则
┌─────────────────────────────────────────────────────────────────┐
│ │
│ 1. 清晰优先 │
│ ─ AI 放大你的清晰度，也放大你的困惑 │
│ │
│ 2. 规格先行 │
│ ─ 先想清楚要什么，再让 AI 实现 │
│ │
│ 3. 迭代优化 │
│ ─ 不追求一次完美，快速迭代验证 │
│ │
│ 4. 保持判断 │
│ ─ AI 是助手不是主人，最终决策在你 │
│ │
│ 5. 持续学习 │
│ ─ 从 AI 的输出中学习，提升自己 │
│ │
└─────────────────────────────────────────────────────────────────┘
工作流最佳实践
==============
日常开发工作流
--------------
.. code-block:: text
氛围编程日常工作流
┌─────────────────────────────────────────────────────────────────┐
│ │
│ 开始任务 │
│ │ │
│ ▼ │
│ 理解需求 ──→ 不清楚 ──→ 与 AI 讨论澄清 │
│ │ │
│ ▼ 清楚 │
│ 写简要规格 │
│ │ │
│ ▼ │
│ 让 AI 生成代码 │
│ │ │
│ ▼ │
│ 审查代码 ──→ 有问题 ──→ 让 AI 修改 │
│ │ │
│ ▼ 通过 │
│ 运行测试 ──→ 失败 ──→ 调试修复 │
│ │ │
│ ▼ 通过 │
│ 提交代码 │
│ │
└─────────────────────────────────────────────────────────────────┘
大型功能开发流程
----------------
1. **需求分析阶段**
::
与 AI 讨论需求，澄清模糊点：
我要实现一个 [功能]，请帮我分析：
1. 需要考虑哪些场景？
2. 有哪些边界情况？
3. 可能的技术挑战是什么？
2. **设计阶段**
::
请帮我设计这个功能的架构：
1. 模块划分
2. 接口设计
3. 数据流
4. 技术选型建议
3. **实现阶段**
- 按模块分批实现
- 每个模块完成后测试
- 及时提交，保持小步快跑
4. **测试阶段**
::
@module.py
请生成完整的测试用例，覆盖：
1. 正常流程
2. 边界条件
3. 异常处理
5. **代码审查**
::
@feature/
请审查这个功能的实现，关注：
1. 代码质量
2. 安全性
3. 性能
4. 可维护性
提示词最佳实践
==============
结构化提示词
------------
使用一致的结构让 AI 更好理解：
.. code-block:: markdown
## 任务
[简要描述要做什么]
## 上下文
[提供必要的背景信息]
## 要求
1. [具体要求 1]
2. [具体要求 2]
3. [具体要求 3]
## 约束
- [不要做什么]
- [技术限制]
## 输出格式
[期望的输出形式]
渐进式细化
----------
从高层开始，逐步细化：
**第一轮**::
设计一个用户管理模块的整体架构
**第二轮**::
基于这个架构，详细设计用户注册流程
**第三轮**::
实现用户注册的 API 端点
**第四轮**::
为注册 API 添加输入验证
上下文管理
----------
有效管理上下文，避免信息过载：
.. list-table::
:header-rows: 1
:widths: 30 70
* - 做法
- 说明
* - 使用 @ 引用
- 精确引用需要的文件，而不是整个项目
* - 分批处理
- 大型任务分成多个小任务
* - 及时清理
- 新话题开新对话
* - 提供摘要
- 长对话中定期总结上下文
Rules 最佳实践
==============
项目 Rules 模板
---------------
.. code-block:: markdown
# Project: [项目名称]
## Tech Stack
- Language: [语言和版本]
- Framework: [框架和版本]
- Database: [数据库]
- Other: [其他重要技术]
## Code Style
- [代码风格规范]
- [命名约定]
- [文件组织]
## Architecture
- [架构模式]
- [目录结构]
- [模块划分]
## Conventions
- [团队约定 1]
- [团队约定 2]
## Examples
[提供示例代码]
分层 Rules
----------
.. code-block:: text
.cursor/rules/
├── global.md # 通用规则
├── python.md # Python 特定
├── api.md # API 开发
├── frontend.md # 前端开发
└── testing.md # 测试规范
代码质量最佳实践
================
生成代码后的检查清单
--------------------
.. code-block:: markdown
## AI 生成代码检查清单
### 正确性
- [ ] 逻辑是否正确
- [ ] 边界条件是否处理
- [ ] 错误处理是否完善
### 安全性
- [ ] 输入是否验证
- [ ] 是否有注入风险
- [ ] 敏感数据是否保护
### 性能
- [ ] 算法复杂度是否合理
- [ ] 是否有 N+1 问题
- [ ] 是否需要缓存
### 可维护性
- [ ] 命名是否清晰
- [ ] 是否有必要的注释
- [ ] 是否符合项目规范
### 测试
- [ ] 是否有测试
- [ ] 测试覆盖是否充分
代码审查要点
------------
1. **不要盲目接受**
- 理解每一行代码的作用
- 质疑不合理的实现
- 验证关键逻辑
2. **关注 AI 常见问题**
- 过度复杂的解决方案
- 不必要的依赖
- 忽略项目现有代码
- 使用过时的 API
3. **保持代码一致性**
- 与项目现有风格一致
- 使用项目已有的工具函数
- 遵循项目的架构模式
协作最佳实践
============
团队协作
--------
1. **共享 Rules**
将 Rules 纳入版本控制，团队共享：
.. code-block:: bash
git add .cursorrules
git add .cursor/rules/
git commit -m "Add team coding rules"
2. **建立提示词库**
团队共享有效的提示词模板：
.. code-block:: text
prompts/
├── code-review.md
├── test-generation.md
├── bug-fix.md
└── refactoring.md
3. **统一工具配置**
- 统一 AI 模型选择
- 统一代码格式化工具
- 统一 linter 配置
与 AI 协作
----------
1. **明确角色分工**
- **你**: 需求、设计、决策、审查
- **AI**: 实现、建议、解释、生成
2. **建立反馈循环**
::
你的实现有以下问题：
1. [问题 1]
2. [问题 2]
请修改并解释你的改动
3. **利用 AI 学习**
::
你刚才使用了 [某技术/模式]，
请详细解释：
1. 为什么选择这种方式
2. 有什么优缺点
3. 什么场景下适用
常见陷阱与避免
==============
陷阱 1：过度依赖
----------------
**问题**: 完全依赖 AI，失去自己的判断力
**避免**:
- 理解 AI 生成的每一行代码
- 定期手写代码保持技能
- 对关键逻辑进行人工验证
陷阱 2：上下文丢失
------------------
**问题**: 长对话后 AI 忘记之前的上下文
**避免**:
- 定期总结对话上下文
- 重要信息写入 Rules
- 大任务分多个对话
陷阱 3：盲目接受
----------------
**问题**: 不审查就使用 AI 生成的代码
**避免**:
- 建立代码审查清单
- 运行测试验证
- 关注安全和性能
陷阱 4：提示词不清
------------------
**问题**: 模糊的提示词导致不理想的结果
**避免**:
- 使用结构化提示词
- 提供具体的示例
- 明确约束条件
陷阱 5：忽略规格
----------------
**问题**: 跳过规格直接让 AI 写代码
**避免**:
- 先写简要规格
- 让 AI 确认理解
- 分步骤实现
效率提升技巧
============
快捷键熟练度
------------
.. list-table::
:header-rows: 1
:widths: 30 70
* - 快捷键
- 用途
* - ``Cmd+L``
- 快速打开 Chat
* - ``Cmd+K``
- 快速内联编辑
* - ``Cmd+I``
- 多文件编辑
* - ``Tab``
- 接受补全
* - ``Cmd+Shift+L``
- 新建 Chat
常用提示词收藏
--------------
建立你的提示词快捷方式：
.. code-block:: text
# 我的常用提示词
## 代码生成
/gen: 生成代码，要求类型注解和文档
## 测试
/test: 生成 pytest 测试，包含正常、边界、异常
## 审查
/review: 审查代码质量、安全、性能
## 解释
/explain: 解释代码的作用和原理
## 重构
/refactor: 重构代码，保持功能不变
工作流自动化
------------
1. **Git Hook 集成**
- pre-commit: AI 代码审查
- commit-msg: 生成 commit message
2. **CI/CD 集成**
- PR 自动审查
- 测试覆盖率检查
持续改进
========
定期回顾
--------
每周/每月回顾你的氛围编程实践：
1. 哪些提示词效果好？
2. 哪些场景 AI 帮助最大？
3. 哪些地方需要改进？
4. 学到了什么新技巧？
更新 Rules
----------
根据项目演进更新 Rules：
- 技术栈升级
- 新的代码规范
- 团队约定变化
- 发现的最佳实践
关注社区
--------
- 关注 AI 编程工具的更新
- 学习社区分享的技巧
- 参与讨论和分享
小结
====
氛围编程最佳实践总结：
**核心原则**:
1. 清晰优先
2. 规格先行
3. 迭代优化
4. 保持判断
5. 持续学习
**工作流**:
- 理解 → 规格 → 生成 → 审查 → 测试 → 提交
**关键技能**:
- 结构化提示词
- 有效的上下文管理
- 代码审查能力
- 持续改进意识
氛围编程不是取代编程能力，而是放大你的能力。
掌握这些最佳实践，让 AI 成为你最强大的编程伙伴。
进一步学习
==========
推荐资源
--------
- `Cursor 官方文档 `_
- `Anthropic Prompt Engineering `_
- `AI-Assisted Development `_
社区资源
--------
- `Cursor Directory `_: 社区 Rules 分享
- `Awesome Cursor Rules `_
- `Prompt Engineering Guide `_
练习
====
1. 创建你的个人 Rules 文件
2. 建立你的提示词模板库
3. 实践一个完整的 SDD 流程
4. 与团队分享你的最佳实践
5. 定期回顾和改进你的工作流
结语
====
氛围编程代表了软件开发的新范式。它不是简单地让 AI 写代码，
而是建立人与 AI 之间高效协作的框架。
记住：
**AI 是生产力放大器——它既放大你的清晰度，也放大你的困惑。**
保持清晰的思维，建立系统的方法，持续学习和改进，
你就能在 AI 时代成为更高效的开发者。
祝你的氛围编程之旅愉快！🚀