@alenfitz/spec-copilot 1.0.0

package/framework/rules/coding-style.md

@@ -0,0 +1,74 @@
+# 编码规范（通用原则）
+
+> 本文件定义跨技术栈的编码通用原则。栈相关的具体语法、工具链和约定请见 `spec_copilot/stack-adapters/<stack>.md`。
+
+## 1. 注释覆盖原则（强制，T1 起生效）
+
+不关心具体语法（Javadoc / docstring / JSDoc），关心**覆盖面**：
+
+- **数据模型字段**：每个字段必须有说明，枚举值必须列出所有合法值
+- **公共接口/方法**：必须说明用途、参数含义、返回值/副作用
+- **对外接口层（Controller/API handler）**：必须注释接口用途和关键参数含义
+- **UI 组件**：文件顶部说明组件职责，关键 props/events 必须注释
+- **非显而易见的字段/变量**：必须加注释（"显而易见"标准：读了命名 3 秒内能理解用途）
+
+具体语法规则 → 对应 stack adapter §1。
+
+## 2. 命名原则
+- 见名知意，避免缩写（`cfg` / `mgr` / `tmp` 等除非是领域通用缩写）
+- 方法/函数名以动词开头，描述行为
+- 常量全大写下划线分隔
+- **禁止拼音命名**（如 `fangshui` / `daima`）
+- **禁止中英混拼**（如 `sendXiaoxi` / `getUserXinxi`）
+- 模块/包/文件的命名风格保持全项目一致，不混用
+
+栈相关命名约定（大驼峰/小驼峰/蛇形）→ 对应 stack adapter §5。
+
+## 3. 魔法值（强制提取）
+
+**禁止在业务逻辑中直接写字符串/数字字面量**，必须提取为常量或枚举。
+
+判定标准：
+- 如果这个值在另一个文件里也出现过 → 一定要提取
+- 如果这个值代表一个状态/类型/分类 → 一定要提取
+- 单次出现的纯计算值（如 `* 100` 算百分比）可以不提取，但建议加注释说明含义
+
+违规示例（语言无关）：
+```
+// ❌ 裸字符串判断状态
+if (status == "OPEN") { ... }
+
+// ❌ 裸数字作为阈值
+if (retryCount > 3) { ... }
+
+// ✅ 提取为常量或枚举
+if (status == DefectStatus.OPEN) { ... }
+if (retryCount > MAX_RETRY_COUNT) { ... }
+```
+
+## 4. 异常处理原则
+
+- **业务异常**：使用自定义业务异常基类，携带错误码（便于前端区分业务错误类型）
+- **系统异常**：向上抛出，由统一异常处理器兜底
+- **禁止空 catch**（吞掉异常不记录、不处理、不转换）
+- **catch 中必须保留堆栈**：日志必须输出完整异常对象，禁止只打 `e.getMessage()` 丢失堆栈
+
+栈具体的异常基类名称和错误码约定 → 对应 stack adapter §2。
+
+## 5. 日志原则
+- **Controller/API 入口层**：INFO 级别，含请求关键参数
+- **异常**：ERROR 级别，含完整堆栈
+- **敏感信息脱敏**：详见 `spec_copilot/rules/security.md`
+
+栈具体的日志框架和语法 → 对应 stack adapter §3。
+
+## 6. 数据初始化规范
+- **测试/种子数据的日期字段必须使用相对时间**（如"当前时间减 N 天"），禁止写死静态日期
+- 原因：静态日期几个月后会失效，导致"近 N 日"类查询结果异常
+
+## 7. 单一职责
+- **禁止在同一个 task 里混入多个不相关的功能**（职责单一原则）
+- 一个类/一个方法只做一件事
+
+## 8. 安全相关
+→ 详见 `spec_copilot/rules/security.md`，本文件不重复安全条目。

package/framework/rules/domain-rules.md

