| name | codebase-maintainability-guardrails |
| description | Use for most substantial coding work, especially frontend/fullstack apps, greenfield apps built from scratch, production refactors, UI migrations, and feature work where Codex should preserve maintainable code style: small typed feature-owned files, thin entrypoints, pure domain logic, centralized contracts, behavior-preserving refactors, protected persisted state, feature-owned CSS/Tailwind, focused tests, and real viewport visual QA. |
Codebase Maintainability Guardrails
Use this skill to counter the common coding-model drift toward giant files, vague utility dumps, global CSS sprawl, and cleanup that quietly changes product behavior.
Default Posture
- Treat existing apps as production apps unless the user explicitly says the code is disposable.
- Preserve behavior while refactoring. Do not mix broad cleanup with behavioral changes unless the bug fix is explicit and tested.
- Protect persisted state, stored schemas, localStorage, database rows, and deployed API contracts. Prefer compatibility normalizers and migrations over resets.
- Keep implementation slices buildable and reviewable. Every staged refactor should leave the repo easier for the next agent to edit.
Code Shape Rules
- Keep app entrypoints thin.
main, App, route files, layouts, and top-level stylesheets should orchestrate, not own product behavior.
- Prefer focused modules over huge files. Aim for roughly 250-400 LOC per source file when practical. Anything over 500 LOC needs a reason and should be considered for splitting.
- Split by product feature and behavior, not by vague
utils buckets. Good module names describe the domain, such as messageActions, themeModel, ReferenceImagePicker, providerRetry, or characterDraftWorkflow.
- Separate pure domain logic from React rendering and side effects. Put schemas, reducers, normalizers, prompt builders, retry helpers, provider parsing, and transformations in testable pure modules.
- Centralize frontend/backend contracts and shared request/response types at the boundary between client and server.
- Avoid pass-through prop blobs. Component props should be explicit and behavior-oriented, except for stable domain objects like
message, character, operation, or theme.
- Consolidate duplicate parsing, retry, provider, API, and logging helpers behind small well-named modules.
Frontend And CSS Rules
- Use Tailwind when available, but keep styling feature-owned.
- Keep global CSS limited to reset, tokens, browser fixes, and small shared primitives.
- Use semantic theme tokens as the source of truth. Avoid one-off hard-coded palettes scattered across components.
- Do not allow a prototype screen to grow into a permanent god component. For greenfield apps, create feature folders and typed contracts early.
Safety And Observability
- Add structured client logging and recoverable error boundaries around risky UI surfaces.
- Do not log full private/user-generated content by default. Keep prompt-bearing or user-content-heavy debug data local unless explicitly intended.
- Treat layout regressions as product bugs. Inspect real screenshots across mobile, desktop, iPad/tablet, and ultrawide when UI changes matter.
Testing Standard
- Tests should carry their weight. Prefer focused tests for pure helpers and high-value E2E flows over broad duplicated snapshots.
- Add or update tests for risky paths: migrations, schema compatibility, API contracts, provider parsing, retry behavior, reducers, and user-visible flows.
- For browser/E2E QA, visually inspect screenshots rather than only checking that artifacts were produced.
Before Finishing
Check:
- No entrypoint or route became a god file.
- No source file crossed 500 LOC without an explicit reason or follow-up split.
- No new vague dumping ground such as
utils, helpers, or misc absorbed product behavior.
- Pure logic is testable without rendering React or calling the network.
- Shared contracts are typed and centralized.
- Persisted state remains compatible.
- CSS is feature-owned or token-based.
- The risky behavior is covered by focused tests or a clearly stated verification gap.
- UI changes were visually checked at realistic viewport sizes when relevant.
