ai-engineering-init 1.13.0 → 1.14.1

package/.codex/skills/collaborating-with-codex/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: collaborating-with-codex
 description: |
-  与 OpenAI Codex CLI 协同开发。支持 MCP 原生集成和桥接脚本两种模式。
-  默认模型：gpt-5.3-codex
+  与 Codex MCP 协同开发。通过 GuDaStudio/codexmcp 集成，使用 mcp__codex__codex 工具。
+  默认沙箱：read-only（严禁 codex 修改真实代码）。
 
   触发场景：
   - 需要算法实现或复杂逻辑分析
@@ -14,110 +14,128 @@ description: |
   触发词：Codex、协作、多模型、原型、Diff、算法分析、代码审查、codex协同
 
   前置要求：
-  - 已安装 Codex CLI (npm install -g @openai/codex)
-  - 已配置 OpenAI API Key (codex auth login)
+  - 已通过 `claude mcp add codex -s user --transport stdio -- uvx --from git+https://github.com/GuDaStudio/codexmcp.git codexmcp` 注册
+  - ~/.claude/settings.json 的 permissions.allow 已加入 mcp__codex__codex
 ---
 
-# 与 Codex CLI 协同开发
+# 与 Codex MCP 协同开发
 
-> 两种调用方式：**MCP 原生集成**（推荐）和桥接脚本。默认模型 `gpt-5.3-codex`。
+> 通过 `mcp__codex__codex` 工具直接调用，无需命令行。始终使用 `read-only` 沙箱，要求 codex 只输出 unified diff patch。
 
 ---
 
-## 方式一：MCP 原生集成（推荐）
+## MCP 工具说明
 
-已通过 `codex-mcp-server` 注册为 Claude Code 的 MCP 工具，可直接在对话中使用。
+### 工具名
+`mcp__codex__codex`
 
-### MCP 工具列表
+### 参数
 
-| 工具 | 用途 | 示例指令 |
-|------|------|---------|
-| `codex` | AI 编码助手，支持会话、模型选择 | "用 codex 分析这个函数" |
-| `review` | 代码审查（未提交代码、分支、提交） | "用 codex review 检查 main 分支差异" |
-| `listSessions` | 查看活跃会话 | "列出 codex 会话" |
-| `ping` | 测试连接 | "ping codex" |
-
-### MCP 使用示例
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `PROMPT` | string | ✅ | - | 发送给 Codex 的任务指令（建议用英语） |
+| `cd` | Path | ✅ | - | 工作目录根路径（必须存在） |
+| `sandbox` | string | ❌ | `read-only` | `read-only` / `workspace-write` / `danger-full-access` |
+| `SESSION_ID` | UUID | ❌ | None | 继续之前的会话，保持上下文 |
+| `return_all_messages` | bool | ❌ | False | 是否返回推理过程和工具调用详情 |
+| `model` | string | ❌ | None | 指定模型（None 使用用户默认配置） |
+| `image` | List[Path] | ❌ | None | 附加图片文件 |
+| `yolo` | bool | ❌ | False | 跳过沙箱审批（危险，不推荐） |
+| `profile` | string | ❌ | None | 从 `~/.codex/config.toml` 加载的配置名 |
+| `skip_git_repo_check` | bool | ❌ | False | 允许在非 Git 仓库中运行 |
+
+### 返回值
+
+```json
+// 成功
+{
+  "success": true,
+  "SESSION_ID": "uuid-string",     // 必须保存，用于多轮交互
+  "agent_messages": "codex回复内容"
+}
+
+// 失败
+{
+  "success": false,
+  "error": "错误信息"
+}
+```
 
-**基础调用**：直接在 Claude Code 对话中说：
-- "用 codex 工具分析 OrderInfoService 的业务逻辑"
-- "用 codex review 检查当前未提交的代码变更"
-- "用 codex 生成这个方法的单元测试，模型用 gpt-5.3-codex"
+---
 
-**多轮会话**：codex 工具支持 `sessionId` 参数，自动维持上下文。
+## 标准协作流程
 
