主题
给 AI 写项目说明书：以本站 CLAUDE.md 为例
Skill 回答「某一类任务怎么做」；
CLAUDE.md回答「你掉进这个仓库时，默认要知道什么」。
本站根目录就有一份在用的说明书——下面按真实结构拆，不写空泛模板。
用 Claude Code（或同类 agent）改项目时，它第一轮往往会读仓库里的说明文件。说明写得好，少重复口述；写得像官网文案，agent 照样乱改 dist/。
一、它是给谁看的
| 读者 | 需要什么 |
|---|---|
| Coding agent | 命令怎么跑、别碰哪里、内容/测试约定、架构入口文件 |
| 三个月后的自己 | 同上，外加「为什么测试不跑 build」 |
| 协作者 | 不必先翻完所有笔记 |
不是给面试官的技术博客，也不是把 搭建指南 全文粘进来。
一句话标准：
一个新开的 agent 会话，只读这一份，应能改对笔记、跑对测试、不上线误伤。
Skill 更适合「发一篇笔记」这种流程；CLAUDE.md 更适合 跨任务的全局约束。分工见 自己写 Skill。
二、本站实际结构（可对照仓库）
当前 CLAUDE.md 大致是这些块：
- Commands — 怎么 dev / build / test
- Testing — 测什么、故意不测什么、踩过的 flaky 坑
- What this is — 一句话架构 + 部署模型后果
- Deployment — Nginx、cleanUrls、SNI 端口
- Architecture — 关键配置文件职责
- Brand color — 令牌约束（可验证）
- Content conventions — frontmatter、文风
- Adding a note — 最短发文路径
下面按「为什么这样写」说明，而不是再贴全文。
三、Commands：给可复制的真相，不给精神鼓励
bash
npm run docs:dev
npm run docs:build # 静态构建 -> docs/.vitepress/dist/
npm test # Playwright，桌面 + 移动
npx playwright test tests/e2e/a11y.spec.ts写命令区时三条原则：
- 和
package.json一致，过期命令比没有更糟 - 标注 副作用：本站写明 build 输出即线上根目录
- 给出 高频子集：全量
npm test约 45s，日常可先chromium单项目
agent 最常做的是「改完怎么验证」。你不写，它会发明 npm run lint（本站没有）。
四、Testing：把「坑」写成默认知识
本站测试段最有价值的不是「我们用了 Playwright」，而是：
- E2E 打 dev server，不打 build——因为 dist 是 Nginx 根，build 会清空线上
- RSS / og / sitemap 只在 build 产物里，用
artifacts.spec.ts读磁盘 - 已踩过的陷阱列表：
allTextContents不自动等待、reducedMotion嵌套不生效、search 的role="option"等
这类内容一旦只活在某篇博客里，agent 下次写测试仍会重踩。写进 CLAUDE.md 后，它变成 会话级先验。
对应长文：给博客加自动化测试。说明书里保留摘要即可，细节链出去。
五、What this is：部署模型一句话决定半本手册
text
VitePress 静态博客，Nginx 直接指向 docs/.vitepress/dist/
部署 = 在机器上 npm run docs:build，无独立 CI因为这个选择，后面才有：
- 永远不要手改 / 暂存 dist
- build 失败可能留下烂站
docs/public/才是持久静态资源入口
架构段落要写「后果」，不写「我们很简洁」。
更完整的暗礁清单：本站工程暗礁。
六、Architecture：入口文件表，而不是目录树倾倒
本站点名的文件：
| 文件 | 职责 |
|---|---|
docs/.vitepress/config.mts | 站点配置、侧边栏硬编码、中文 UI 文案、og |
docs/posts.data.mts | 文章列表单源 |
docs/.vitepress/rss.ts | RSS + HOSTNAME |
docs/.vitepress/theme/* | 主题、插槽、进度条、404 |
docs/.vitepress/theme/custom.css | 共享样式与品牌色 |
agent 改功能时需要的是 「该打开哪个文件」，不是 node_modules 有多深。
侧边栏硬编码值得单独加粗：只建 docs/notes/x.md 不够，还要改 config.mts，否则列表有、导航无。
七、Content conventions：可机器执行的约束
text
frontmatter: title, description, date, readingTime, tags
draft: true → 不进列表和 RSS
正文中文，术语可英文
emoji 不进 nav/sidebar 文案好的约定能直接变成检查清单；坏的约定是「请保持高质量写作」。
缺 title 会在列表里出空白条目——这种 可观察失败 最适合写进说明书。
八、怎么写才不会膨胀
做
- 用清单、表格、路径
- 写 禁区（dist、手写双列表）
- 写 验证命令
- 链到长文，不复制长文
不做
- 粘贴大段官方 VitePress 文档
- 写「本项目致力于探索…」
- 把 194 个 skill 的目录塞进
CLAUDE.md - 与 Skill 正文维护两套互相矛盾的步骤
长度经验：本站这份大约数百行以内仍可读。再长就拆：docs/notes/ 给人读，CLAUDE.md 给会话读，Skill 给单流程读。
九、最小骨架（可抄到新仓库）
markdown
# CLAUDE.md
## Commands
（dev / build / test，注明副作用）
## Must not
- 不要编辑构建产物目录
- 不要…
## Architecture
| 路径 | 职责 |
|------|------|
## Content / API conventions
（字段、命名、错误格式…）
## Verify
改完至少跑：…然后按项目把「Must not」和「Verify」写满——这两节对 agent 的收益通常高于「愿景」。
十、和本站其它文档的关系
| 文档 | 角色 |
|---|---|
CLAUDE.md | 全局默认：命令、禁区、入口、约定 |
| 自己写 Skill | 单流程：如何发文、如何开 PR… |
| 工程暗礁 | 人读的决策与事故复盘 |
| 学习路径 | 读者怎么学 Claude Code |
改发文规则时：先改 CLAUDE.md 的 Content / Adding a note，再改 add-blog-note skill，最后改博客里的教程——三处顺序一致，agent 才不会站队站错。
十一、验收：说明书有没有用
新开一个干净会话，只说：
text
读 CLAUDE.md，然后加一篇 draft 笔记，标题「说明书验收」，不要部署。看它是否：
- 写了完整 frontmatter
- 改了 sidebar
- 没碰 dist
- 用对了测试或说明「draft 不必 build」
任一失败，回去改说明书或 skill，而不是只骂模型。
项目说明书的终点不是「文档齐全」，而是：默认行为变得安全、可预测。
本站能把 build 当部署、能把测试当护栏，有一半要归功于这些写进仓库根目录的丑句子，而不是首页粒子。