菜单
Systematic 5-step backend debugging flow for AI-coded FastAPI apps. Load this skill when a bug is reported, a test fails, or unexpected behavior appears in any backend layer. Forces layer isolation before touching code — prevents the "touch 8 files and make it worse" pattern.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Checklist for adding a new AI provider (image, video, text, audio) that satisfies all 5 integration principles — ACL, bulkhead, idempotency, observability, and contract test. Load when integrating any new external AI API. Prevents the most common mistake of pasting httpx calls directly into a service.
Systematic 5-step debugging flow for Next.js 15 + React 19 + TypeScript apps. Load when a UI bug is reported, hydration error appears, Server Action returns wrong data, or cache invalidation fails. Forces layer isolation (server vs client, action vs component, cache vs render) before touching code — prevents "fix here, break there" cascades.
Systematic 5-step debugging flow for Go 1.22+ services. Load when a test fails, a goroutine leaks, a downstream provider hangs, errors lose context, or production logs are unhelpful. Forces layer isolation (handler vs service vs repo vs provider) and runs the 5 most common Go antipattern greps before any code change — prevents the "add a goroutine to fix a slow handler" cascade.
Pre-flight checklist for adding a new feature to a Go 1.22+ service. Load when creating a new endpoint, internal package, external integration, or background worker. Forces "accept interfaces, return structs", `context.Context` propagation, error wrapping, and bulkhead-per-provider from line one — prevents the most common AI failures (God interfaces, raw goroutines without errgroup, http.DefaultClient everywhere, panic on errors).
Pre-flight checklist for adding a new feature to a Next.js 15 + TypeScript app. Load when creating a new page, route, server action, or feature module. Forces feature-driven colocation, RSC-first thinking, and the typed cache-tag pattern from line one — prevents the most common AI failures (1500-line page.tsx, 'use client' on the layout, scattered revalidateTag magic strings).
Pre-flight checklist that must complete before writing the first line of code for any new feature. Load this skill when starting a new endpoint, service method, or integration. Prevents the most common AI-coding failure mode — writing code before defining layer boundaries, which leads to features that work today and break in 3 months.
| name | debug-backend |
| description | Systematic 5-step backend debugging flow for AI-coded FastAPI apps. Load this skill when a bug is reported, a test fails, or unexpected behavior appears in any backend layer. Forces layer isolation before touching code — prevents the "touch 8 files and make it worse" pattern. |
Stop. Do not edit any file yet. Work through these 5 steps in order.
Run these greps to find where the bug lives. Check one layer at a time.
# Is it a routing problem? (wrong status code, missing auth, bad request parsing)
grep -n "HTTPException\|status_code\|Depends(" app/routers/<file>.py
# Is it a service logic problem? (wrong calculation, wrong state transition)
grep -n "def \|raise \|return " app/services/<file>.py
# Is it a repository problem? (wrong query, missing user_id scope, transaction issue)
grep -n "SELECT\|filter\|where\|FOR UPDATE" app/repositories/<file>.py
# Is it a provider problem? (timeout, wrong response shape, missing error handling)
grep -n "httpx\|raise\|return\|except" app/providers/<file>.py
Decision: fix only in the layer where the bug lives. Never fix a service bug in the router.
These cause 80% of production bugs in AI-coded backends. Grep for each:
# Antipattern 1: SQLAlchemy Session leaked into services
grep -rn "AsyncSession\|Session\|from sqlalchemy" app/services/
# Antipattern 2: Provider returning raw dict instead of domain type
grep -rn "return {" app/providers/
# Antipattern 3: Business logic in router (calculation, state change, external call)
grep -c "await.*service\|await.*repo\|if.*balance\|FOR UPDATE" app/routers/*.py
| Result | Root cause | Principle |
|---|---|---|
| Session in services | Hexagonal boundary broken | B1 |
return {} from provider | Missing ACL | B3 |
| Logic in router | Layer violation | A3 / code-standards |
No user_id filter in query | Multi-tenancy gap | security-rules |
Before changing any production code, write a failing test that captures the exact bug.
# Template: place in tests/unit/ or tests/integration/
async def test_<bug_description>():
# Arrange: minimal setup that triggers the bug
repo = FakeCreditsRepo()
repo.seed_balance("user-1", Decimal("5.00"))
service = CreditsUserService(repo=repo)
# Act: call the exact code path that fails
with pytest.raises(ValueError, match="Insufficient balance"):
await service.charge("user-1", Decimal("10.00"), idempotency_key="idem-1")
# Assert: prove the invariant that was violated
assert await repo.get_balance("user-1") == Decimal("5.00") # not negative
Run it: pytest tests/unit/test_<file>.py::test_<bug_description> -v
It must be RED before you fix anything.
Minimum change. No opportunistic refactoring. No unrelated cleanup.
Router bug → fix only app/routers/
Service bug → fix only app/services/
Repo bug → fix only app/repositories/
Provider bug → fix only app/providers/
After fixing: run the reproducing test. It must turn GREEN.
pytest tests/unit/test_<file>.py::test_<bug_description> -v
# Expected: PASSED
bash scripts/lint-architecture.sh
Must exit 0. If a check fails, the fix introduced a new architecture violation — revert and fix properly.
| Error | Where to look first | Likely cause |
|---|---|---|
422 Unprocessable Entity | Router — Pydantic schema | Wrong field type or missing required field |
500 Internal Server Error | Service — exception not caught | Provider returned unexpected shape (dict not JobResult) |
KeyError: 'url' | Provider — ACL missing | Provider response changed, parser not updated |
InsufficientFunds on correct balance | Repo — concurrent hold | Two requests raced, no FOR UPDATE lock |
401 on authenticated route | Router — Depends(get_current_user_id) missing | Auth dependency not wired |
| Test passes, prod fails | Repo — fake vs real diverged | FakeCreditsRepo doesn't match CreditsRepoProtocol |
| Logs silent on error | Service — bare except: | Exception swallowed, add logger.exception(...) |
The skill was applied correctly when:
bash scripts/lint-architecture.sh exits 0