# 生成式软件工程 Best Practice 

## P1 级别：强烈推荐

### 1. 高质量代码 = 高质量 Context

**核心观点：**
- 架构、命名、抽象、范例会直接影响 AI 后续生成
- 成熟代码库是好的 Context（Linux kernel 例子）
- 混乱代码库会让 AI 学到坏模式
- 软件架构本身已经变成 Prompt

**实践要点：**
- Clean Code、Good Architecture、Documentation、Consistency 不仅方便人维护，也在训练当前 Session 里的 Agent
- 代码不只是"给 CPU 执行的东西"，在 Agent 时代也是"Agent 的上下文"
- 好的设计模式会通过 self-attention 被 AI 发现并复用

### 2. 避免 AI Slop

**特征识别：**
- 大量硬编码
- 不断 patch 而非重构
- 难以修改和扩展
- 每次改动消耗大量 token

**预防措施：**
- 提前建立抽象
- 定期重构而非堆积
- 用架构约束而非规则列表
- 出现问题时推倒重来，而非持续 patch

**警告信号：**
- AI 开始反复阅读同一段代码
- 修改一个地方需要同时改很多地方
- 测试开始频繁失败
- Token 消耗突然增加

### 3. 知道 AI 的边界

**核心能力：**
- 判断什么该交给大模型，什么不该
- OCR 可以用 AI，精确计算用确定性程序
- 不要让 LLM 承担需要完全确定性的任务

**实践案例：**
- ✅ AI 做图像识别、文本理解、代码生成
- ❌ AI 做精确加法、关键安全决策、最终提交
- ✓ 人负责：验证、确认、关键决策
- ✓ AI 负责：探索、生成、迭代

### 4. 建立中间抽象/DSL

**思路：**
- 不要直接从需求跳到最终实现
- 设计中间表示/抽象层
- 分别验证：逻辑正确？翻译正确？结果正确？
- 类似编译器的中间语言思想

**案例（QR 项目）：**
```
需求 → 中间 DSL → Python 实现 + Excel 实现
       ↓
   逻辑验证 → Python 验证 → Excel 验证 → 结果验证
```

### 5. Reward Hacking 警惕

**定义：**
AI 完成了字面目标，却偏离真正意图

**危险示例：**
- "证明 A 有用" ≠ "判断 A 是否有用"
- "让测试通过" ≠ "修复真正的 bug"
- "快速完成" ≠ "高质量完成"

**预防：**
- Prompt Objective 必须精确对齐 Human Intention
- 明确区分"探索性问题"和"验证性问题"
- 定期回顾目标，而非只看进度

---

## P2 级别：进阶实践

### 6. 设计优先，分层抽象

**五层模型：**
```
Motivation（动机/哲学/品味）
    ↓
Design（框架性描述）
    ↓
Design-Specs（自动补全的设计细节）
    ↓
Spec（详尽的需求规范）
    ↓
Implementation（代码实现）
```

**职责分离：**
- 人维护更高层（Motivation、Design）
- AI 填充细节（Design-Specs、Spec、Implementation）
- 当某一层超出注意力极限，转而维护更高一级抽象

### 7. 双向反馈闭环

**不是单向推导，而是双向修正：**

**闭环 1：Motivation ↔ Design**
- Design 依据 Motivation 调整
- Design review 可以反向质疑 Motivation
- Motivation 不是一次定死的宪法

**闭环 2：Design ↔ Implementation**
- 实现中的问题反向更新 Design
- Agent 发现 Design 不合理时主动提出质疑
- 这些"抱怨"被收集起来用于改进

### 8. Context Pollution 与 Grounding

**Context Pollution 现象：**
- 完整论文/文档会带着自己的叙事逻辑"污染" AI 判断
- AI 的"总结"只是站在作者立场重新组织一遍原有论述

**Grounding 方法：**
- 先对齐已有知识基线（"你已经知道什么"）
- 再看增量（Δ = 新信息）
- 不要让 AI 从零总结，要从"人类已知边界"开始

**实践：**
```
错误：请总结这篇论文
正确：我已经了解 [背景知识]，这篇论文在此基础上增加了什么？
```

### 9. 算力换智力

**核心思路：**
开放问题不要要求一次生成最优答案，而应拆搜索空间

**方法：**
- 把大的难验证问题，转化成很多小的、易验证的问题
- 多个 Agent 并行搜索 + 过滤 + 比较
- 用更多算力换取更高质量决策

**案例（取名）：**
```
大空间："给我想个最好的名字" → 高概率趋同
拆解：
1. 枚举读音选项
2. 过滤不好读音
3. 每个读音开子 Agent 搜字
4. 按《诗经》等来源搜索
5. 过滤 + 比较 + 收敛
```

