feat(template): ADR-013 Skill 替代脚本 — 框架脱敏/初始化机制重构

- 废弃 ADR-008 双分支+shell脚本方案（ai_project分支已过时） - 新增 project-init Skill：export（脱敏导出） + init（初始化新项目）双模式 - 保留 SYNC.md（框架/项目边界）+ TEMPLATE.yaml（变量定义） - L-006: 当 AI 是执行者时，Skill 优于 Shell 脚本 - 3 文件替代 4文件+1分支，零维护成本 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-26 15:33:05 +08:00
parent 6992f59cd2
commit 473f61b4cc
6 changed files with 282 additions and 7 deletions
@@ -59,18 +59,38 @@
 ## ADR-008: 框架/项目双分支 + 同步机制

 - 日期: 2026-05-25
- 状态: 已采纳
- 决策: 采用双分支策略：`main` 分支开发具体项目（ErrLens），`ai_project` 分支保持为去敏的通用模板。通过 `sync-template.sh` 从 main 单向同步框架层变化到模板分支
- 理由:
+- 状态: 已废弃（被 ADR-013 替代，2026-05-26）
+- 决策: ~~采用双分支策略：`main` 分支开发具体项目（ErrLens），`ai_project` 分支保持为去敏的通用模板。通过 `sync-template.sh` 从 main 单向同步框架层变化到模板分支~~ 废弃原因：双分支维护成本高，容易过时。ai_project 分支在新架构升级后已严重落后于 main
+- 理由（原）:
  - 框架层变化需要传播到模板，但重做去敏化消耗巨大（~100K tokens）
  - 两个分支的差异本质是"变量替换"，可以脚本自动化
  - 框架层（AGENTS/权限/提示词/工作流）和项目层（任务/日志/代码）的边界清晰
- 影响:
-  - 新增 `SYNC.md` 定义框架层/项目层边界
-  - 新增 `sync-template.sh` 实现自动同步
-  - 新增 `TEMPLATE.yaml` + `init.sh` 实现一键初始化
+- 影响（原）:
+  - 新增 `SYNC.md` 定义框架层/项目层边界（保留，被 ADR-013 复用）
+  - 新增 `sync-template.sh` 实现自动同步（已删除）
+  - 新增 `TEMPLATE.yaml` + `init.sh` 实现一键初始化（TEMPLATE.yaml 保留，init.sh 删除）
  - AI 项目框架从此可复用，token 节省 95%+

+## ADR-013: Skill 替代脚本 — 框架脱敏/初始化的正确方式
+
+- 日期: 2026-05-26
+- 状态: 已采纳
+- 决策: 废弃 ADR-008 的「双分支 + shell 脚本」方案，改为「Skill + 配置文件」方案。框架脱敏和项目初始化由 `project-init` Skill 按需执行，不再维护独立模板分支
+- 理由:
+  - **双分支方案的问题已被验证**：ADR-008 的 ai_project 分支在新架构升级（dashboard.md / .ai/tasks/ / 归档）后严重过时，SYNC.md 和 sync-template.sh 的文件清单全是旧结构引用
+  - **AI 是执行者，不需要可执行脚本**：shell 脚本是给人类或 CI 用的。但当前场景中，脱敏/初始化是由 AI（Claude Code）执行的——AI 需要的是清晰的规格说明（SYNC.md + TEMPLATE.yaml + Skill 指令），而不是可执行脚本
+  - **Skill 方案不过时**：脚本写死了文件列表，框架一变脚本就过时。Skill 描述的是「方法」——读 SYNC.md 获取边界 → 读 TEMPLATE.yaml 获取变量 → 执行替换。框架变化时只需更新 SYNC.md，Skill 本身不变
+  - **零维护成本**：不再需要 sync-template.sh、init.sh、独立 Git 分支。3 个文件（SYNC.md + TEMPLATE.yaml + Skill）vs 旧方案的 4 个文件 + 1 个分支
+- 关键洞察:
+  - **「脚本优于 Skill」的前提是执行者是机器**。当执行者是 AI 时，Skill（语义描述 + 约束）优于脚本（硬编码文件列表）
+  - **边界定义文件（SYNC.md）是长期资产**，脚本是短期负债——脚本依赖边界定义，但边界定义不应绑定于特定的执行方式
+- 影响:
+  - 保留 `SYNC.md`（更新为新架构文件结构）
+  - 保留 `TEMPLATE.yaml`（变量定义）
+  - 新增 `.trae/skills/project-init/SKILL.md`
+  - 废弃 `sync-template.sh`、`init.sh`
+  - 废弃 `ai_project` 分支（不再维护，仅保留历史参考）
+
 ## ADR-009: 人机协同数据质量闭环

 - 日期: 2026-05-26