@@ -0,0 +1,35 @@
+# 业务领域约束
+
+> 涉及业务逻辑时加载本规则。
+> 每个章节给出示例条目（`<!--` 包裹），替换为你的项目的实际规则后删掉示例。
+
+## 状态机
+
+> 列出核心业务实体的状态流转规则。格式：实体名 → 允许的状态流转 → 触发条件。
+
+<!-- 示例 -->
+- **订单**：待支付 → 已支付（支付成功回调）/ 已取消（超时 30min 或用户取消）
+- **订单**：已支付 → 已发货（仓库确认）/ 已退款（退款审核通过）
+- **订单**：已完成 = 终态，不可流转
+- **推送任务**：待发送 → 发送中 → 已送达 / 发送失败（可重试 3 次）
+<!-- 示例结束 -->
+
+## 计算口径
+
+> 列出关键业务指标的计算公式和口径定义。AI 写查询/统计逻辑时必须对齐。
+
+<!-- 示例 -->
+- **订单金额** = SUM(order_items.price * quantity) - 优惠券面额 + 运费，不含积分抵扣
+- **退款金额** = 订单实付 × (退货商品原价 / 订单商品总原价)，运费不退
+- **活跃用户**：近 30 天有任意操作（登录/下单/评论），排除标记为"测试账号"的用户
+<!-- 示例结束 -->
+
+## 业务流程
+
+> 描述核心业务流程的步骤和约束。每个流程列出参与者、步骤顺序、异常分支。
+
+<!-- 示例 -->
+- **用户注册**：填写手机号 → 验证码校验（60s 内有效，同号 1min 限发 1 次）→ 设置密码（8-20 位，含数字+字母）→ 创建用户 → 发欢迎推送
+- **定时推送**：Quartz 触发 → 查询待推送目标（分页 200 条/批）→ 逐批调用推送 SDK → 更新推送状态 → 批次间隔 100ms 防限流
+- **数据删除**：所有删除操作均为软删除（set deleted_at），不做物理删除；查询默认带 deleted_at IS NULL
+<!-- 示例结束 -->

package/framework/rules/project-context.md

@@ -0,0 +1,43 @@
+# 工程上下文
+
+> 本文件由 /spec:init 命令自动填充，描述当前项目的技术栈和结构。
+> 切换项目时重新执行 /spec:init 覆盖本文件。
+
+## 1. 应用概况
+- 应用名：
+- 简介：
+- 技术栈：
+- 构建工具：
+
+## 2. 目录结构
+
+## 3. 分层架构（后端）
+
+## 4. 关键依赖与版本
+| 中间件/框架 | 版本 | 用途 | 特别说明 |
+|------------|------|------|---------|
+
+## 5. 主键命名约定
+
+## 6. 数据初始化规范
+
+## 7. API 响应格式
+
+## 8. 本地启动
+```bash
+# 后端
+
+# 前端
+```
+
+## 9. 镜像与依赖源
+> 内网环境必填，公网项目可为空
+
+| 包管理器 | Registry/Mirror URL | 认证方式 | 配置文件路径 |
+|----------|-------------------|---------|-------------|
+| npm | | 无 / token / 密码 | .npmrc |
+| Maven | | 无 / 用户名密码 | settings.xml |
+| pip | | 无 / token | pip.conf |
+| Go | | 无 / 环境变量 | GOPROXY |
+
+> 注意：认证凭据不可写入配置文件，通过环境变量注入。配置文件（.npmrc/pip.conf/settings.xml）需加入 .gitignore。

package/framework/rules/security.md

