🎯 历史项目 + 新需求：AI 提效方案

这是个非常关键的问题！AI 理解历史需求的能力有限但可用，关键是如何引导 AI。

🧠 AI 能否理解之前的需求？

实话实说：部分能，但需要帮助

AI 能理解的

AI 难以理解的

✅ 代码结构和逻辑

❌ 业务背景和商业决策

✅ 数据流和依赖关系

❌ 为什么当初这样设计（历史原因）

✅ 接口定义和用法

❌ 未文档化的"潜规则"

✅ 测试用例覆盖的场景

❌ 用户的真实使用习惯

✅ 提交历史中的变更原因

❌ 团队内部的默契约定

📋 核心策略：人机协作，AI 辅助

┌─────────────────────────────────────────────────────┐

│                   新需求开发流程                      │

├─────────────────────────────────────────────────────┤

│  1. 人类：提供业务背景和需求描述                      │

│  2. AI：分析现有代码，理解技术实现                    │

│  3. 人类：解释关键设计决策和历史原因                  │

│  4. AI：生成实现方案和代码                           │

│  5. 人类：评审方案，补充边界条件                      │

│  6. AI：生成代码 + 测试                              │

│  7. 人类：验证业务逻辑正确性                          │

│  8. AI：文档更新 + 经验记录                          │

└─────────────────────────────────────────────────────┘

🔧 具体实施方案

阶段 1：需求理解与上下文注入（关键！）

1.1 创建"需求上下文包"

# 新需求上下文文档

## 业务背景

- 这个功能解决什么问题？

- 目标用户是谁？

- 预期使用场景？

## 与现有功能的关系

- 依赖哪些现有模块？

- 会影响哪些现有功能？

- 是否需要向后兼容？

## 历史设计决策（重要！）

- 为什么用户模块用 JWT 而不是 Session？

- 为什么数据库用 MySQL 而不是 PostgreSQL？

- 为什么 API 版本化用 URL 而不是 Header？

## 约束条件

- 性能要求（QPS、响应时间）

- 安全要求（认证、授权、审计）

- 合规要求（数据隐私、日志保留）

1.2 让 AI 学习现有代码

使用我的 workspace-analyzer 和 superpowers 技能：

# 分析现有代码结构

python evoclaw/validators/check_workspace.py

# 让 AI 理解关键模块

sessions_spawn({

 task: "分析用户认证模块的实现逻辑，总结设计模式",

 mode: "run",

 runTimeoutSeconds: 300

})

1.3 建立"知识检索"机制

使用 RAG（检索增强生成）思路：

新需求 → 检索相似历史代码 → AI 参考实现 → 生成新代码

我可以帮你：

用 tavily-search 搜索类似技术方案

用 memory_search 查找历史经验

用 feishu_doc 读取项目文档

阶段 2：Spec 驱动开发（我的强项！）

2.1 使用 openspec 技能

需求 → Spec 文档 → AI 评审 → 代码生成 → 测试验证

工作流程：

// 1. 先写 Spec（人类 + AI 协作）

// specs/new-feature.md

## 功能描述

用户可以在个人中心上传头像

## 现有模块复用

- 使用现有的 file-upload 服务

- 使用现有的 user-store 更新用户信息

- 复用现有的 auth 中间件

## 新增接口

POST /api/v1/user/avatar

- 输入：multipart/form-data (image)

- 输出：{ avatarUrl: string }

## 边界条件

- 图片大小 ≤ 5MB

- 格式：jpg/png/webp

- 自动裁剪为正方形

## 测试场景

- 正常上传

- 超大文件拒绝

- 不支持格式拒绝

- 未登录拒绝

2.2 AI 评审 Spec

# 使用 openspec 技能

/opsx:propose specs/new-feature.md

AI 会检查：

✅ 是否与现有架构一致

✅ 是否遗漏边界条件

✅ 是否有潜在冲突

✅ 测试场景是否完整

2.3 代码生成

# Spec 确认后，AI 生成代码

/opsx:apply specs/new-feature.md

阶段 3：增量开发与回归保护

3.1 识别影响范围

# AI 分析代码依赖

sessions_spawn({

 task: "分析 user-avatar 功能会影响哪些现有模块，列出需要回归测试的点",

 mode: "run"

})

产出：

影响分析：

├── 直接影响

│   ├── user-store.ts (更新用户信息)

│   └── file-upload.service.ts (文件上传)

├── 间接影响