-**模型指定**：调用时传入 `model: "gpt-5.3-codex"` 参数（已配置为默认）。
+```
+1. 需求分析阶段
+   Claude 形成初步分析 → 告知 codex → codex 完善方案
 
-### MCP 配置位置
+2. 编码前（原型阶段）
+   调用 codex（read-only）→ 要求输出 unified diff patch
+   Claude 以 diff 为逻辑参考 → 重写为生产级代码
 
-```
-~/.claude.json → projects → mcpServers → codex-cli
-~/.codex/config.toml → profiles（review/analyze/prototype）
+3. 编码后（审查阶段）
+   调用 codex review 改动 → 验证需求完成度和代码质量
 ```
 
 ---
 
-## 方式二：桥接脚本
+## 调用示例
 
-适用于需要精细控制参数或后台批量执行的场景。
+### 场景一：需求分析完善
 
-### 快速开始
+```
+PROMPT: "Here is my requirement: [需求描述]. My initial approach: [初步思路].
+Please review and improve the analysis and implementation plan.
+Output: structured analysis with potential risks."
 
-```bash
-python .claude/skills/collaborating-with-codex/scripts/codex_bridge.py \
-  --cd . --model gpt-5.3-codex --PROMPT "Your task"
+cd: /path/to/project
+sandbox: read-only
 ```
 
-### 参数说明
+### 场景二：获取代码原型（Diff）
 
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| `--PROMPT` | str | ✅ | - | 发送给 Codex 的任务指令（使用英语） |
-| `--cd` | Path | ✅ | - | 工作目录根路径 |
-| `--model` | str | ❌ | `gpt-5.3-codex` | 指定模型 |
-| `--sandbox` | Literal | ❌ | `read-only` | 沙箱策略 |
-| `--SESSION_ID` | UUID | ❌ | `None` | 会话 ID（继续之前的对话） |
-| `--profile` | str | ❌ | `None` | Codex profile（review/analyze/prototype） |
-| `--return-all-messages` | bool | ❌ | `False` | 返回完整推理信息 |
-| `--image` | List[Path] | ❌ | `None` | 附加图片 |
-| `--yolo` | bool | ❌ | `False` | 跳过审批（危险） |
-
-### 使用示例
+```
+PROMPT: "Generate a unified diff patch to implement [功能描述].
+File: [目标文件路径]
+Requirements:
+- [要求1]
+- [要求2]
 
-```bash
-# 代码分析（只读）
-python .claude/skills/collaborating-with-codex/scripts/codex_bridge.py \
-  --cd . --model gpt-5.3-codex --profile analyze \
-  --PROMPT "Analyze the four-layer architecture in OrderInfoWebController"
-
-# 代码审查
-python .claude/skills/collaborating-with-codex/scripts/codex_bridge.py \
-  --cd . --model gpt-5.3-codex --profile review \
-  --PROMPT "Review OrderWebBusiness.java for bugs. OUTPUT: Review with line numbers."
-
-# 生成 Diff 补丁
-python .claude/skills/collaborating-with-codex/scripts/codex_bridge.py \
-  --cd . --model gpt-5.3-codex \
-  --PROMPT "Generate unified diff to add logging. OUTPUT: Unified Diff Patch ONLY."
-
-# 多轮会话
-python .claude/skills/collaborating-with-codex/scripts/codex_bridge.py \
-  --cd . --model gpt-5.3-codex \
-  --SESSION_ID "uuid-from-previous" \
-  --PROMPT "Now write unit tests for the method we discussed"
+IMPORTANT: Output unified diff patch ONLY. Do NOT modify any real files.
+IMPORTANT: All Java comments and SQL COMMENTs MUST be in Chinese."
+
+cd: /path/to/project
+sandbox: read-only
 ```
 
----
+### 场景三：代码审查
+
+```
+PROMPT: "Review the following code changes for correctness, performance, and security.
+[粘贴代码或说明文件路径]
+
+Check:
+1. Logic correctness
+2. Edge cases
+3. Performance issues
+4. Security vulnerabilities
+
+Output: review with line numbers and severity (CRITICAL/WARNING/INFO)."
+
+cd: /path/to/project
+sandbox: read-only
+```
 
-## Codex Profile 配置
+### 场景四：多轮交互（继续会话）
 
-已在 `~/.codex/config.toml` 中预设 3 个 profile：
+```
+// 第一轮
+SESSION_ID: None → 保存返回的 SESSION_ID
 
