Codex Engineering Guardrails

View saved version →

---
name: code-verification
description: Independently review, test, diagnose, and verify software against explicit requirements, repository standards, and material risks using traceable fresh evidence. Use when Codex is asked to review code or a diff, inspect a pull request, diagnose a failing check without changing code, run or assess tests, validate a bug fix or feature, audit code quality, identify coverage gaps, judge release readiness, or report whether an implementation is correct. Default to read-only source inspection and existing checks; create or change tests only when explicitly requested, and do not modify production code unless the user separately authorizes a fix.
---

# Code Verification

Determine what the evidence actually establishes. Keep verification independent from implementation assumptions, distinguish requirements from general quality, and do not repair findings under a review-only request.

## Preserve verification independence

- Treat the user's explicit requirements and final decisions as authoritative.
- Default to read-only source inspection. Running existing checks is allowed, including normal temporary build or cache output, but do not edit source, tests, configuration, lockfiles, or infrastructure without explicit authorization.
- Do not install dependencies, alter external systems, deploy, commit, push, or fix findings unless those actions are separately in scope.
- Inspect applicable repository instructions, the current status, and the exact diff or target before drawing conclusions. Preserve all user-owned changes.
- Evaluate the implementation against requirements and independent invariants, not against its own structure or comments.
- Report adjacent findings without expanding the audit target.

If the user asks to add tests, enter a bounded test-writing mode: change only authorized tests, fixtures, and indispensable test infrastructure. A failing test that exposes a production defect is a valid result. Do not alter production code merely to make the new test pass without a separate command.

## Define the verification contract

Establish:

1. The target: files, diff, commit range, component, API, artifact, or running behavior.
2. The baseline to compare against.
3. Explicit requirements and acceptance criteria.
4. Repository standards and supported environments.
5. Material failure modes and risk boundaries.
6. Allowed actions and available resources.
7. The evidence necessary for a pass decision.

When the specification is incomplete, separate confirmed requirements from assumptions. Ask only when an ambiguity would change the verdict or make a check unsafe.

## Build traceability before execution

Create a compact working matrix:

`requirement or risk -> observable behavior -> best evidence -> result`

Keep two independent review axes:

- **Specification:** Does the implementation do exactly what was requested, including edge and failure behavior?
- **Engineering quality:** Is it correct, understandable, maintainable, secure, efficient enough, and consistent with repository conventions?

Passing one axis must not conceal failure on the other. Read [references/verification-matrix.md](references/verification-matrix.md) when selecting checks, evaluating test quality, assigning severity, or coordinating parallel verification.

## Review in evidence-producing passes

### 1. Establish the changed surface

- Resolve the exact baseline and final state.
- Inspect changed callers, consumers, schemas, configuration, generated artifacts, and public interfaces.
- Identify behavior that may change indirectly, including error paths and state transitions.

### 2. Inspect tests before trusting them

- Map tests to requirements and important risks.
- Prefer tests through public behavior or stable seams.
- Verify that expected values come from a specification, invariant, standard, known example, or independent calculation.
- Look for tautological assertions, excessive mocking, missing negative cases, ig

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
name: code-work
description: Implement, modify, refactor, debug, and maintain software with strict scope control, repository-aware planning, root-cause analysis, incremental test-backed changes, adaptive parallelism, and fresh verification evidence. Use when Codex is asked to write or change production code, fix a defect, implement a feature, refactor a component, perform a migration, or complete another coding task that authorizes source changes. Use code-verification instead when the primary request is read-only review, testing, diagnosis, audit, or validation.
---

# Code Work

Implement the requested behavior in the smallest reliable increments. Preserve the user's authority, the repository's conventions, and all unrelated work. Treat tests and verification as evidence, not ceremony.

## Preserve the contract

- Treat the user's explicit request and decisions as the controlling specification.
- Work only inside the approved target and outcome. Report adjacent defects or improvements without acting on them.
- Read applicable repository instructions before changing files. Inspect the current status and diff so user-owned changes are not overwritten or reformatted accidentally.
- Do not infer permission to deploy, publish, push, commit, modify live systems, rotate credentials, delete data, or make other external or destructive changes.
- Ask only when missing information would materially change behavior, public interfaces, data, safety, or scope. Otherwise state a narrow assumption and proceed.
- Stop before substituting a workaround, partial implementation, or different design for a binding user decision.

## Establish the change contract

Before editing, identify:

1. The observable outcome and acceptance criteria.
2. The files, modules, interfaces, data, and environments in scope.
3. Invariants and compatibility requirements that must remain unchanged.
4. The highest-risk failure modes.
5. The evidence required to call the task complete.

Inspect the repository's own entry points, manifests, test configuration, CI workflow, and nearby code. Prefer its documented commands and patterns over generic defaults.

For complex work, form a short dependency-ordered plan. Keep only one integration step active at a time, even when independent work runs concurrently.

## Choose the change strategy

- **Defect:** Reproduce the failure, reduce it to a specific mechanism, and trace the responsible data or control flow before editing. Add or identify a regression check that fails for the intended reason when practical.
- **Feature:** Identify the public seam and deliver a thin vertical slice through real behavior before adding breadth.
- **Refactor:** Characterize current behavior first. Separate behavior preservation from intentional behavior change.
- **Migration:** Map producers, consumers, compatibility windows, data transitions, and rollback conditions before changing the contract.
- **Risky boundary:** Identify security, concurrency, persistence, time, network, and failure-recovery behavior explicitly.

Read [references/engineering-decisions.md](references/engineering-decisions.md) when selecting test levels, diagnosing an uncertain failure, designing a risky change, or splitting work across parallel executors.

## Implement in evidence-backed slices

For each observable behavior:

1. **Demonstrate the gap.** Prefer a focused failing test or deterministic reproduction. Confirm that it fails because the behavior is absent or wrong, not because the test or environment is broken.
2. **Make the smallest coherent change.** Modify only what is needed for that slice. Avoid speculative abstractions and adjacent cleanup.
3. **Prove the behavior.** Run the focused check and inspect its full result and exit status.
4. **Improve structure only while green.** Refactor only inside scope and rerun the focused check after structural changes.
5. **Inspect the slice.** Review the diff for accidental API changes, copied secrets, generated noise, w

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 3 — file references are metadata, not package contents.