@@ -0,0 +1,38 @@
+# 安全红线
+
+> 本文件是安全规则的**唯一来源**，其他文件（coding-style.md 等）不再重复安全条目。
+> 栈相关的具体实现方式（配置注入语法、依赖库选型）见 `spec_copilot/stack-adapters/<stack>.md` §4。
+
+## 1. 密钥与敏感信息（通用）
+- ❌ 禁止在代码中硬编码 API 密钥、AK/SK、数据库密码、第三方服务 Token
+- ❌ 禁止提交包含真实手机号、身份证、姓名等个人信息的测试数据
+- ❌ 禁止在日志中打印手机号、API Key、密码、Token 等敏感信息
+- ✅ 敏感字段必须脱敏或不打印：
+  - 手机号：`138****1234`（保留前 3 后 4）
+  - 邮箱：`a***@example.com`
+  - API Key / Token：`***`（不输出任何片段）
+  - 密码：完全不打印
+- ✅ 敏感配置必须通过配置文件（gitignore）注入 → 具体语法见对应 stack adapter §4
+
+## 2. 接口安全（通用）
+- ✅ 对外接口必须做参数非空/范围/格式校验
+- ❌ 禁止信任前端传入的任何值，服务端必须独立校验
+- ✅ 涉及权限的接口必须校验调用方身份，不能仅靠前端隐藏入口
+- ✅ 分页接口必须限制单页最大条数（防止恶意构造大 size 拖垮数据库）
+
+## 3. 业务安全（通用）
+- ⚠️ 涉及外部推送（短信/邮件/IM）的逻辑，必须在 spec 中明确推送范围，人工确认后方可编码
+- ⚠️ 推送前必须校验接收人信息完整性
+- ⚠️ 定时任务必须有幂等保护，防止重复执行
+- ⚠️ 写接口必须考虑幂等（尤其是推送、支付、扣款等有副作用的操作）
+- ⚠️ 批量操作接口必须有单次上限和频率限制
+
+## 4. 数据安全（通用）
+- ✅ 删除操作默认软删除（加 `deleted_at` 字段），物理删除需要明确业务理由
+- ✅ 涉及资金/关键业务数据的变更必须有操作审计日志（谁、何时、改了什么）
+- ❌ 禁止在公开日志/错误响应中泄露数据库表结构、堆栈中的内网 IP、敏感配置路径
+
+## 5. 依赖安全（通用）
+- ✅ 生产依赖必须锁定版本（不要用 `latest` / `^`）
+- ✅ 定期运行依赖漏洞扫描（`npm audit` / `mvn dependency-check` / `pip-audit`）
+- ⚠️ 引入新依赖前评估：官方/社区活跃度、最近维护时间、已知 CVE

package/framework/scripts/install-hooks.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# install-hooks.sh — 把 spec-lint.sh 安装为 Git pre-commit hook
+#
+# 用法：在项目根目录运行
+#   bash spec_copilot/scripts/install-hooks.sh
+
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+if [[ ! -d "$ROOT_DIR/.git" ]]; then
+  echo "✗ 未在 Git 仓库中（找不到 $ROOT_DIR/.git）"
+  exit 1
+fi
+
+HOOK_FILE="$ROOT_DIR/.git/hooks/pre-commit"
+
+if [[ -f "$HOOK_FILE" ]]; then
+  echo "⚠ 已存在 pre-commit hook，备份为 pre-commit.bak.$(date +%s)"
+  mv "$HOOK_FILE" "$HOOK_FILE.bak.$(date +%s)"
+fi
+
+cat > "$HOOK_FILE" <<'EOF'
+#!/usr/bin/env bash
+# spec_copilot pre-commit hook
+
+ROOT_DIR="$(git rev-parse --show-toplevel)"
+LINT="$ROOT_DIR/spec_copilot/scripts/spec-lint.sh"
+
+if [[ -x "$LINT" ]]; then
+  bash "$LINT" --hook
+fi
+EOF
+
+chmod +x "$HOOK_FILE"
+chmod +x "$SCRIPT_DIR/spec-lint.sh"
+
+echo "✓ pre-commit hook 已安装到 $HOOK_FILE"
+echo "  每次 commit 前会自动跑 spec-lint，检查 changes/ 下有改动的需求"
+echo "  如需跳过：git commit --no-verify"

package/framework/scripts/spec-gate.sh

