Kleio vs TDD / Tests as Documentation
Tests verify behavior.
They can't capture why.
Tests document what the code should do. They can't document why it should do it that way, what alternatives were considered, or what tradeoffs were accepted.
Where TDD works well
- Executable specifications — tests define expected behavior and catch regressions automatically.
- Self-updating documentation — if the behavior changes and the test fails, you know the docs are wrong.
- Readable by new team members — well-written tests explain what the code does by example.
- Confidence in refactoring — tests let you change implementation without changing behavior.
- Proven methodology with decades of practice and tooling support.
Where tests fall short as documentation
- Tests document what the code should do, not why it should do it that way.
- Test names and assertions encode the decision outcome but not the alternatives considered or tradeoffs accepted.
- AI-generated tests often test implementation details, not intent — they verify the how, not the why.
- No temporal context — tests don't tell you when a behavior was decided or what changed.
- Can't capture cross-cutting decisions that span beyond a single unit or service.
- "This test exists because we decided X over Y due to Z" — that reasoning lives nowhere in the test suite.
How Kleio is different
- Captures the reasoning behind decisions, not just the outcome. "We chose X over Y because Z."
- Temporal context — when decisions were made, by whom, and what led to them.
- Cross-cutting decisions that span services, modules, and time are first-class objects.
- kleio_ask can answer "why does this test exist?" when the decision context is captured.
- Signal links connect decisions to the PRs and commits where they were implemented — including the tests.
- Works alongside TDD — tests verify behavior, Kleio preserves the reasoning.
See it in action
An agent plans a migration. Kleio captures every signal along the way.
Agent Plan
Task: Migrate auth from Firebase to Clerk
- 1.Scaffold Clerk provider and session hooks
- 2.Replace Firebase login/signup flows
- 3.Update API middleware for Clerk JWT validation
Press Build to run the capture demo.
Your AI agents already make decisions. Kleio makes sure they're remembered. Try it free →
Side-by-side
| Capability | TDD / Tests as Documentation | Kleio |
|---|---|---|
| Executable specs | ||
| Regression detection | ||
| Refactoring confidence | ||
| Decision rationale | ||
| Alternatives considered | ||
| Temporal context | ||
| Cross-cutting decisions | ||
| Natural language query |
Better together or full replacement?
Complementary. Tests + Kleio = both the "what" and the "why" are preserved. Tests give you executable specifications. Kleio gives you the reasoning behind those specifications — the alternatives considered, the tradeoffs accepted, and the context that made this the right choice.
Related comparisons
Ready to try Kleio?
Start free, connect your workspace, and stop losing the \u201cwhy.\u201d