zhenyu23

规范编程

vibe coding的缺点：需求不明确，ai编程发散，导致后期维护困难
提出specify coding：使用ai进行编程前，先制定对应的一系列规范，告诉ai 我要做什么，具体怎么做，做了之后验收验收标准是什么，然后在ai在编程中遵守这套规范进行编程
保证ai 在规范下进行编程，保证项目合规，没有技术债的积累；

怎么进行specfiy coding：
1 明确需求：要做什么（specify)
这一步要明确应用的核心功能，具体的使用用户以及对应的痛点是什么
比如：vibe coding的时候，可能只会说一句帮我编写一个用户登录系统
但是spec coding就需要写的更加详细一些，帮我编写一个用户登录系统，用户必须输入账号和密码才能登录，管理员对用户进行禁用，禁用后并不在数据库删除用户数据，只是用户不能登录，但是用户的历史记录必须保留；
也就是要告诉ai要做什么，什么不能做，那些边界不能碰
2 开始制定
specify：产品定义，requirement.md: 明确功能，目标用户，核心通点，告诉ai做什么
plan：技术规划，plan.md:指定技术架构，开发契约：告诉ai怎么做，把技术栈、接口格式、错误码、日志、并发、安全这些规则提前写好，后面让 AI 写代码时，它就不太容易跑偏。
task：任务分配，task.md:拆分为原子任务，验收标准：告诉ai做到什么程度所算满足要求了
implement：如何在配置完上述内容后将任务分配给ai
3 分配spec 项目文档
图片

实践：
1 做什么：specify
帮我编写一个用户登录系统，支持邮箱注册和登录；邮箱必须唯一，密码长度至少为8位；暂不支持第三方登录；管理员可以禁用用户；用户禁用后不能登录，但是历史数据可以保留。
2 怎么做：plan/design
技术选型，接口规范，对应前后端契约和业务名称

## 技术栈

- 语言: Java 21 (LTS)
- 框架: Spring Boot 3.2.x
- 数据库: PostgreSQL 16
- 缓存: Redis 7.x

## 架构设计

- 分层: Controller → Service → Repository
- 通信: REST API + gRPC（内部服务）
- 部署: Docker + Kubernetes

## 接口约定

- API 规范: OpenAPI 3.0
- 错误码: 统一格式 {"code": "USER_NOT_FOUND", "message": "..."}
- 日志格式: JSON，必须包含 trace_id

3 任务拆分
注册、登录、查询、禁用、权限、参数校验、异常处理、单元测试，全都塞在一个任务里，AI 很容易写着写着漏东西。最后你看代码时，还得一项一项往回补
将具体的每一个小的模块作为一个任务，分配给ai说清楚具体的任务和验收标准：task

### Task-001: 用户注册接口

描述：实现用户注册，包含参数校验、密码加密和用户入库。

验收标准：

- [ ] POST /api/v1/users 成功时返回 201
- [ ] 密码使用 bcrypt 加密后存储
- [ ] 邮箱唯一，重复注册返回 409
- [ ] 返回体必须包含 user_id、email、created_at
- [ ] 分支覆盖率（branch coverage）不低于 80%

预估工时：2h

4 调用ai执行任务：implement


发送给ai的内容：

请根据以下 Spec 实现 Task-001。

需求说明：
[粘贴 requirements.md 相关段落]

技术约束：
[粘贴 design.md 相关段落]

任务验收标准：
[粘贴 tasks.md 里的 Task-001]

发送给ai的内容/总结的文档
请根据以下 Spec 实现 Task-001。

需求说明：
[粘贴 requirements.md 相关段落]

技术约束：
[粘贴 design.md 相关段落]

任务验收标准：
[粘贴 tasks.md 里的 Task-001]

注意:
单次会话里，我会优先放三类内容：

全局约束，比如代码风格、错误码格式、日志规范；
当前任务的需求说明；
当前任务的验收标准

阅读博客：javaguide，什么是spec coding

导航