@@ -0,0 +1,122 @@
+#!/bin/bash
+# spec-gate.sh — 阶段进入条件检查
+# Usage: spec-gate.sh <变更名> <phase>
+# Exit 0 = gate passed, exit 1 = gate failed (blocked)
+
+set -euo pipefail
+
+CHANGE="$1"
+PHASE="$2"
+CHANGE_DIR="spec_copilot/changes/${CHANGE}"
+
+die() { echo "GATE FAILED: $1"; exit 1; }
+ok()  { echo "  ✓ $1"; }
+
+[ -d "$CHANGE_DIR" ] || die "变更目录不存在: $CHANGE_DIR"
+
+SPEC="$CHANGE_DIR/spec.md"
+TASKS="$CHANGE_DIR/tasks.md"
+LOG="$CHANGE_DIR/log.md"
+
+case "$PHASE" in
+  apply)
+    echo "→ 门禁检查: apply 阶段"
+    [ -f "$SPEC" ] || die "spec.md 不存在 — 请先执行 /spec:propose"
+
+    # HARD-GATE: §9 待澄清必须为空
+    if grep -q '^[[:space:]]*- \[ \]' "$SPEC"; then
+      echo ""
+      echo "  §9 待澄清仍有未解决项:"
+      grep '^[[:space:]]*- \[ \]' "$SPEC" || true
+      die "HARD-GATE 未通过 — 待澄清全部解决后才能进入 /spec:apply"
+    fi
+    ok "§9 待澄清已清空"
+
+    # 检查复杂度并验证相应制品
+    if grep -q 'complexity:.*🔴' "$SPEC"; then
+      [ -f "$TASKS" ] || die "🔴 复杂需求需要 tasks.md — 请重新执行 /spec:propose 生成 tasks"
+      ok "tasks.md 已就绪（复杂需求）"
+
+      # 检查 tasks.md 是否有未完成项（但允许进行中的 task）
+      incomplete=$(grep -c '^\s*- \[ \]' "$TASKS" 2>/dev/null || true)
+      if [ "${incomplete:-0}" -gt 0 ]; then
+        echo "  ⚠ tasks.md 仍有 ${incomplete} 个未开始 task（AI 将逐 task 推进）"
+      fi
+    elif grep -q 'complexity:.*🟡' "$SPEC"; then
+      ok "中等需求，无需 tasks.md"
+    elif grep -q 'complexity:.*🟢' "$SPEC"; then
+      die "🟢 简单需求不应进入 apply 流程 — 直接在对话中编码"
+    fi
+
+    echo "GATE PASSED → 可以开始编码"
+    ;;
+
+  review)
+    echo "→ 门禁检查: review 阶段"
+    [ -f "$SPEC" ] || die "spec.md 不存在"
+
+    # 检查冒烟通过
+    if [ -f "$LOG" ]; then
+      if grep -qi '冒烟.*通过\|smoke.*pass\|编译.*0.*error' "$LOG"; then
+        ok "冒烟验证已通过"
+      else
+        die "log.md 中未找到冒烟通过记录 — 请先执行 /spec:smoke"
+      fi
+    else
+      die "log.md 不存在 — 请先执行 /spec:smoke"
+    fi
+
+    # 检查所有 task 已提交
+    if [ -f "$TASKS" ]; then
+      if grep -q '^\s*- \[ \]' "$TASKS" 2>/dev/null; then
+        echo "  ⚠ tasks.md 仍有未完成 task（可能影响审查完整性）"
+      fi
+    fi
+
+    echo "GATE PASSED → 可以开始审查"
+    ;;
+
+  archive)
+    echo "→ 门禁检查: archive 阶段"
+    [ -f "$SPEC" ] || die "spec.md 不存在"
+
+    # 检查审查通过
+    if grep -qi '结论.*通过\|审查.*通过' "$SPEC"; then
+      ok "审查结论: 通过"
+    elif grep -qi '结论.*需修复\|审查.*未通过\|审查.*✗' "$SPEC"; then
+      die "审查未通过 — 请先执行 /spec:fix 修复 Critical 问题"
+    else
+      die "spec.md 中未找到审查结论 — 请先执行 /spec:review"
+    fi
+
+    # 检查是否有未沉淀的知识发现
+    if [ -f "$LOG" ]; then
+      if grep -qi '知识发现\|knowledge\|#tip' "$LOG"; then
+        echo "  ℹ log.md 含知识发现，归档时将提示沉淀到 knowledge/"
+      fi
+    fi
+
+    echo "GATE PASSED → 可以归档"
+    ;;
+
+  test)
+    echo "→ 门禁检查: test 阶段"
+    [ -f "$SPEC" ] || die "spec.md 不存在"
+
+    # 🔴 复杂需求必须跑测试
+    if grep -q 'complexity:.*🔴' "$SPEC"; then
+      ok "🔴 复杂需求 — 强制执行自动化测试"
+    elif grep -q 'complexity:.*🟡' "$SPEC"; then
+      echo "  ℹ 🟡 中等需求 — 测试可选但推荐"
+    else
+      die "此阶段仅适用于 🔴 复杂需求"
+    fi
+
+    echo "GATE PASSED → 可以生成测试"
+    ;;
+
+  *)
+    echo "Usage: spec-gate.sh <变更名> <apply|review|archive|test>"
+    exit 1
+    ;;
+esac

package/framework/scripts/spec-lint.sh

