Spec Coding 的 Landing Zone

约束层（AI 不能乱来 + 输出必须验证）
    ↓ 有了约束，AI 的输出才有下限
上下文层（AI 了解你的项目）
    ↓ 有了上下文，AI 的输出才贴合你的架构
规格层（AI 知道要做什么）
    ↓ 有了规格，AI 的输出才对题
━━━━━━━━━━━━━━━━━━━━━━━
    → Spec Coding 开始工作
以下还有一层"扩展层"，但不是地基的一部分。
它在三层跑顺之后才需要。

# AGENTS.md
## 1. 项目身份
- 语言：Java 17 / Python 3.11 / TypeScript
- 框架：Spring Boot 3.2 / FastAPI / Next.js
- 构建工具：Maven / Poetry / pnpm
## 2. 技术栈快照
| 类别 | 产品 | 版本 |
|------|------|------|
| ORM | MyBatis-Plus | 3.5.3.1 |
| 数据库 | MySQL | 8.0 |
| 缓存 | Redis | 7.0 |
## 3. 项目结构
src/main/java/com.xxx.module/
├── controller/    # HTTP 入口
├── service/       # 业务逻辑
├── mapper/        # 数据访问
└── entity/        # 实体类
## 4. 永久红线
| 编号 | 禁止 | 原因 |
|------|------|------|
| RED-01 | 修改 com.xxx.finance.* | 财务对账逻辑，高风险 |
| RED-02 | 引入新依赖不申请 | 安全合规 |
| RED-03 | 在 Controller 中写 SQL | 违反分层 |
## 5. AI 行为约束
- 禁止臆造不存在的接口——调用前必须确认
- 禁止同时生成测试和实现——先生成实现，确认后再生成测试
- 禁止明文密钥——使用占位符 ${SECRET_KEY}
- 所有接口返回 ResultVO<T>，不使用裸 Map

## 验证命令（生成代码后必须运行）
1. mvn compile          # 编译通过
2. mvn test             # 单元测试全绿
3. mvn checkstyle:check # 代码规范检查
## AI 生成代码 Review Checklist
□ 实现是否覆盖了所有 AC？
□ 是否调用了已存在的服务（而非重复实现）？
□ 是否在红线模块之外？
□ 异常处理是否符合 BizException 规范？
□ 是否有对应的单元测试？
□ 测试覆盖了所有 AC 场景？

没有约束层的 AI Coding：
用户需求 → AI 生成 → [引入错误依赖] → 编译失败
                        → [跳过分层] → 架构不一致
                        → [格式不统一] → Code Review 被批
                        → [改动红线模块] → 生产事故


每一轮生成都要人工修正 30%~50%，
"AI 帮我写代码"变成"AI 写 + 我改 + 再 Review"，
实际效率可能比手写还低。

## 现有公共服务（可直接调用，禁止重复实现）
- OrderService：订单核心服务，提供 createOrder / cancelOrder
- ProductService：商品信息查询
- UserService：用户信息和权限
- RedisTemplate：已注入，直接用
- RocketMQTemplate：已注入，直接用
## 已有的基础设施类
- ResultVO<T>：统一返回包装
- BizException：业务异常
- BaseEntity：含 createTime / updateTime / createBy / updateBy

## 历史踩坑记录
### 2026-03-15：并发场景重复发货
- 问题：虚拟商品自动发货在并发下重复触发
- 根因：缺少分布式锁
- 修复：使用 Redis 锁，key = order:{orderId}
- 教训：所有自动处理流程必须考虑并发
### 2026-02-20：关键字匹配误判
- 问题：商品名含"虚拟"但不是虚拟商品
- 根因：仅用关键字匹配，没有结合 ID 清单
- 修复：关键字 + ID 清单双重验证
- 教训：单一规则容易误判
③ 系统依赖图谱
## 本系统可以调用的
- 商品系统（product-service）：REST API，查商品信息
- 用户系统（user-service）：gRPC，查用户信息
## 禁止直接调用的
- 支付系统（payment-service）：由订单中台统一调用
  → 原因：支付逻辑复杂，需要统一对账

有了约束层，但没有上下文层：
AI 生成的代码 → 规范是对的（分层/命名/返回格式）
                → 但调用了已存在的接口（重复实现）
                → 或在不该加逻辑的地方加了（越过系统边界）
                → 或没考虑已知的并发问题


结果是：代码"看起来对"，但和现有系统冲突。
合并后要花更多时间处理集成问题。

## US-001：虚拟商品自动识别
作为一个订单系统，
我希望自动识别订单中的虚拟商品，
以便对虚拟商品执行自动发货流程。
### 验收条件
- AC-01：商品条码命中虚拟商品清单 → 标记为虚拟商品
- AC-02：商品金额为 0 → 标记为虚拟商品
- AC-03：同时命中条码清单 AND 金额为 0 → 标记为虚拟商品
- AC-04：以上条件都不满足 → 标记为实体商品
- AC-05：虚拟商品进入自动发货队列，实体商品进入普通发货流程
- AC-06：并发场景下同一订单不重复处理

