AI 辅助编程和AI Specs 实战

---## 一、AI 编程团队协作### 1.1 历史背景AI 辅助编程经历了从 GPT-3 问答式交互到 AI Agent 自动编码的快速演进：1. **对话式代码生成**：通过自然语言描述需求，获取代码片段，降低编程门槛2. **Vibe Code（氛围编程）**：开发者只需描述高阶意图，AI 完成全量代码编写与迭代3. **Spec Code（规范编程）**：先写规范再生成代码，确保质量和可控性### 1.2 当前 AI 编程的核心问题#### 大语言模型层面| 问题 | 描述 ||------|------|| **目标漂移** | 多步骤任务中 AI 易偏离初始目标，如优化数据库查询却去重写 UI 组件 || **重复犯错** | 缺乏长期记忆，相同错误反复出现 || **上下文爆炸** | 大量代码和文档塞入上下文窗口，导致效率下降、关键信息被忽略 || **进度丢失** | 对话重置后，开发进度和中间决策全部消失 || **幻觉生成** | 编造不存在的 API 或语法，生成无法运行的代码 |#### AI IDE 层面| 问题 | 描述 ||------|------|| **上下文管理不足** | 依赖模型自带上下文窗口，无法高效关联项目文件和历史操作 || **任务追踪缺失** | 缺乏结构化任务拆解与进度可视化 || **错误记录薄弱** | 修复方案无法自动归档和复用 || **文件协同不足** | AI 生成的中间产物缺乏统一存储管理 || **人机协作不畅** | 开发者难以直接干预 AI 任务执行流程 || **性能与成本失衡** | 频繁加载全量上下文导致卡顿和 Token 消耗增加 |### 1.3 团队协作痛点在团队缺乏标准化协作机制时，AI 编程易陷入"单兵作战"困境：- **代码碎片化**：成员各自用 AI 生成代码，风格和逻辑差异显著，后期维护成本激增- **规范失控**：不同提示词下 AI 编写的代码风格各异，偏离团队规范和安全标准- **知识孤岛**：个人 AI 使用经验无法共享，提示词和上下文无法在团队内流通- **协作低效**：功能重复生成，任务分配和代码评审流程难以统一### 1.4 核心诉求- 维持一致的代码质量- 防止安全漏洞- 减少重复工作量- 标准化协作流程- 加快开发周期- 实现从"快速原型"到"工程化落地"的跨越> 关于效率提升：根据 [METR 研究报告](https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/)，AI 辅助编程的编码速度大约提升 21%，并非"一天完成一个月工作量"。---## 二、规范开发 (Spec-Driven Development)### 2.1 SDD 概念SDD 强调在使用 AI 编写代码之前，先有 Specification（规范），以约束 AI 生成高质量、符合业务需求和技术要求的代码。社区主要的三类 SDD 工具：**OpenSpec**、**Kiro**、**Spec-Kit**### 2.2 选择 SDD 工具的考量- **工具与流程适配**：选择支持规范定制、多场景协作的工具，避免与团队流程脱节- **重视规范落地**：将团队规则转化为可执行的钩子和 Spec 模板，而非仅停留在文档层面- **构建协作文化**：鼓励成员共享 AI 使用经验，参与流程优化- **平衡自动化与人工**：AI 负责标准化和重复性工作，人类聚焦核心架构与创意决策### 2.3 Kiro 简介Kiro 是亚马逊云科技推出的 AI IDE，以"规范驱动开发"为核心，对国内用户友好，无需特殊网络配置。### 2.4 团队知识对齐团队成员（包括产品和测试）需了解 LLM、MCP、Agent 等核心概念，确保交流协作无知识障碍。推荐资源：- [Best LLMs for Coding | LLM Leaderboards](https://llm-stats.com/)- [AIBase](https://www.aibase.com/zh)### 2.5 项目模板无论使用何种开发框架，团队应有统一的项目模板和开发习惯约束。AI 会参考项目已有代码和约束文件，编写符合要求的代码。示例模板项目（C# / CQRS 架构）：[https://github.com/whuanle/aispec](https://github.com/whuanle/aispec)```src/{domain}/├── MoAI.{Domain}.Shared/     # 共享层 - DTO、Command、Query 定义├── MoAI.{Domain}.Core/       # 核心层 - Handler 实现、业务逻辑└── MoAI.{Domain}.Api/        # API 层 - Controller/Endpoint 暴露```依赖关系：`Api → Core → Shared`### 2.6 Steering（项目引导规则）Steering 是 Kiro 中的概念，让 AI 在编程过程中始终遵循团队已建立的 patterns、libraries、standards。> 官方文档：[https://kiro.dev/docs/steering/](https://kiro.dev/docs/steering/)#### 常见 Steering 文件| 文件 | 用途 ||------|------|| `product.md` | 产品概述 — 目的、目标用户、关键功能、业务目标 || `tech.md` | 技术栈 — 框架、库、开发工具、技术约束 || `structure.md` | 项目结构 — 文件组织、命名约定、架构决策 || `api-standards.md` | API 标准 — REST 约定、错误格式、认证流程 || `testing-standards.md` | 测试方法 — 单元测试模式、覆盖率期望 || `code-conventions.md` | 代码风格 — 命名模式、导入排序、反模式 || `security-policies.md` | 安全指南 — 认证要求、输入清理、漏洞预防 || `deployment-workflow.md` | 部署流程 — 构建程序、CI/CD、回滚策略 |> 只要看着写就行，可以在摸索过程中逐渐积累和完善。### 2.7 协作流程设计使用 AI 编程后，团队角色和参与内容会发生变化：1. **开发流程改变**：更接近敏捷开发模式，而非传统的产品原型→需求会→开发→提测2. **角色职责改变**：产出的资料需能被 AI 吸收，知识可沉淀，降低角色间的知识和职责边界3. **平台一体化趋势**：可能出现以 AI 编程为中心的产品研发一体化平台---## 三、实战：短链接服务### 3.1 架构设计即使在 AI 时代，开发人员仍需自行设计技术方案，让 AI 在边界内实现代码。#### 短链接核心算法- **生成**：长链接存入数据库，使用 int64 雪花 ID 做主键，再用 Base62 编码生成短链接- **还原**：短链接经 Base62 解码还原为雪花 ID，查数据库获取原始长链接- **缓存策略（三层）**：  1. Redis 布隆过滤器 — 快速判断数据是否存在，防止恶意请求打崩数据库  2. Redis 数据分片缓存 — 避免频繁查数据库  3. 本地离线缓存 — 减少 Redis 查询频率#### 数据库设计```sqlCREATE TABLE `short_url` (  `id` bigint(20) unsigned NOT NULL AUTO_INCREMENT COMMENT '唯一ID（对应短链接编码）',  `long_url` varchar(2048) NOT NULL COMMENT '原始长链接',  `hash` varbinary(32) NOT NULL COMMENT '网址哈希值，方便对比',  `create_user_id` int(11) NOT NULL DEFAULT 0 COMMENT '创建人',  `create_time` datetime NOT NULL DEFAULT current_timestamp() COMMENT '创建时间',  `update_user_id` int(11) NOT NULL DEFAULT 0 COMMENT '更新人',  `update_time` datetime NOT NULL DEFAULT current_timestamp() ON UPDATE current_timestamp() COMMENT '更新时间',  `is_deleted` bigint(20) NOT NULL DEFAULT 0 COMMENT '软删除',  PRIMARY KEY (`id`),  KEY `short_url_hash_index` (`hash`)) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='短链接';CREATE TABLE `user` (  `id` int(11) NOT NULL AUTO_INCREMENT COMMENT '用户ID',  `user_name` varchar(50) NOT NULL COMMENT '用户名',  `email` longtext NOT NULL COMMENT '邮箱',  `password` varchar(255) NOT NULL COMMENT '密码',  `nick_name` varchar(50) NOT NULL COMMENT '昵称',  `password_salt` varchar(255) NOT NULL COMMENT '计算密码值的salt',  `is_deleted` bigint(20) NOT NULL COMMENT '软删除',  `create_user_id` int(11) NOT NULL COMMENT '创建人',  `create_time` datetime NOT NULL DEFAULT utc_timestamp() COMMENT '创建时间',  `update_user_id` int(11) NOT NULL COMMENT '最后修改人',  `update_time` datetime NOT NULL DEFAULT utc_timestamp() COMMENT '最后更新时间',  PRIMARY KEY (`id`),  UNIQUE KEY `users_user_name_is_deleted_uindex` (`user_name`,`is_deleted`)) ENGINE=InnoDB AUTO_INCREMENT=2 DEFAULT CHARSET=utf8mb4 COMMENT='用户';```### 3.2 Steering 配置实战#### product.md定义产品目的、目标用户、关键功能和业务目标。可以一句话描述核心需求，让 Kiro 生成具体产品说明后再调整。#### structure.md概述文件组织、命名约定、架构决策。需随项目进展持续更新。#### tech.md记录项目选择的框架、库和技术约束，防止 AI 引入不必要的依赖。示例技术栈：| 类别 | 技术 ||------|------|| Framework | ASP.NET Core 9 || Language | C# 12 || ORM | Entity Framework Core 9 (MySQL) || CQRS | MediatR || Validation | FluentValidation || Authentication | JWT Bearer tokens || Logging | Serilog || API Docs | OpenAPI/Swagger with Scalar UI || Caching | Redis (StackExchange.Redis) || Module System | Maomi.Core || Code Analysis | StyleCop.Analyzers |### 3.3 Kiro Specs 三阶段工作流Specs 弥合了概念产品需求和技术实施细节之间的差距，生成三个关键文件：#### 阶段一：需求 (requirements.md)使用 **EARS 表示法**（Easy Approach to Requirements Syntax）定义用户故事和验收标准：```当[条件/事件]发生时系统应[预期行为]```EARS 表示法的优势：- 结构化、精确，减少歧义- AI 可基于 EARS 需求生成对应的编码需求和测试用例- 确保代码逻辑与需求一致#### 阶段二：设计 (design.md)记录技术架构、序列图和实现注意事项，全面了解系统工作方式和组件交互。#### 阶段三：实施 (tasks.md)提供详细的实施计划，包含离散的、可跟踪的任务和子任务。每个任务有明确描述、预期结果和依赖关系。### 3.4 实战示例：创建短链接接口```Create Spec: 实现创建短链接的接口，创建的数据存储到 ShortUrlEntity，使用雪花id赋值id，将长地址使用 SHA-256 生成 32 字节存储到 hash 字段。插入数据时要判断数据库是否存在对应的数据。```流程：编辑 requirements.md 和 design.md → 确认方案 → 打开 tasks.md → 点击 Start task 逐步执行### 3.5 使用 Hook 自动构建单元测试Hook 可在文件创建、保存或删除时自动触发操作。#### 单元测试策略- **框架/工具/算法代码**：单独设计验证的单元测试- **模型类**：验证 API 请求参数限制、字段长度范围等规则- **Api + Handler**：编写集成测试，使用 TestWebHost 模拟请求#### Hook 提示词示例```给 Api 编写单元测试，使用 EFCore 内存数据库模拟，redis 使用 mock 替代。对于无业务相关的框架、工具、算法代码，单独设计验证的单元测试即可。对于模型类，要验证 api 请求时参数限制，要识别字段长度范围等规则。对于 Api、Handler 可以一起测，编写集成测试，直接使用 TestWebHost 模拟请求。```---## 四、总结| 阶段 | 关键动作 ||------|----------|| **团队建设** | 统一 AI 编程认知，了解 LLM/MCP/Agent 概念 || **基础设施** | 建立项目模板 + Steering 规则，约束 AI 生成代码的质量和风格 || **需求阶段** | 使用 EARS 表示法编写结构化需求，生成 requirements.md || **设计阶段** | 输出技术架构和序列图，生成 design.md || **实施阶段** | 拆解任务列表，逐步执行，生成 tasks.md || **质量保障** | 通过 Hook 自动触发单元测试和代码规范检查 || **持续优化** | 在实践中逐步完善 Steering 和 Spec 模板 |核心理念：**只有足够简单，规范才能真正落地。** 通过 Kiro 的 Steering + Specs + Hooks 机制，将团队规范转化为可执行的约束，让 AI 在边界内生成高质量代码，实现从原型到产品的工程化落地。