-| Profile | 模型 | 沙箱 | 推理强度 | 适用场景 |
-|---------|------|------|---------|---------|
-| `review` | gpt-5.3-codex | read-only | medium | 快速代码审查 |
-| `analyze` | gpt-5.3-codex | read-only | high | 深度逻辑分析 |
-| `prototype` | gpt-5.3-codex | workspace-write | high | 原型生成 |
+// 第二轮
+SESSION_ID: "上一轮返回的 uuid"
+PROMPT: "Now refine the diff based on the feedback: [反馈内容]"
+```
 
 ---
 
@@ -125,24 +143,18 @@ python .claude/skills/collaborating-with-codex/scripts/codex_bridge.py \
 
 | 角色 | Claude Code 负责 | Codex 负责 |
 |------|-----------------|-----------|
-| **架构** | 设计、决策、审校 | 分析现有代码 |
-| **开发** | 规范重构、最终代码 | 原型生成（Diff） |
-| **审查** | 规范检查、最终判定 | 逐文件审查、安全扫描 |
-| **调试** | 日志分析、定位 | 深度代码分析、补丁 |
+| **架构** | 设计决策、规范审校 | 分析现有代码结构 |
+| **开发** | 规范重写、最终代码实施 | 输出原型 diff（只读参考） |
+| **审查** | 规范检查、最终判定 | 逐文件逻辑审查 |
+| **调试** | 日志分析、问题定位 | 深度代码分析、补丁建议 |
 
 ### 重要约束
 
-1. **只读优先**: 默认 `read-only`，仅原型生成用 `workspace-write`
-2. **英语 Prompt**: 与 Codex 交互用英语
-3. **中文强制**: 每次 PROMPT 末尾追加：
-   ```
-   IMPORTANT LANGUAGE RULES:
-   - All SQL COMMENT values MUST be in Chinese
-   - All Java/code comments MUST be in Chinese
-   - Variable names and class names remain in English
-   ```
-4. **脏原型思维**: Codex 输出视为草稿，Claude 按项目规范重构
-5. **后台运行**: 长时间任务用 subagent `run_in_background`
+1. **只读优先**：始终使用 `sandbox="read-only"`
+2. **英语 Prompt**：与 codex 交互用英语，代码注释要求中文
+3. **脏原型思维**：codex 输出视为草稿，Claude 按项目规范重构
+4. **保存 SESSION_ID**：每次调用后记录，多轮对话时传入
+5. **质疑 codex**：codex 仅供参考，必须有独立判断
 
 ---
 
@@ -150,8 +162,19 @@ python .claude/skills/collaborating-with-codex/scripts/codex_bridge.py \
 
 | 问题 | 解决方案 |
 |------|---------|
-| MCP 工具未出现 | 重启 Claude Code 会话，检查 `~/.claude.json` |
-| `codex: command not found` | `npm i -g @openai/codex` 并确认 PATH |
-| 模型不对 | 调用时显式传 `model: "gpt-5.3-codex"` |
-| MCP 连接超时 | `npx -y codex-mcp-server` 手动测试 |
-| 桥接脚本 SESSION_ID 失败 | 检查网络和 API Key |
+| 工具未出现 | 重启 Claude Code，检查 `~/.claude.json` 中 codex 配置 |
+| `cd` 参数报错 | 确认目录存在，使用绝对路径 |
+| 连接超时 | 检查网络，`uvx --from git+https://github.com/GuDaStudio/codexmcp.git codexmcp` 手动测试 |
+| SESSION_ID 失效 | 重新开启新会话（不传 SESSION_ID） |
+| codex 修改了文件 | 确认 `sandbox="read-only"` 已设置 |
+
+## 安装验证
+
+```bash
+# 查看 MCP 配置
+cat ~/.claude.json | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('mcpServers', {}).get('codex', 'not found'))"
+
+# 重启后运行
+claude mcp list
+# 期望看到: codex: uvx ... - ✓ Connected
+```

