KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #ai-agent #developer-tools #claude-code #codex #deepseek-harness #ai-agents #react #mcp #rust

aispec

★ 28 Open GitHub ↗

Ai辅助团队编程模板项目

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

作者：痴者工良

作者博客地址：https://www.whuanle.cn/archives/22312

## AI 编程团队协作

### 历史背景

AI 发展的速度实在太快了，在 GPT-3 横空出世的阶段，那个时候只能使用对话框一问一答，到现在各种 RAG、AI Workflow、AI Agent 等各类技术，使得 AI 可以做更多的事情，实现更加强大的功能。在 cursor、trae 等 AI IDE 出现后，很多人便彻底迷上了这项足以颠覆传统工作模式的技术，尤其在编程领域，这场变革的浪潮来得尤为迅猛 —— 最初，当我们面对复杂的业务功能、晦涩的语法实现或是陌生的框架调用时，无需再耗费大量时间翻阅文档、调试代码，只需通过自然语言向 AI 描述需求，就能借助它的问答式回复获取可用的代码片段，这不仅大大降低了编程的门槛，更让开发者从重复的基础编码工作中得到了初步解放，也为后续对话式代码生成、Vibe Code 乃至 Spec Code 等更先进的编程范式，埋下了充满无限可能的种子。

目前，主流的 AI 辅助编程主要是 AI Agent，在 AI IDE 中输入要做的功能，AI 会自动读取项目文件，经过思考后编写对应的代码，并且会自动修正代码错误，确保代码可以编译通过。这便是大语言模型催生的对话式 AI 代码生成，开启了自然语言交互生成代码的时代，开发者通过多轮对话让 AI 产出代码片段并手动整合，AI 仅作为辅助工具；随后演进的 Vibe Code（氛围编程）范式，让开发者只需描述高阶意图即可驱动 AI 完成全量代码的编写与迭代，人类角色从编码者转向需求引导者与测试者，聚焦快速原型与创意验证。

