# How a .codex Folder Made Our AI Output Consistent

> My team's AI agents wrote the same feature in a different style for every teammate. This is the .codex folder I put in a NestJS boilerplate to make Codex follow one set of rules and remember our decisions.

- Date: 2026-04-01
- Tags: softwareengineering, ai, nestjs, productivity
- Also on dev.to: [https://dev.to/jimzandueta/from-ai-chaos-to-team-flow-codex-boilerplate-that-actually-worked-5fa1](https://dev.to/jimzandueta/from-ai-chaos-to-team-flow-codex-boilerplate-that-actually-worked-5fa1)

When my team started using AI agents in our daily programming work, we did it in a structured way, not vibe-coding. We wanted to move faster and repeat ourselves less. We wrote detailed tickets. Still, in the first week each teammate's agent came back with its own naming, its own folder structure, and its own way of handling errors and writing tests. Every merge felt like stitching code from different universes.

![The Distracted Boyfriend meme.](/blog/from-ai-chaos-to-team-flow-codex-boilerplate-that-actually-worked/1.jpg)

We tried a few setups first. A strong `CLAUDE.md` helped a lot early on, and Claude Opus reasoned well and broke work down step by step. The trouble was practical, because we kept hitting usage limits and timeouts. Our company sponsors Codex, so we moved to it as our main tool. Out of the box it felt a bit lackluster next to Claude, and that made us look at the system around the model instead of the model.

![The Drake meme.](/blog/from-ai-chaos-to-team-flow-codex-boilerplate-that-actually-worked/2.jpg)

What we moved to is an agentic software development lifecycle, or A-SDLC. In the traditional lifecycle, people write most of the code as the work moves through phases in a line. In the agentic one, people and agents work together in short feedback loops. Our job as developers became setting guardrails, giving the agent context, reviewing quickly and updating the project's memory. This is how we work day to day, not just an idea we talk about.

I built a NestJS boilerplate to share the `.codex` setup that worked best for us. It lives at [github.com/jimzandueta/nestjs-http-server-boilerplate-codex-ai-assisted](https://github.com/jimzandueta/nestjs-http-server-boilerplate-codex-ai-assisted).

## The .codex folder

The `.codex` folder holds everything an agent reads before it works on the repo.

```text
.codex/
  START_HERE.md
  RULES.md
  MANIFEST.yaml
  instructions/
  patterns/
  anti-patterns/
  checklists/
  skills/
  prompts/
  templates/
  overrides/
  memory/
```

![The Expanding Brain meme.](/blog/from-ai-chaos-to-team-flow-codex-boilerplate-that-actually-worked/3.jpg)

`START_HERE.md` and `RULES.md` set the baseline rules for every task.

```md
## Output Rules
1. Reuse existing patterns before inventing new ones.
2. Keep diffs minimal.
3. Never commit secrets.
```

With those three rules alone, the same task came back in different styles far less often.

`MANIFEST.yaml` routes context. It tells the agent which files to read for each kind of task, so a new feature starts with the right playbook already loaded.

```yaml
task_routes:
  new-feature:
    read:
      - .codex/instructions/global.md
      - .codex/patterns/repo-structure.md
      - .codex/patterns/error-handling.md
    skills:
      - .codex/skills/new-feature/SKILL.md
```

The other folders hold our instructions, patterns, anti-patterns, checklists, skills and templates. This is part of the test checklist:

```md
## Tests
- [ ] New logic has happy path + failure test
- [ ] Coverage stays at 100% threshold
- [ ] No flaky tests introduced
```

I use `overrides/` so the generic Codex files can stay generic and still fit this project. A generic pattern might recommend a folder structure, and the override says this repo uses `src/common`, `src/clients` and `src/modules`.

## Project memory

The part that matters most is `memory/`. It has three files. `project-facts.md` keeps stable facts about the project. `decisions.md` keeps decisions and their tradeoffs as ADRs, or architecture decision records. `learned-patterns.md` keeps conventions we found while doing the work. When a developer and the agent decide something new, the memory gets updated, so later tasks start with the same context.

Here is an example. A developer wants a `requestId` in the logs so the team can trace requests. The agent offers two options, `AsyncLocalStorage` or passing the ID along explicitly. The team picks explicit propagation first, because it's simpler and easier to test. The memory then gets an ADR:

```md
### ADR-002: Standardize request correlation IDs in HTTP logs

**Date**: 2026-04-02
**Status**: Accepted

**Context**: Debugging incidents was slow because logs across layers were hard to correlate.
**Decision**: Add `requestId` at the HTTP boundary and propagate it through services/clients.
**Consequences**: Better traceability, with slight method-signature overhead.
```

A new convention in the project facts:

```md
## Conventions
- Logging: include `requestId` in structured logs for HTTP flows.
- Request context: generate/forward `x-request-id` at ingress and propagate downstream.
```

And a learned pattern:

```md
### LP-001: Propagate requestId from boundary to integrations

**Observed**: Missing correlation fields made multi-step failures harder to debug.
**Rule**: Controllers create context; services/clients forward `requestId`; logs include it at each layer.
```

![The Change My Mind meme.](/blog/from-ai-chaos-to-team-flow-codex-boilerplate-that-actually-worked/4.jpg)

With this setup we built the sample NestJS HTTP server in the repo. It has validated runtime config, structured logging, a reusable HTTP client with timeouts and retries, and a sample `posts` module that calls JSONPlaceholder. Its tests have 100% coverage thresholds.

I tuned this `.codex` for a NestJS HTTP app. I keep a separate Codex baseline for Terraform and infrastructure, because the workflows and quality gates there are different. Next I want to try orchestrating agents with open-source tools like LangChain, Langfuse and local models.

![The One Does Not Simply meme.](/blog/from-ai-chaos-to-team-flow-codex-boilerplate-that-actually-worked/5.jpg)

And this is my cat, Chidi.

![My cat Chidi.](/blog/from-ai-chaos-to-team-flow-codex-boilerplate-that-actually-worked/6.png)