From 82b3eaa90c88c17c6cdc93706bb8b23a4d0b3ef0 Mon Sep 17 00:00:00 2001
From: zichun <zhuzichunhogan@gmail.com>
Date: Thu, 28 May 2026 15:34:38 +0800
Subject: [PATCH] templates: move per-section LLM guidance from template comments into the consuming SKILL.md

---
 skills/plan/frontend-scope-lock/templates/fe-scope-template.md   | 12 ------------
 skills/plan/project-init/templates/docs-08-initial-template.md   | 17 -----------------
 skills/plan/scope-lock/templates/config-vars-template.yaml       | 13 ++-----------
 skills/plan/scope-lock/templates/req-card-template.md            | 26 +++-----------------------
 skills/plan/skeleton-gen/templates/docs-04-skeleton-template.md  | 28 ----------------------------
 skills/plan/skeleton-gen/templates/docs-06-static-template.md    | 20 --------------------
 skills/plan/skeleton-gen/templates/docs-07-env-template.md       | 15 ---------------
 skills/plan/skeleton-gen/templates/docs-09-structure-template.md | 19 -------------------
 8 files changed, 5 insertions(+), 145 deletions(-)

diff --git a/skills/plan/frontend-scope-lock/templates/fe-scope-template.md b/skills/plan/frontend-scope-lock/templates/fe-scope-template.md
index bb8bd6a..e5b7c09 100644
--- a/skills/plan/frontend-scope-lock/templates/fe-scope-template.md
+++ b/skills/plan/frontend-scope-lock/templates/fe-scope-template.md
@@ -1,15 +1,3 @@
-<!--
-fe-scope-template：A6 frontend-scope-lock 的产出骨架。
-本模板被 frontend-scope-lock 填充后写入两处：
-  - § 一 ~ § 三（UI 约定 / Design Tokens / 组件库）→ 写入 docs/06-UI交互规范.md（合并进 § 一/§ 二/§ 四 对应小节，不另起文件）
-  - § 四（前端栈摘要）→ 写入 docs/04-技术规范.md § 二（前端编码规范）的引用说明
-  - § 五（每个 FE-NN 设计决策表）→ 写入 docs/06 § 三 之后，作为 FE 级设计契约
-渲染约定：
-1) 所有 {{占位符}} 必须由 frontend-scope-lock 用「从 prototype + docs/01 + docs/05/06 提炼并经 AskUserQuestion 确认」的真实值替换。
-   不允许留 {{...}} 占位，也不允许留示例值——留占位/示例即视为 A6 未完成。
-2) § 五 的 FE-NN 行数 = docs/08 § 三 推导出的 FE 清单条目数，一 FE 一行。
-3) 渲染后这段 HTML 注释要剥掉，不进入最终文档。
--->
 ## 一、项目级 UI 约定
 
 > 来源：prototype/*.html 实测 + docs/01 REQ 卡片 UI 描述 + docs/06 已有布局。经用户确认。
diff --git a/skills/plan/project-init/templates/docs-08-initial-template.md b/skills/plan/project-init/templates/docs-08-initial-template.md
index 61fc530..eed4e6f 100644
--- a/skills/plan/project-init/templates/docs-08-initial-template.md
+++ b/skills/plan/project-init/templates/docs-08-initial-template.md
@@ -51,26 +51,9 @@
 
 （A5 填入后，每行一个后端模块。每个模块的 `里程碑:` 字段在 `—` 和 `milestone/<id>` 之间变化，完成由本地 `git tag -l` 判定。`coding-start` 每次按 docs/02 REQ 序扫每模块的里程碑 tag 决定派发。后端模块全部打里程碑后自动进入 § 三 前端阶段。）
 
-<!-- 模块格式示例（由 A5 downstream-gen 追加；功能子项由 coding.mjs 的 review stage 在 approve 时勾选）：
-- module_sys 系统管理
-  - 依赖: —
-  - 路径: backend/module/sys/
-  - 里程碑: —
-  - 功能:
-    - [ ] REQ-SYS-001 用户登录
-    - [ ] REQ-SYS-002 用户注册
--->
-
 ## 三、Coding 阶段（前端整体）
 
 （FE 业务功能清单在 Plan 期 A6 `frontend-scope-lock` 由 prototype/ + docs/01 + docs/05 推导后写入下方"功能:"项；Coding 阶段 `coding.mjs` 的 Router 把全部未完成 FE 聚合为单一 `frontend-phase` 阶段，排在所有后端模块之后。整个前端阶段 1 个里程碑 tag，分支 `frontend-phase`。）
 
 - 整体里程碑: —
 - 功能:
-  <!-- AI 进入时按以下行格式写入（每行 1 个 FE，可关联多个 REQ / 多份原型）：
-  - [ ] FE-NN 功能名 ｜ 关联 REQ：REQ-A, REQ-B ｜ 关联原型：prototype/<file>.html, prototype/<other>.html
-
-  示例：
-  - [ ] FE-01 用户登录与注册 ｜ 关联 REQ：REQ-SYS-001, REQ-SYS-002 ｜ 关联原型：prototype/auth.html
-  - [ ] FE-02 仪表盘总览 ｜ 关联 REQ：REQ-DASH-001 ｜ 关联原型：prototype/dashboard.html
-  -->
diff --git a/skills/plan/scope-lock/templates/config-vars-template.yaml b/skills/plan/scope-lock/templates/config-vars-template.yaml
index f986f4e..6711bce 100644
--- a/skills/plan/scope-lock/templates/config-vars-template.yaml
+++ b/skills/plan/scope-lock/templates/config-vars-template.yaml
@@ -1,12 +1,5 @@
-# config-vars.yaml — 项目配置清单
-#
-# 用途：登记「需人工提供 / 确认」的非敏感、项目级配置（根包名、应用端口、前端包名、初始账号等）。
-#       YAML 分组，逐项填写与核对一目了然。
-# 规则：命名约定 / 端口约定 / 安全要求统一写在 docs/07-环境配置.md，本文件只放值、不重复写规则。
-# 边界：
-#   - 机器 / 环境相关的连接信息（DB_HOST / DB_PORT / DB_USER / DB_SCHEMA 等）→ 仓库根 .env.local，不写在此。
-#   - 敏感凭据（密码 / 密钥 / token）→ .env.local；本文件 secrets_ref 只登记键名供核对，绝不写真实值。
-# 填写：A1 scope-lock 按 docs/04 § 零 技术栈推断默认值填入；无对应技术栈的整节删除；无法推断的留 【人工填写：…】（A2 skeleton-gen 补填）。
+# config-vars.yaml — non-sensitive project config; rules live in docs/07.
+# Sensitive values go in .env.local; only list key names under secrets_ref.
 
 backend:
   base_package: 【人工填写：后端根包名 / 命名空间，如 com.acme.erp】
@@ -20,8 +13,6 @@ admin_init:
   username: 【人工填写：超级管理员初始账号，如 admin】
   # 初始密码属敏感 → 见 .env.local 的 ADMIN_INIT_PASSWORD
 
-# 敏感值引用：真实值在 .env.local，此处只登记「键名 + 含义」，供 A2 skeleton-gen 核对 .env.local 是否齐全。
-# 按技术栈增删行（注释行表示可选，按需取消注释）。
 secrets_ref:
   - DB_PASSWORD            # 数据库密码
   - JWT_SECRET             # JWT / 令牌签名密钥
diff --git a/skills/plan/scope-lock/templates/req-card-template.md b/skills/plan/scope-lock/templates/req-card-template.md
index 1b88515..667f364 100644
--- a/skills/plan/scope-lock/templates/req-card-template.md
+++ b/skills/plan/scope-lock/templates/req-card-template.md
@@ -1,25 +1,5 @@
 <!--
-req-card-template：单张 REQ 卡片骨架。每张卡片是 docs/01-需求清单/<module>/REQ-XXX-NNN.md 一个独立文件。
-
-渲染约定：
-1) scope-lock 渲染时替换 6 个占位符：{{req_id}} / {{title}} / {{goal}} / {{rules}} / {{constraints}} / {{acceptance}}
-   这 6 项由 CC 根据 docs/01-需求清单/index.md 的「核心功能点」推断起草：
-     - req_id / title：从核心功能点拆分命名得来
-     - goal：用一句话展开 title
-     - rules / constraints / acceptance：业务语义层面的合理起草，待人工审阅修订
-2) `**输入字段**` / `**输出字段**` 为**结构化字段表**：每个字段一行，6 列固定结构
-   （字段名 | 类型 | 必填 | 校验规则 | 业务规则 | 示例值）。
-   模板内每张表给出一行示例行，列首注明 `【示例行，替换为真实字段】`。
-   人工拿到卡片后按本 REQ 实际业务**逐行替换为真实字段 / 增删行**：
-     - 字段名：本 REQ 真实的输入 / 输出字段
-     - 类型：真实数据类型（文本 / 整数 / 金额 / 日期 / 布尔 / 枚举 / …）
-     - 必填：是 / 否
-     - 校验规则：长度 / 格式 / 范围 / 唯一性等可验证约束（如「3-20 位字母数字下划线；系统内唯一」）
-     - 业务规则：该字段的业务含义 / 来源 / 默认值 / 联动逻辑
-     - 示例值：一个真实约束下的合法取值
-3) **「示例值」列必须替换为真实约束下的取值。留模板默认占位（`【示例行，替换为真实字段】` 或 `<示例值>`）即视为该 REQ 卡片未完成，A1 终结校验会阻断进入下一阶段。**
-4) `**依赖表**: TBD(A3 自动补)` 和 `**依赖接口**: TBD(A5 自动补)` 是后续 skill 自动回填的占位，渲染时**保持原样**，不要替换为 `-` 也不要替换为 `{{...}}`
-5) 渲染后这段 HTML 注释要**剥掉**，不进入最终卡片（lib/render.mjs 自动剥离）
+req-card-template：单张 REQ 卡片骨架。两处 `TBD(A3 自动补)` / `TBD(A5 自动补)` 须保持原样。
 -->
 ### {{req_id}} {{title}}
 
@@ -29,13 +9,13 @@ req-card-template：单张 REQ 卡片骨架。每张卡片是 docs/01-需求清�
 
 | 字段名 | 类型 | 必填 | 校验规则 | 业务规则 | 示例值 |
 | --- | --- | --- | --- | --- | --- |
-| 【示例行，替换为真实字段】 | 文本 | 是 | 3-20 位字母数字下划线；系统内唯一 | 用户登录账号，系统内唯一标识 | <示例值> |
+| {{input_field_name}} | {{input_field_type}} | {{input_field_required}} | {{input_field_validation}} | {{input_field_business}} | {{input_field_example}} |
 
 **输出字段**:
 
 | 字段名 | 类型 | 必填 | 校验规则 | 业务规则 | 示例值 |
 | --- | --- | --- | --- | --- | --- |
-| 【示例行，替换为真实字段】 | 整数 | 是 | 大于 0 | 新建记录的主键 id | <示例值> |
+| {{output_field_name}} | {{output_field_type}} | {{output_field_required}} | {{output_field_validation}} | {{output_field_business}} | {{output_field_example}} |
 
 - **跨字段规则**: {{rules}}
 - **边界**: {{constraints}}
diff --git a/skills/plan/skeleton-gen/templates/docs-04-skeleton-template.md b/skills/plan/skeleton-gen/templates/docs-04-skeleton-template.md
index 7f2c116..37484e1 100644
--- a/skills/plan/skeleton-gen/templates/docs-04-skeleton-template.md
+++ b/skills/plan/skeleton-gen/templates/docs-04-skeleton-template.md
@@ -1,54 +1,31 @@
-<!--
-本文件是 docs/04-技术规范.md 的 § 一+ 大纲。
-skeleton-gen 读取 docs/04 § 零（技术栈表）和 docs/01-需求清单/index.md（模块索引），
-按下述大纲生成本项目专属的规范内容。LLM 不要原样拷贝提示文字，只保留 section 标题。
--->
-
 ## 一、后端规范
 
 ### 1.1 规则
-<!-- 后端通用约定：保留下方占位符不要代填，由人工在 skeleton-gen § E 填写；每条一个 bullet，按需复制本行新增更多。 -->
 - 【人工填写：一条后端通用约定，按需复制本行新增更多；无则填「无」】
 
 ### 1.2 分层结构
-<!-- 按 § 零 的后端框架定层次：controller/service/mapper 等；每层职责一句话。 -->
 
 ### 1.3 命名约定
-<!-- 包名（根包用【人工填写：根包名】占位）/ 类名 / 方法名 / 常量的大小写规则，含 2 个示例。 -->
 
 ### 1.4 统一响应格式
-<!-- 成功/失败的 JSON 结构，错误码段位划分。 -->
 
 ### 1.5 异常处理
-<!-- 全局异常处理器的使用方式；哪些异常要 catch，哪些禁止；**接口响应禁止回显后端异常堆栈**（返用户友好错误码 + 文案）。 -->
 
 ### 1.6 事务
-<!-- 事务边界（通常 service 层）；跨服务调用的禁止/替代方案。 -->
 
 ### 1.7 认证
-<!-- 基于 § 零 认证方案推导：token 生命周期、刷新机制、密钥管理。 -->
 
 ## 二、前端规范
 
 ### 2.1 目录约定
-<!-- 基于 § 零 前端框架推导：api/components/pages/store/hooks/utils 的职责；**前端禁止直接写 SQL / 操作 DB**，所有数据访问走 api/ 层统一封装。 -->
 
 ### 2.2 状态管理
-<!-- 基于 § 零 状态管理技术推导：全局 vs 局部、服务端数据的存放。 -->
 
 ### 2.3 请求封装
-<!-- HTTP 客户端的拦截器、超时、错误重试、鉴权注入。 -->
 
 ### 2.4 错误处理
-<!-- 网络错误 / 业务错误 / 页面级错误的分层处理。 -->
 
 ### 2.5 样式与主题
-<!-- 基于 § 零 UI 库给出 CSS 变量约定：
-     - 命名格式 `--color-<scope>-<role>-<state>`（scope=form/table-row/...，role=bg/fg/border，state=edit/readonly/hover/selected）
-     - 文件位置 `src/styles/tokens.css`，由 skeleton-gen 生成空骨架，色值由 docs/06 § 四锁定后填入
-     - 组件样式中只用 var(--color-xxx)，禁止硬编码 hex/rgba
-     - 与 UI 库主题对接（如 Ant Design ConfigProvider.theme.token）的映射方式
-     具体 token 表见 docs/06 § 四。 -->
 
 ## 三、共同约定
 
@@ -56,14 +33,9 @@ skeleton-gen 读取 docs/04 § 零（技术栈表）和 docs/01-需求清单/ind
 `<type>(<scope>): <subject> REQ-XXX-NNN`
 
 ### 3.2 分页查询
-<!-- 后端分页对象 + 前端分页组件，入参出参约定。 -->
 
 ### 3.3 日期与金额
-<!-- 后端类型（如 LocalDateTime / BigDecimal）+ 前端展示工具；金额精度约定。 -->
 
 ### 3.4 数据访问规约
-<!-- 基于 § 零 数据访问技术（MyBatis-Plus / JPA 等）：SELECT 字段显式列举，**禁止 `SELECT *`**；循环中不得执行 DB 查询（**N+1 反模式**），改用批量查 / IN 子句 / JOIN；Mapper XML 里字段与表名用常量或引用，避免拼字符串。 -->
 
 ### 3.5 配置与安全
-<!-- 配置：DB 连接 / 端口 / 密钥 / 第三方 URL 等一律放 `application.yml` + `.env.local`，代码里**禁止硬编码**。
-     前端安全：`localStorage` 不存敏感信息（token / 身份 / 个人数据），推荐 HttpOnly Cookie 或 内存 + 刷新 token 模式；接口响应禁止回显后端异常堆栈（与 § 1.5 一致）。 -->
diff --git a/skills/plan/skeleton-gen/templates/docs-06-static-template.md b/skills/plan/skeleton-gen/templates/docs-06-static-template.md
index 21dd358..be8db0c 100644
--- a/skills/plan/skeleton-gen/templates/docs-06-static-template.md
+++ b/skills/plan/skeleton-gen/templates/docs-06-static-template.md
@@ -1,9 +1,3 @@
-<!--
-本文件是 docs/06-UI交互规范.md 的 § 一 ~ 三 大纲（§ 三页面清单由 downstream-gen 按模块追加；FE 决策表由 A6 frontend-scope-lock 追加到 § 三之后）。
-skeleton-gen 读取 docs/04 § 零 和 docs/01 index，按下述大纲生成项目专属内容。
-布局/页面骨架以项目根的 prototype/ 静态 HTML mockup 为权威，本文件仅承载跨页面通用规则与 Design Tokens。
--->
-
 # 06-UI交互规范
 
 > 本项目所有页面布局以项目根 `prototype/` 目录下的静态 HTML mockup 为权威。前端阶段实现时直接以 prototype/ HTML 推导组件树与样式。本文件仅承载跨页面通用规则与 Design Tokens。
@@ -11,32 +5,18 @@ skeleton-gen 读取 docs/04 § 零 和 docs/01 index，按下述大纲生成项�
 ## 一、通用交互规则
 
 ### 1.1 操作反馈
-<!-- 成功/失败消息；危险操作二次确认；长耗时按钮 loading 态。 -->
 
 ### 1.2 数据展示
-<!-- 空状态 / 加载 / 异常 的统一组件与文案。 -->
 
 ### 1.3 权限控制（前端）
-<!-- 菜单级 / 按钮级 / 路由级的控制方式，关联后端 RBAC。 -->
 
 ## 二、Design Tokens
 
-<!-- 所有色值统一以 CSS 变量定义于 src/styles/tokens.css；命名规范见 docs/04 § 2.5。 -->
-
 ### 2.1 全局调色板
-<!-- 与 § 零 UI 库主题对齐：列名 = 语义 / 变量名 / 默认值 / 用途。
-     至少含：主色/成功/警告/错误/主文字/次文字/边框/背景。 -->
 
 ### 2.2 组件级状态色
-<!-- 场景 × 状态映射表：列名 = 序号 / 组件 / 编辑bg / 只读bg / 悬浮bg / 编辑fg / 只读fg / 悬浮fg / 备注。
-     单元格写 token 名（var(--color-xxx) 形式），不写 hex；"—" 表示该状态不适用。
-     表后追加「Token 默认值」表，列出每个 --color-xxx 在 tokens.css 的默认值。 -->
 
 ### 2.3 引用约定
-<!-- 一句话三条：
-     - 组件样式只用 var(--color-xxx)，禁止硬编码
-     - 新增 token 须先登记到 § 2.1/2.2 再补 tokens.css
-     - 修改色值只改 tokens.css 一处，不允许组件覆盖 -->
 
 ## 三、页面清单
 （由 `downstream-gen` 按模块追加段落）
diff --git a/skills/plan/skeleton-gen/templates/docs-07-env-template.md b/skills/plan/skeleton-gen/templates/docs-07-env-template.md
index bc246c9..2a3da65 100644
--- a/skills/plan/skeleton-gen/templates/docs-07-env-template.md
+++ b/skills/plan/skeleton-gen/templates/docs-07-env-template.md
@@ -1,22 +1,9 @@
-<!--
-本文件是 docs/07-环境配置.md 的大纲。
-docs/07 只记规则与约定，不记具体配置值——端口 / 包名 / 库名等真实值在 config-vars.yaml（A1 锁定）与 .env.local（敏感）。
-skeleton-gen 基于 docs/04 § 零 技术栈表推导各节内容：
-  § 一 依赖清单 → 从技术栈的每一行技术推导运行时和构建依赖
-  § 二 端口约定 → 从后端/前端/数据库/缓存/反向代理 各取默认端口（约定值；项目实际采用值记在 config-vars.yaml）
-  § 四 常用命令 → 基于构建工具、包管理器给出开发者最常用命令
--->
-
 # 07-环境配置
 
 ## 一、依赖清单
 
-<!-- 表格：| 层 | 依赖 | 版本 | 说明 |；覆盖 运行时 / 构建 / 容器 / CLI 工具。 -->
-
 ## 二、端口约定
 
-<!-- 表格：| 服务 | 端口 | 说明 |；至少列 后端 HTTP / 前端 dev / 数据库 / 缓存 / 反代。这里给默认约定值；项目实际采用的端口记在 config-vars.yaml。 -->
-
 ## 三、配置与凭据规则
 
 项目配置分两处存放，**本文档只记规则、不记具体值**：
@@ -30,5 +17,3 @@ skeleton-gen 基于 docs/04 § 零 技术栈表推导各节内容：
 - 任何敏感值不得出现在 `config-vars.yaml`、docs、源码或日志中——只允许出现在 `.env.local`。
 
 ## 四、常用命令
-
-<!-- 表格：| 命令 | 说明 |；包含 启动后端 / 启动前端 / 打包 / 运行测试 / 重置测试数据。 -->
diff --git a/skills/plan/skeleton-gen/templates/docs-09-structure-template.md b/skills/plan/skeleton-gen/templates/docs-09-structure-template.md
index d913c08..20a5e3c 100644
--- a/skills/plan/skeleton-gen/templates/docs-09-structure-template.md
+++ b/skills/plan/skeleton-gen/templates/docs-09-structure-template.md
@@ -1,28 +1,11 @@
-<!--
-本文件是 docs/09-项目目录结构.md 的大纲。
-skeleton-gen 基于 docs/04 § 零 技术栈推导目录树：
-  § 二 后端目录 → 按后端框架的惯例（如 Spring Boot 的 src/main/java）
-  § 三 前端目录 → 按前端框架的惯例（如 Vite + React 的 src/）
-  § 四 docs 目录 → 沿用插件标准
-  § 五 命名约定 → 按后端语言的包/命名空间习惯
-
-模块划分参考 docs/01-需求清单/index.md 的模块索引，将业务模块落到代码目录。
--->
-
 # 09-项目目录结构
 
 ## 一、仓库顶层
 
-<!-- 用代码块画出顶层目录树，含 CLAUDE.md / README.md / .env.local / scripts / docs / sql / backend / frontend 等。 -->
-
 ## 二、后端目录
 
-<!-- 基于后端框架的目录树；按 docs/01 index 的模块代码把业务模块列出（module/user/、module/order/ 等）。 -->
-
 ## 三、前端目录
 
-<!-- 基于前端框架的目录树；pages/ 下按业务模块建子目录。 -->
-
 ## 四、docs/ 结构
 
 ```
@@ -41,5 +24,3 @@ docs/
 ```
 
 ## 五、命名与放置约定
-
-<!-- 根包 / 命名空间用【人工填写：】占位；Controller / Service / Mapper / DTO / VO / 前端组件 / 前端页面 的放置规则。 -->
--
libgit2 0.22.2