![image-20260109185650106](https://raw.githubusercontent.com/whuanle/aispec/master/images/image-20260109185650106.png)

但是，AI Agent 模式下的 AI 辅助编程，也存在一些常见的问题，所以在 IT 圈流行着这图：

![896b42e496e1d780c1b2ba5685065dc5](https://raw.githubusercontent.com/whuanle/aispec/master/images/896b42e496e1d780c1b2ba5685065dc5.jpg)

> 感谢热心网友【迪迦】提供的图片。

虽然上图有搞笑成分，这里我们将问题分为大语言模型和 AI IDE 两部分，下面介绍常见的 AI 辅助编程问题。

大语言模型：

*  **目标漂移**：在多步骤、长流程的编程任务中（如复杂功能开发、项目重构），AI 执行到中后阶段易偏离初始目标，例如原本需求是优化数据库查询性能，后续却无端重写 UI 组件，本质是缺乏有效的目标锚定机制。
* **重复犯错**：对已出现过的错误缺乏长期记忆，相同问题会反复出现（如未正确处理异步函数的 `await` 关键字、文件路径引用错误），无法自动沉淀历史解决方案。
* **上下文爆炸**：为让 AI 掌握完整项目信息，需将大量代码、需求文档、历史对话塞进上下文窗口，导致模型处理效率下降、响应延迟，且易忽略关键信息。
* **进度丢失**：依赖对话窗口存储任务状态，一旦对话重置、刷新或中断，之前的开发进度、中间决策、已积累的项目认知会全部消失，无法无缝续工。
* **幻觉生成**：在缺乏明确参考依据时，可能编造不存在的 API 方法、语法规则或项目配置，生成看似合理但实际无法运行的代码，增加调试成本。

AI IDE：

* **上下文管理能力不足**：多数 AI IDE 未建立独立的外部记忆机制，仍依赖模型自带的上下文窗口，无法高效关联项目文件、历史操作记录，难以支撑复杂任务的连贯开发。
* **任务追踪与可视化缺失**：缺乏对编程任务的结构化拆解与进度可视化功能，无法像 `task_plan.md` 那样清晰呈现阶段划分、完成状态、决策依据，开发者难以掌控 AI 的工作轨迹。
* **错误记录与复用薄弱**：未集成错误追踪体系，AI 遇到的报错、修复方案无法自动归档，既不便于开发者回溯问题根源，也无法让 AI 后续快速复用已验证的解决方案。
* **文件协同与持久化不足**：对 AI 生成的中间产物（如调研笔记、技术选型文档）缺乏统一的存储与管理机制，文件分散且易丢失，无法形成可追溯、可复用的项目知识库。
* **人机协作衔接不畅**：开发者难以直接干预 AI 的任务执行流程，例如无法通过编辑结构化计划文件调整开发方向，也缺乏便捷的方式审查 AI 的决策逻辑，导致人机协同效率低下。
* **性能与成本失衡**：处理大规模项目时，频繁加载全量上下文会导致 IDE 运行卡顿，且重复处理相同静态内容（如项目框架定义、工具配置）会增加 Token 消耗，提升使用成本。

所以，在目前的技术局限下，要玩 AI 编程，其实还不能为所欲为，同时使用 AI 编程时也会碰到很多阻碍问题，降低了编程的体验和项目代码质量。

### AI 编程下的团队协作痛点与核心诉求

前面介绍了 AI 编程本身容易出现的问题和技术局限，回到以团队为单位进行 AI 编程协作时，当团队缺乏标准化协作机制时，AI 编程易陷入 “单兵作战” 的困境，会出现更加多的头疼的问题。

因为笔者在公司带一个项目组，已经有很多成员使用 AI 写代码，在经过一段时间的观察和思考后，发现了一些问题，所以才想到写这篇文章的，相信这些问题在大家的公司里面也会存在。

**代码碎片化**

> 很多同事发现用 AI 写代码，可以早点下班，于是大家都用 AI 写代码，你写你的我写我的，导致成员各自使用 AI 生成代码，风格、逻辑差异显著，模块衔接困难，后期维护成本激增。反正同事用 AI 写的代码，我是压根不行维护。

**规范失控**

> 大家应该都有感受，在不同提示词、编写不同功能时，AI 编写的代码风格各异，没有统一的规范和风格，AI 生成代码可能偏离团队代码规范、安全标准，埋下质量隐患。

**知识孤岛**

> 个人使用 AI 积累的经验无法共享，团队整体效率难以提升。你用 cursor，我用 kiro，各写各的代码，没法为团队沉淀知识经验，提示词、功能历史记录、背景上下文等完全没法再团队内共享，每个人都得在本地使用 AI 阅读代码生成上下文记忆。

**协作低效**

> AI 写的代码实际上会出现一个简单的功能写一堆代码的情况，也有可能 A 同事写 A 功能时生成了 C，B 同事写 B 功能时又生成了一个类似的 C，项目各种代码错综复杂。导致难以统一任务分配、进行代码评审流程，导致信息传递滞后，冲突频发。

除了以上问题在团队编程中需要解决，很多公司都有代码质量规范要求、安全要求、单元测试覆盖率要求，所以基于这些问题和常见公司编程要求，笔者认为团队 AI 编程的核心诉求应聚焦：

- 维持一致代码质量
- 防止安全漏洞
- 减少重复工作量
- 标准化协作流程
- 加快开发周期
- 实现从 “快速原型” 到 “工程化落地” 的跨越。

很多领导对 AI 编程的想法很难评，觉得可以 ”降本增效“ ，一个项目平时需要一个月做完，用 AI 一天就行，代码还能写得比开发还好，这样可以开除很多开发人员，所以号召大家在公司使用 AI 编程。

> 后面会提到 AI 辅助编程大约可以提高多少速度，但不可能是一天写完一个月的代码。

而实际上，除非原因开盲盒，产品做得怎么样取决于 AI 怎么写，前期速度确实很快。但是到了中后期，AI 写的代码难以维护，反而会因为要 AI 写代码，花费大量时间编写提示词，为了实现一个小需求，可能要跟 AI 一直对骂，最终陷入混乱。

其实，正如笔者前面所说的，大语言模型和 AI IDE 在目前有一些技术局限，而且在团队使用 AI 编程时会带来很多协作问题，如果没有应对这些问题的解决方法，那么使用 AI 编写的代码最终可能是一片混乱，而且生成代码人类可能无法阅读，鬼才知道 AI 写的是啥。

公司落地 AI 编程，确实可以提高开发速度，缩短开发周期，但是不应该荒谬到认为 ”一个月工作量使用 AI 一天就行“ 。笔者认为，除了提速，应当更多聚焦实现前面提到的 AI 编程的核心诉求。

很多公司天天鼓吹单元测试、代码规范、高性能高质量代码，给开发指定单元测试覆盖率和代码审查等指标，反复折腾开发人员，但是公司存在各种各样的开发管理和技术问题，盲目定制高要求的开发指标，完全解决不了当前的问题，又会使得开发身心疲倦。

笔者之所以要说这些，是因为代码审查、代码规范、单元测试等，做起来没有那么简单，有多少公司折腾这些，又能最终真正做到？

> 能不能做好这些，其实跟公司基因有关系，跟落地难度也有关系。

其实，只有足够简单，规范才能真正落地。

所以，笔者一直在思考，如何解决 AI 编程下的团队协作痛点与满足核心诉求，并且真正落地单元测试、代码审查等技术要求。

这就是本文的重点，AI Spec，到底要怎么做，接下来本文将以架构师的角度，去思考，去研究，我们是架构师，那么应该怎么把 AI 编程落地到团队协作中。

## 规范开发(Spec development)

前面提到，AI 辅助编程逐渐成为主流，大部分开发人员已经在日常工作中使用 AI 编写代码，但是也会引入很多问题，导致生成很多不可预测的、质量参差不齐的代码。那么为了解决这些问题，出现了 SDD(Spec-Driven Development) 这种概念，强调在使用 AI 编写代码之前，先有 Specification，以便约束 AI 生成高质量的、符合业务需求和技术要求的代码。

目前社区中主要存在三类 SDD 工具：OpenSpec、Kiro、Spec-Kit。

为了实现 Spec development，选择 SDD 工具时，需要考虑：

* **工具与流程适配**：选择 Kiro 这类支持规范定制、多场景协作的 AI 工具，避免工具功能与团队流程脱节；

* **重视规范落地**：将团队规则转化为可执行的钩子、Spec 模板，借助 AI 强制落地，而非仅停留在文档层面；

* **构建协作文化**：鼓励成员主动共享 AI 使用经验、参与流程优化，避免 “单兵作战” 思维；

* **平衡自动化与人工**：AI 负责标准化、重复性工作（如测试、规范检查），人类聚焦核心架构与创意决策，实现人机协同增效。

在本文，笔者要讲解的是 Kiro 落地的内容。

在搜索资料的过程中，笔者发现几篇写得不错的文章，这里供读者参考，本文就不单独讲解这些 SDD 工具了。

> AI 规范驱动开发“三剑客”深度对比：Spec-Kit、Kiro 与 OpenSpec 实战指南 - 技术栈：
>
> https://jishuzhan.net/article/1988226029513670657
>
> Transforming Dev Practices with Kiro’s Spec-Driven Tools | AI Native Dev
>
> https://ainativedev.io/transforming-dev-practices-with-kiros-spec-driven-tools

这里简单介绍一下 Kiro。

Kiro 是亚马逊云科技推出的 AI IDE，以 “规范驱动开发” 为核心，完美适配团队协作需求。

> 对国内用户友好，无需特殊网络配置。

![img](https://raw.githubusercontent.com/whuanle/aispec/master/images/1767774499128-2.png)

### 团队对齐：AI 编程核心概念解析

在深入团队协作实践前，需先明确支撑 AI 编程的关键技术概念，无论是产品还是测试，也必须了解 LLM、MCP、Agent 等概念，需要团队对一些知识都过关，确保整个团队交流协作不存在知识障碍。

> 这些概念的知识，笔者就不赘述了。

主流大语言模型用于编程的评分，作为架构师需要清晰了解不同模型的特长和优缺点，在编程领域哪个模型最优秀最适合用于编程。

> 笔者发现几个网站很不错，有各类模型的介绍和评分，地址：
>
> [Best LLMs for Coding | LLM Leaderboards](https://apxml.com/zh/leaderboards/coding-llms)
>
> https://llm-stats.com/
>
> https://www.aibase.com/zh

![image-20260109204244573](https://raw.githubusercontent.com/whuanle/aispec/master/images/image-20260109204244573.png)

主流企业使用 AI 辅助编程提升的效率。

要是领导觉得你一个月写的代码不如 AI 一天写的，那就尴尬了。作为技术人员，必须合理评估使用 AI 编程后，整个团队到底提升了多少效率，编码速度提高了多少。

比如，根据这篇研究报告，完成任务的编码速度大概提升了 `21%`，报告地址 https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/

而根据豆包联网搜索总结的内容来看，提升的开发速度并没有那么夸张。

![image-20260109205849267](https://raw.githubusercontent.com/whuanle/aispec/master/images/image-20260109205849267.png)

总而言之，打造 AI 辅助编程团队，要求团队人员对 AI 有足够的认识，了解基础知识，并且争取在 AI 编程上的认知一致，否则可能会闹出各种笑话，被人引为笑谈。**知识和认知都很重要**，否则团队分分钟散架。

### 项目模板

为什么要使用开发框架，这个事情不用多说，C# 开发应该知道 ABP 框架，Go 开发应该知道 gin、beego，使用框架后大大简化了开发负担。在使用开发框架的情况下，其实团队还需要定制项目模板，以便适配公司技术栈，以及约束公司内的一些技术要求，例如审计属性、微服务通讯方式和鉴权等，好的项目模板可以统一开发模式和习惯。

笔者在写个人开源项目过程中，结合 DDD 、清洁架构、CQRS 的一些概念，辅以 AI 编程，形成了个人开发习惯，所以为了写这篇文章整理了一个模板项目：

https://github.com/whuanle/aispec

如果以我的开发习惯来定，我会使用模块化 + CQRS，每个业务领域遵循三层模块化架构，无论开发还是做单元测试，都比较简单。

```
src/{domain}/
├── MoAI.{Domain}.Shared/     # 共享层 - DTO、Command、Query 定义
├── MoAI.{Domain}.Core/       # 核心层 - Handler 实现、业务逻辑
└── MoAI.{Domain}.Api/        # API 层 - Controller/Endpoint 暴露
```

依赖关系：`Api → Core → Shared`，具体参考：

代码编写约束参考：https://github.com/whuanle/aispec/blob/master/.kiro/steering/cqrs-conventions.md

![image-20260109211559319](https://raw.githubusercontent.com/whuanle/aispec/master/images/image-20260109211559319.png)

![image-20260109211703315](https://raw.githubusercontent.com/whuanle/aispec/master/images/image-20260109211703315.png)

具体设计思路和各类细节就不讲解，本节其实目的是说，无论你使用何种开发框架，是否使用 DDD，还是传统三层结构，团队应该要有一个统一的项目模板以及开发习惯约束，AI 会参考项目已有代码和约束文件，编写符合要求的代码，避免代码天马行空。

关于模板项目就不展开说了，读者可以在这里找到这个本身用于实战演示的模板项目：https://github.com/whuanle/aispec

### 准备定制团队规则与项目索引

在使用 AI 编程时，会有一些常见问题：

1，开发跟 AI 容易陷入盲目对话，AI 始终没有给出想要的代码，导致代码可用率和确定性低下。

2，开发难以清晰准确向 AI IDE表达目标方案和代码

3，前置需要大量精力对项目的 Rules、Docs 进行编写和积累

4，啥都让 AI 写，但是 AI 写出来的方案总是不满意

解决这些问题本身不难，但是要落到团队协作中，作为架构师就要思考更多了，需要保证代码质量和开发效率，避免反复处理这些问题。

#### 什么是 Steering

这里的 steering 其实是 Kiro 里面的概念，目的是让 AI 编程过程中，始终遵循团队已建立的 patterns、libraries、standards。

> https://kiro.dev/docs/steering/

也就是说，基于团队的项目模板，我们要指定一些跟业务无关的技术约束，例如审计属性怎么定，这个开发框架/项目模板怎么使用，不同功能的代码文件怎么命名等，都可以写到 Kiro steering 里面。AI 在写代码时，会一直围绕这些 steering 去写，如果写出的代码不符合 steering 要求，则 AI 会逐步修正代码。

那么，团队要落地代码规范，是不是变简单了？前面提到的 AI 编程的问题和核心诉求，是不是可以解决了？

是的，所以，要重视项目模板和 steering，在团队开发实现需求之前，就应该定制团队乃至公司研发部门的 steering。

#### 常见 Steering 文件策略

后面会提到 Kiro 默认会有的 steering 规则模板，但是从团队的角度考虑，可能还需要这些 steering ：

**API 标准** (`api-standards.md`) - 定义 REST 约定、错误响应格式、认证流程和版本策略。包括端点命名模式、HTTP 状态码使用和请求/响应示例。

**测试方法** (`testing-standards.md`) - 建立单元测试模式、集成测试策略、模拟方法和覆盖率期望。记录首选测试库、断言样式和测试文件组织。

**代码风格** (`code-conventions.md`) - 指定命名模式、文件组织、导入排序和架构决策。包括首选代码结构、组件模式和要避免的反模式示例。

**安全指南** (`security-policies.md`) - 记录认证要求、数据验证规则、输入清理标准和漏洞预防措施。包括特定于您应用程序的安全编码实践。

**部署流程** (`deployment-workflow.md`) - 概述构建程序、环境配置、部署步骤和回滚策略。包括 CI/CD 管道详细信息和环境特定要求。

当然，这些 steering 不需要都首选，可以先做一个项目模板，然后让 Kiro 阅读代码并生成即可。

不同公司团队可能有不同要求，只要看着写就行，可以在摸索的过程中，逐渐积累团队经验，逐渐完善 steering。

### 核心执行：AI 驱动的协作流程设计

团队协作 AI 编程，把要做的功能丢在对话框，让 AI 写代码就行？

No！大错特错！

让我们回到 Kiro 的介绍，`Agentic AI development from prototype to production`，翻译过来是从原型到产品的 Agentic AI 开发。

注意，要玩 AI 编程，我们是要做从原型到产品整个周期的东西，而不单单是用 AI 写完代码早点下班。

所以要考虑，团队的角色有哪些，大家应该怎么参与协作，**更重要的是怎么设计新的团队研发流程**。

不同公司的团队组成不一样，所以笔者按照常规团队（产品、UI设计师、前后端开发、测试）组成来讲解后面的内容。

> 感谢这位作者的文章，给了我很多想法：[https://aicodingtools.blog/zh/kiro/kiro-spec-guide](https://aicodingtools.blog/zh/kiro/kiro-spec-guide)

使用 AI 编程后，团队中各个角色要负责的内容会发生变化，要求工作输出的内容能够被 AI 识别并引用，并且在团队内流通。

> 如果产品输出的需求文档，AI 都不会分析总结，你给开发看？逻辑狗屁不通，AI 怎么写代码？
>
> 产品的需求文档，可以经过开发整理后，作为让 AI 编写代码的提示词和需求约束，大大减轻开发的负担。

开发和测试将会大大依赖需求文档（或其它形式的文档），因为需求文档会作为开发、测试和验收依据，在 AI 编程阶段就要让 AI 知道写代码还要考虑怎么测试和验收，不能等让 AI 写完代码，再叫 AI 写单元测试、检查验收能不能过。

另外，前期准备阶段，也依赖架构师或 leader 的架构设计和功能实现设计，而不是说 ”实现一个短链接服务，将长链接缩短为短链接“，技术负责人需要思考和设计，使用何种算法缩短地址、还原地址，怎么存储到数据库，高并发环境下怎么提高并发量和减少对数据库的压力。

所以，要思考，使用 AI 编程落地后，

* 团队需要哪些角色？

* 每个角色要负责哪些内容？
* 整个研发流程应该分哪些阶段？

每个公司情况都是不一样的，所以针对这些问题，笔者没有什么说法和观点，不过后面实战部分会提到 Kiro Specs 是怎么划分研发流程阶段。

笔者设想，未来围绕 AI 辅助编程开发，团队的角色和参与内容可能发生重大改变。

一是团队开发流程发生改变，不再像以往从产品原型设计、需求会、开发、提测的模式，而是围绕 AI 编程更加靠敏捷开发模式接近。

二是团队角色负责的内容发生改变，更多围绕产生的资料能够被 AI 吸收，知识可以沉淀，减少信息流通的难度，以及降低产品、设计师、开发、测试之间的知识和职责边界。

三是可能会出现以 AI 编程为中心的产品研发一体化平台，无论是产品、设计师、开发、测试，都可以围绕这个平台进行符合自己角色的参与，例如产品编写需求文档和验收文档时，可以借助 AI 平台检测需求是否合理、调整设计、细化需求，转化为开发人员便于阅读的文档。产品、设计师通过需求文档借助 AI 平台快速实现产品原型设计。开发人员则可以将需求导入 AI，创建开发任务，逐步与 AI 协作编写代码，还可以借助 AI 快速生成单元测试、集成测试等，最后根据验收文档验证检测最终输出。

而关于团队的研发流程，则会在 [工作流程](#工作流程) 一节详细讲解。

### 总结

作为文章的第二部分，主要是思考怎么建设使用 AI 辅助编程的团队，以及进行团队协作。

第三部分将会讲解实战，从原型到产品的整个环节，每个步骤应该做什么。

## 实战

作为文章的第三部分内容，将会以短链接服务为案例，去讲解如何落地实战团队协作和 AI 编程，去设计一个以 AI 辅助开发为核心的项目研发流程。

### 思考整体架构

AI 时代，还需要我去设计项目？

是的，开发人员要自行对技术方案进行调研、上手尝试，然后让 AI 根据你的方案和设计做出来，不要都让 AI 帮你做解决方案。

只需要一个 idea，AI 就可以写代码，可是 AI 写出来的东西可能跟专业人员需要的东西相去甚远，并且还有大量细节满足不了需求，开发人员可能会陷入跟 AI 的对骂中，不断调整提示词，不断等待 AI 生成，最终生成了 90% 的内容，剩下的 10%，开发人员只能对着键盘一点点敲完。

虽然是 AI 编程，但是编程的重点是人的想法和需求，而不是 AI 的天马行空，虽然 AI 实现的项目可能有很多很好的创意和想法，质量可能很好，但是对于专业领域和公司业务项目来说，需求的中心是公司对应的业务，而不是一个 idea。

而且 AI 有上下文限制，有幻觉等，你只需要一个简单的一个登录功能，可能 AI 把单点登录、OAuth2 等一堆东西给你加上去了（目标偏移）。

所以即使在 AI 时代，我们也要构思项目设计和功能实现的算法和逻辑，让 AI 在这个边界内实现代码和测试。

> 当然，我们可以利用 AI 去帮助我们验证想法和构思设计，然后将这些内容生成为架构设计和技术方案。

#### 短链接服务的架构

由于本文的重点不是怎么实现一个短链接服务，所以笔者这里只简单讲解这个服务的一些算法和实现思路，以便后续使用 AI 写出符合需求的代码。

核心问题1：短链接生成和还原

核心问题2：短链接存储和查找

笔者的设计是，短链接跟长链接无直接映射关系，也就是不能通过算法转换直接将长链接生成短链接。

对于每个长链接，创建记录存到数据库时会使用 int64 雪花做主键，存到数据库。

例如新增一个长链接 `https://whuanle.cn`，当前雪花id 是 2009194627277520896，经过检查数据库没有重复数据后存储到数据库。

接着，将雪花 id 使用 base62 生成短链接编码。之所以使用 base62 做缩短编码，是因为`[0-9]`、`[a-z]`、`[A-Z]` 刚刚好是 62 个字符，能够在不使用特殊符号的情况下，使用数字和大小写字母表达值，也就是相当于 62 进制。将 2009194627277520896 使用 base62 编码是得出字符串是 `00E3uWKkzx`，而存数据只需要一个 int64 就行。

满足能够将长链接生成短链接，存储空间小，不容易被人碰撞规则的需求。

![image-20260108174726106](https://raw.githubusercontent.com/whuanle/aispec/master/images/image-20260108174726106.png)

有了短链接生成和还原算法后，我们继续聊一下数据查找。

用户访问 `/00E3uWKkzx` 时，还原得到 2009194627277520896，然后通过这个 id 从数据库查找数据得到  `https://whuanle.cn`，然后让用户跳转到这个地址即可。

每次都要查数据库，数据库压力大，而且万一被人攻击，机器人随机拼接的字符串，也要到数据库检查数据在不在，数据库迟早被打崩。

所以第一层是使用 redis 的布隆过滤器，先判断数据是否存在。

![image-20260108180240039](https://raw.githubusercontent.com/whuanle/aispec/master/images/image-20260108180240039.png)

第二层，数据分片，将数据存储到 redis，避免频繁从数据库查找。还可以做本地离线缓存，避免高频度从 redis 查找数据。

也就是最终是三层缓存。

其它就不多说了，前面提到的算法处理逻辑，将会作为后续 AI 编写功能的依据。

### 模板项目

首选是安装笔者提供的项目模板。

```bash
dotnet new install Maomi.AiSpec.Templates
```

![image-20260109092342372](https://raw.githubusercontent.com/whuanle/aispec/master/images/image-20260109092342372.png)

执行命令从模板创建新的项目，将 `MyShortUri` 替换为你需要的项目名称即可。

```bash
dotnet new aispec -n MyShortUri
```

![image-20260109092658516](https://raw.githubusercontent.com/whuanle/aispec/master/images/image-20260109092658516.png)

### 后端开发原则和规范

使用 Kiro 打开 `MyShortUri` 项目， 在 AGENT STEERING 菜单可以看到已经模板自带四个 steering 文件。

![image-20260109224727421](https://raw.githubusercontent.com/whuanle/aispec/master/images/image-20260109224727421.png)

Kiro 通过 `.kiro/steering/` 目录中的 markdown 文件设置项目约束规定，Kiro 只规定了 product.md、tech.md、structure.md 三个文件，这些基础文件默认包含在每次交互中，形成 Kiro 项目理解的基线。

cqrs-conventions.md 则是笔者的模板项目的开发规则，约定 AI 生成的代码文件如何存放以及代码格式约束，AI 会生成符合项目要求的代码。

读者也可以创建一些其它文件，例如 `rest-api.md` 要求生成的 api 接口需要符合 restapi 格式，将公司研发规范等写入到  `.kiro/steering/` 目录。

#### 后端代码规范约束

`cqrs-conventions.md` 是笔者自定义的 steering 文件，用来约束 AI 生成的代码必须分为 `Command/Query`、`Api`、`Handler` 三层的 CQRS 结构。

定义了很多约束规范，这里就不讲解了，自己研究一下。

![image-20260109094451145](https://raw.githubusercontent.com/whuanle/aispec/master/images/image-20260109094451145.png)

#### 我要做什么样的产品

拉取项目模板后，第一步是修改 `product.md`，告诉 AI 这是一个短链接项目。

> **产品概述** (`product.md`) - 定义产品的目的、目标用户、关键功能和业务目标。

一般来说，**产品概述** (`product.md`)  是产品经理的工作任务，开发只需要将产品经理写的文档拷贝到代码项目即可，不过既然现在没有产品经理，我们可以一句话描述核心需求，让 Kiro 帮助我们生成具体的产品说明，等 AI 生成后，根据实际情况，调整好 `product.md` 文件。

![image-20260109094959587](https://raw.githubusercontent.com/whuanle/aispec/master/images/image-20260109094959587.png)

生成效果：

![image-20260109094351449](https://raw.githubusercontent.com/whuanle/aispec/master/images/image-20260109094351449.png)

#### 项目结构

**项目结构** (`structure.md`) - 概述文件组织、命名约定、导入模式和架构决策，这确保生成的代码无缝融入现有的代码结构里面，这样 AI 不会乱创建文件以及随便找个地方塞代码。

`structure.md` 要常常随着项目的进展而更新，不要一直不变，每次新增模块后，都要重新生成 `structure.md` 。

现在我们点击 Kiro 的 `Refine` ，重新生成 `structure.md` 。

![image-20260109095652954](https://raw.githubusercontent.com/whuanle/aispec/master/images/image-20260109095652954.png)

#### 技术约定

**技术栈** (`tech.md`) - 记录这个项目选择的框架、库、开发工具和技术约束，当 Kiro 建议实现方案时，它会优先选择已建立的技术栈而非替代方案。

突然想起来一个事情，某同事写 Go 语言程序需要解决一个打印功能，结果用 AI 写的代码引入了 python，后面被我发现了，我要求用 Go 重写，然后某同事又用 AI 劈里啪啦写了一天，总算用 Go 写出来了。

所以 `tech.md` 可以避免这种情况，不然 AI 为了实现一个功能，到处查资料，然后引入一堆依赖，用一种意想不到的方式去实现功能。

现在我们点击 Kiro 的 `Refine` ，重新生成 `tech.md` ，例如这个项目使用的技术栈如下：

```
| Category | Technology |
|----------|------------|
| Framework | ASP.NET Core 9 |
| Language | C# 12 (nullable reference types enabled) |
| 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 |
```

作者还可以加上接口设计约定等文件，这里不再赘述。

### 数据库设计

现在出现了一个使用 AI 做数据库设计方案的方向：Text2SQL。

Text2SQL 指将自然语言转换为 SQL 的技术，当一个项目从零开始时，我们可以借助 AI 构思、设计项目架构，最后总结输出 SQL，这一步其实比较简单。

但是后续项目迭代后，需要 AI 去了解整个数据库表结构，需要 AI 根据业务情况设计新的索引、字段约束等，这就要求 AI 需要挖掘数据价值，应对复杂的分析任务，才能给出合理的数据库变更建议。

可以借助专业的 AI DB 客户端去做，例如 Chat2DB、也可以在 Kiro 装上 MCP 工具读取数据库，由于不是本文重点，这里只讲解思路，就不再详细讲述。

数据库创建表，以便后续实战让 AI 写代码。

```csharp
CREATE 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='用户'

```

![image-20260109110209561](https://raw.githubusercontent.com/whuanle/aispec/master/images/image-20260109110209561.png)

修改数据库链接，启动 MysqlScaffold 还原数据库生成代码，将 `Database` ，目录的文件放到对应位置接口。

> 您看，有个项目模板多重要，很多时候省下大量的时间，例如笔者这个模板，先设计数据库，然后定制数据库生成代码的步骤，使得生成的实体结构和 数据库上下文类能够符合业务需求，大大提高开发效率。

![6f39e423-8590-4a90-bee3-cd0f34a55caa](https://raw.githubusercontent.com/whuanle/aispec/master/images/6f39e423-8590-4a90-bee3-cd0f34a55caa.png)

### UI 原型设计

UI 原型设计就是 UI 设计师根据产品原型设计页面的过程，随着专业的原型设计工具支持 AI 后，产品经理跟 UI 设计师更好地协作，有时候一句话就可以生成一个不错的界面。产品经理可以借助这些 AI 工具快速实现原型页面。

![image-20260109103159002](https://raw.githubusercontent.com/whuanle/aispec/master/images/image-20260109103159002.png)

由于墨刀的 AI 需要付费使用，太贵了，本来想演示 AI 根据设计稿生成页面代码的，最后放弃了，用这钱买了几盒凤爪。

本节意思读者理解就行，就是说目前市面上有很多 AI 生成设计稿的产品，产品可以不用化那么多时间画原型了，可以专心思考产品设计和流程逻辑，最大程度输出文档，把画原型这些事情留给 AI，然后还可以进一步转换为 UI，设计师也可以借助 AI 快速实现初版界面。

### 后端开发实战

基于项目模板和 steering，其实一句话需求，就可以让 Kiro 给我们编写一个模块的后端代码。

但是 Kiro 提出了 Specs，让团队协作和开发人员早点下班的神器。

Specs 弥合了概念产品需求和技术实施细节之间的差距，确保了一致性并减少了开发迭代。Specs 提供了一种系统化的方法，将需求和想法转化为详细的实施计划，生成验收标准、技术实现和代码生成及测试验收计划。

接下来，我们将会使用 Kiro Specs 生成某个功能的工作流程，最后根据方案生成代码并通过测试验收代码。

#### 实现创建短链接的接口

要做短链接服务，第一步是实现一个长链接转短链接的功能，Kiro Specs 要求编码之前需要按照三阶段工作流程进行：需求 → 设计 → 实施。

在 Kiro 面板中，点击 **Specs** 下的 `+` 按钮，或者从聊天面板中选择 **Spec**，在对话框内输入要做的功能。

```
Create Spec: 实现创建短链接的接口，创建的数据存储到 ShortUrlEntity，使用雪花id赋值id，将长地址使用 SHA-256 生成 32 字节存储到 hash 字段。插入数据时要判断数据库是否存在对应的数据。
```

![a91e33a4-6ae2-48cc-af68-25cffb5a7898](https://raw.githubusercontent.com/whuanle/aispec/master/images/a91e33a4-6ae2-48cc-af68-25cffb5a7898.png)

![382cf906-3618-4d01-abc1-5b3f6bb39e51](https://raw.githubusercontent.com/whuanle/aispec/master/images/382cf906-3618-4d01-abc1-5b3f6bb39e51.png)

按照引导操作后，最后一步会显示 “保留可选任务（更快完成 MVP）”、“全部设为必需（完整测试覆盖）”。

如果选择了 “全部设为必需（完整测试覆盖）”，AI 在任务列表加上基于属性的测试要求和执行步骤，Kiro 从提出的需求中提取 `属性` 并生成测试用例，以便确保 AI 生成的代码符合开发者的意图。

> Kiro 文档里面解释 `属性`：对于任何一组具有特定前提条件的输入，某些预期行为是成立的。Kiro 从格式化的需求中提取属性 (例如，“THE System SHALL 允许经过认证的用户查看活动车辆列表”)，确定哪些属性可以进行逻辑测试，然后在你选择运行它们时生成数百或数千个随机测试用例。

![image-20260109115335208](https://raw.githubusercontent.com/whuanle/aispec/master/images/image-20260109115335208.png)

结果一顿操作后，需求已经下发到 `.kiro/specs/create-short-url`，Kiro 会生成三个关键文件，这三个文件构成一个 spec。

- **requirements.md**：使用结构化的 EARS 记号法捕获用户故事和验收标准
- **design.md**：记录技术架构、序列图和实施考虑因素
- **tasks.md**：提供详细的实施计划，包含离散的、可跟踪的任务

![image-20260109115648904](https://raw.githubusercontent.com/whuanle/aispec/master/images/image-20260109115648904.png)

我们可以先编辑 requirements.md、design.md，确保 AI 生成的具体业务要求和测试说明、技术栈和实现思路符合我们的要求，最后打开 tasks.md 文件，点击任务旁边的 `Start task` 按钮开始实现代码。

![0dce46d5-0884-4a84-ac8d-792c18df1988](https://raw.githubusercontent.com/whuanle/aispec/master/images/0dce46d5-0884-4a84-ac8d-792c18df1988.png)

由于创建短链接存储代码时，使用的算法跟我的设想相差甚远，所以这里也可以重新生成代码，不过建议好好写  requirements.md、design.md，不要在对话框调整代码逻辑，只有沉淀的文档才是最重要的。

![image-20260109130137218](https://raw.githubusercontent.com/whuanle/aispec/master/images/image-20260109130137218.png)

### 工作流程

前面利用做 ”实现创建短链接的接口“ 这个需求，上手了 Kiro specs，各位应该大概了解怎么玩了，但是回到团队协作下，我们要好好构思，研发团队应该怎么做 specs。

所以，在这一节中，讲解 Kiro specs 的一些概念，以便回答 [核心执行：AI 驱动的协作流程设计](#核心执行：AI 驱动的协作流程设计) 中提到的问题，怎么指定新的团队研发流程。

#### 需求阶段

Kiro specs 提出在需求阶段用结构化 EARS 表示法定义用户故事和验收标准，也就是 requirements.md 应该撰写的内容。requirements.md 文件以用户故事的形式写成，其中包含 EARS 表示法中的验收标准。

核心工作如下：

* 定义用户故事
* 编写验收标准
* 采用 EARS 符号进行需求规范

与传统需求编写方法的比较，EARS 符号表示需求有很大优势，尤其在使用 AI 编程时。

| **方面**         | **传统要求**                   | **EARS 符号**              |
| ---------------- | ------------------------------ | -------------------------- |
| **明晰**         | 通常含糊不清或冗长             | 简洁明了                   |
| **标准化**       | 不同团队之间存在很大差异       | 所有需求的统一语法         |
| **易于理解**     | 对于非技术利益相关者来说很困难 | 所有利益相关者都能轻松理解 |
| **可追溯分析仪** | 维持起来很困难                 | 通过结构化语法增强可追溯性 |

回想我们公司，产品经理使用飞书文档写产品文档，逻辑混乱，阅读起来非常头疼，常常在编码开发过程中反复调整，在提测和验收环节存在各种各样的问题，上线后一堆 bug。研发流程和上线后的软件，存在各种各样大大小小的问题，研发怪产品经理文档写得烂，产品经理怪研发没有理解需求，测试人员喷研发代码写得烂。

而领导们忙着定制各种 ”规范“，要求产品经理写产品文档要按照某些排版格式去做，做了各种研发流程要求，试图通过指定一系列所谓的规范去彻底解决研发团队内的问题。

EARS 表示法，做了深入了解后，发现这个真的很适合团队落地，既可以解决产品经理到编码、提测后的一些常见问题，又能便于 AI 理解需求。AI 可以很容易基于 EARS 需求表示法，生成对应的编码需求和测试用例，确保代码的逻辑跟需求一致，并且生成对应的验收文档，作为最终代码验收依据。

requirements.md 文档分为多个部分，其中 **Requirements** 部分应当使用 EARS 表示法编写，每个 requirement 都遵循以下模式。

```
当[条件/事件]发生时
系统应[预期行为]
```

![image-20260110103653398](https://raw.githubusercontent.com/whuanle/aispec/master/images/image-20260110103653398.png)

#### 设计阶段

design.md 文件是记录技术架构、顺序图和实现注意事项的地方，通过 design.md 可以全面了解系统的工作方式，包括组件及其交互。Kiri 的规范为设计文档提供了一种结构化的方法，使得理解和协作复杂系统变得更加容易。

设计阶段可以参考前面 AI 生成的 `design.md`，包括了下图中的内容。

![image-20260110104444972](https://raw.githubusercontent.com/whuanle/aispec/master/images/image-20260110104444972.png)

#### 实施阶段

tasks.md 文件提供了一个详细的实施计划，其中包含离散的、可跟踪的任务和子任务。每个任务都有明确的定义，包括清晰的描述、预期结果以及任何必要的资源或依赖关系。每个步骤都可以点击，AI 执行任务后会实时刷新到 task.md 里面。

AI 生成的 task.md 如下，基本也是分三步：分解任务、定义任务输出结果、设置任务上下依赖关系，当然最后可能还有验收实施的说明

![image-20260109131506945](https://raw.githubusercontent.com/whuanle/aispec/master/images/image-20260109131506945.png)

#### 执行阶段

其实就是我们在 task.md 手动点击各个 task 的过程，我们应该一直跟踪任务进度，随时调整更新补充 specs 三个文档，完善内容，让 AI 输出的效果更加好。

### 使用 Hook 自动构建单元测试

当在工作空间中创建、保存或删除与特定全局模式匹配的文件时，会触发文件钩子。这些钩子需要一个模式数组来指定要监视的文件。

这里笔者使用单元测试来做 Hook，让读者了解 Kiro 的 Hook 怎么玩。

单元测试是项目最重要的一部分，由于笔者这个模板项目采用整洁架构，所以做测试也是相当简单。

主要分为三部分考虑：

对于无业务相关的框架、工具、算法代码，单独设计验证的单元测试即可。

对于模型类，要验证 api 请求时参数限制，要识别字段长度范围等规则。

对于 Api、Handler 可以一起测，编写集成测试，直接使用 TestWebHost 模拟请求。

现在我们编写对应的提示词，让 Kiro 生成 Hook。

```
给 Api 编写单元测试，使用 EFCore内存数据库模拟，redis 使用mock替代对于无业务相关的框架、工具、算法代码，单独设计验证的单元测试即可。对于模型类，要验证 api 请求时参数限制，要识别字段长度范围等规则。对于 Api、Handler 可以一起测，编写集成测试，直接使用 TestWebHost 模拟请求。
```

![image-20260109125656799](https://raw.githubusercontent.com/whuanle/aispec/master/images/image-20260109125656799.png)

![image-20260109130251045](https://raw.githubusercontent.com/whuanle/aispec/master/images/image-20260109130251045.png)

![image-20260109125731788](https://raw.githubusercontent.com/whuanle/aispec/master/images/image-20260109125731788.png)

现在使用 spec 加入新的功能：

```
Create Spec: 用户访问短链接后，先将短链接使用 base62 还原为雪花id，先从redis布隆过滤器里面过滤，如果查找不到则直接404。然后从 key `short_url:{雪花id}` 里面找，找不到就查数据库然后重新塞到 redis（超时时间30分钟）。
```

创建完成后，执行 Task list。

可以等待 Hook 自动触发，或在对话界面告诉 AI 手动执行 `api-unit-test-gen.kiro.hook`。

最终生成单元测试如下：

![image-20260109134821100](https://raw.githubusercontent.com/whuanle/aispec/master/images/image-20260109134821100.png)

![image-20260109135655490](https://raw.githubusercontent.com/whuanle/aispec/master/images/image-20260109135655490.png)

### 最后

希望可以通过本文帮助您在公司内建设一个 AI 辅助编程团队。

aispec

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README