---

## 补充：NJU GenSE 课程其他 Best Practice

### 10. Git 工作流规范化

**Conventional Commits 提交信息规范**
```
feat: 新功能
fix: bug 修复
docs: 文档更新
refactor: 重构
test: 测试相关
chore: 构建/工具链
```

**Atomic Change 原则：**
- 每个 commit 只做一件事
- 保持可回滚
- 便于 git bisect 定位问题

**关键实践：**
- 使用 .gitignore 避免提交敏感信息（API keys、.DS_Store、build artifacts）
- git bisect 定位 bug 引入点
- git blame 结合 --ignore-rev 追溯代码来源
- 空提交标记里程碑：`git commit --allow-empty -m "chore: finalize v0.1"`
- 避免 merge，优先 rebase 保持历史清晰
- 不依赖 -v1/-v2 文件版本管理，用 Git 提交记录

### 11. 上下文工程与提示词设计（扩展）

**四要素扩展为六要素清单：**
1. **目标（Goal）** - 想要什么体验
2. **权限（Permission）** - 可以做什么、不可以做什么
3. **工作流（Workflow）** - 按什么顺序执行
4. **规则（Rules）** - 约束和边界条件
5. **环境事实（Environment）** - 当前状态、可用工具
6. **优先级（Priority）** - 发生冲突时如何选择

**Intent → Spec → Impl 三层拆解细化：**
- **Intent**：表达想要什么体验（用户视角）
- **Spec**：决定哪些行为和约束必须成立（验收标准）
- **Impl**：选择数据结构、引擎、算法（技术实现）

**验收条件优先：**
- 把"做好"改写为可检查的 V(T)=1
- 明确"什么情况下算成功"
- 提供可程序化验证的标准

**分层规则管理：**
- **系统规则（长期）**：权限边界、安全约束
- **项目规则（项目期）**：构建命令、代码约定
- **Skill（任务期）**：可复用流程
- **会话证据（短期）**：工具输出、临时决定

### 12. AI 学习反馈闭环

**五分钟学习循环：**
```
a. 写下可在五分钟内验证的小问题
b. 先给出预测和理由
c. 让 AI 提供最小解释/实验
d. 用代码/教材核对差异
e. 重新讲给 AI，让它追问薄弱环节
```

**费曼学习法反转：**
- 让 AI 当听众
- 通过复述暴露理解缺口
- AI 扮演"什么都不懂的学生"，指出逻辑跳步和遗漏

**关键：**
- 一步推理优于多步跳跃
- 每一步都可以单独验证
- 理解边界比记忆结论更重要

### 13. Agent 安全边界设计

**三层安全责任：**
1. **模型建议（Suggest）** - 提出命令
2. **Harness 决策（Decide）** - 解析、匹配批准策略
3. **操作系统强制（Enforce）** - 不可绕过的沙箱

**Fail-closed 原则：**
- 不确定时默认拒绝，而非允许
- 宁可漏掉一些安全操作，也不要错误执行危险操作

**五问动作门：**
1. 动作是什么？
2. 目标资源是谁？
3. 权限如何？
4. 能否恢复？
5. 默认行为？

### 14. 约束语言与设计规范

**把形容词翻译为可组合变量：**
- "现代" → 字体、色彩、间距、动效
- "专业" → 信息层级、对齐、密度
- "好用" → 关键任务、状态反馈、错误恢复

**设计语言要素：**
- 色彩范围（主色、辅色、语义色）
- 字体层级（Display、Heading、Body、Caption）
- 栅格系统（列数、间距、断点）
- 留白规则（内边距、外边距、行高）
- 组件参考（按钮、表单、卡片）
- 交互状态（Hover、Active、Focus、Disabled）
- 禁用模式（灰化、不可点击、提示）

**关键：**
- 提供参考物、范围或截图检查口
- 避免"AI 味"：不要只说"现代风格"
- 具体约束压缩搜索空间

### 15. Verifier 驱动开发（扩展）

**形式约束作为搜索空间压缩：**
- 可程序检查的约束（字数、格式、类型）
- 让模型能先生成候选、再根据失败位置补偿
- 迭代改进直到满足所有约束

**双层 Verifier：**
- **第一层：机器判定**
  - 格式正确性
  - 类型正确性
  - 边界条件
  - 权限检查
- **第二层：独立人工**
  - 解释合理性
  - 审美判断
  - 证据充分性
  - 用户体验

**测试是代理目标：**
- 需保留隐藏测试
- 需保留真实使用情境
- 不能只优化已知测试用例

### 16. AI Code Review 升级路径

