Agent Skills › trycompai/crm › pit-of-success

pit-of-success

GitHub

一种代码重构策略，旨在通过修改公共接口（如API、Hook、Props等）将正确行为设为默认路径，消除使用陷阱。核心步骤包括识别调用点、运行足部测试、将不变量移入接口并删除绕过逻辑，确保未来维护者能直观且安全地调用。

.agents/skills/pit-of-success/SKILL.md trycompai/crm

Trigger Scenarios

发现API或组件存在易误用的设计缺陷需要重构代码以提高健壮性和易用性公共接口允许调用者产生非预期行为

Install

npx skills add trycompai/crm --skill pit-of-success -g -y

More Options

Non-standard path

npx skills add https://github.com/trycompai/crm/tree/release/.agents/skills/pit-of-success -g -y

Use without installing

npx skills use trycompai/crm@pit-of-success

指定 Agent (Claude Code)

npx skills add trycompai/crm --skill pit-of-success -a claude-code -g -y

安装 repo 全部 skill

npx skills add trycompai/crm --all -g -y

预览 repo 内 skill

npx skills add trycompai/crm --list

SKILL.md

Frontmatter

{
    "name": "pit-of-success",
    "description": "Review or refactor code so the correct behavior is the default path; use when APIs, setters, hooks, helpers, or component props have footguns where a natural call bypasses required semantics.",
    "user-invocable": true
}

Pit of Success

Make misuse hard and the obvious call correct.

Steps

Find the public seam being used: exported function, hook return value, setter, component prop, route body, schema, or command. Then search every caller of that seam. Done when you know the natural call a future maintainer would write.
Run the footgun test: “If someone does the obvious thing without knowing the hidden helper or convention, does behavior break?” Examples: setSelection(null) should mean the product’s normal clear behavior; a schema should reject states the UI never wants; a prop should not require sibling props in the right combo.
Move the invariant into the seam. Prefer, in order:
- make the existing API do the safe thing,
- narrow the type/schema so bad states cannot be represented,
- rename/split the API so the dangerous path is explicit,
- only then add a helper, and only if all natural callers use it.
Delete bypasses and duplicate meanings. Replace local wrappers, parallel helper names, and comments that explain the trap with one shared implementation at the seam.
Prove the pit with one check: a focused test or type/schema assertion showing the obvious call now preserves behavior, plus a grep confirming no caller still uses the old footgun.

Rules

Do not fix only the named callsite. If the seam is wrong, fix the seam.
Do not rely on “remember to call this helper first” when callers can still call the raw API.
Do not add comments as a substitute for making misuse impossible or obvious.
Keep the diff boring: one invariant, one owner, no speculative abstraction.
If compatibility prevents changing the seam, name the dangerous API accordingly and expose a safe default API beside it.