package/.codex/skills/leniu-code-patterns/SKILL.md

@@ -394,9 +394,186 @@ public class OrderService {
 }
 ```
 
-## 通用代码规范
+## 数据类型规范
+
+### 布尔字段命名
+
+```java
+// ❌ 错误：前缀冗余、类型错误
+private Integer ifNarrow;
+private Integer isEnabled;
+
+// ✅ 正确：Boolean 类型，无前缀
+private Boolean narrow;     // getter → isNarrow()
+private Boolean enabled;    // getter → isEnabled()
+```
+
+### 枚举字段标注
+
+```java
+// ❌ 错误：只靠注释 @see
+/** @see AccTradeTypeEnum */
+private Integer tradeType;
+
+// ✅ 方案一：VO/DTO 用枚举类型（配合 @JsonValue）
+private AccTradeTypeEnum tradeType;
+
+// ✅ 方案二：@ApiModelProperty 标注合法值
+@ApiModelProperty(value = "操作类型：1-充值 2-消费 3-退款", allowableValues = "1,2,3")
+private Integer tradeType;
+```
+
+## MyBatis-Plus 安全规范
+
+### selectOne 必须有唯一保障
+
+```java
+// ❌ 危险：多条记录时抛 TooManyResultsException
+Entity entity = mapper.selectOne(wrapper);
+
+// ✅ 方案一：LIMIT 1
+Entity entity = mapper.selectOne(wrapper.last("LIMIT 1"));
+
+// ✅ 方案二：selectList 取第一条
+List<Entity> list = mapper.selectList(wrapper);
+Entity entity = CollUtil.isNotEmpty(list) ? list.get(0) : null;
+
+// ✅ 方案三：确保有唯一索引（注释说明）
+// 唯一索引：UNIQUE KEY (order_no, del_flag)
+Entity entity = mapper.selectOne(wrapper);
+```
+
+### 存在性判断用 EXISTS，禁用 selectCount
+
+```java
+// ❌ 低效：100万行表 ~200ms
+Long count = mapper.selectCount(wrapper);
+if (count > 0) { ... }
+
+// ✅ 高效：~2ms（MyBatis-Plus 3.5.4+）
+boolean exists = mapper.exists(wrapper);
+
+// ✅ 或 selectList + LIMIT 1
+boolean exists = CollUtil.isNotEmpty(mapper.selectList(wrapper.last("LIMIT 1")));
+```
+
+### Wrapper 嵌套不超过 2 层
+
+```java
+// ❌ 过于复杂的 Wrapper
+wrapper.and(w -> w.eq(A::getType, type)
+    .or(q -> q.eq(A::getType, 0))
+    .or(!PersonTypeEnum.LABOUR.getKey().equals(type),
+        q -> q.eq(A::getType, PSN_TYPE_SHARED)));
+
+// ✅ 复杂查询写到 XML 中
+List<Entity> list = mapper.selectByTypeCondition(type, isLabour);
+```
+
+### 禁止 SELECT *
+
+```xml
+<!-- ❌ 禁止 -->
+<select id="selectAll">SELECT * FROM t_order WHERE del_flag = 2</select>
+
+<!-- ✅ 明确列出字段 -->
+<select id="selectAll">SELECT id, order_no, amount, status, crtime FROM t_order WHERE del_flag = 2</select>
+```
+
+## Redis 使用规范
+
+### 禁止 KEYS 命令
 
-无论使用哪种项目架构，以下规范都是通用的：
+```java
+// ❌ 严禁：KEYS 阻塞 Redis
+Set<Object> keys = keysByPattern(pattern);
+Set<Object> keys = redisTemplate.keys(pattern);
+
+// ✅ 使用 Redisson deleteByPattern（内部 SCAN + UNLINK）
+RedissonClient redisson = SpringUtil.getBean(RedissonClient.class);
+redisson.getKeys().deleteByPattern(keyPattern);
+```
+
+## Optional 使用规范
+
+```java
+// ❌ 错误：of() 不接受 null
+Optional.of(value).orElse(defaultValue);
+
+// ✅ 正确：ofNullable()
+Optional.ofNullable(value).orElse(defaultValue);
+
+// ✅ 链式安全转换
+Optional.ofNullable(model.getReserveRate())
+    .map(BigDecimal::new)
+    .orElse(BigDecimal.ZERO);
+
+// ❌ 禁止作为方法参数或类字段
+// ✅ 允许作为方法返回值
+```
+
+## @Transactional 规范
+
+```java
+// ❌ 默认只回滚 RuntimeException
+@Transactional
+public void createOrder() { ... }
+
+// ✅ 显式指定 rollbackFor
+@Transactional(rollbackFor = Exception.class)
+public void createOrder() { ... }
+```
+
+- 事务方法不要 try-catch 吞掉异常
+- 只读查询不加 `@Transactional`
+
+## 业务逻辑分层规范
+
+```java
+// ❌ 错误：业务判断混在数据操作中
+public void processOrder(Long orderId) {
+    OrderInfo order = orderMapper.selectById(orderId);
+    if (order.getStatus() == 1 && order.getPayTime() != null
+        && ChronoUnit.HOURS.between(order.getPayTime(), LocalDateTime.now()) < 24) {
+        order.setStatus(2);
+        orderMapper.updateById(order);
+        accWalletService.deduct(order.getCustId(), order.getAmount());
+    }
+}
+
+// ✅ 正确：分层清晰
+public void processOrder(Long orderId) {
+    OrderInfo order = orderMapper.selectById(orderId);
+    if (ObjectUtil.isNull(order)) {
+        throw new LeException(I18n.getMessage("order_not_found"));
+    }
+    checkCanProcess(order);           // 业务校验（独立方法）
+    order.markAsProcessed();          // 状态变更（Entity 方法封装）
+    orderMapper.updateById(order);
+    afterOrderProcessed(order);       // 后续动作（独立方法）
+}
+```
+
+| 层 | 职责 | 不应做的 |
+|----|------|---------|
+| Controller | 参数接收、格式转换 | 不含业务判断 |
+| Business | 业务编排、跨 Service 协调 | 不直接操作 Mapper |
+| Service | 单表 CRUD、单表事务 | 不含跨表业务逻辑 |
+| Mapper | SQL 映射 | 不含业务逻辑 |
+
+## TODO 管理规范
+
+```java
+// ❌ 错误
+// TODO 修改一下
+
+// ✅ 正确
+// TODO(@陈沈杰, 2026-03-20, #TASK-1234): 移动端 AppId 赋值逻辑待产品确认
+```
+
+- 不用的代码直接删除，不要注释保留
+
+## 通用代码规范
 
 1. **禁止使用 `SELECT *`**：明确指定字段
 2. **使用参数化查询**：`#{}` 而非 `${}`

