Custom Instructions

## Testing

- Write tests for all business logic
- Use Vitest for unit tests
- Place test files adjacent to source: `component.tsx` → `component.test.tsx`

## Important

Do NOT modify files in the `generated/` directory - they are auto-generated.

## Common Use Cases

<AccordionGroup>
  <Accordion title="Enforce coding style">
    Example AGENTS.md showing code style preferences:
    
    - Use single quotes for strings
    - Include trailing commas in multiline arrays/objects
    - Prefer arrow functions over function declarations
    - Use template literals instead of string concatenation
    
    Keep your style preferences documented so Codex follows them consistently.
  </Accordion>
  
  <Accordion title="Document architecture decisions">
    Use AGENTS.md to document key architectural decisions for your project, such as:
    
    - Monorepo structure and workspace organization
    - Data flow patterns (e.g., unidirectional data flow)
    - Module boundaries and dependencies
    - Coding patterns that should be followed
    
    This helps Codex understand and maintain your architecture.
  </Accordion>
  
  <Accordion title="Define project constraints">
    Document technical constraints in AGENTS.md:
    
    - Browser support requirements
    - Bundle size limits
    - Performance targets (FCP, TTI, Lighthouse scores)
    - Dependency management policies
    - Security and compliance requirements
    
    Clear constraints help Codex make appropriate trade-offs.
  </Accordion>
  
  <Accordion title="Workflow preferences">
    Document team workflows in AGENTS.md:
    
    - Git workflow (branching strategy, commit conventions)
    - Code review requirements
    - Development commands and scripts
    - Testing practices
    - Deployment procedures
    
    Consistent workflows improve code quality and team productivity.
  </Accordion>
  
  <Accordion title="Communication style">
    Set communication preferences in AGENTS.md:
    
    - Explanation depth (concise vs thorough)
    - When to ask clarifying questions
    - How to handle ambiguous requirements
    - Code example preferences
    - Technical writing style
    
    This helps Codex communicate in the style you prefer.
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Be Specific" icon="crosshairs">
    Provide concrete examples and explicit rules rather than vague guidelines
  </Card>
  
  <Card title="Keep It Updated" icon="rotate">
    Review and update instructions as your project evolves
  </Card>
  
  <Card title="Focus on Context" icon="brain">
    Include information Codex can't infer from code alone
  </Card>
  
  <Card title="Use Structure" icon="list">
    Organize with headers and lists for easy scanning
  </Card>
</CardGroup>

### What to Include

<Check>**DO** include:</Check>

- Coding standards and conventions
- Architecture principles
- Project-specific constraints
- Workflow preferences
- Important context about design decisions
- Links to relevant documentation

<Warning>**AVOID** including:</Warning>

- Information that's obvious from the code
- Detailed API documentation (use inline comments instead)
- Temporary notes (use regular comments or TODOs)
- Secrets or sensitive information

## Disabling Project Docs

You can disable loading of AGENTS.md files:

### Command-Line Flag

```bash
codex --no-project-doc

export CODEX_DISABLE_PROJECT_DOC=1
codex

# Polyglot Project Guidelines

## Backend (Rust)

- Follow the Rust API guidelines
- Use `cargo fmt` and `cargo clippy`
- Write doc comments with examples
- Place unit tests in the same file using `#[cfg(test)]`

## Frontend (TypeScript)

- Use strict TypeScript mode
- No `any` types without explicit justification
- Prefer type inference over explicit types when obvious

## Database (PostgreSQL)

- All schema changes go through migrations
- Use snake_case for column names
- Always add indexes for foreign keys
- Include `created_at` and `updated_at` timestamps

## API Contracts

- Use OpenAPI 3.0 specification
- Version APIs with `/v1/`, `/v2/` prefixes
- Never remove fields from existing endpoints (deprecate instead)

# Microservices Guidelines

## Service Boundaries

- auth-service: Authentication and authorization
- user-service: User profiles and preferences
- payment-service: Payment processing and billing
- notification-service: Email, SMS, push notifications

## Inter-Service Communication

- Use gRPC for synchronous calls
- Use message queue (RabbitMQ) for async events
- Never make database calls across services
- Each service owns its data exclusively

## Observability

- Instrument all endpoints with OpenTelemetry
- Log structured JSON with trace IDs
- Set up alerts for error rate > 1%
- Dashboard: https://grafana.internal/services

## Deployment

- Services run in Kubernetes
- Use Helm charts in `k8s/charts/`
- Staging: `kubectl config use-context staging`
- Production: Requires approval + deploy script