engineering-pitfalls-checklist
Skill3 starsChanged 8 days agoApache-2.0View on GitHub
当文件首字节异常或差异里多出看不见的首行改动、子代理报的内容与远端对不上、部署前检查报运行时版本不一致、shell 输出乱码或命令被吞、测试时过时不过时使用:按六类工程坑给出症状、先跑的检查与判读,先查证再下结论。
In this repository25 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- claude-session-observabilitySkill
- closeout-report-draftingSkill
- context-guard-hooksSkill
- contract-and-test-infraSkill
- doc-pointer-checkSkill
- first-window-requirementsSkill
- frontend-integration-preflightSkill
- hive-dispatchSkill
- legacy-project-onboardingSkill
- memory-index-foldingSkill
- memory-writingSkill
- merge-and-deploySkill
- open-source-preflightSkill
- pointer-handoffSkill
- repo-scale-reportingSkill
- shared-checkout-safetySkill
- short-book-draftingSkill
- subtraction-reviewSkill
- ticket-desk-usageSkill
- top-audit-dispatchSkill
- verify-agent-claimsSkill
- window-handoff-draftingSkill
- zero-window-taskbook-draftingSkill
The file
Files
这个 skill 是干什么的(人话)
文件开头被悄悄多了看不见的字节、子代理报的内容和远端对不上、部署前检查报版本不一致、命令输出乱码或被吞、测试时过时不过时,用这个 skill 先跑一条对应的检查再下结论。它把六类常见工程坑各写成症状、先跑的检查、怎么看结果三格。不用它,容易把环境问题当成代码问题乱改,或把读错的结论当真写进文档。
分类
分类:单独装即可用
用前填这几个名字
- {{远端主支}}:正文第 2 类比对远端用的主干完整引用名;例:origin/main
- {{全回归命令}}:正文第 6 类连跑两次的整包测试命令;例:python run_tests.py
什么时候用
- 改过的文件在差异里多出一处看不出区别的首行改动,或怀疑编辑工具加了 BOM。
- 子代理或别的窗口报的行号、分支状态和你自己核到的对不上。
- 本机测试全过,部署前检查在服务器上红了,且红处与本次改动无关。
- 命令输出乱码、替换零命中、明明存在的文件说找不到,或脚本在不相干的行报语法错。
- 测试整包偶发红、重跑变绿,要判断是真问题还是环境抖动。
- 多个窗口共用一个检出,状态里冒出别人的改动或推送被拒(转 shared-checkout-safety)。
步骤
- 对照「用前填这几个名字」一节,把正文里的占位换成你们的实值。
- 读本目录
references/engineering-pitfalls-checklist.md照做:按症状找到对应一类,先跑那一类的检查,再按判读下结论。 - 回报带数字和提交短号(如「在某提交上核了 N 个文件,新增 0 个」),不写「应该没问题」这类没跑过检查的话。
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.

