Appearance
落地构件：AGENTS.md / Rules / Skills
上下文工程 讲的是"该给代理什么信息"，本章回答"这些信息写成什么文件、放在哪、长什么样"。把理念变成能直接抄用的模板。
一、为什么需要"落地构件"
在执行工装工程里有一条铁律：仓库即事实来源（system of record）——对代理来说，仓库里没有 = 不存在。
问题是：你口头交代、聊天记录里的约定，换个会话、换个人、换个代理就全丢了。解决办法就是把约束写成仓库里的结构化文件。这就是 AGENTS.md、Rules、Skills 这三类构件的用武之地：
text
把"每次都要重复叮嘱的话" → 沉淀成仓库里的文件 → 代理自动读取 → 不用再重复💡 心智模型：这三类构件就是上下文工程的物理载体。SDD 的 spec 是"这个功能要做什么"，而它们是"这个项目/团队永远遵守什么、擅长做什么"。
二、三类构件对比
| 构件 | 作用范围 | 回答的问题 | 加载方式 | 典型文件名 |
|---|---|---|---|---|
| AGENTS.md | 整个仓库 / 某子目录 | "在这个项目里干活，通用规则和上下文是什么？" | 代理自动读取项目根的 AGENTS.md | AGENTS.md |
| Rules（规则） | 按文件类型 / 场景触发 | "改某类文件时必须遵守什么？" | 按 globs 匹配或 alwaysApply 常驻 | .cursor/rules/*.mdc |
| Skills（技能） | 按任务意图触发 | "遇到某类任务，该走什么流程、用什么专业能力？" | 描述匹配需求时按需加载 | SKILL.md（含 prompt.md/reference.md） |
一句话区分：
- AGENTS.md = 项目的"总纲 / 地图"，长期常驻；
- Rules = 硬约束、编码规范，按文件类型生效；
- Skills = 可复用的"做事流程 + 专业知识包"，按任务召唤。
三、AGENTS.md：项目总纲
放在仓库根目录，供各类编码代理（Agent）自动识别。写"稳定、通用、每个任务都用得上"的信息，别写一次性需求。
markdown
# 项目：awna-book（VitePress 技术文档 monorepo）
## 结构约定
- 每个教程是独立的 book-<topic>/ 站点，docs/ 下放 Markdown 章节。
- 站点配置在 docs/.vitepress/config.mts，侧栏在 sidebar.mts。
## 编码 / 写作规范
- 全文中文，术语首次出现附英文原文。
- 代码块必须标注语言；命令标注执行环境（终端 / PowerShell / 容器内）。
- 侧栏 link 必须与 docs/ 下真实文件路径逐字匹配。
## 构建命令（PowerShell，命令分隔用 ; 不用 &&）
- npm install
- npm run docs:build # 必须无死链
## 禁区
- 不要臆测示例输出；数值 / 运行结果必须实机验证后再写入。
- 不要在文档里提交密钥、Token 或内网地址。🕳️ 你可能会遇到的坑：把 AGENTS.md 写成"项目百科"，几百行什么都往里塞。结果每次都全量加载，稀释了关键约束的权重——这正是上下文工程里"上下文灌水"反模式。AGENTS.md 要精炼，把大段专业知识拆进 Skills / Rules，按需召唤。
四、Rules：按文件类型生效的硬约束
Rules 用来表达"改某类文件时必须遵守的规范"，靠 frontmatter 里的元数据决定何时加载。以 .cursor/rules/ 下的规则文件为例：
mdc
---
description: VitePress 文档写作规范
globs: "book-*/docs/**/*.md"
alwaysApply: false
---
- 章节遵循 7 段式结构（为什么→概念→上手→实战→进阶→排错→总结）。
- 每个示例代码都要真实运行验证，禁止手算或臆测输出。
- 刻意埋 1-2 个常见错误并演示排查；对不安全用法加安全警告。三种触发方式：
| 字段 | 含义 |
|---|---|
globs | 只在匹配这些文件路径时加载该规则 |
alwaysApply: true | 常驻加载（相当于强约束，慎用以免污染上下文） |
description | 供模型判断"这次任务是否相关"，决定是否拉入 |
⚠️ 安全提示：Rules 会被自动注入上下文，绝不要在规则文件里写入密钥、数据库口令、内网地址——它们会随每次对话发给模型。规则只放"规范与约束"，敏感配置走环境变量 / 密钥管理。
五、Skills：可复用的"流程 + 专业知识包"
Skill 是把"做某类任务的完整方法论"打包，平时不占上下文，命中任务时才加载。标准形态是一个目录 + SKILL.md（用 YAML frontmatter 声明 name 和 description）：
markdown
---
name: write-tutorial
description: 在本仓库撰写新的技术教程章节，遵循 7 段式与 VitePress 约定。当用户要求"写教程/新增章节/做 XX 入门指南"时使用。
---
# 写教程（Write Tutorial）
## 何时用
- 新建 book-<topic> 站点，或往已有站点补章节。
## 核心原则
1. 代码必须实机验证，输出以运行结果为准。
2. 讲"为什么"和"怎么用"，抽象概念配类比与图。
3. 埋 1-2 个踩坑；不安全用法给安全警告。
4. 构建必须通过：npm install + npm run docs:build 无死链。
## 工作流程（清单）
- [ ] 分析上下文 → 规划目录 → 配置站点 → 撰写 → 验证 → 构建 → 接入主站description 是触发关键：它要写清"做什么 + 何时用"，代理据此判断该不该召唤这个技能。主 SKILL.md 保持精炼，把冗长模板放到同目录的 reference.md、把提示词放到 prompt.md，按需引用——这本身就是上下文工程的"渐进式加载"。
💡 你此刻用的这个教程站的写法，就是照着仓库里的
write-tutorial技能生成的——它正是 Skills 的一个活例子。
六、三者如何配合
text
AGENTS.md → 常驻总纲：项目地图 + 通用规则（保持精炼）
Rules → 命中文件类型时生效：编码/写作硬约束
Skills → 命中任务意图时加载：完整流程 + 专业知识包配合原则（呼应上下文工程）：
- 分层：长期通用的进 AGENTS.md，按类型的进 Rules，按任务的进 Skills；
- 少即是多：能按需召唤的，就别常驻加载，避免污染上下文；
- 单一事实来源：同一条约束只写在一个地方，避免多处打架。
七、最佳实践清单
- 从最小可用起步：先写一份精炼 AGENTS.md，遇到反复叮嘱的规则再抽成 Rules / Skills。
- 规则可验证：像"构建必须无死链"这种能被机器检查的约束，比"代码要优雅"更有效（呼应执行工装工程的"约束 > 指令"）。
- 定期回顾瘦身：删掉过时或从未被触发的规则，防止构件库膨胀成新的噪音源。
- 版本化：这些文件和代码一样进 Git、走评审。
八、本章小结
- AGENTS.md / Rules / Skills 是上下文工程的落地文件，把"重复叮嘱"变成"仓库里的事实来源"。
- 三者分工：总纲常驻、规则按类型、技能按任务；核心都是"给相关、不给过量"。
- 安全红线：构件会被自动加载，严禁写入密钥 / 敏感配置。