@@ -31,6 +31,14 @@
 - [x] `.ai/principles.md` 新增「Arch AI 上下文资源管理」硬约束
 - [x] L-005: 上下文窗口是硬约束——盲目冲刺 = 带残缺记忆做决策

+### 模板机制重构（ADR-013）
+- [x] 废弃 ADR-008 的「双分支 + shell 脚本」方案
+- [x] ADR-013: Skill 替代脚本——project-init Skill 按需执行脱敏/初始化
+- [x] 保留 SYNC.md（更新为新架构）、保留 TEMPLATE.yaml（变量定义）
+- [x] 新增 project-init Skill（export + init 双模式）
+- [x] L-006: 当 AI 是执行者时，Skill 优于 Shell 脚本
+- [x] 废弃 sync-template.sh、init.sh、ai_project 分支
+
 ### 知识库变更汇总

 | 文件 | 新增 |
@@ -72,6 +72,26 @@

 ---

+## L-006: 当 AI 是执行者时，Skill 优于 Shell 脚本
+
+**日期**: 2026-05-26
+**上下文**: ADR-008 的「双分支 + sync-template.sh」模板同步方案，在新架构升级后 ai_project 分支严重过时。用户要求把脱敏模板价值提取到 main，放弃独立分支
+**问题**:
+- `sync-template.sh` 硬编码了旧架构的文件列表（DASHBOARD.md / ROADMAP.md / today.md / queue.md），框架一升级脚本就过时
+- 维护一个独立 Git 分支的成本 > 收益：需要手动切换分支、跑脚本、处理冲突
+- Shell 脚本的设计假设是「人类或 CI 执行」，但实际场景是 AI 执行。AI 不需要可执行脚本——AI 需要清晰的规格
+**教训**:
+1. **「用什么执行」决定「用什么描述」**。人/CI 执行 → 写脚本。AI 执行 → 写 Skill（语义描述 + 约束 + 边界定义）。Skill 描述「方法」，不会因文件路径变化而过时
+2. **边界定义文件是长期资产，执行脚本是短期负债**。SYNC.md 定义了什么属于框架、什么属于项目——这个定义独立于任何执行方式。脚本绑定了执行方式，框架一变就废
+3. **让 Git 做版本管理，让 Skill 做逻辑执行**。不需要为「脱敏」这个逻辑维护一个独立分支，Skill 从当前 main 实时执行脱敏，永远不过时
+4. **3 文件 > 4 文件 + 1 分支**。新方案：SYNC.md + TEMPLATE.yaml + Skill。旧方案：SYNC.md + TEMPLATE.yaml + sync-template.sh + init.sh + ai_project 分支
+**行动**:
+- ADR-008 标记废弃，新增 ADR-013
+- 废弃 sync-template.sh、init.sh、ai_project 分支
+- 保留并更新 SYNC.md（框架/项目边界），新增 TEMPLATE.yaml（变量定义），新增 project-init Skill
+
+---
+
 ## L-004: 跨平台 AI 协作下，文档是唯一的通信协议

 **日期**: 2026-05-26
