给 Agent 上个紧箍咒：功能文档 + Cursor Skill

个人站最近一口气塞了影集、说说、移动导航动画，聊着聊着方向就容易飘：图床换过一轮、灯箱交互改了三版、说说空列表还踩过 content store 的坑。

人脑记不住没关系，Agent 下一轮对话更记不住。于是做了件很「文档党」但实际好用的事——把技术方案和每次功能增删改写进仓库，再写一条 Cursor Skill（外加 always rule）约束：改功能前先读文档，改完再回写。

这篇就是这次做法的备忘，方便以后自己抄。

问题从哪来#

典型对话长这样：

「影集用 ImageKit，导航动画先不做」
过两天：「导航 blur 也可以做了」
再过两天：「灯箱要像 react-photo-view 那样轮播」
新开一个 chat：「把说说页做了」——模型对前面锁定的决策一无所知

没有持久化的「方向备份」，就会出现：

已拍板的图床/交互被悄悄推翻
同一模块修了又修，changelog 全在聊天记录里，搜都搜不到
新功能不知道该复用哪套约定（content collection？纯前端 JSON？）

人肉靠记忆不可靠，指望 Agent「记得上周说的」更不可靠。

解决思路：文档是源，Skill 是闸#

两层东西，分工不同：

层	放哪	干什么
文档	`docs/`	记架构、锁定决策、功能 changelog
约束	`.cursor/skills/` + `.cursor/rules/`	强迫读写文档的流程

文档负责「真相」；Skill / Rule 负责「下次动手前必须看真相」。

只写文档不约束，三个月后文档照样落灰。只写 rule 不写文档，规则变成空话。两边一起上才有用。

文档怎么拆#

当前个人站大致是这四块：

docs/
  README.md           # 入口：先读啥
  architecture.md     # 技术栈、集合、模块边界
  decisions.md        # 已锁定决策（冲突先问人）
  changelog/
    README.md         # 怎么写 changelog
    2026-08-xxx.md    # 按功能拆的变更

architecture：别写成说明书小说#

只写边界就够了，例如：

Astro 6 SSG、Content Collections、ImageKit、Vercel
posts / gallery / notes 各自干什么
影集灯箱和文章 lightbox 为什么要拆开

细节甩到 changelog，架构页保持「一张地图」。

decisions：拍板过的就钉死#

把「不要再讨论了」的结论单独拎出来，例如：

影集主图床用 ImageKit
说说正文不做完整 Markdown
进度条不够溢出就隐藏

新需求如果和这里打架，先问人，再改文档，最后改代码。顺序反了就会又聊飞。

changelog：按功能记增删改#

文件名用 YYYY-MM-短横线功能名.md，每条至少：

摘要
动机 / 方向
关键文件
行为变化（用户能感知的）
后续约束（下次改这块别踩的坑）

同一功能的修补可以在文末加 ## 修订 YYYY-MM-DD，不必每次新建文件。

Skill 怎么约束行为#

项目里加了 .cursor/skills/feature-doc-sync/SKILL.md，核心就一件事：功能改动必须走 Doc Sync 清单。

Doc Sync:
- [ ] 1. 读 docs/README + architecture + decisions
- [ ] 2. 读相关 changelog
- [ ] 3. 对照方向设计（冲突先问）
- [ ] 4. 写代码
- [ ] 5. 回写 changelog
- [ ] 6. 架构/决策有变则同步更新

description 里把触发词写清楚（影集、说说、ImageKit、changelog、功能改动……），方便 Agent 自动捞到这条 skill。

Skill 偏「流程说明书」。要让它每轮都生效，再补一条 alwaysApply 的 rule：

.cursor/rules/feature-docs.mdc

rule 写得很短：先读 docs/，再动手，完事回写；细节指向 skill。这样不用每次手动 @skill。

落地时踩过的两个小坑#

1. 文档路径别写飘#

Skill 在 .cursor/skills/feature-doc-sync/，链到仓库根下的 docs/ 要用相对路径算准层级。写错了 Agent 读不到，约束等于没写。

2. Dev 内容集合不同步#

说说页加了 notes collection 和一堆示例 md，本地却显示「暂无说说」。原因不是没文件，是 dev 的 content store 没把新 collection 同步进来。

处理很土但有效：动一下 content.config.ts 触发同步，或重启 astro dev。这类坑也值得写进对应 changelog 的「后续约束」，免得下次又空欢喜一场。

什么时候可以偷懒#

不是每个空格对齐都要开一篇 changelog。个人约定是：

要写：新页面、新 collection、交互增删改、换存储/图床、删功能
可跳：纯 typo、和产品行为无关的格式化

跳过写文档时，也别去碰 decisions.md 里已经钉死的行为。

值不值得#

写文档的那半小时，换来的是：

新开 chat 也能对齐「图床是 ImageKit、说说不跑 MD」
改灯箱前能看到「曾经双结算导致乱序」这种血泪
自己三个月后回来，不用翻几十屏对话记录

Agent 不是不听话，是没有长期记忆。把记忆放进 git，再用 skill / rule 当门禁，比反复在 prompt 里念经靠谱。

以后这站再加功能，默认流程就是：先翻 docs/，再改代码，再补 changelog。紧箍咒是自己给的，疼一下，省很多次返工。