failure-archaeology
Skill0 starsChanged 5 months agoApache-2.0View on GitHub
GEODoctor 事故档案馆——每次真实踩坑的现象/根因/修复/防复发规矩。新人入职先读;发生新事故时按模板归档。
2 other projects use a version of this.
Adopted by
Most recently taken up by
- usecompai/compound-operations-modeltheir own version, first seen Nov 8, 2026
- nic095layson/claudetheir own version, first seen Jul 10, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- usecompai/compound-operations-model★ 31same name
- nic095layson/claude★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository14 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- acceptance-gatesSkill
- architecture-contractsSkill
- bilingual-docs-contractSkill
- debug-audit-pipelineSkill
- debug-site-quirksSkill
- debug-test-failuresSkill
- diagnostic-commandsSkill
- evidence-registry-contractSkill
- release-versioning-controlSkill
- rule-change-controlSkill
- security-boundariesSkill
- showcase-refresh-protocolSkill
- skill-mapSkill
The file
Files
失败案例考古
适用场景
了解仓库怎么疼过;或刚发生新事故,需要归档。每案格式固定:现象 → 根因 → 修复 → 规矩 → 反事实代价。
案 1:管道吞退出码——红着测试完成了 commit(本仓库最贵事故)
- 现象:改仓库地址后
tests/reports.test.ts挂了,但 commit 照常完成。git reflog 里af36f9e → ac31244 (amend)是补救现场 - 根因:验证链写成
pnpm test 2>&1 | tail -3 && git commit——bash 管道的退出码取最后一个命令(tail 恒 0),&&判断的是被洗白后的 0 - 修复:输出落文件、显式保存
$?再判断;同时把测试断言从硬编码 URL 改为断言REPO_URL常量(消掉挂的根源) - 规矩:① 任何"验证 && 提交"链禁止管道接 tail;② 测试断言外部可变字面量(URL、版本号)时必须改为断言常量
- 反事实代价:当时若直接 push,公开首日 GitHub 首页挂红 CI——对一个卖"可验证"的审计工具是形象自杀
案 2:阈值-fixture 联动断裂(200 vs 175)
- 现象:首次全量跑测试,
chunk.list-table-density对 good-article fixture 返回na,"good article passes" 断言挂 - 根因:该规则适用门槛写了 200 units,而 fixture 正文只有 ≈175 units;其他内容规则门槛都是 150。阈值各自为政,没有统一共识(注:200 这个状态发生在首个 commit 之前的工作区,git 历史不可考——以本案叙述和测试快照为准)
- 修复:统一全部内容规则适用门槛为 150
- 规矩:150 = 全仓库统一的内容规则适用门槛;改任何一处等于改共识,必须全改并按 rule-change-control 走
- 反事实代价:低(测试当场拦截)——这正是"good article 全 pass"这种粗粒度断言的价值:它是阈值漂移的金丝雀
案 3:vhs 命令名记错(Hidden vs Hide)
- 现象:录 demo GIF,
vhs解析报Invalid command: Hidden,连挂两次 - 根因:凭记忆写 tape,vhs 的隐藏块命令是
Hide/Show,不存在Hidden - 修复:
sed批量改两个 tape - 规矩:写 tape 这类小众 DSL 先
vhs manual | grep确认命令名(已收录进 diagnostic-commands 发布物验证节);tape 已入库(docs/assets/*.tape),复用别重写 - 反事实代价:仅几分钟——但若发生在直播演示就难看了
案 4:npm login 撞上 CNPM 镜像
- 现象:用户执行
npm login跳出 "Sign in to CNPM",困惑"我不是发 GitHub 吗" - 根因:本机
~/.npmrc指向 npmmirror(国内加速镜像,只读);npm login默认登配置源 - 修复:登录带
--registry https://registry.npmjs.org;package.json 加publishConfig锁发布源(装包仍走镜像) - 规矩:
publishConfig不许删;所有 npm 发布文档必须写全带 registry 的完整命令 - 反事实代价:登录了 CNPM 也发不了包,最多浪费时间;但若镜像同名包存在还可能装错包
案 5:Edit 工具改不动含不可见字节的行
- 现象:
stripControlChars的正则里控制字符写成了字面字节(ESC 等不可见),Edit 工具精确匹配失败,改不动 - 根因:正则用字面控制字符书写,文件里存了不可见字节——工具与人眼都无法可靠匹配
- 修复:
perl -i -pe 'if ($. == 147) {...}'按行号替换;重写为new RegExp('\\x1b...')显式转义形式 - 规矩:源码中控制字符一律
\xNN转义书写,禁止字面量;遇到含不可见字节的行,用行号定位的 perl/sed 而不是内容匹配 - 反事实代价:低——但这类字节若进了 git diff,review 时人眼完全不可见,是潜在的供应链隐患形态
新事故归档模板
## 案 N:<一句话名字>
- **现象**:
- **根因**:
- **修复**:commit <hash>
- **规矩**:<写进哪份姊妹文档了?没有归属的规矩会丢>
- **反事实代价**:归档后:把"规矩"落到对应的 contract/control 文档里——考古馆存故事,规矩要住进法典。
什么时候不该用这份文档
- 找"现在该怎么做"→ 各 control/contract 文档(本馆只存"为什么会有那条规矩")
- 正在救火 → debug-audit-pipeline / debug-test-failures,救完再回来归档
姊妹文档
每案的"规矩"分别住在:debug-test-failures(案 1)· rule-change-control(案 2)· diagnostic-commands(案 3 的 DSL 确认命令)· release-versioning-control(案 4)· security-boundaries(案 5 的字节纪律与行号替换手法)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

