让 AI 编程 不忘约束 —— 四件套防遗忘 + Skill 沉淀 SOP。

模板 A · CLAUDE.md 约束区完整版

放在 CLAUDE.md 文件最前面。

# Hard Constraints —— 必须遵守

> 每次新任务开始前先 Read 一遍本节，回复第一句复述生效约束摘要（≤30 字）。

## 禁止改动的文件 / 目录
- `src/auth/`、`src/payment/` —— 安全审计区，PR 需双人 review
- `src/legacy/parser.ts` —— 旧 API 兜底，2026Q3 前下线计划未定
- 任何带 `// LOCKED:` 注释的代码块 —— 连格式化、重排 import 都不允许
- `.env*`、`*.local`、`secrets/**` —— 禁止读取、删除、改名
- `prisma/migrations/` 下已存在的迁移文件 —— 只能新增，不能改历史

## 禁止执行的命令
- `git push --force`、`git push -f` —— 无论分支
- `git reset --hard`、`git clean -fd` —— 会丢未提交工作
- `rm -rf`、批量删除超过 5 个文件
- `pnpm install <新包>` —— 任何新依赖必须先问
- 数据库 schema 变更（`prisma migrate`）—— 必须先问

## 必须先询问的动作
- 删除任何超过 5 行的代码块
- 修改 CI / CD 配置（`.github/`、`vercel.json`、`Dockerfile`）
- 修改公共 API 签名（导出的函数、Route Handler 路径、event 名）
- 接近受保护目录的「相关改动」

## 不确定时的默认动作
- 模糊指令（"优化一下"）→ 先列计划，等确认再执行
- diff 里出现禁止清单的文件 → 立刻停下来，原文展示给用户
- 自动 compact 发生后 → 第一件事 Read .claude/CONSTRAINTS.md 再继续

## 违反时
- 已经违反 → 立刻停手，向用户说明违反了哪条规则、影响了哪些文件
- 不要自己「修复」违反 —— 由用户决定是 revert 还是接受

模板 B · 会话开场白

B.1 轻量版（< 20 轮预期）

任务：<一句话目标>
约束：<最关键 1~2 条，比如「不要动 src/auth/」>
期望产出：<diff / 方案 / 排查报告 ……>
开始前请确认你理解了约束。

B.2 完整版（长任务 / 敏感区域）

# 任务设定

## 目标
<一句话明确目标>

## 范围
- 可改：<src/api/orders/、相关测试>
- 只读：<src/legacy/、prisma/schema.prisma>
- 禁改：见 .claude/CONSTRAINTS.md

## 验收标准
- <可量化的 1~3 条>
- 现有测试全部通过
- 不引入新依赖

## 工作方式
1. 先 Read .claude/CONSTRAINTS.md，复述生效约束
2. 列出 3~5 步执行计划，等我确认再开工
3. 每完成一步停下来，让我看 diff 再继续
4. 不确定时停下来确认，不要自行决定

确认理解后，开始第 1 步。

模板 C · Checkpoint 复诵

C.1 标准 checkpoint

Checkpoint。继续前：
1. Read .claude/CONSTRAINTS.md
2. 用一句话复述当前任务目标
3. 列出接下来 3 步打算做什么、涉及哪些文件
4. 标注其中是否有任何文件属于禁止 / 只读清单
等我确认再继续。

C.2 高风险 checkpoint

Risk checkpoint。
你接下来打算改动的文件里出现了 src/<某目录>/，接近受保护区域。
1. Read .claude/CONSTRAINTS.md
2. 解释这次改动为什么必须涉及该路径
3. 列出可以替代的「绕开方案」（如果有）
4. 列出如果改动出错，回滚的具体步骤
不要直接执行，等我决定。

C.3 Compact 后复活（最重要）

刚刚压缩了。重启对齐：
1. Read .claude/CONSTRAINTS.md
2. Read <当前正在改的关键文件>
3. 复述当前任务目标和已完成的步骤
4. 列出接下来 3 步计划
等我确认再继续。

检查 1 · Claude Code 版本支持 Skills

claude --version
# 太老就升级
npm i -g @anthropic-ai/claude-code
brew upgrade claude-code

检查 2 · Skills 目录的位置

检查 3 · 项目里能正常跑 claude

cd <您的项目根>
claude
> 当前项目根目录是？

能正常对话 + 返回正确路径 = 环境 OK。

<项目根>/
└── .claude/
    └── skills/
        └── <skill-name>/
            ├── SKILL.md          ← 主说明书（必需）
            └── references/
                └── checklist.md  ← 详细资料（按需 Read）

为什么要拆 references/

