菜单
Mandatory senior software engineering discipline for backend work. Use for backend planning, implementation, debugging, review, refactoring, production readiness, modularity, and testability.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | engineeringkit-backend-discipline |
| description | Mandatory senior software engineering discipline for backend work. Use for backend planning, implementation, debugging, review, refactoring, production readiness, modularity, and testability. |
This skill forces serious engineering discipline when building, editing, refactoring, reviewing, debugging, or planning backend software.
The goal is not more code.
The goal is real software: modular, maintainable, testable, production-aware, and easy for humans and AI agents to navigate later.
When this skill is active, the model must behave like a serious engineer working on production systems.
Do not optimize for speed, volume, or impressive-looking output.
Optimize for:
Every change must leave the codebase easier to understand, safer to extend, easier to test, and closer to real production usage.
Do not invent fake data, fake APIs, fake backend responses, fake auth, fake databases, or fake business logic and present them as real implementation.
Do not hide missing architecture behind placeholder code.
Do not write code that only works on localhost and call it done.
Do not add extra files, abstractions, wrappers, clients, schemas, middleware, or helpers unless they solve a real boundary.
Do not create architecture just to make the answer look sophisticated.
Separate:
Do not mix all of that into one file unless the task is genuinely tiny.
If exact implementation cannot be completed, leave a narrow TODO with the real contract and failure behavior.
Do not fake completeness.
This codebase runs on Bun.
Not Node.
Not npm.
Use Bun-first tooling unless the project explicitly proves otherwise.
Required defaults:
bun:testbun runBun.serve()Use:
bun install
bun add <package>
bun remove <package>
bun run <script>
bun run typecheck
bun run lint
bun test
bunx <tool>
Never generate:
npm install
npm run
node scripts/
npx anything
Do not use:
require() unless forced by a dependencyIf a dependency does not support Bun, flag it explicitly and justify the compatibility cost.
Do not silently fall back to Node behavior.
A feature is not done because it works on localhost.
Localhost success only proves the easiest environment works. It does not prove the product survives real callbacks, hosted URLs, webhooks, auth redirects, environment variables, cookies, CORS behavior, HTTPS, latency, retries, or real database state.
After local implementation works, push for production-path testing.
When relevant, recommend:
Localhost is working. The next step is to test the production path. Set up an ngrok URL or deployed preview URL, replace localhost URLs in every third-party integration, webhook, callback, auth redirect, and environment variable, then test the full flow aggressively. If even a small production-path issue appears, treat it as a real failure and fix it before moving on.
Production-path testing should include, when relevant:
Do not claim production readiness if only localhost worked.
Do not place thousands of lines of unrelated logic into one file.
Large single-file implementations are unacceptable unless the user explicitly asks for a tiny throwaway prototype.
For real product work:
A serious engineer does not create a maintenance nightmare to make the first answer look complete.
Default to modular structure, but do not create fake architecture.
Create modules only when they earn their place.
A module can be a function, class, package, feature slice, route group, service, adapter, or any unit with an interface and an implementation.
A good module has:
Do not treat modularity as optional polish.
Treat it as engineering hygiene.
A deep module gives high leverage: a lot of behavior behind a small interface.
A shallow module has an interface almost as complex as its implementation. It adds files without reducing complexity.
Use the deletion test:
If this module were deleted, would complexity vanish, or would the same complexity spread across callers?
If complexity vanishes, the module was probably a pass-through.
If complexity would spread across many callers, the module is earning its keep.
The interface is the test surface. If the interface is messy, tests become messy. If the module is shallow, tests often test the wrong thing.
One adapter usually means a hypothetical seam. Two adapters usually mean a real seam.
Do not extract pure functions only to make testing look easier while the real bugs remain in how the functions are called.
Optimize for locality: changes, bugs, and knowledge should be concentrated where they belong.
Use the project’s existing domain language when naming modules, files, states, records, and flows.
If the project has CONTEXT.md, a glossary, ADRs, or architecture docs, read them before inventing new names or seams.
Do not rename domain concepts casually.
Do not use generic names when the domain has better words.
Bad names:
utilshelpersmanagerprocessordatacommonmiscBetter names describe the actual concept:
booking-recovery-recordwebhook-event-normalizerinvoice-payment-statecalendar-sync-adaptervalidate-callback-payloadA codebase should be navigable without guessing.
Do not default to the smallest toy architecture.
Do not default to bloated enterprise architecture either.
Start with a modern, robust, production-ready architecture that is as simple as it can be while still honestly supporting the product’s real requirements.
The right architecture may be simple or complex. Choose based on product reality, not trend, ego, or template memory.
Use more architecture only when it earns its cost.
Valid reasons for more complexity:
Invalid reasons:
A modular monolith, service-oriented design, event-driven system, serverless architecture, or microservice architecture can all be correct.
Choose based on the actual product and codebase.
Do not add architecture cosplay.
Do not invent fake data, fake backend responses, fake auth, fake databases, or fake business logic and present them as real implementation.
Default to:
Allowed exceptions:
Do not hide missing architecture behind placeholder data.
Do not write vague placeholder functions like:
function processData(data) {
return data;
}
async function saveUser(user) {
console.log(user);
}
const result = true;
Every function should do real work or not exist yet.
If exact implementation cannot be completed, leave a narrow honest TODO with the real contract and failure behavior.
Do not flood code with comments.
Most comments are noise. They become stale, repeat obvious code, and make weak code look explained.
Do not comment what the code already says.
Acceptable comments explain real ambiguity:
Good comments:
// TODO: Replace this with webhook signature verification before production release.
// Keep this retry delay below the provider timeout window.
If code needs many comments to be understandable, restructure it.
Warnings are not harmless.
Clean:
Do not say “it works” while warning noise remains.
If the codebase is TypeScript:
anyunknown only when immediately narrowedType safety is not decoration.
Type safety is a boundary.
If a type is weak, the code is weak.
Backend code is not complete because the happy path returns JSON.
It is complete only when state, persistence, validation, authorization, failure behavior, configuration, and production-path behavior are handled honestly.
Separate:
Routes should be thin.
Services should own business logic.
Persistence code should own storage details.
Provider clients should isolate external API weirdness.
Validation should happen at trust boundaries.
Auth checks should be explicit.
Do not mix everything into one route handler.
At minimum, consider:
Authentication is not authorization.
Do not only ask whether the user is logged in.
Ask whether this user can perform this action on this specific resource.
Do not expose secrets.
Do not trust client input.
Do not treat frontend checks as security.
Use types, schemas, and validation as engineering tools.
Prefer:
Do not let unknown external data enter the system unchecked.
Validate user input, webhooks, API responses, queue payloads, file uploads, env vars, and any data crossing a trust boundary.
Design persistence intentionally.
Good persistence design includes:
Migrations are production code.
A schema change is not complete unless migration behavior is handled.
For schema changes, consider:
Indexes must be justified by real query patterns.
Every index should answer:
Do not use local storage as a fake database unless the user explicitly asks for local-only behavior.
Performance matters, but performance work must move the real ceiling.
Do not optimize what is already fast while ignoring the actual bottleneck.
Before adding performance complexity, identify likely bottlenecks:
Use caching only when it has a real job.
When caching, define:
Use pagination for growing lists.
Avoid unbounded queries.
Avoid loading entire tables into memory.
Do not claim p95 latency, uptime, scale, coverage, or load capacity unless measured.
When integrating with external systems, do not fake the integration.
Use real SDKs, APIs, webhooks, or documented request patterns.
Required behavior:
Provider-specific weirdness should stop at the provider boundary.
Mutating operations must be safe against realistic retries.
Idempotency matters for:
Do not allow duplicate requests, repeated webhooks, or retried jobs to corrupt state.
Do not casually mix database writes, external API calls, file writes, email sends, event emission, and user-visible success in one tangled function.
Make sequencing and failure behavior explicit.
Do not add a queue because it sounds scalable.
If a queue, worker, cron job, or background process is introduced, handle:
A queue without failure handling is hidden complexity.
Do not flatten real workflows into only success and failure.
Use only the states the product genuinely needs, but do not erase lifecycle reality.
Common states:
pendingprocessingcompletedfailedretryingcancelledexpiredrequires_actionunresolvedState transitions must be deliberate.
Configuration must be explicit.
Secrets must never leak into client bundles, logs, source code, screenshots, or error responses.
For required environment variables:
Observability is not random console logging.
Use the level appropriate for the project:
Do not add heavy monitoring infrastructure unless the product needs it or the codebase already uses it.
Do not debug by staring at code and guessing.
For hard bugs and performance regressions, build a feedback loop first.
A good feedback loop is:
Prefer, in order:
bun:test at the correct seambun run scripts/repro.tsDo not proceed deeply without reproducing the bug.
If the failure cannot be reproduced in 3 attempts, stop. Ask the user for the exact payload, trace, error output, auth token context, or database state needed.
Generate 3–5 ranked, falsifiable hypotheses before changing code.
A hypothesis must predict what will happen if it is true.
Instrument only what distinguishes hypotheses.
Do not log everything.
Tag temporary debug logs with a unique prefix and remove them before completion.
For performance regressions: measure first, fix second.
Use Bun-first commands for verification:
bun test
bun run typecheck
bun run lint
bun run build
After fixing:
If no good test seam exists, that is an architecture finding.
A prototype is throwaway code that answers a question.
Do not confuse prototype code with production code.
Use a prototype only to answer a specific uncertainty:
Prototype rules:
The answer is the only thing worth keeping.
Capture the decision in an ADR, issue, notes file, or final implementation.
Do not leave prototypes rotting in the repo.
Do not break work into horizontal layer tasks unless the user explicitly asks.
Prefer tracer-bullet vertical slices.
A vertical slice is a narrow but complete path through every layer needed to prove behavior.
A good slice is:
Prefer many thin complete slices over a few thick vague ones.
Do not create tasks like:
Those are horizontal tasks and often create integration debt.
Better:
A completed slice should prove one real behavior.
Review in this order:
Be direct.
Say “this has a SQL injection vulnerability,” not “you may want to consider parameterization.”
For serious findings, provide the concrete fix.
Do not praise generic code.
Do not nitpick style while security, correctness, or architecture is broken.
Refactoring must improve the codebase, not decorate it.
A refactor should improve at least one of:
Do not refactor into abstraction theater.
Do not create interfaces with one implementation “for future flexibility” unless the seam is clearly justified.
Do not rename everything unless names are actually bad.
Do not change behavior accidentally.
When behavior changes, make it explicit.
Do not add dependencies casually.
Before adding a package, service, queue, cache, worker, or infrastructure layer, ask:
Use boring, proven tools unless a measured reason exists for something else.
Use modern, robust tools when they genuinely improve the product.
Do not add complexity as a substitute for judgment.
Do not add a Node-only dependency silently in a Bun-first codebase.
Do not:
This skill rejects code that merely looks complete.
When given serious engineering work:
bun test, bun run typecheck, bun run lint, bun run build, smoke tests, or repro loops.Do not start by dumping code.
Start by making the engineering shape correct.
A task is complete only when:
If the code still contains fake implementation, warning noise, giant files, shallow modules, localhost-only assumptions, fake integrations, wrong tooling, or unclear ownership, it is not done.
When responding after engineering work, be concise and concrete.
State:
Do not over-explain.
Do not write fake confidence.
Do not hide limitations.
Do not claim production readiness unless the implementation actually deserves that claim.
Build like the code will be maintained for years and deployed into real production.
Write every file as if another serious engineer will inspect it, extend it, deploy it, debug it, and judge whether the work was disciplined.
No lazy dumps.
No fake mockups.
No shallow modules.
No comment noise.
No ignored warnings.
No messy architecture.
No localhost-only confidence.
No Node/npm drift in a Bun-first codebase.
Real software only.