@@ -0,0 +1,197 @@
+#!/usr/bin/env bash
+# spec-lint.sh — 检查 changes/<变更名>/ 下 spec/tasks/log 三件套的完整性
+#
+# 用法：
+#   ./scripts/spec-lint.sh <变更名>        检查指定需求
+#   ./scripts/spec-lint.sh --all           检查 changes/ 下所有进行中的需求
+#   ./scripts/spec-lint.sh --hook          作为 Git pre-commit hook 运行（仅检查有暂存改动的变更）
+#
+# 退出码：
+#   0  全部通过
+#   1  发现问题
+#   2  用法错误
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+CHANGES_DIR="$ROOT_DIR/changes"
+
+RED=$'\033[31m'
+YELLOW=$'\033[33m'
+GREEN=$'\033[32m'
+RESET=$'\033[0m'
+
+ERRORS=0
+WARNINGS=0
+
+log_err()  { echo "${RED}✗ ERROR${RESET}   $1"; ERRORS=$((ERRORS+1)); }
+log_warn() { echo "${YELLOW}⚠ WARN${RESET}    $1"; WARNINGS=$((WARNINGS+1)); }
+log_ok()   { echo "${GREEN}✓ OK${RESET}      $1"; }
+
+check_spec() {
+  local change_dir="$1"
+  local spec="$change_dir/spec.md"
+
+  if [[ ! -f "$spec" ]]; then
+    log_err "$spec 不存在"
+    return
+  fi
+
+  local required_sections=(
+    "## 1. 背景与目标"
+    "## 2. 代码现状"
+    "## 3. 功能点"
+    "## 4. 业务规则"
+    "## 9. 待澄清"
+    "## 13. 确认记录"
+  )
+
+  for section in "${required_sections[@]}"; do
+    if ! grep -q "^${section}" "$spec"; then
+      log_err "$spec 缺少章节：$section"
+    fi
+  done
+
+  if ! grep -qE "^> status: (propose|apply|review|done)" "$spec"; then
+    log_err "$spec 缺少 status 字段或值非法"
+  fi
+
+  if ! grep -qE "^> complexity:" "$spec"; then
+    log_err "$spec 缺少 complexity 字段"
+  fi
+
+  local status
+  status=$(grep -oE "status: (propose|apply|review|done)" "$spec" | awk '{print $2}' | head -1)
+  if [[ "$status" == "apply" || "$status" == "review" || "$status" == "done" ]]; then
+    if awk '/^## 9\./,/^## 10\./' "$spec" | grep -qE "^- \[ \]"; then
+      log_err "$spec status=$status 但 §9 待澄清仍有未勾选项"
+    fi
+  fi
+}
+
+check_tasks() {
+  local change_dir="$1"
+  local tasks="$change_dir/tasks.md"
+  local spec="$change_dir/spec.md"
+
+  if [[ -f "$spec" ]] && grep -q "complexity:.*🔴" "$spec"; then
+    if [[ ! -f "$tasks" ]]; then
+      log_err "$change_dir 是 🔴 复杂需求但缺少 tasks.md"
+      return
+    fi
+  elif [[ ! -f "$tasks" ]]; then
+    log_ok "$change_dir 非 🔴 复杂需求，tasks.md 可选"
+    return
+  fi
+
+  if ! grep -q "^## 前置条件" "$tasks"; then
+    log_err "$tasks 缺少 ## 前置条件 章节"
+  fi
+
+  if ! grep -qE "^## Task [0-9]+" "$tasks"; then
+    log_err "$tasks 没有任何 Task"
+  fi
+
+  if grep -qE "^## Task [0-9]+" "$tasks"; then
+    local tc vc
+    tc=$(grep -cE "^## Task [0-9]+" "$tasks" 2>/dev/null); tc=${tc:-0}
+    vc=$(grep -c "验证命令" "$tasks" 2>/dev/null); vc=${vc:-0}
+    if [[ "${vc:-0}" -lt "${tc:-0}" ]]; then
+      log_warn "$tasks 部分 Task 可能缺少'验证命令'（${vc}/${tc}）"
+    fi
+  fi
+
+  if [[ -f "$spec" ]] && grep -qE "status: (review|done)" "$spec"; then
+    if ! grep -q "^## 变更摘要" "$tasks"; then
+      log_err "$tasks status 已进入 review/done 但缺少'变更摘要'章节"
+    fi
+  fi
+}
+
+check_log() {
+  local change_dir="$1"
+  local log="$change_dir/log.md"
+
+  if [[ ! -f "$log" ]]; then
+    log_err "$log 不存在"
+    return
+  fi
+
+  local required=(
+    "## 时间线"
+    "## 知识发现"
+    "## Spec-Code 偏差记录"
+  )
+
+  for section in "${required[@]}"; do
+    if ! grep -q "^${section}" "$log"; then
+      log_err "$log 缺少章节：$section"
+    fi
+  done
+}
+
+check_change() {
+  local change_name="$1"
+  local change_dir="$CHANGES_DIR/$change_name"
+
+  echo ""
+  echo "▶ 检查 $change_name"
+
+  if [[ ! -d "$change_dir" ]]; then
+    log_err "目录不存在：$change_dir"
+    return
+  fi
+
+  check_spec "$change_dir"
+  check_tasks "$change_dir"
+  check_log "$change_dir"
+}
+
+case "${1:-}" in
+  --all)
+    for dir in "$CHANGES_DIR"/*/; do
+      name=$(basename "$dir")
+      [[ "$name" == "templates" ]] && continue
+      check_change "$name"
+    done
+    ;;
+  --hook)
+    if ! staged=$(git diff --cached --name-only 2>/dev/null); then
+      echo "不在 Git 仓库，跳过 hook 检查"
+      exit 0
+    fi
+    changes=$(echo "$staged" | grep -oE "spec_copilot/changes/[^/]+" | sort -u | sed 's|spec_copilot/changes/||')
+    if [[ -z "$changes" ]]; then
+      exit 0
+    fi
+    for name in $changes; do
+      [[ "$name" == "templates" ]] && continue
+      check_change "$name"
+    done
+    ;;
+  "")
+    echo "用法：$0 <变更名> | --all | --hook"
+    exit 2
+    ;;
+  -*)
+    echo "未知参数：$1"
+    exit 2
+    ;;
+  *)
+    check_change "$1"
+    ;;
+esac
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+if [[ $ERRORS -eq 0 && $WARNINGS -eq 0 ]]; then
+  echo "${GREEN}全部通过${RESET}"
+  exit 0
+elif [[ $ERRORS -eq 0 ]]; then
+  echo "${YELLOW}$WARNINGS 个警告（不阻塞）${RESET}"
+  exit 0
+else
+  echo "${RED}$ERRORS 个错误 / $WARNINGS 个警告${RESET}"
+  exit 1
+fi

package/framework/stack-adapters/_template.md

@@ -0,0 +1,70 @@
+# {{技术栈名称}} 适配层
+
+> 本文件是某个技术栈的具体规范补充。通用原则见 `spec_copilot/rules/coding-style.md`。
+
+## 1. 注释规范
+> 对应 `rules/coding-style.md` §1。列出本栈的文档注释语法、工具链、覆盖要求。
+
+- 类/函数/方法注释语法：
+- 字段/属性注释语法：
+- 工具链（生成器、lint 规则）：
+
+## 2. 异常处理
+> 对应 `rules/coding-style.md` §4。
+
+- 自定义业务异常基类：
+- 错误码约定：
+- 统一异常处理器：
+
+## 3. 日志规范
+> 对应 `rules/coding-style.md` §5。
+
+- 日志框架：
+- 日志级别使用约定：
+- 脱敏方式：
+
+## 4. 配置注入
+> 对应 `rules/security.md` §1。敏感配置如何通过配置文件注入。
+
+- 配置文件命名和位置：
+- 注入方式：
+- gitignore 条目：
+
+## 5. 命名约定
+- 类/类型名：
+- 方法/函数名：
+- 常量：
+- 文件名：
+
+## 6. 分层架构
+```
+{{分层调用关系，如 Controller → Service → Repository}}
+```
+
+## 7. 前端特有（如适用）
+- 状态管理：
+- 路由组织：
+- 样式组织：
+- API 调用封装位置：
+- 组件命名和文件组织：
+
+## 8. 测试规范
+- 单元测试框架：
+- 集成测试方式：
+- 测试文件命名和位置：
+- 覆盖率工具：
+
+## 9. 常见坑与注意事项
+> 这个栈特有的、容易踩的坑。随着知识积累持续更新。
+
+## 10. code-quality-reviewer 栈相关检查项
+> 本栈专属的 review 规则，会被 /spec:review 阶段二读取。
+
+### Critical
+- [ ]
+
+### Important
+- [ ]
+
+### Minor
+- [ ]