• SKILL.md 主体每次匹配上就全量进上下文，太长会浪费 token
• 详细的检查清单 / 模板代码放 references/，只在真需要时 Read
• 这叫 progressive disclosure（渐进式披露）

创建命令（一行完成）

# PowerShell
New-Item -ItemType Directory -Force -Path .claude\skills\<skill-name>\references

# Bash
mkdir -p .claude/skills/<skill-name>/references

最简骨架

---
name: <skill-name>
description: 当用户请求 ... 时使用
---

# <Skill 名字（人类可读）>

按以下步骤执行 ……（正文）

frontmatter · 三个易错点

• 三个横线 —— 不能是两个、四个
• 前后必须各有一对 ---
• --- 顶格 —— 不能有任何缩进

description 字段（最关键）

模型靠这一行决定要不要加载这个 Skill。

易错点速查表

为什么这个场景适合做 Skill

vibeapi-qa 站点新增页面是典型的「步骤多 + 易错 + 高频复用」场景：

• 建文件夹 → 命名格式 YYMMDD-english-slug，禁止中文
• 复制模板 → 替换 8 个 {{占位符}}
• 更新 pages.json → 必须插数组开头，6 个字段不能错
• HTML 必须 <link> qa-base.css + 末尾 <script> nav.js
• tag 必须先看现有的复用，避免「速度/速率」近义词分裂
• 提交 push 触发 Vercel 部署

.claude/skills/qa-page-new/
├── SKILL.md              ← 主说明书（~150 行）
│                          每次匹配自动加载
└── references/
    └── checklist.md      ← 详细清单（~120 行）
                           按需 Read

frontmatter

---
name: qa-page-new
description: 当用户请求在 vibeapi-qa 站点新增 QA 文档、新增 notes 笔记、新增 changelog、或添加一篇新文章时使用。覆盖完整流程：建目录、写 HTML、更新 pages.json、push 部署。
---

硬约束（违反即停手）

## 硬约束

### 文件夹命名
- **必须** YYMMDD-english-slug 格式
- **禁止中文** —— Vercel URL 编码会变成 %E4%B8%AD...
- 日期取今天（用户没指定时）

### pages.json 字段
- 新条目**插在数组最前面**
- id 必须**和文件夹名完全一致**
- title **中文、明确具体**
- tags 1~3 个，**先看现有 tags 复用**

### 禁止动作
- **禁止删除已有页面文件夹**
- **禁止改 nav.js / qa-base.css**
- **禁止 git push --force**

5 步 SOP（节选）

### Step 1：收集信息
- Read public/pages.json 看现有 tags，提示用户复用
- 列出完整字段让用户确认
- **等用户确认后再进入 Step 2**

### Step 2：建文件夹和 HTML
- 复制模板，替换所有 {{占位符}}
- 确认 </body> 前有 <script src="/nav.js"></script>

### Step 3：更新 pages.json
- 在数组**最前面**插入新条目
- Read 一遍改后的 pages.json 确认 JSON 合法

### Step 5：提交部署
- git push origin main
- Vercel 1~2 分钟内自动部署

创建好两个文件后，下一次 Claude Code 启动时会在系统级提示里显式列出可用的 Skill。本对话写到这里时，系统提示原样如下：

The following skills are available for use with the Skill tool:

- qa-page-new: 当用户请求在 vibeapi-qa 站点新增 QA 文档、新增 notes 笔记、新增 changelog、或添加一篇新文章时使用。覆盖完整流程：建目录、写 HTML、更新 pages.json、push 部署。

看到这条 = Skill 真的被系统识别。你写的 description 一字不漏出现在「售货机的目录」里。

上方展示的是 qa-page-new 的初版精简形态（约 150 行）。但 Skill 的真正价值不在初版，而在持续沉淀。 本文创建过程中，每踩一次坑就回到 Skill 补一条规则 —— 文章写完时，Skill 已经从 150 行长到了 256 行。

Skill 不是"写一次就完"的文档，是会随项目一起长大的活资产。

判断标准：你过去 3 个月做过 2 次以上 + 每次都有「这步又忘了」的环节 = 应该做成 Skill。

看完未付诸实践，三天后即遗忘。提供三个不同投入度的起点，建议从其一入手：

• 5 分钟版：新建项目根目录的 CLAUDE.md，把这周踩过的 3 个最痛的坑写进硬约束区。
• 30 分钟版：完成 5 分钟版 + 装 guard-bash.js 拦截 git push --force 和 rm -rf。
• 2 小时版：完成 30 分钟版 + 把团队过去 3 个月做过 3 次以上的高频动作做成一个 Skill。