用三个钩子、一份项目 wiki 和门禁,让 Claude Code 压缩上下文后不失忆,说「做完」时要拿出证据(作者公开了钩子代码)
波兰前端开发者 Mateusz Muszarski 用 Claude Code 大约两周做完个人作品集站,写了一篇复盘:CLAUDE.md 只做 76 行的「路由表」,指向 33 页项目 wiki;SessionStart 钩子在新会话和每次压缩后重新注入工作约定、git 状态和 lessons;UserPromptSubmit 钩子给每条提示词打分,附上最相关的最多 5 个 wiki 页;Stop 钩子在改了代码却没更新 wiki 时拦一次。每次纠正写成一行规则,规则反复被违反就改成测试;「做完」是一串必须通过的命令和截图。他的钩子脚本在 GitHub 公开,我们在测试机上跑了。
访问官网 Claude Code hooks (SessionStart / UserPromptSubmit / Stop) + project wiki ↗- 定价
- 付费
- 地区
- 海外
- 出自哪里
- 海外社区
- 上架日期
- 2026 年 10 月 20 日
- 实测日期
- 2026 年 10 月 20 日
- 用的版本
- MuchaSsak/muszarski.com @ 090022f (2026-10-18): .claude/hooks/session-start.mjs, wiki-context.mjs, wiki-check.mjs, run with Node 20.19 outside Claude Code
- 我们实测
- 部分实测
- 成本 / 耗时
- 钩子是几个 Node 小脚本,免费;需要 Claude Code(Claude 订阅或 API)。作者用订阅,没有统计 token。主要成本是前期搭 wiki 和门禁的时间。
要解决的事
长项目里,Claude Code 压缩上下文后会忘掉之前说好的规矩,又常常在「看起来做完了」时就停下来汇报。
步骤
- 先从最小的开始(作者自己的建议):今天就建一个 lessons.md,每纠正 Claude 一次就写一行带日期的祈使句规则;再加一个 Claude 说「做完」之前必须跑的门禁命令。下方提示词是我们按这个做法写的示例,不是作者原话。
- 把 CLAUDE.md 改成路由表:一个「## Routing table」小节,表头 | Task touches | Read |,左列写任务关键词,右列用反引号写对应的 wiki 页路径(如 .claude/project-info/site/i18n.md),再加几条绝不能破的规则;具体知识放进 .claude/project-info/ 下的 wiki 页。
- 在 .claude/settings.json 里配三个钩子(可参考作者仓库 MuchaSsak/muszarski.com 的 .claude/hooks/):SessionStart → session-start.mjs,在新会话、恢复、/clear 和每次压缩后注入「怎么干活」卡片、git 状态和 lessons 的 ## Rules;UserPromptSubmit → wiki-context.mjs,按路由表给提示词打分,注入最多 5 个最匹配的页面;Stop → wiki-check.mjs --stop-hook,改了代码却没改 wiki 时拦一次。
- 规则反复被违反就升级成检查:作者的例子是 CSS 里 animation 简写和 animation-timeline 写在一起会被 Chrome 整条拒掉、动画静默失效;写成规则后第二天又有三处退回简写,于是加了一个读取所有样式表的单元测试。
- 把「做完」定义成一串看退出码的命令:typecheck、lint、单元测试;Playwright e2e(每个路由跑 axe WCAG 2.2 AA、320–2560px 不出现横向滚动、各语言文字不溢出);Lighthouse 移动端性能不低于 95、其他项 100;发布构建里留着占位符就失败。
- 让 Claude 自己看成品:用 Playwright 按 390–1920px、每种语言截图,并要求它逐张打开看。
- 大任务一节一节切:调研 → 用真实内容做 → 检查 → 修最弱的一处,循环到挑不出值得修的地方。缺事实时写可搜索的占位符并登记,发布构建只要还有占位符就失败。
- 读多写少的活交给子代理:并行调研、对照官方文档核对事实、让没看过草稿的新代理审稿。
提示词
从现在起,每当我纠正你,或者某个工具让你踩了坑,就在 .claude/project-info/lessons.md 的「## Rules」下面追加一行带日期的祈使句规则。说「做完」之前,先运行类型检查、单元测试和 e2e,把每条命令和它的退出码列出来;任何一条失败都不算做完。
原文怎么说
作者说(2026-10-18)这个作品集站是他和 Claude Code 大约两周做出来的;CLAUDE.md 是 76 行的路由表,wiki 有 33 页。规则卡片注入 lessons 时上限 8000 字符,lessons 文件已经超了,末尾的规则会被截掉。写这篇文章时,一个子代理不到一分钟对照文档核对了 12 条说法,全部成立。他还碰到过后台构建日志写着 Build failed、退出码却是 0,因为输出被管道接给了 tail。他明确说明:一个人一个项目、Windows 环境、没统计 token 成本;两天的小脚本只写个短 CLAUDE.md 就够了。文章是他用 Claude Code 根据项目 wiki、代码和笔记起草的。
我们实测
我们没有在 Claude Code 里挂上这些钩子跑一个真实项目,也没有复现他的门禁、截图和子代理流程;只克隆了作者公开的 muszarski.com 仓库,用模拟的钩子输入(stdin JSON)在测试机上直接运行了三个钩子脚本,并验证了管道退出码这个坑。
我们亲自试下来:2026-10-20 实测(仓库 commit 090022f,Node 20):CLAUDE.md 确为 76 行,wiki 检查脚本报告 33 页、0 错误、0 警告。用作者文中的提示词「have it consistent over languages」调用 UserPromptSubmit 钩子,注入内容与文中展示的一致,指向 .claude/project-info/site/i18n.md;少于 25 个字符的提示词不输出任何内容。用 {"source":"compact"} 调用 SessionStart 钩子,生成约 9,900 字符的卡片,开头提示「上下文刚被压缩,这不是暂停,继续当前任务」并给出 git 状态,末尾标注 lessons.md 超出上限被截断。Stop 钩子:改动一个代码文件后,第一次返回 decision: block 并列出要更新的 wiki 页和 log.md;同一状态第二次放行;stop_hook_active 为 true 时直接放行;往 log.md 加一条格式不对的标题后,返回 block 并指出这一行格式错误。bash 里 false | tail 退出码为 0,set -o pipefail 后为 1。
怎么用上
原文在作者博客 muszarski.com(英文,同步发在 dev.to),国内一般能打开;钩子代码在 GitHub MuchaSsak/muszarski.com(仓库没有放许可证文件,照思路自己写更稳)。Claude Code 需要海外 Claude 账号;同样的「规则卡片 + 按任务注入文档 + 收尾检查」思路也能搬到其他支持钩子或规则文件的代理上。
适合谁
用 Claude Code 做持续几周以上的项目、常被压缩后「失忆」困扰的人;多个会话、多台电脑同时改一个仓库的独立开发者。
踩坑提示
- 钩子以你的完整用户权限执行 shell 命令,加别人写的钩子前先把代码读一遍。
- 写在 CLAUDE.md 里的「不许读 .env」只是引导,拦不住;真正拦住读取要在 settings 里写 deny 规则(作者说这是他下一步要补的)。
- lessons 越写越长会超出注入上限:我们跑作者仓库里的卡片约 9,900 字符,末尾标注 lessons 超限被截断。要定期合并、删掉已经有测试兜底的规则。
- 输出用管道接给 tail 会吞掉真实退出码:加 set -o pipefail,或在日志里 grep 失败字样(我们实测 false | tail 退出码是 0,开 pipefail 后是 1)。
- 串行的检查脚本(作者的 bun run check)在第一个失败处就停,后面的错误被藏住;修完一项要把每项都重跑一遍。
- 多个会话改同一个仓库:只 stage 自己改的文件,别 git add -A;每个构建用自己的目录和端口;按端口的 PID 停服务,别按进程名全杀;push 被拒就 git pull --rebase。
- 无头 Chromium 用软件渲染 WebGL,着色器截图会像是坏了;会动的页面截图要开 reduced motion 或固定时钟,否则截到的是随机一帧。
- 作者是 Windows 环境,Git Bash 路径改写、taskkill、路径过长这几个坑是 Windows 专属。
同类用例
- 文档每页配演示视频,界面一改就报红视频创作ScreenplayClaude Code工具免费;需 Claude 等 agent 额度◐ 部分实测海外
- 让 AI 写后端时默认防并发、越权和改表事故编程开发backendskillsClaude CodePostgreSQL免费;每次任务多花约一倍额度◐ 部分实测海外
- 一个下午让 AI 做出能在浏览器里玩的 3D 动作游戏编程开发Claude CodeTripo即梦技能免费;需 Claude 额度,素材工具另计◐ 部分实测国内
- 长期让 AI 写同一个项目,仓库也不乱编程开发ClaudeCodexoil-delegate需 Claude 和 Codex 订阅◐ 部分实测国内
- 边用一个网页产品,边让 AI 写出它的工作原理调研搜索REAClaude CodeChrome工具免费;需 Claude 或 Codex◐ 部分实测海外