一、核心理念：3文件底线

放弃一切中间文档，只保留3个防崩底线：

1. .trae/skills/（技术宪法-模块化）：按场景自动加载的防崩规则（多租户/状态机/防御注释）[推荐]
   • 备选：.trae/rules/（技术宪法-全局版）：简单项目单文件兜底 [Trae同时支持]
2. prd/feature-xxx.md（唯一真相源）：Living PRD，业务+技术约束，聊天迭代即更新
3. DECISIONS.md（决策日志）：可选，仅记录"为什么选A不选B"（防止3个月后失忆）

其他全部外包：Prompt模板存Gist，不放在项目里。

二、极简目录结构（Trae 专用）

mes-project/
├── .trae/
│   ├── skills/               # ✅ 方案A：模块化Skills（复杂项目推荐）
│   │   ├── bladex-tenant/
│   │   │   └── SKILL.md      #     多租户隔离（自动识别Java文件时加载）
│   │   ├── mes-state-machine/
│   │   │   └── SKILL.md      #     状态机防跳步
│   │   └── tdengine-query/
│   │       └── SKILL.md      #     时序查询规范
│   └── rules/                # ⚠️ 方案B：全局Rules（简单项目备选）
│       └── global.md         #     单文件兜底（Skills为空时 fallback）
├── prd/
│   └── feature-001.md        # ✅ Living PRD（唯一需求源）
├── DECISIONS.md              # ⚠️ 可选（技术债务提醒）
├── .git/hooks/pre-commit     # ✅ 提交前自动检查（防崩）
└── src/                      # 源码（自解释注释关联PRD）

