菜单
Safe procedure for decomposing a god file (400+ LOC) into a sub-package without breaking any imports. Load when a file exceeds 400 lines or mixes multiple concerns. Implements vibecodex Principles A1 and A8 — folder-instead-of-file with backward-compatible re-exports.
用 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 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.
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).
| name | split-monolith |
| description | Safe procedure for decomposing a god file (400+ LOC) into a sub-package without breaking any imports. Load when a file exceeds 400 lines or mixes multiple concerns. Implements vibecodex Principles A1 and A8 — folder-instead-of-file with backward-compatible re-exports. |
A file split done wrong breaks every caller. Follow this procedure exactly — it is reversible at every step.
wc -l app/services/<file>.py
| Lines | Action |
|---|---|
| < 400 | Do not split — you're solving a non-problem |
| 400–600 | Plan the split now, execute when convenient |
| > 600 | Split immediately (Principle A7 hard cap) |
Also ask: does this file mix multiple concerns? A file that is long but cohesive is better than a premature split.
Do NOT split by size. Split by type of responsibility.
Good splits (by domain):
wallet_service.py (1200 LOC) →
wallet/user.py ← user-facing operations (charge, refund)
wallet/admin.py ← admin operations (top-up, override)
wallet/history.py ← read-only queries
Good splits (by layer):
generation_service.py (1000 LOC) →
generation/orchestrator.py ← coordinates the flow
generation/cost.py ← cost calculation logic
generation/storage.py ← result persistence
Bad splits (by size only — don't do this):
big_service.py →
big_service_part1.py ← meaningless
big_service_part2.py ← meaningless
Write the target structure before touching any file.
mkdir app/services/<domain>/
Do NOT move any code yet.
For each sub-file, copy (not move) the relevant functions:
# Create the new file with the relevant subset
touch app/services/<domain>/user.py
# Copy relevant classes/functions from the original
Each sub-file must:
* imports)__init__.py with ALL old names re-exportedThis is the most important step. Every name that existed in the original file must still be importable from the same path.
# app/services/<domain>/__init__.py
# Principle A8: re-export everything so callers don't change.
from app.services.<domain>.user import CreditsUserService
from app.services.<domain>.admin import CreditsAdminService
from app.services.<domain>.user import get_credits_user_service
# Backward-compat alias if the old class had a different name
CreditsService = CreditsUserService # old name → new class
__all__ = [
"CreditsUserService",
"CreditsAdminService",
"CreditsService", # backward compat
"get_credits_user_service",
]
# Check every file that imported from the old module still works
python3 -c "from app.services.<domain> import <OldClassName>"
python3 -c "from app.services.<domain> import <AnotherClass>"
# Run the full test suite
pytest tests/ -x -q
All tests must be GREEN before deleting the original file.
Only after Step 5 passes:
rm app/services/<original_file>.py
Run tests again:
pytest tests/ -x -q
bash scripts/lint-architecture.sh
Both must pass.
| Mistake | Consequence | Prevention |
|---|---|---|
Split before writing __init__.py | Import errors everywhere | Always create __init__.py first |
| Split by size, not responsibility | Sub-files still coupled | Ask: "what is the single job of this file?" |
| Forget to re-export old names | Callers break silently | List every public name before splitting |
| Move code instead of copy+verify | Can't roll back | Copy first, delete only after tests pass |
| Split and refactor at same time | Impossible to debug | One PR = one split. No logic changes. |
The split was done correctly when:
__init__.py re-exports every name that existed beforepython3 -c "from app.services.<domain> import <OldName>" workspytest tests/ -x -q is greenbash scripts/lint-architecture.sh exits 0