Skip to main content

TDD mode — nimbus run --tdd

Write tests first, implement to pass. The output is code that is provably correct by construction.

Usage​

nimbus run --tdd "add user authentication with JWT"

Or from inside the REPL:

nimbus › run "add rate limiting to /api/upload" --tdd

How it works​

  1. Generate tests — Claude Opus writes a comprehensive test suite covering all expected behaviors, edge cases, and error conditions from your task description
  2. Show test plan — lists all test functions for your approval before writing anything
  3. Confirm failures — writes the test file and runs the suite to confirm all tests fail (sanity check that tests are meaningful)
  4. Implement — runs the standard Nimbus implementation pipeline, augmented with the test file as a constraint
  5. Verify — re-runs the full test suite to confirm all tests pass and no regressions were introduced

Example output​

  ◆ TDD mode  write tests first, implement to pass

  generating test suite...

  test plan  8 tests

  · test_jwt_token_is_issued_on_login
  · test_jwt_token_expires_after_30_days
  · test_invalid_token_returns_401
  · test_expired_token_returns_403
  · test_missing_token_returns_401
  · test_refresh_token_rotation
  · test_token_payload_contains_user_id
  · test_logout_invalidates_token

  Proceed with TDD? [y/N] y

  wrote  tests/test_nimbus_tdd_add_user_auth.py
  running tests (expecting failures)...
  ✓  8 tests failing as expected

  implementing to make tests pass...

  [standard pipeline runs]

  verifying all tests pass...
  ✓  all tests pass

Why TDD mode​

Standard Nimbus implementation is fast but the output can drift from intent on ambiguous tasks. TDD mode makes the contract explicit and machine-verifiable. The tests define exactly what "done" means before a single line of production code is written.

Test file location​

The generated test file is written to your existing test directory (tests/, test/, or __tests__/). The filename is test_nimbus_tdd_<task_slug>.py. The file is preserved after the task — commit it alongside the implementation.