← Volver al listado de tecnologías ← Índice de AGENTS.md

Secciones Esenciales

Por: Artiko
agents-mdseccionesestructurabuenas-practicas

Secciones Esenciales

Las 6 areas criticas

El analisis de mas de 2,500 repositorios por GitHub revelo que cubrir estas 6 areas posiciona un AGENTS.md en el top tier de efectividad:

  1. Comandos
  2. Testing
  3. Estructura del proyecto
  4. Estilo de codigo
  5. Flujo de Git
  6. Boundaries (limites)

1. Comandos

La seccion mas referenciada por los agentes. Pon los comandos temprano en el archivo con flags completos.

## Commands

### Development
- Dev server: `bun dev` (port 4321)
- Build: `bun run build`
- Preview: `bun preview`

### Testing
- All tests: `bunx vitest run`
- Single file: `bunx vitest run path/to/file.test.ts`
- Watch mode: `bunx vitest`
- Coverage: `bunx vitest run --coverage`

### Quality
- Lint: `bunx biome check src/`
- Lint fix: `bunx biome check --write src/`
- Type check: `bunx tsc --noEmit`
- Format: `bunx biome format --write src/`

Clave: incluye comandos para archivos individuales. Los agentes trabajan archivo por archivo; ejecutar la suite completa es lento e innecesario.

2. Testing

Los agentes necesitan saber como escribir tests, no solo como ejecutarlos.

## Testing

- Framework: Vitest 3
- Test files alongside source: `module.test.ts`
- Naming: `describe("ModuleName")` > `it("should behavior")`
- Mocks in `__mocks__/` directory next to source
- Minimum coverage: 80% lines and branches
- Use `vi.mock()` for external dependencies
- Never mock internal implementation details

### Example test structure
See `src/services/auth.test.ts` for reference pattern.

Apuntar a un archivo real como ejemplo es mas efectivo que explicar el patron en prosa.

3. Estructura del proyecto

Guia al agente a los directorios correctos sin necesidad de explorar todo el repo.

## Project structure

src/ ├── domain/ # Business logic, entities, value objects ├── application/ # Use cases, ports (interfaces) ├── infrastructure/ # Adapters, DB, external APIs ├── api/ # HTTP routes and controllers └── shared/ # Utilities, types, constants


- New features go in domain/ first, then application/, then infrastructure/
- Each module has: index.ts (exports), types.ts, and module.test.ts
- Configuration in `config/` directory, not scattered in source

4. Estilo de codigo

Un snippet real vale mas que tres parrafos de explicacion.

## Code style

- Functional components, no classes
- Named exports only (no default exports)
- Functions under 30 lines
- Files under 150 lines
- Use Zod for runtime validation at boundaries
- Prefer composition over inheritance

### Naming conventions
- Files: kebab-case (`user-service.ts`)
- Types/interfaces: PascalCase (`UserService`)
- Functions/variables: camelCase (`createUser`)
- Constants: UPPER_SNAKE_CASE (`MAX_RETRIES`)

### Good example
See `src/domain/user/user-entity.ts` for reference.

Apuntar a archivos de referencia es mas efectivo que describir el estilo en abstracto. El agente puede leer el archivo y extraer el patron.

5. Flujo de Git

## Git workflow

- Branch naming: `feat/description`, `fix/description`, `refactor/description`
- Commit format: `feat: description` / `fix: description` / `refactor: description`
- Atomic commits: one logical change per commit
- Always run `bunx biome check --write` before committing
- Never commit: `.env`, `node_modules/`, `dist/`, `coverage/`

6. Boundaries

La seccion mas importante para seguridad. Se cubre en profundidad en el Capitulo 5, pero aqui va lo esencial:

## Boundaries

### Always do
- Run tests after modifying source files
- Validate inputs with Zod at API boundaries
- Use TypeScript strict mode

### Ask first
- Before adding new production dependencies
- Before modifying database schemas
- Before changing CI/CD pipelines

### Never do
- Never commit secrets, tokens, or API keys
- Never modify `.env` or `credentials.json`
- Never delete or skip failing tests
- Never use `any` as TypeScript type
- Never force-push to main

Seccion opcional: API y servicios externos

Si tu proyecto consume APIs externas, guia al agente:

## External APIs

- API client in `src/infrastructure/api/`
- Use typed clients generated from OpenAPI specs
- Base URL from environment variables, never hardcoded
- Rate limiting: max 100 req/min to external services
- Error handling: retry 3 times with exponential backoff

Seccion opcional: Seguridad

## Security

- Validate all user input with Zod before processing
- Passwords hashed with bcrypt (cost 12)
- JWT expiration: 1 hour max
- Rate limiting on public endpoints
- No logging of sensitive data (passwords, tokens, PII)
- SQL injection: use parameterized queries only

Resumen

← Capitulo 2: Tu Primer AGENTS.md | Capitulo 4: Monorepos y Jerarquias →

← Volver al listado de tecnologías ← Índice de AGENTS.md