AGENTS.md: cómo dar instrucciones permanentes a Codex

~/.codex/AGENTS.md

# Global Codex instructions

- Explica brevemente los cambios al terminar.
- No hagas commits salvo que lo solicite.
- Prioriza soluciones simples.
- Evita modificar archivos no relacionados.
- Ejecuta las verificaciones disponibles antes de finalizar.
- Reporta limitaciones o tests que no pudiste ejecutar.

~/.codex/

├── AGENTS.md
└── AGENTS.override.md

mi-proyecto/
├── AGENTS.md
├── src/
├── tests/
├── package.json
└── .git/

# AGENTS.md

## Project overview

This repository contains
a web application with:

- PHP backend
- MySQL database
- JavaScript frontend


## Repository structure

- `src/` application code
- `public/` public entry points
- `tests/` automated tests
- `docs/` technical documentation


## Development rules

- Keep changes focused on the requested task.
- Reuse existing patterns before creating new abstractions.
- Do not add dependencies unless clearly necessary.
- Preserve public APIs unless the task requires a breaking change.


## PHP

- Maintain PHP 8.2+ compatibility.
- Use PDO for database access.
- Use prepared statements for SQL.
- Validate external input.
- Escape output where appropriate.


## JavaScript

- Follow existing project conventions.
- Avoid global variables.
- Do not add a framework for isolated UI changes.


## Verification

Before finishing:

1. run PHP syntax checks
2. run automated tests
3. run lint if configured
4. review `git diff`
5. report any checks that could not be executed


## Git

- Do not create commits unless explicitly requested.
- Do not modify unrelated files.
- Never include secrets in commits.

~/development/
├── AGENTS.md
│
└── mi-proyecto/
    ├── .git/
    ├── AGENTS.md
    └── src/

repo/
├── AGENTS.md
│
├── backend/
│   ├── AGENTS.md
│   └── src/
│
└── frontend/
    ├── AGENTS.md
    └── src/

# AGENTS.md

- Keep public APIs backward compatible.
- Do not commit generated files.
- Run the relevant test suite before finishing.

# backend/AGENTS.md

- Use prepared SQL statements.
- Run `composer test`.
- Run `vendor/bin/phpstan analyse`.
- Preserve PHP 8.2 compatibility.

# frontend/AGENTS.md

- Use existing UI components.
- Run `npm test`.
- Run `npm run lint`.
- Run `npm run build`.
- Preserve responsive behavior.

repo/
├── AGENTS.md
│
└── services/
    └── payments/
        ├── AGENTS.md
        ├── AGENTS.override.md
        └── src/

# services/payments/AGENTS.override.md

## Payments rules

- Run `make test-payments`.
- Never log card data.
- Never expose payment credentials.
- Preserve idempotency behavior.
- Treat database migrations as high-risk.
- Do not rotate credentials automatically.
- Add regression tests for payment failures.

monorepo/
├── AGENTS.md
│
├── apps/
│   ├── web/
│   │   ├── AGENTS.md
│   │   └── src/
│   │
│   └── admin/
│       ├── AGENTS.md
│       └── src/
│
├── services/
│   ├── api/
│   │   ├── AGENTS.md
│   │   └── src/
│   │
│   └── billing/
│       ├── AGENTS.override.md
│       └── src/
│
└── packages/
    └── ui/
        ├── AGENTS.md
        └── src/

# AGENTS.md

## WordPress project

This is a WordPress project.

Custom development lives in:

- `wp-content/plugins/`
- `wp-content/themes/`
- `wp-content/mu-plugins/`


## Important restrictions

- Never modify WordPress core.
- Do not edit files inside `vendor/`.
- Do not modify `wp-config.php` unless explicitly requested.
- Do not modify uploaded media.
- Never expose credentials or salts.


## WordPress conventions

- Prefer WordPress APIs over custom replacements.
- Sanitize and validate input.
- Escape output.
- Use nonces for state-changing requests.
- Check capabilities for privileged operations.
- Use `$wpdb->prepare()` for dynamic SQL.
- Prefix global functions and hooks.
- Preserve backward compatibility where possible.


## Verification

Before finishing:

- run `php -l` on modified PHP files
- run PHPCS if configured
- run PHPUnit if configured
- review AJAX and REST permissions
- review database queries
- review `git diff`

# wp-content/plugins/mi-plugin/AGENTS.md