@@ -0,0 +1,107 @@
+---
+name: "project-init"
+description: "框架脱敏/初始化：将当前项目框架层导出为通用模板，或从模板初始化新项目。用户说「导出框架」「初始化新项目」「套这个框架开新项目」时调用。"
+---
+
+# 项目框架脱敏与初始化
+
+## 功能
+
+将当前项目的「框架层」（AI 协作体系）与「项目层」（ErrLens 具体内容）分离。框架层可导出为通用模板，用于初始化任意新项目。
+
+**核心逻辑**：框架是骨架（角色、权限、工作流、Skill），项目是肉（PRD、架构、代码、ADR）。同一套骨架可以长出不同的肉。
+
+## 触发条件
+
+- 用户说「导出框架」「脱敏」「生成模板」
+- 用户说「初始化新项目」「套这个框架开新项目」「用这个骨架开个 IC 验证项目」
+- 当前项目框架层有重大更新后，用户想刷新模板
+
+## 两个模式
+
+### Export（脱敏导出）
+
+将当前项目框架层文件复制 → 把 ErrLens 具体值替换为 `{{变量}}` → 输出干净的模板目录。
+
+### Init（初始化新项目）
+
+读取模板 → 把 `{{变量}}` 替换为用户提供的新项目值 → 输出可开工的新项目目录。
+
+## 变量定义
+
+见 `TEMPLATE.yaml`。核心变量：
+
+| 变量 | 当前值（ErrLens） | 说明 |
+|------|-------------------|------|
+| `{{PROJECT_NAME}}` | ErrLens | 项目名 |
+| `{{PROJECT_CONCEPT}}` | 学生错题本 | 核心概念 |
+| `{{PROJECT_DESCRIPTION}}` | AI 驱动的学生错题整理与分析应用 | 一句话描述 |
+| `{{P01_NAME}}` | P01_errlens_app | 主应用目录名 |
+| `{{DATABASE_URL}}` | postgresql://.../errlens | 数据库连接 |
+
+## 框架层 vs 项目层
+
+见 `SYNC.md`。核心区分：
+
+**框架层（导出/同步）**：
+- `AGENTS.md` — AI 角色+权限
+- `dashboard.md` — 控制面板结构
+- `DECISIONS.md` — 决策入口
+- `.ai/principles.md` — 设计原则
+- `.ai/config/` — AI 配置
+- `.ai/prompts/` — 提示词模板
+- `.ai/roles/*/card.md` — 角色身份卡
+- `.ai/phases/INDEX.md` — 阶段索引
+- `.ai/knowledge/patterns.md` — 可复用模式
+- `.ai/knowledge/lessons.md` — 框架级教训
+- `.ai/tasks/templates/` — Task 模板
+- `.trae/skills/` — 全部 Skill
+- `docs/使用手册.md` — 使用说明
+- `ENVIRONMENT.md` — 环境结构
+- `TEMPLATE.yaml` — 变量定义
+- `SYNC.md` — 边界定义
+
+**项目层（不导出，新项目自己写）**：
+- `.ai/tasks/active/` — 具体 task
+- `.ai/phases/phase-*/goal.md, scope.md, architecture.md, decisions.md, completion.md`
+- `.ai/knowledge/decisions.md` — 项目 ADR
+- `.ai/knowledge/journal/` — 开发日志
+- `docs/01_*/ ~ docs/06_*/` — PRD、架构设计等
+- `docs/share/` — 对外分享
+- `projects/` — 代码
+- `reports/` — 测试报告
+
+## 执行步骤
+
+### Export 模式
+
+1. 读 `SYNC.md` 确认框架层文件清单
+2. 读 `TEMPLATE.yaml` 获取变量清单和当前值
+3. 对每个框架层文件：
+   - 复制内容
+   - 将当前值（如 `ErrLens`）替换为 `{{PROJECT_NAME}}`
+   - 将 `errlens` 替换为 `{{PROJECT_NAME_LOWER}}`
+   - 依此类推，覆盖 TEMPLATE.yaml 中所有变量
+4. 输出到指定目录（默认 `../project-template/`）
+
+### Init 模式
+
+1. 询问用户：项目名、核心概念、一句话描述
+2. 读 `TEMPLATE.yaml`，生成新值（如 `PROJECT_NAME: "ICValidator"`）
+3. 复制框架层文件到新项目目录
+4. 将所有 `{{变量}}` 替换为新值
+5. 创建项目层空目录结构（.ai/tasks/active/, .ai/phases/, docs/01_产品需求/ 等）
+6. 告知用户：新项目就绪，Arch AI 可以开始写 PRD
+
+## 注意事项
+
+1. **框架层不包含具体业务的 ADR**。ADR-009（人机协同）是 ErrLens 特有的，不导出。ADR-007（分层架构）是框架级的，可导出
+2. **Skill 本身属于框架层**，会被导出。新项目自带全套 Skill
+3. **TEMPLATE.yaml 导出后变量值变为 `{{}}` 占位符**，等待 init 时填入新值
+4. **脱敏检查**：export 后应人工抽查，确保没有 ErrLens 特有信息泄露到模板
+
+---
+
+**Version**: 1.0
+**Created**: 2026-05-26
+**Based On**: ADR-008（模板同步机制），废弃 ai_project 分支方案，改为 Skill 按需执行
@@ -0,0 +1,83 @@
+# 模板同步边界定义
+
+> 定义哪些文件属于"框架层"（跨项目复用），哪些属于"项目层"（项目特有）。
+> 框架层变化通过 `sync-template.sh` 从 main 同步到 ai_project 模板分支。
+
+---
+
+## 规则
+
+```
+框架层 = 可以复用的结构和逻辑（同步）
+项目层 = 某个具体项目的内容和数据（不同步）
+```
+
+---
+
+## 文件分类
+
+### 框架层（自动同步）
+
+| 文件/目录 | 说明 |
+|-----------|------|
+| `AGENTS.md` | AI 角色定义 + 权限矩阵 + 工作流 + 命名规范 |
+| `dashboard.md` | 控制面板结构（人类+Arch AI 入口） |
+| `DECISIONS.md` | 决策入口结构 |
+| `.ai/principles.md` | 架构设计原则 + Arch AI 上下文管理 |
+| `.ai/config/*.json` | AI 配置（权限路径、职责定义、工作流） |
+| `.ai/prompts/` | 提示词模板（架构、编码、测试） |
+| `.ai/roles/README.md` | 角色工作台说明 |
+| `.ai/roles/{arch,dev,qa}/card.md` | 角色身份卡（身份、权限、启动流程） |
+| `.ai/phases/INDEX.md` | 阶段索引 + 切换规则 |
+| `.ai/knowledge/patterns.md` | 可复用模式 |
+| `.ai/knowledge/lessons.md` | 框架级经验教训 |
+| `.ai/tasks/templates/` | Task 模板（Coder + Tester） |
+| `.trae/skills/` | Skill 定义 |
+| `docs/使用手册.md` | 使用手册（框架层） |
+| `ENVIRONMENT.md` | 开发环境结构（框架层） |
+| `sync-template.sh` | 同步脚本本身 |
+| `TEMPLATE.yaml` | 模板变量配置 |
+| `init.sh` | 新项目初始化脚本 |
+| `SYNC.md` | 本文档 |
+
+### 项目层（不同步）
+
+| 文件/目录 | 说明 |
+|-----------|------|
+| `.ai/tasks/active/` | 活跃 task 文件（项目特定） |
+| `.ai/tasks/completed/` | 已完成 task（项目特定） |
+| `.ai/phases/phase-*/goal.md` | 阶段目标（项目特定） |
+| `.ai/phases/phase-*/scope.md` | 阶段范围（项目特定） |
+| `.ai/phases/phase-*/architecture.md` | 架构快照（项目特定） |
+| `.ai/phases/phase-*/decisions.md` | 阶段决策（项目特定） |
+| `.ai/phases/phase-*/completion.md` | 完成状态（项目特定） |
+| `.ai/knowledge/decisions.md` | ADR 全文（项目特定） |
+| `.ai/knowledge/journal/` | 每日日志（项目特定） |
+| `.ai/archive/` | 归档文件 |
+| `docs/01_*/ ~ docs/06_*/` | 项目文档（PRD、架构、数据模型等） |
+| `docs/share/` | 对外分享内容 |
+| `projects/` | 项目代码 |
+| `reports/` | 测试报告 |
+| `review/` | 旧 review 流程（已废弃，由 .ai/tasks/ 替代） |
+
+---
+
+## 使用流程
+
+```bash
+# 1. 切换到模板分支
+git checkout ai_project
+
+# 2. 运行同步脚本
+bash sync-template.sh main ai_project
+
+# 3. 检查变更 + 提交
+git diff --stat
+git add -A && git commit -m "sync: 框架更新 from main"
+```
+
+## 原则
+
+1. **脚本覆盖框架层** — 直接 checkout 无需人工判断
+2. **项目层隔离** — 任务、日志、代码、决策不受影响
+3. **新架构适配** — dashboard.md / DECISIONS.md / .ai/tasks/ 已纳入框架层定义
@@ -0,0 +1,37 @@
+# ============================================================
+# 项目模板变量定义
+# 用于 project-init Skill 的 export/init 双向替换
+# ============================================================
+
+# --- 项目身份 ---
+PROJECT_NAME: "ErrLens"
+PROJECT_NAME_LOWER: "errlens"
+PROJECT_CONCEPT: "学生错题本"
+PROJECT_DESCRIPTION: "AI 驱动的学生错题整理与分析应用"
+
+# --- 子项目 P01（主应用）---
+P01_NAME: "P01_errlens_app"
+P01_DESC: "ErrLens 主应用"
+P01_FRONTEND: "Taro 4 + React 18 + TypeScript"
+P01_BACKEND: "NestJS 10 + TypeScript"
+
+# --- 子项目 P02（训练/AI）---
+P02_NAME: "P02_errlens_training"
+P02_DESC: "ErrLens AI 训练模块"
+
+# --- 子项目 P03（管理后台）---
+P03_NAME: "P03_errlens_web"
+P03_DESC: "ErrLens Web 管理后台"
+
+# --- 阶段定义 ---
+PHASE1_NAME: "基础搭建"
+PHASE1_GOAL: "搭建项目骨架：协作框架、脚手架、权限体系"
+PHASE2_NAME: "MVP"
+PHASE2_GOAL: "实现学生错题本核心功能"
+PHASE3_NAME: "功能完善"
+PHASE3_GOAL: "功能迭代、多端适配、性能优化"
+PHASE4_NAME: "打磨发布"
+PHASE4_GOAL: "质量提升、安全审计、文档完善"
+
+# --- 数据库 ---
+DATABASE_URL: "postgresql://user:password@localhost:5432/errlens"