package/.cursor/skills/analyze-requirements/SKILL.md

@@ -29,7 +29,7 @@ description: |
   │   - 用户已给出完整字段列表
   │
   └─ 复杂需求？ ──→ Agent 路径（启动 requirements-analyzer）
-      - 提供了 Axure 原型链接或截图
+      - 提供了 Axure 原型截图
       - 提供了云效任务编号
       - 多页面/多模块联动
       - 业务流程复杂，需要状态流转设计
@@ -45,34 +45,12 @@ description: |
 
 ## Agent 路径（复杂需求）
 
-### Axure 链接处理（重要）
-
-> **Axure 是 SPA 应用，WebFetch 必定失败（TLS/JS 渲染问题）。禁止用 WebFetch 访问 Axure 链接。**
-
-当用户提供 Axure 链接时，必须用 Playwright 截图：
-
-```bash
-# 1. 先用 Playwright 截图（每个页面单独截）
-npx playwright screenshot --wait-for-timeout 3000 "https://xxx.axure.cloud/page1" /tmp/axure-1.png
-npx playwright screenshot --wait-for-timeout 3000 "https://xxx.axure.cloud/page2" /tmp/axure-2.png
-
-# 2. 截图完成后，将文件路径传给 image-reader Agent 分析
-# 3. 如果原型有多个页面，URL 通常带 #page 参数，逐页截图
-```
-
-**判断规则**：
-- URL 包含 `axure.cloud` 或 `.axshare.com` → Playwright 截图
-- 用户说"Axure 链接" → Playwright 截图
-- 本地截图文件（.png/.jpg） → 直接 image-reader 分析
-
-### 完整流程
-
 ```
 步骤 1：收集信息（从用户消息中提取）
-  - Axure 原型链接 → Playwright 截图 → image-reader 分析
-  - Axure 原型截图文件 → 直接 image-reader 分析
-  - 云效任务编号 → task-fetcher 获取详情
+  - Axure 原型截图路径
+  - 云效任务编号
   - 需求描述文字
+  - 关联模块信息
 
 步骤 2：启动 requirements-analyzer Agent
   └── requirements-analyzer(Opus) 内部自动编排：
@@ -91,23 +69,13 @@ npx playwright screenshot --wait-for-timeout 3000 "https://xxx.axure.cloud/page2
 |---------------|---------|
 | 只有文字描述 | 快速路径（不启动 Agent） |
 | 文字 + 原型截图 | requirements-analyzer → 内部调 image-reader |
-| 文字 + Axure 链接 | Playwright 截图 → requirements-analyzer → image-reader |
 | 文字 + 云效任务号 | requirements-analyzer → 内部调 task-fetcher |
 | 原型截图 + 云效任务号 | requirements-analyzer → 内部并行调 image-reader + task-fetcher |
 
 ### 启动示例
 
 ```