## Plugin architecture

- `mi-plugin.php` is the bootstrap file.
- `includes/` contains PHP classes.
- `assets/js/` contains JavaScript.
- `assets/css/` contains styles.
- `templates/` contains frontend templates.


## AJAX

For every authenticated AJAX handler:

- verify nonce
- verify capabilities when required
- sanitize request data
- return `wp_send_json_success()` or `wp_send_json_error()`


## Database

Custom tables use the prefix:

`{$wpdb->prefix}mi_plugin_`

All dynamic SQL must use `$wpdb->prepare()`.


## WooCommerce

- Prefer official WooCommerce hooks.
- Do not modify WooCommerce core files.
- Avoid template overrides unless a hook cannot solve the requirement.


## Tests

Run:

`php -l`
`vendor/bin/phpcs`
`vendor/bin/phpunit`

when available.

# AGENTS.md

## PHP

- Support PHP 8.2+.
- Use strict typing where the project already does.
- Follow the project's namespace structure.
- Use existing dependency injection patterns.
- Avoid static state unless already established.


## Database

- Use PDO.
- Use prepared statements.
- Wrap related writes in transactions.
- Do not perform destructive migrations automatically.


## Security

- Validate external input.
- Escape output where appropriate.
- Never expose credentials.
- Do not weaken authentication checks.


## Tests

Run:

composer test
vendor/bin/phpstan analyse
vendor/bin/phpcs

# AGENTS.md

## JavaScript / TypeScript

- Follow the existing TypeScript configuration.
- Do not introduce `any` unless justified.
- Reuse existing utilities and components.
- Preserve public interfaces.
- Avoid adding dependencies for trivial utilities.


## Frontend

- Preserve accessibility.
- Preserve responsive behavior.
- Reuse design-system components.
- Do not introduce inline styles unless the project already uses them.


## Verification

Run:

npm test
npm run lint
npm run typecheck
npm run build

## Verification

For PHP changes:

php -l path/to/file.php
vendor/bin/phpunit


For frontend changes:

npm test
npm run lint
npm run build


For full verification:

composer test
npm test
npm run build

## Code Review Rules

Flag:

- correctness bugs
- security vulnerabilities
- data-loss risks
- backwards-incompatible changes
- race conditions
- missing authorization checks
- missing regression tests for fixed bugs

Do not report:

- formatting handled by automated tools
- subjective naming preferences
- style comments without behavioral impact

~/.codex/config.toml

project_doc_max_bytes = 65536

project_doc_fallback_filenames = [
  "TEAM_GUIDE.md",
  ".agents.md"
]

repo/
├── TEAM_GUIDE.md
│
└── support/
    ├── AGENTS.override.md
    └── src/

# Correcto

- Database credentials are stored in environment variables.
- Never print secrets.
- Do not commit `.env` files.


# Incorrecto

DB_PASSWORD=my-real-password
OPENAI_API_KEY=sk-...

Lista las fuentes
de instrucciones
AGENTS.md
que cargaste
para esta sesión.

Indica:

- ruta
- ámbito
- prioridad
- reglas principales.

CODEX_HOME=$(pwd)/.codex codex

# AGENTS.md

## Project overview

Briefly explain what this project does.


## Architecture

Important directories:

- `src/`
- `tests/`
- `docs/`


## Development principles

- Keep changes focused.
- Prefer existing patterns.
- Avoid unnecessary abstractions.
- Do not fix unrelated issues.
- Do not add dependencies without a clear reason.


## Compatibility

- Runtime:
- Database:
- Browser support:
- API compatibility:


## Security

- Validate external input.
- Escape output where required.
- Never expose credentials.
- Preserve authentication and authorization checks.
- Use prepared database queries.


## Database

- Document the database layer.
- Use transactions for related writes.
- Do not run destructive migrations automatically.


## Testing

Before finishing:

1. run targeted tests
2. run lint
3. run typecheck if applicable
4. run build if applicable
5. review `git diff`


## Code review

Prioritize:

- correctness
- regressions
- security
- data loss
- race conditions
- backwards compatibility
- missing tests


## Git

- Do not commit unless requested.
- Do not modify unrelated files.
- Never commit secrets.
- Keep changes reviewable.


## Documentation

Update documentation when
public behavior changes.


## Final response

Summarize:

- what changed
- files modified
- tests executed
- unresolved risks