codex-dev-norms

name	codex-dev-norms
description	Use when the user asks to modify code, implement features, fix bugs, refactor code, review changes, analyze repositories, create implementation plans, apply repository conventions, enforce development standards, validate testing requirements, or produce code-related final responses.

Codex Dev Norms

Use this skill when the task is explicitly about defining, maintaining, auditing, or applying Codex development norms.

When to use

• The user asks to create or update a Codex skill, repository rule, or development guideline.
• The user asks whether an implementation, review, or final response follows the repository norms.
• The user explicitly asks to apply these norms during implementation or code review.
• The task is to define boundaries for code changes, APIs, tests, comments, frontend/backend work, git safety, or response style.
• The task is to convert informal team habits into reusable Codex guidance.
• For coding tasks, use only the reference files relevant to the task instead of applying every rule broadly.

Workflow

1. Identify whether the request is about behavior, process, or repository conventions.
2. Read only the relevant reference files under references/ for the current task.
3. Keep rules concrete, testable, and short enough to be followed during active coding work.
4. Prefer repository-specific guidance over generic best practices when they conflict.
5. When adding or applying a rule, make sure it changes behavior in a visible way.

Reference map

• Read references/code-change-boundary.md for minimal-change policy, edit scope control, and refactor restrictions.
• Read references/api-integration.md when API fields, request boundaries, response structures, or backend contracts are involved.
• Read references/backend-business-logic.md when changing backend flow, business rules, validation boundaries, persistence flow, or side effects.
• Read references/testing.md when adding, updating, or reviewing tests.
• Read references/docs-and-comments.md when editing comments, local documentation, or explanatory text in code.
• Read references/frontend-implementation.md for component structure, extraction rules, composable boundaries, and UI-change limits.
• Read references/global-frontend.md for frontend-wide change restrictions, encoding requirements, and naming stability rules.
• Read references/naming-and-files.md when introducing new files, choosing names, or reviewing organization boundaries.
• Read references/type-convergence.md when reviewing duplicate types, repeated unions/enums, or runtime/type source-of-truth issues.
• Read references/state-management-boundary.md when changing store usage, URL query state, server state, or repeated async state logic.
• Read references/side-effects-and-subscriptions.md when changing event listeners, subscriptions, timers, watchers, or lifecycle side effects.
• Read references/ui-style-convergence.md when reviewing repeated UI variants, class lists, tokens, or base component opportunities.
• Read references/constants-and-magic-values.md when repeated business values, cache keys, storage keys, routes, regexes, or defaults are involved.
• Read references/engineering-config-convergence.md when reviewing repeated package configs, scripts, dependency version policy, or build/test presets.
• Read references/dependency-management.md before adding, replacing, or broadening third-party dependencies.
• Read references/error-handling-and-logging.md when changing failure handling, fallbacks, or logs.
• Read references/git-workspace-safety.md when working in a dirty tree, touching generated files, or making git-sensitive changes.
• Read references/code-review.md when performing a review or summarizing review findings.
• Read references/final-response.md before writing the final user-facing completion message.
• Read references/convergence-and-abstraction.md only for refactoring, duplicate-code cleanup, abstraction design, or architecture-boundary review.

File selection guidance

• For small bug fixes or narrow feature work, start with code-change-boundary.md.
• Add api-integration.md only if the task touches API definitions or request handling.
• Add backend-business-logic.md when the task changes business rules, backend write paths, or validation flow.
• Add testing.md only if tests are being added, changed, or reviewed.
• Add the frontend references only when the task affects frontend code.
• Add naming-and-files.md when creating or reorganizing files, exports, or public entry points.
• Add type-convergence.md only when type duplication or runtime/type drift is part of the task.
• Add state-management-boundary.md only when state ownership or repeated state behavior is part of the task.
• Add side-effects-and-subscriptions.md only when side-effect lifecycle or cleanup behavior is part of the task.
• Add ui-style-convergence.md only when repeated UI styling or variants are part of the task.
• Add constants-and-magic-values.md only when repeated values represent shared behavior or business meaning.
• Add engineering-config-convergence.md only for config, monorepo, script, build, test, or dependency-policy convergence work.
• Add dependency-management.md before introducing or replacing packages.
• Add error-handling-and-logging.md when changing error boundaries, fallbacks, or diagnostics.
• Add git-workspace-safety.md when the workspace has unrelated changes or the task touches git-sensitive files.
• Add code-review.md for review-style tasks.
• Add final-response.md when preparing the final response.
• Avoid loading convergence-and-abstraction.md during simple edits unless the task explicitly involves refactoring.

Authoring guidance

• Write norms as direct instructions.
• Avoid duplicating the same rule in multiple files.
• Prefer examples only when a rule is easy to misread.
• Split long guidance by topic so future edits stay local.
• Keep this file as a routing layer; put detailed rules in references/.