Trae 加载优先级：skills/（模块化）> rules/（全局）> 内置默认。
底线原则：不要并存——简单项目用rules/global.md，复杂项目用skills/*，避免规则重复。

三、三步工作流（每日执行）

Step 1: Living PRD迭代（聊天驱动，3分钟）

目的：通过聊天补全技术细节，AI自动Merge到PRD

前置：已有业务PRD（或从零开始）

操作：

1. 打开Trae，粘贴当前PRD作为基线
2. 发送 开场Prompt（保存到Trae全局或Gist）：

角色：Living PRD维护助手（MES架构师）

基线PRD：
[粘贴当前PRD全文]

模式：
- 我聊天补充细节（口语化，如："并发要50，上次30就崩了"）
- 你说【入PRD】时，生成Diff并输出完整新版PRD（版本号+1）
- 你说【生成代码】时，基于最新PRD生成Java

关键词：
【入PRD】= 固化到文档（立即执行）
【暂定】= 只讨论不记录
【生成】= 基于当前PRD生成代码

开始。

3. 自由聊天（示例）：

你：并发要支持50，上次30就崩了
AI：识别到第3章性能指标：30→50，是否【入PRD】？
你：入PRD

你：还有，状态机绝对不能回退，除非老板审批
AI：识别到第2章状态机：增加"禁止逆向，除非有RollbackApproval单"，是否【入PRD】？
你：入PRD

4. 保存：复制AI输出的完整新版PRD，替换原文件（版本号v1.0→v1.1）

Step 2: 基于PRD生成代码（5分钟）

目的：AI严格按PRD第6章技术约束生成代码，自检违规点

Prompt（发送给AI）：

基于PRD v1.x生成Java代码（SpringBoot+MyBatis-Plus）：

[粘贴最新PRD]

硬性要求（违反则拒收）：
1. 实现PRD第6章所有技术约束（代码注释标记// PRD-6.x）
2. 每10行业务逻辑加// DEFENSE: If [业务条件], then [风险]
3. PRD第5章错误码必须对应具体Exception（409=MaterialShortageException）
4. 自检报告：列出3个可能违反PRD的代码行及修复方案

历史错误提醒：[粘贴PRD第7章内容，如：上次忘了QC校验]

输出：Java代码文件 + 自检报告

人类动作：

• 审查自检报告，有[FAIL]则让AI修复，无则Accept
• 确认代码含 // DEFENSE 注释（防3个月后改代码时踩坑）

Trae 技术宪法自动生效机制：

• 若用 Skills：检测到你在写 DeviceController.java，自动加载 .trae/skills/bladex-tenant/SKILL.md；写SQL时自动加载 tdengine-query/SKILL.md。无需手动@，Model-invoked。
• 若用 Rules：全局规则始终生效，适合"所有文件必须加DEFENSE注释"这类通用约束。

Step 3: 记录ADR（重大决策时，2分钟）

目的：记录"为什么选A不选B"，给3个月后的自己看

触发：遇到技术选型（乐观锁vs分布式锁、硬编码vs状态机框架）

操作：

1. 在 DECISIONS.md 末尾追加（单文件堆叠，不按目录）：

## 2025-02-08: 选乐观锁而非Redis分布式锁
- 决策：用@Version乐观锁（非RedLock）
- 原因：单机部署50并发足够，避免引入Redis复杂度（我是单人，维护不动）
- 后果：未来集群部署时必须重构为分布式锁（信号：写第5个if-else时重构）
- 关联：PRD-v1.2第6.2节，代码WorkOrderService.issue()

极简替代：如果懒得维护文件，直接写在代码关键行：

// ADR: 选乐观锁因单机部署，未来集群需重构（见PRD-6.2）
@Version
private Long version;

四、3个底线文件模板（复制即用）

1. Trae 技术宪法（二选一，不要并存）

方案A：Skills（复杂项目推荐，Model-invoked）

目录结构：

mkdir -p .trae/skills/bladex-tenant
mkdir -p .trae/skills/mes-state-machine  
mkdir -p .trae/skills/tdengine-query

Skill 模板（bladex-tenant/SKILL.md）：

---
name: bladex-tenant-guard
description: 强制所有SQL通过TenantLine拦截，禁止硬编码tenant_id
---

## 触发条件（AI自动识别）
- 文件匹配：*.java, *.xml (MyBatis)
- 关键词：tenant, mapper, sql, query

## 铁律（违反则拒收代码）
1. **Multi-Tenancy**: ALL SQL MUST include `tenant_id` via `TenantLineInnerInterceptor`
2. **Forbidden Pattern**: 禁止任何 `where tenant_id = 1` 或 `setTenantId(1)` 硬编码
3. **Mandatory**: Mapper接口必须继承 `TenantBaseMapper<T>`

## 自检报告（生成代码后AI自动执行）
- [ ] 扫描 `tenant_id.*=` 硬编码
- [ ] 验证使用 `TenantLineInnerInterceptor` 而非手工拼接SQL
- [ ] 检查是否继承 `TenantBaseMapper`

## 违规拦截（如果检测到以下代码，立即阻止生成）
```java
// 危险！硬编码tenant_id
wrapper.eq("tenant_id", 1);

**技能叠加**：Trae 支持同时加载多个Skills。写代码时自动组合 `bladex-tenant` + `mes-state-machine` + `tdengine-query`。

#### **方案B：Rules（简单项目备选，全局生效）**

**单文件模板**（`.trae/rules/global.md`）：

```markdown
# Role: MES Architect (Java/SpringBoot)
# Hard Rules (Never Violate)

1. Multi-Tenancy: ALL SQL MUST include tenant_id via TenantLineInnerInterceptor. Forbidden: hard-coded tenant_id.

2. State Machine: STRICT transition (CREATE→RELEASE→START→COMPLETE). Forbidden: backward flow without RollbackApproval.

3. Defense Comment: Every 10 lines of business logic MUST include // DEFENSE: If [biz condition], then [manufacturing risk].

选择建议：

• 50租户以下/单人项目：用 Rules（global.md 3条规则足够）
• 50租户以上/团队协作：用 Skills（防止规则过长导致AI遗漏）

2. prd/feature-001.md（Living PRD模板）

# PRD: 工单下发

---
版本: v1.0
日期: 2025-02-08
---

## 1. 业务背景
[中文描述，如：注塑车间工单从纸质转为电子化]

## 2. 业务规则
- 状态机: Create → Release → Start → Complete（禁止逆向）
- 工艺: 必须Op-10完成才能Op-20（防跳步）

## 3. 数字指标
- 并发: 50线程
- 响应: <200ms
- 损耗率: BOM×1.02

## 4. 接口契约
POST /api/mes/wo/{id}/issue
- 409: 物料不齐套（返回缺料清单）
- 422: 工艺未审核

## 5. 验收标准（Gherkin）
Scenario: 并发领料
  Given 库存100 When 50线程同时领料 Then 只扣100（幂等）

## 6. 技术实现约束（Living Tech Spec）
### 6.1 状态机
- 机制: 硬编码枚举（非Spring State Machine，原因见DECISIONS.md）
- 校验: Service入口validateStateTransition()

### 6.2 并发控制
- 机制: 乐观锁@Version（非分布式锁）
- 重试: 3次指数退避（100/200/400ms）

## 7. 历史风险（防重复踩坑）
- v0.9错误: 忘了QC校验导致NG品流出
- v1.0修复: 增加QC Gate拦截

3. .git/hooks/pre-commit（提交前检查）

#!/bin/bash
# 检查3个致命错误
grep -rn "tenant_id.*=" --include="*.java" src/ | grep -v "TenantLine" && echo "❌硬编码tenant_id" && exit 1
grep -rn "setStatus.*COMPLETE" --include="*.java" src/ | grep -v "START" && echo "❌状态机跳步" && exit 1
! grep -r "// DEFENSE:" --include="*.java" src/ && echo "⚠️缺少防御注释" && exit 1
echo "✅通过"

chmod +x .git/hooks/pre-commit

五、Skills vs Rules（Trae 用户决策表）

底线建议：

• 起步阶段（验证MVP）：用 rules/global.md 3条铁律快速启动
• 生产阶段（50租户+）：迁移到 skills/，防止tenant_id硬编码等事故

六、参考资源（Verified Links）

七、立即启动检查清单（Trae 用户）

1. 选择技术宪法方案：

   • 简单项目 → 创建 .trae/rules/global.md（复制方案B模板）
   • 复杂项目 → 创建 .trae/skills/ 目录，复制3个Skill模板（方案A）

2. 复制2个底线文件（prd/template.md 重命名为功能名、.git/hooks/pre-commit）

3. 配置Trae全局（Settings）：粘贴Living PRD开场Prompt

4. 跑通一次循环：

   • 加载PRD → 聊天补充（说"并发要50"）→ 【入PRD】→ 保存v1.1
   • 【生成代码】→ 观察AI自动加载Skills（或应用全局Rules）→ 审查自检报告 → Accept
   • 遇到技术选型 → 追加到 DECISIONS.md

5. 尝试提交代码，确认pre-commit拦截（故意写死tenant_id=1，看是否阻断）

底线红线：

• 没有 .trae/rules/ 或 .trae/skills/ 不生成代码（AI会乱写）
• 没有PRD不生成代码（需求会漂移）
• 没跑通pre-commit不push（会带毒进仓库）

打印本页，贴显示器旁。每日工作流：聊天→【入PRD】→【生成】→记录ADR。