**从角色扮演升级为证据审计：**
- 建立 claim–evidence–assumption 表格
- 显式标注置信度与证据来源
- 区分"作者声称"和"证据支持"

**三条独立审稿路线：**

**a. 剥离贡献**
- 重写问题定义
- 重写方法描述
- 重写新增信息
- 对比原文找差异

**b. 证据审计**
- 为核心 claim 建账本
- 每个 claim 找支撑证据
- 标注证据强度

**c. 反方复现**
- 寻找最小反例
- 尝试证伪核心结论
- 找边界条件

**流程：**
先独立重建 claim，再回正文寻找证据

### 17. 长上下文注意力管理

**阶段边界"呼吸"：**
- 实现结束后重述目标
- 记录已证实事实
- 列出未决问题
- 清理临时状态

**机制化胜过提示：**
| 约束类型 | 机制化方案 |
|---------|-----------|
| 类型约束 | 编译器 |
| 接口约束 | Property tests |
| 回归约束 | CI |
| 权限边界 | 执行层 |

**关键思路：**
- 把关键状态搬到注意力更有利的位置
- 用工具链强制约束，而非靠 prompt 提醒
- 定期总结和压缩上下文

### 18. AGENTS.md 与项目规范

**职责：**
- 为 agent 建立项目级行为约定
- 记录 best practice、警告和约束
- 定义代码库特定的工作流程

**注意事项：**
- 不要无限堆积规则（Context 污染）
- 只记录真正高频、高价值的约定
- 定期审查和清理过时规则

### 19. Vibe-Coding 与 Git 协同

**Git 历史清晰原则：**
- 避免 merge，优先 rebase
- 保持线性历史
- 每个 commit 独立可理解

**冲突解决：**
- 使用 IDE 工具（Accept Incoming/Current Change）
- 理解冲突的来源
- 不盲目接受任一方

**版本管理：**
- 不依赖 -v1/-v2 文件版本管理
- 用 Git 提交记录追溯变更
- 用 tag 标记重要版本

---

## 能力积累与长期发展

### 20. 能力飞轮

**循环模式：**
```
任务完成 → 总结方法 → 沉淀 Skill/Script → 自动执行 → 改进 → 继续循环
```

**关键点：**
- 不是每天重复做任务，而是建设"做任务的系统"
- 失败很重要，从失败中蒸馏出 Skill
- 一次成功的经验可以无限复用
- Skill 可以组合，产生 1+1>2 的效果

### 21. Human Time ↔ Compute 权衡

**两种工作模式：**

**模式 A：盯着纠正**
- 省算力，费时间
- 适合：关键路径、不确定性高、学习阶段

**模式 B：放手探索**
- 费算力，省时间
- 适合：明确任务、可验证结果、重复性工作

**判断标准：**
- 如果一件事你已经完全知道怎么做、AI 也能做，就应该更敢于放手
- 人的注意力应该花在 AI 无法替代、收益最大的地方
- 不要为了"我还是比 AI 强"的心理满足而盯着每一行代码

---

## 常见陷阱总结

### 22. 不要迷信神奇咒语

**过时做法：**
- "你是世界顶级专家……"
- "请一步一步思考……"
- 各种"咒语"式提示词

**现代做法：**
- 明确任务目标
- 清晰约束条件
- 可验证标准
- 结构化 > 修辞技巧

### 23. 《人月神话》的 AI 版

**问题模式：**
```
项目已经烂了 → 投入更多 token → 更多 AI slop → 更烂
```

**根本原因：**
- Token 不是架构的替代品
- 更聪明的模型不是工程设计的替代品
- 在错误的基础上堆砌只会更糟

**解决方案：**
- 及时识别"已经烂了"的信号
- 推倒重来而非继续 patch
- 先修架构再写代码

### 24. Long-horizon Task 的挑战

**典型症状：**
- Proof of concept 很容易
- 持续加功能到某个临界点后崩溃
- 修改成本越来越高
- 错误越来越多

**应对策略：**
- 提前规划架构
- 建立模块边界
- 持续重构
- 不要等到"烂了"再处理

---

## 未来方向

### 25. Design 模块化复用（进行中）

**目标：**
让 Design 本身具备模块化、可复用的能力，而不是每个项目从头积累

**思路：**
- 提取通用 Design pattern
- 建立 Design 库
- 跨项目复用
- 持续改进和演化

### 26. 主动利用 Context Pollution

**研究方向：**
- 收集优秀软件工程项目
- 提取好的设计模式
- 压缩成文档/示例
- 放进 Context
- 故意"用好的工程经验污染 AI"

**挑战：**
- 不同设计风格会互相冲突
- 不是简单把几十个优秀项目全塞进去
- 需要提炼出一致的设计哲学

---