{"name":"claude-lessons","version":"2026-08-05","source":"https://tools.cooconsbit.com/claude-lessons","categories":{"verify":{"zh":"验证与实事求是","en":"Verification & Honesty","emoji":"✅","skillDesc":{"zh":"验证与排查守则——声明任务完成、排查故障、检查限制条件前查阅","en":"Verification rules — consult before claiming done, debugging, or checking hard limits"}},"shell":{"zh":"Shell 与文件操作","en":"Shell & File Operations","emoji":"🐚","skillDesc":{"zh":"Shell 安全守则——执行批量文件操作、重命名、删除、写临时脚本前查阅","en":"Shell safety rules — consult before batch file ops, renames, deletions, or throwaway scripts"}},"api":{"zh":"外部 API 集成","en":"External API Integration","emoji":"🔌","skillDesc":{"zh":"外部 API 集成守则——接入第三方 API、写重试逻辑、配置代理时查阅","en":"External API rules — consult when integrating third-party APIs, writing retries, or configuring proxies"}},"ci":{"zh":"Git / CI / 部署","en":"Git / CI / Deployment","emoji":"🚀","skillDesc":{"zh":"CI/部署守则——排查构建失败、触发部署、打版本 tag 时查阅","en":"CI/deploy rules — consult when debugging builds, deploying, or tagging versions"}},"genai":{"zh":"AI 生成内容","en":"AI-Generated Content","emoji":"🎨","skillDesc":{"zh":"AI 生成内容守则——调用文生图/生成式接口、写生成 prompt 时查阅","en":"GenAI content rules — consult when calling image/text generation APIs or writing generation prompts"}},"pipeline":{"zh":"自动化管线","en":"Unattended Pipelines","emoji":"⚙️","skillDesc":{"zh":"自动化管线守则——搭建 cron/无人值守流程、串联异步第三方步骤时查阅","en":"Pipeline rules — consult when building cron/unattended flows or chaining async third-party steps"}}},"lessons":[{"id":"verify-before-done","category":"verify","severity":"high","tier":"hot","version":1,"updated":"2026-08-05","lastConfirmed":"2026-08-05","rule":{"zh":"未验证不声明「完成/修好了」——跑测试、看日志、发真实请求拿到证据再下结论","en":"Never claim \"done/fixed\" without verification — run the test, read the log, or fire a real request first"}},{"id":"measure-dont-eyeball","category":"verify","severity":"medium","tier":"hot","version":1,"updated":"2026-08-05","lastConfirmed":"2026-07-29","rule":{"zh":"长度/数量类硬限制必须脚本实测，「目测砍了不少」不算验证","en":"Hard limits on length/count must be measured by script — \"looks short enough now\" is not verification"}},{"id":"code-over-docs","category":"verify","severity":"medium","tier":"warm","version":1,"updated":"2026-08-05","lastConfirmed":"2026-07-25","rule":{"zh":"文档与代码冲突时以代码为准，并顺手把文档改对","en":"When docs contradict code, trust the code — and fix the docs while you're there"}},{"id":"find-real-log-path","category":"verify","severity":"medium","tier":"warm","version":1,"updated":"2026-08-05","lastConfirmed":"2026-08-05","rule":{"zh":"判断「没流量/没日志」前，先用 nginx -T 等命令确认日志的真实写入路径","en":"Before concluding \"no traffic / no logs\", confirm where logs are actually written (e.g. nginx -T)"}},{"id":"batch-rename-collision","category":"shell","severity":"high","tier":"hot","version":1,"updated":"2026-08-05","lastConfirmed":"2026-08-05","rule":{"zh":"批量 mv/重命名必须 mv -n 或先检测目标存在——撞名 = 静默丢数据","en":"Batch mv/rename must use mv -n or check the target first — name collisions silently destroy data"}},{"id":"rg-r-is-replace","category":"shell","severity":"medium","tier":"warm","version":1,"updated":"2026-08-05","lastConfirmed":"2026-07-24","rule":{"zh":"怀疑「文件被篡改/工具出鬼」前先检查自己的命令 flag——如 rg 的 -r 是 --replace 不是递归","en":"Before suspecting \"file tampered / tool haunted\", check your own flags — rg's -r means --replace, not recursive"}},{"id":"tmp-inside-project","category":"shell","severity":"medium","tier":"warm","version":1,"updated":"2026-08-05","lastConfirmed":"2026-08-03","rule":{"zh":"临时脚本放项目内 ./tmp/，不放系统 /tmp——脚本在 /tmp 找不到项目依赖","en":"Put throwaway scripts in the project's ./tmp/, not system /tmp — Node can't resolve project deps from /tmp"}},{"id":"http200-business-error","category":"api","severity":"high","tier":"hot","version":1,"updated":"2026-08-05","lastConfirmed":"2026-08-05","rule":{"zh":"部分 API（MiniMax 等）业务错误藏在 HTTP 200 的 body 错误码里——只判 HTTP 状态 = 没做错误处理","en":"Some APIs (MiniMax etc.) hide business errors inside HTTP 200 bodies — checking only the HTTP status = no error handling"}},{"id":"retry-only-ratelimit","category":"api","severity":"medium","tier":"warm","version":1,"updated":"2026-08-05","lastConfirmed":"2026-08-05","rule":{"zh":"只有限流值得退避重试；鉴权/余额/内容拦截类错误重试一万次也是同一个结果，直接抛","en":"Only rate limits deserve backoff retries; auth/balance/content-block errors return the same answer ten thousand retries later — throw immediately"}},{"id":"proxy-needs-scheme","category":"api","severity":"medium","tier":"warm","version":1,"updated":"2026-08-05","lastConfirmed":"2026-08-05","rule":{"zh":"代理环境变量必须带 http:// 前缀；且 gRPC 认 grpc_proxy、REST 认 HTTPS_PROXY，各认各的","en":"Proxy env vars need the http:// scheme prefix; and gRPC reads grpc_proxy while REST reads HTTPS_PROXY — each honors its own"}},{"id":"seconds-fail-is-network","category":"ci","severity":"medium","tier":"warm","version":1,"updated":"2026-08-05","lastConfirmed":"2026-07-29","rule":{"zh":"CI 秒级失败 = 网络/鉴权问题，分钟级失败才可能是编译/依赖——先看失败发生在第几秒","en":"CI failing in seconds = network/auth; only minute-scale failures are compile/deps — check the failure timestamp first"}},{"id":"bump-version-before-build","category":"ci","severity":"medium","tier":"warm","version":1,"updated":"2026-08-05","lastConfirmed":"2026-07-29","rule":{"zh":"改动后先 bump 版本号再触发构建——同版本 tag 重复构建会因竞态互相覆盖","en":"Bump the version before triggering a build — rebuilding the same tag races and overwrites itself"}},{"id":"ai-mood-code-information","category":"genai","severity":"high","tier":"warm","version":1,"updated":"2026-08-05","lastConfirmed":"2026-08-05","rule":{"zh":"AI 生图管氛围，程序管信息：标题/数字/品牌元素用代码合成，别让模型画（中文必乱码）；宽幅构图写明确指令（主体居中、铺满全宽），别用「留白」这类审美形容词","en":"AI images own the mood, code owns the information: composite titles/numbers/brand marks programmatically (model-drawn CJK text is always garbled); for wide banners give explicit composition orders (subject centered, filling the full width) — never aesthetic adjectives like \"negative space\""}},{"id":"await-async-before-save","category":"pipeline","severity":"high","tier":"warm","version":1,"updated":"2026-08-05","lastConfirmed":"2026-08-05","rule":{"zh":"保存/提交前必须等第三方的异步过程真正完成——轮询目标状态，不要 sleep 猜时间","en":"Before saving/submitting, wait for third-party async work to actually finish — poll for the target state, don't sleep and guess"}},{"id":"fallback-every-stage","category":"pipeline","severity":"high","tier":"hot","version":1,"updated":"2026-08-05","lastConfirmed":"2026-08-05","rule":{"zh":"无人值守管线的每一环都要有降级回落——AI/外部接口天生不可靠，靠兜底不靠祈祷","en":"Every stage of an unattended pipeline needs a fallback — AI and external APIs are inherently flaky; survive by degradation, not prayer"}}]}