│   ├── 个人中心页面 (需要显示新头像)

│   └── 缓存层 (头像 URL 需要缓存更新)

└── 回归测试

   ├── 用户登录流程

   ├── 用户信息编辑

   └── 文件上传功能

3.2 自动生成回归测试

使用 superpowers 技能：

// AI 生成测试用例

describe('头像上传 - 回归测试', () => {

 it('不应影响现有用户登录流程', async () => {

   // 验证登录不受影响

 });

 it('不应影响现有用户信息更新', async () => {

   // 验证其他字段更新正常

 });

});

阶段 4：知识沉淀（避免下次重复）

4.1 记录到记忆系统

使用我的 self-improving-agent 技能：

// memory/experiences/2026-03-15.jsonl

{

 "type": "new_feature",

 "feature": "用户头像上传",

 "learnings": [

   "复用了现有 file-upload 服务，避免重复造轮子",

   "需要在缓存层增加头像 URL 失效逻辑",

   "图片裁剪使用后端处理而非前端，保证一致性"

 ],

 "relatedFiles": [

   "src/user/avatar.controller.ts",

   "src/file-upload/upload.service.ts"

 ]

}

4.2 更新架构文档

# AI 自动更新文档

sessions_spawn({

 task: "根据新增的头像功能，更新架构文档和用户模块说明",

 mode: "run"

})

🛠️ 我的技能如何帮你

技能

用途

使用场景

openspec

Spec 驱动开发

新需求规范化

superpowers

TDD + 代码生成

实现 + 测试

self-improving-agent

经验记录

避免重复踩坑

workspace-analyzer

代码分析

理解现有结构

tavily-search

方案搜索

找类似实现

1/2

📝 实战模板

新需求启动清单

## 📋 新需求启动清单

### 1. 需求理解

- [ ] 编写需求上下文文档

- [ ] 识别相关业务模块

- [ ] 列出关键设计决策（需人工解释）

### 2. 代码分析

[ ] AI 分析现有代码结构

[ ] 识别可复用的模块

[ ] 评估影响范围

3. Spec 编写

[ ] 编写功能 Spec

[ ] AI 评审 Spec

[ ] 确认测试场景

4. 开发实施

[ ] AI 生成代码框架

[ ] 人工补充业务逻辑

[ ] 生成测试用例

[ ] 运行回归测试

5. 知识沉淀

[ ] 更新架构文档

[ ] 记录经验到 memory/

[ ] 更新 README/CHANGELOG

---

## ⚠️ 常见陷阱与规避

| 陷阱 | 表现 | 规避方法 |

|------|------|---------|

| **AI 过度自信** | AI 说"这个简单"但忽略了历史原因 | 要求 AI 先列出假设，人工确认 |

| **上下文缺失** | AI 不知道某些"潜规则" | 创建上下文文档，明确说明 |

| **回归遗漏** | 新功能破坏了旧功能 | AI 生成影响分析 + 回归测试清单 |

| **文档不同步** | 代码改了文档没改 | 将文档更新纳入完成定义 (DoD) |

| **经验不沉淀** | 同样的坑踩两次 | 强制记录到 memory/experiences/ |

---

## 🎯 最佳实践总结

### ✅ 这样做

1. **先写 Spec 再写代码** - 让 AI 理解意图

2. **人工提供业务上下文** - AI 不知道商业逻辑

3. **AI 生成 + 人工评审** - 双重保障

4. **回归测试自动化** - 防止破坏现有功能

5. **经验强制沉淀** - 避免重复踩坑

### ❌ 别这样做

1. **直接让 AI 改代码** - 没有 Spec 容易跑偏

2. **假设 AI 理解业务** - AI 只看代码不懂业务

3. **跳过评审环节** - AI 会犯错

4. **只测新功能** - 必须回归测试

5. **开发完就结束** - 不沉淀经验下次重来

---

## 💡 今天就能开始的 3 件事

### 1. 创建需求上下文模板

```bash

# 在项目根目录创建

mkdir -p docs/requirements

touch docs/requirements/TEMPLATE.md

2. 配置 AI 工具链

# 安装 Codeium 或 Copilot

# 配置 openspec 技能

# 设置 memory/ 目录结构

3. 试运行一个小型需求

# 用小需求练手，验证流程

sessions_spawn({

 task: "分析现有代码，为 [小功能] 生成实现方案",

 mode: "run",

 runTimeoutSeconds: 300

})