项目提示词写一次管全程
一份完整项目提示词长什么样九个模块，重点是「承重约定」
项目提示词（本仓库就是 CLAUDE.md）一次写好，AI 每次进项目都自动读、所有任务都按它干活。它不只写「用什么技术」，更把承重约定——AI 容易做错、必须强制的事——写成规矩。下表是它的九块骨架，后面挑承重的几块展开。
| 模块 | 作用 | 为什么承重 |
|---|---|---|
| 语言约定 | 怎么跟你说话（用中文回答） | 不写就各说各的 |
| 项目定位与状态 | 这是什么项目、做到哪了 | 给 AI 建立心智模型 |
| 目标技术栈 | 用什么、不用什么 | 防止引入禁区工具 |
| 命令契约（pnpm） | 固定脚本名 + 构建顺序 | AI 不用猜命令 |
| 工作流约定 | 组件走脚手架、不手写 | 防止绕过流程 |
| 架构原则 | 静态优先、schema 在边界 | 守住技术底线 |
| lint 三层 | eslint / stylelint / prettier | 规则替你盯 |
| 设计语言 | 配色 / 字体 / 阴影基线 | 防止视觉漂移 |
| 红线 | 不要自创、不要硬编码 | 把禁止项写明 |
pnpm 脚本名字固定，构建顺序承重
命令契约写死两件事：①脚本名固定——pnpm dev、build、gen:component，AI 要跑命令就用这些名字，不自创；②构建顺序是承重的——令牌 → 内容校验 → astro build → Pagefind 索引，前一步失败后面就不能跑。
"scripts": {
"dev": "astro dev",
"tokens:build": "style-dictionary build",
"content:check": "tsx scripts/validate-content.ts",
"build": "tokens:build && content:check && astro check && astro build && search:build",
"gen:component": "tsx scripts/gen-component.ts"
}顺序为什么不能乱：Pagefind 只对已构建的 dist/ 建索引，所以 search:build 必须排在 astro build 之后；令牌 CSS 必须在 astro build 之前生成，否则组件拿不到颜色。这条链路写在 build 一行里，AI 改构建时不敢拆。
eslint + stylelint + prettier把规矩写成机器能查的规则
三层各管一摊，由 eslint-config-prettier 解耦：Prettier 管格式、ESLint 管代码质量、Stylelint 管 CSS + token 约束。关键是——你把「不许硬编码颜色」写成 Stylelint 规则，AI 写错立刻被拦。规矩从「口头叮嘱」变成「机器强制的闸门」。
| 工具 | 管什么 | 一条典型规则 |
|---|---|---|
| Prettier | 格式 | 缩进、引号、换行 |
| ESLint | 代码质量 | 未用变量、any、hooks 规则 |
| Stylelint | CSS + token 约束 | 禁裸 hex、强制 –sx-* 前缀、color/background 只能 var() |
Stylelint 还守住一条：「业务代码不得引用 –sx-ref- 原语，只能用 / –sx-sys-–sx-comp-*」。这把「设计令牌是唯一来源」从口号落成可执行的规则——AI 一旦写裸 hex 或引用原语，pnpm lint 直接报错。
新增组件走一条命令数据驱动，不要手写
设计系统页是数据驱动的：展示页用 import.meta.glob 自动捕获所有 demo 文件。所以新增组件走 pnpm gen:component <Name> 一条命令，它会同时生成组件本体、demo、并把 registry 标记为 live——刷新即生效。承重约定：不要手写组件文件、不要手改展示页。
$ pnpm gen:component Button 主要、次要、幽灵变体
✔ 生成 src/components/design-system/Button.tsx （React 组件本体）
✔ 生成 src/components/design-system/demos/ButtonDemo.tsx （React 演示）
✔ 更新 src/data/components-registry.ts （标记 live）手写绕过脚手架，registry 和文件就会脱节——展示页要么漏组件、要么 demo 找不到报错。一条命令保证三处永远同步，AI 不必去理解三者的关联，照着规矩跑命令就行。
schema 在边界，不在业务代码令牌是视觉真相的唯一来源
「Schema 优先」不是「到处加 schema」。schema 只加在系统边界：构建期内容用 Zod / Content Collection、外部 API（GitHub）做运行时校验、跨窗口通信（Playground postMessage）用消息 schema、设计令牌用 DTCG JSON。普通业务逻辑只用 TS 类型——为了品牌理由在业务代码里到处加运行时 schema 是反模式。
// 构建期内容边界 —— 这里该加 schema
const lessonSchema = commonFields.extend({
slug: z.string(),
course: z.string(),
order: z.number(),
presentation: z.enum(['scroll', 'board', 'stepper']),
});设计令牌是视觉真相的唯一来源：以 DTCG JSON 在 tokens/src/ 写，Style Dictionary 构建，全局只导入一次。业务代码禁用 –sx-ref- 原语，只用 / –sx-sys-–sx-comp-，一个组件只能覆盖自己的 。结果：改一个色 = 改一处 token = 全站联动。–sx-comp-
改提示词，就是改 AI 的行为发现反复出错，就写进 CLAUDE.md
项目提示词是最高杠杆的文件：AI 每次进项目都读它，所以你改一行 CLAUDE.md，等于改了 AI 在所有任务里的默认行为。发现 AI 反复犯同一个错？别在对话里一次次纠正——把那条规矩写进 CLAUDE.md，一劳永逸。
| 禁止 | 原因 |
|---|---|
| 自创规范里已有的名称 / 枚举 / 路由 | 规范是权威，跟随而非另起 |
| 硬编码品牌色 | 只能用 –sx-sys-* 令牌 |
| 手写大段 inline style | 用设计系统组件 + Tailwind |
业务代码引用 –sx-ref-* 原语 | 令牌分层不可越级 |
手写组件文件绕过 gen:component | 走脚手架保三处同步 |
这个 skill 的全部：把一整套工程规矩（命令、lint、设计系统、schema）固化成一份项目提示词，AI 长期遵守，你只管改规矩、不用管每次任务。