> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trykode.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# TDD Mode: Enforce Test-First AI Code Generation

> TDD Mode enforces test-driven development by blocking Kode from writing production code until a corresponding test file exists in your project.

AI coding tools have a well-known failure mode: they generate production code with no tests, the tests never get written, and your coverage ratchets steadily downward. TDD Mode closes this loophole at the infrastructure level. With TDD Mode enabled, Kode cannot write a production file until a corresponding test file is present — and when you run `kode loop`, the test suite must be executed and the results verified before production code is accepted.

## How TDD Mode works

TDD Mode activates a `TDDEnforcer` that runs before any file write. It inspects every file in the proposed patch and classifies each one as either a test file or a production file.

**Test file detection:** A file is considered a test file if its name matches any of these patterns:

| Pattern      | Language           |
| ------------ | ------------------ |
| `*_test.go`  | Go                 |
| `*.test.ts`  | TypeScript         |
| `*.spec.ts`  | TypeScript         |
| `*.test.tsx` | TypeScript (React) |
| `*.spec.tsx` | TypeScript (React) |
| `*.test.js`  | JavaScript         |
| `*.spec.js`  | JavaScript         |
| `*_test.py`  | Python             |

If a patch contains **only production files** (no test files), the write is blocked with:

```
TDD mode: write or modify a test file before modifying production code
```

If a patch contains **both test files and production files**, Kode runs the test command. The production files are accepted only if the tests pass.

## Configuring TDD Mode

Enable TDD Mode in `.kode/kode.json` under the `engine` section:

```json theme={null}
{
  "engine": {
    "tdd_mode": true,
    "test_command": "go test ./..."
  }
}
```

If you omit `test_command`, Kode auto-detects the correct command by scanning your project for language markers:

| File found         | Auto-detected command |
| ------------------ | --------------------- |
| `go.mod`           | `go test ./...`       |
| `package.json`     | `npm test`            |
| `Cargo.toml`       | `cargo test`          |
| `pyproject.toml`   | `pytest`              |
| `requirements.txt` | `python -m pytest`    |

Detection walks the project tree, skipping `node_modules`, `.git`, and `vendor` directories.

## What happens in a loop with TDD Mode on

When you run `kode loop` with TDD Mode enabled, Kode enforces a strict test-first sequence:

<Steps>
  ### Generate the test file first

  Kode generates a test file for the new functionality. Because no production file exists yet, the test file write is always allowed — TDD Mode only blocks production files, never test files.

  ### Run the tests (expect failure)

  Kode executes your test command. At this stage the tests should fail because the implementation doesn't exist yet. A failing test result here is **expected and correct** — it means your tests are actually testing something. Kode records this as a healthy TDD signal.

  ### Generate the production implementation

  With a test file in place and the tests confirmed failing, Kode generates the production implementation. The patch contains both the test file (already on disk) and the production file.

  ### Run the tests again (require pass)

  Kode runs the test command again against the full patch. If the tests pass, both files are written to disk. If the tests fail, Kode rolls back all changes to the pre-patch snapshot and reports the test failure.
</Steps>

## Example configuration

Here is a complete `kode.json` for a Go project with TDD Mode enabled:

```json theme={null}
{
  "engine": {
    "tdd_mode": true,
    "test_command": "go test ./..."
  },
  "llm": {
    "model": "gpt-4o"
  }
}
```

And for a TypeScript project:

```json theme={null}
{
  "engine": {
    "tdd_mode": true,
    "test_command": "npm test"
  }
}
```

<Tip>
  TDD Mode pairs perfectly with `kode loop`, which includes automatic test execution and rollback. Running `kode loop --branches 3` with TDD Mode active means each Ghost Branch must also produce passing tests to be eligible for winner selection — branches that fail tests score `-1.0` and are eliminated.
</Tip>

## Related pages

* [Guides: Loop mode](/guides/loop-mode) — full walkthrough of the `kode loop` workflow with test integration and rollback behaviour