## POST /api/order/{orderId}/classify
### 请求
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| orderId | Long | 是 | 订单 ID |
### 响应 200
{
  "code": 0,
  "data": {
    "orderId": 12345,
    "productType": "VIRTUAL",
    "autoShipEnabled": true
  }
}
### 响应 404
| 字段 | 说明 |
|------|------|
| code | 1001 |
| message | 订单不存在 |

## order_classify_log（订单分类记录）
| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| order_id | bigint | 订单 ID |
| product_type | varchar(20) | VIRTUAL / PHYSICAL |
| auto_ship_enabled | tinyint | 是否自动发货 |
| classify_result | varchar(500) | 分类详情 |
| create_time | datetime | 创建时间 |

Spec（精确输入）→ AI 生成 → 对照 AC 验证 → 差多少补多少
整个过程可控、可追溯、可重复。

有了约束 + 上下文，但没有 Spec：

AI 生成的代码 → 规范对（分层/命名/返回格式）
               → 架构对（不冲突/不越界）
               → 但做的东西不是你想要的

结果是：代码质量不差，但方向错了。
返工成本 = 重新理解需求 + 重新生成 + 重新 Review，
比没有约束层更浪费时间。

## Spec 分工
- PM / 产品：写用户故事（US）和验收条件（AC）
- 架构师：写 API 接口规格和数据模型
- Tech Lead：审查 Spec 的一致性和可实现性
- 开发：AI 生成代码 + 人工 Review + 补充边界情况

Skill Hub 初始化清单（第一个月，不需要更多）
- 编码规范.skill（命名/日志/异常/返回值的标准写法）
- CRUD 标准流程.skill（最常见的代码模式）
- 分页查询.skill（高频场景的标准实现）
- 事务管理.skill（什么时候加 @Transactional）

前三层在一个人的仓库里运行良好，
但扩展到 3 个团队、10 个项目后：

每个项目的 AGENTS.md 各异 → AI 在每个项目里"重新学习"
没有共享的 Skill → 好的实践无法复制
Spec 格式不统一 → 跨团队协作时接口不一致

结果是：个人效率提升了，但团队效率没有提升。
组织级的效果为零。

三层地基（必须）
━━━━━━━━━━━━━━
Layer 1  约束层     AGENTS.md + 验证门禁    代码下限保障       ★★★★☆
Layer 2  上下文层   Context Pack            系统一致性         ★★★★☆
Layer 3  规格层     Spec 文档集（最少3份）   做对的事           ★★★★★
一层扩展（三层跑顺后再加）
━━━━━━━━━━━━━━━━━━━━━━
Layer 4  团队层     共享模板 + Skill 库      组织级放大         ★★★★☆

到位标准：
拿到一个新的业务需求，让 AI 生成代码，
编译通过率 ≥ 80%，分层/命名/返回格式不需要人工修正。

不到位信号：
AI 每次都在 import 不存在的包、跳过分层、格式混乱。
→ 说明约束写得太笼统，需要更具体的规则。

过头信号：
AGENTS.md 写了超过 50 条规则，AI 开始违反其中某些规则。
→ 规则太多等于没有规则，应该合并、删减到 15~20 条核心约束。

到位标准：
AI 不会重复实现已有的 Service、不会调用被禁止的系统、
不会踩之前踩过的坑。

不到位信号：
新项目里 AI 又写了一个和现有功能重复的类。
→ 说明上下文文件没有覆盖到这个项目，需要补充。

过头信号：
踩坑记录写了超过 50 条，AI 的上下文窗口被挤占。
→ 只保留最近 10~15 条高频坑，更早的归档到文档库按需引用。

到位标准：
一份完整的 Spec（US + API + 数据模型 + AC），
AI 一次生成的代码覆盖 80% 以上的 AC。

不到位信号：
每次生成后需要大幅重写才能用。
→ 说明 Spec 不够精确（AC 模糊、接口字段不完整）。
注意：不是 Spec 要写更多，而是要写得更精确。

过头信号：
一份 Spec 写了 30+ 页，AI 生成时遗漏了关键约束。
→ Spec 太长反而导致 AI 注意力分散，应该拆分为"核心Spec（5页内）+ 附录"。

到位标准：
新项目基于团队模板初始化 AGENTS.md 和 Context Pack，
30 分钟内可以开始用 AI 写代码。

不到位信号：
每个新项目都要花几天写规范，团队没有共享资产。
→ 说明 Skill 库和模板机制需要完善。

过头信号：
Skill 库建了上百个 Skill，团队成员不知道该用哪个。
→ 只保留每个季度 Top 10 最常用的 Skill，其余归档。

Week 1 Day 1：选一个真实的、非核心的需求（比如一个 CRUD 接口）
              ↓
              花 30 分钟铺 Layer 1 + 2（AGENTS.md + Context Pack）
              ↓
              让 AI 用这个需求生成代码
              ↓
              看看哪里错了 → 更新 AGENTS.md / 补充 Context
              ↓
Week 1 Day 2~5：每天做 2~3 个类似需求
              每遇到一次 AI 犯错 → 补一条规则或一条踩坑记录
              ↓
Week 2：开始写 Layer 3（Spec）
       用"这周做完的需求"反推 Spec 模板
       下周的需求直接用 Spec 驱动