-# 有 Axure 链接（先截图再分析）
-Bash: npx playwright screenshot --wait-for-timeout 3000 "https://xxx.axure.cloud/page1" /tmp/axure-1.png
-Bash: npx playwright screenshot --wait-for-timeout 3000 "https://xxx.axure.cloud/page2" /tmp/axure-2.png
-
-Agent(subagent_type="requirements-analyzer",
-  prompt="分析以下 Axure 原型截图，输出需求分析报告和开发任务清单：
-  截图路径：/tmp/axure-1.png, /tmp/axure-2.png
-  需求描述：xxx")
-
-# 有原型截图文件
+# 有原型截图
 Agent(subagent_type="requirements-analyzer",
   prompt="分析以下 Axure 原型截图，输出需求分析报告和开发任务清单：
   截图路径：/path/to/image1.png, /path/to/image2.png
@@ -142,4 +110,3 @@ Agent(subagent_type="requirements-analyzer",
 - 与 `bug-detective` / `fix-bug` 的区别：本技能面向**新功能开发前的需求分析**，不涉及 Bug 排查
 - 数据库设计必须遵循项目规范（雪花 ID、审计字段、del_flag=2 正常）
 - 如果需求信息不完整，主动列出需要确认的点，而不是猜测
-- **Axure 链接必须用 Playwright 截图，禁止 WebFetch**

package/.cursor/skills/code-patterns/SKILL.md

@@ -101,6 +101,120 @@ feat(order): 新增订单导出功能
 Closes #123
 ```
 
+## 数据类型规范
+
+### 布尔语义字段必须使用 Boolean
+
+```java
+// ❌ 错误
+private Integer ifNarrow;
+private Integer isEnabled;
+
+// ✅ 正确
+private Boolean narrow;     // getter 自动生成 isNarrow()
+private Boolean enabled;    // getter 自动生成 isEnabled()
+```
+
+**规则**：
+- 语义为"是/否"的字段，类型必须为 `Boolean`
+- 字段名不加 `if`/`is`/`has` 前缀（JavaBean 规范中 `Boolean` 的 getter 自动生成 `isXxx()`）
+- 数据库字段使用 `TINYINT(1)` 或 `BIT(1)`
+
+### 枚举字段必须提供明确约束
+
+```java
+// ❌ 错误：调用方无法知道合法值
+@ApiModelProperty(value = "操作类型")
+private Integer tradeType;
+
+// ✅ 方案一：VO/DTO 层直接用枚举（推荐）
+@ApiModelProperty(value = "操作类型")
+private AccTradeTypeEnum tradeType;
+
+// ✅ 方案二：保留 Integer 但标注合法值
+@ApiModelProperty(value = "操作类型：1-充值 2-消费 3-退款", allowableValues = "1,2,3")
+private Integer tradeType;
+```
+
+### 金额字段禁止使用浮点类型
+
+```java
+// ❌ 错误
+private Double amount;
+private Float price;
+
+// ✅ 正确：Entity/Service 层用 Long（分），VO 层展示用 BigDecimal（元）
+private Long amountFen;
+private BigDecimal amountYuan;
+```
+
+### 原始类型 vs 包装类型
+
+| 场景 | 用原始类型 | 用包装类型 |
+|------|----------|----------|
+| Entity / VO / DTO 字段 | — | ✅ 统一用包装类型 |
+| 方法参数（不允许 null） | ✅ `int count` | — |
+| 方法参数（允许 null） | — | ✅ `Integer count` |
+| 局部变量 | ✅ `int i = 0` | — |
+
+## Optional 使用规范
+
+```java
+// ❌ 错误：of() 不接受 null，value 为 null 直接 NPE
+Optional.of(value).orElse(defaultValue);
+
+// ✅ 正确：ofNullable() 安全处理 null
+Optional.ofNullable(value).orElse(defaultValue);
+
+// ❌ 禁止：Optional 作为方法参数或类字段
+public void process(Optional<String> name) { ... }
+private Optional<String> name;
+
+// ✅ 允许：Optional 作为方法返回值、链式处理
+public Optional<Entity> findById(Long id) { ... }
+Optional.ofNullable(entity).map(Entity::getConfig).orElse(DEFAULT_VALUE);
+```
+
+## @Transactional 规范
+
+```java
+// ❌ 错误：默认只回滚 RuntimeException
+@Transactional
+public void createOrder() { ... }
+
+// ✅ 正确：显式指定回滚异常
+@Transactional(rollbackFor = Exception.class)
+public void createOrder() { ... }
+```
+
+- 所有 `@Transactional` 必须显式写 `rollbackFor = Exception.class`
+- 只读查询不加 `@Transactional`（或用 `readOnly = true`）
+- 事务方法不要 try-catch 吞掉异常，否则事务不回滚
+
+## TODO 管理规范
+
+```java
+// ❌ 错误：无负责人、无日期、无跟踪
+// TODO 修改一下
+
+// ✅ 正确：完整 TODO 格式
+// TODO(@陈沈杰, 2026-03-20, #TASK-1234): 移动端 AppId 赋值逻辑待产品确认
+```
+
+- 每个 TODO 必须有对应的任务号
+- 超过 2 个迭代未处理的 TODO 必须清理
+- 不用的代码直接删除，不要注释保留
+
+## 代码格式化规范
+
+| 项目 | 规范 |
+|------|------|
+| 缩进 | 4 个空格（不用 Tab） |
+| 行宽 | 120 字符 |
+| 大括号 | K&R 风格（同行开始） |
+| 空行 | 方法间 1 个空行，逻辑块间 1 个空行 |
+| import | 分组排序：java → jakarta → org → net → com，组间空行 |
+
 ## 代码示例
 
 ### 统一响应格式
@@ -161,3 +275,8 @@ public enum OrderStatusEnum {
 | Git 提交信息写"fix bug" | 写清楚修了什么：`fix(order): 修复金额计算精度丢失` |
 | Boolean 变量名：`flag` | 有意义的名字：`isActive`, `hasPermission` |
 | 缩写命名：`usr`, `mgr` | 完整命名：`user`, `manager` |
+| `Optional.of(可能null值)` | `Optional.ofNullable(value)` |
+| `@Transactional` 无 rollbackFor | `@Transactional(rollbackFor = Exception.class)` |
+| TODO 无负责人和日期 | `// TODO(@负责人, 日期, #任务号): 描述` |
+| 布尔字段用 `Integer` | 用 `Boolean` 类型 |
+| 枚举字段无合法值说明 | `@ApiModelProperty` 标注合法值或直接用枚举类型 |