https://github.com/scottconverse/coder-tdd-qa
Portable TDD/QA standards skill for AI coding agents (Claude Code, Codex, any AGENTS.md) — watch-it-fail-first TDD, anti-fabrication evidence rules, falsification pass, size-gated release checklist
https://github.com/scottconverse/coder-tdd-qa
Last synced: 10 days ago
JSON representation
Portable TDD/QA standards skill for AI coding agents (Claude Code, Codex, any AGENTS.md) — watch-it-fail-first TDD, anti-fabrication evidence rules, falsification pass, size-gated release checklist
- Host: GitHub
- URL: https://github.com/scottconverse/coder-tdd-qa
- Owner: scottconverse
- License: mit
- Created: 2026-07-02T17:33:32.000Z (22 days ago)
- Default Branch: main
- Last Pushed: 2026-07-02T18:15:59.000Z (22 days ago)
- Last Synced: 2026-07-02T19:27:11.302Z (22 days ago)
- Language: Python
- Size: 49.8 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# coder-tdd-qa
A portable rulebook for AI coding agents: test-driven development, honest
verification, and a size-gated release checklist — plain markdown that works in
Claude Code, Codex, or any agent that reads instructions. Ships in two forms:
[SKILL.md](SKILL.md) (full standards) and [SKILL-LITE.md](SKILL-LITE.md) (the
condensed contract for small tasks, with a tripwire back to full).
**Landing page:** https://scottconverse.github.io/coder-tdd-qa/
## What this is (plain English)
AI coding assistants have a bad habit: they write code, say "done, it works," and
move on — without ever proving it. Sometimes the tests they wrote don't actually
test anything. Sometimes they summarize a test run in a way that hides failures.
This project is a set of written rules you hand to your AI assistant that closes
those loopholes. The core idea is simple: **a test only counts if the assistant
watched it fail first.** A test that has never failed might be testing nothing at
all. So the rules force the assistant to write the test, watch it fail, then write
the code that makes it pass — and to show you the raw, uneditable proof at each
step. Before calling anything done, the assistant must also try to *break* its own
work and tell you what happened.
You don't need to understand the rules to benefit from them. Install the file,
and your assistant follows them.
## Install (technical)
**Claude Code** — copy [SKILL.md](SKILL.md) into a skills directory:
```
# personal (all projects)
~/.claude/skills/coder-tdd-qa/SKILL.md
# or per-project
/.claude/skills/coder-tdd-qa/SKILL.md
```
**Codex / other agents** — paste everything below the YAML frontmatter of
[SKILL.md](SKILL.md) into the repo's `AGENTS.md` (or the agent's system prompt).
The body is harness-agnostic by construction: no tool names, no skill-loader
features, no file-layout assumptions.
**Lite** — for quick fixes, small scripts, or a small project's `AGENTS.md`,
install [SKILL-LITE.md](SKILL-LITE.md) the same way (as
`~/.claude/skills/coder-tdd-qa-lite/SKILL.md` in Claude Code). Same
non-negotiable rules, Evidence Format, and TDD loop — enforced identical to the
full document by `check_sync.py` in CI — minus workflow and release ceremony.
Its escalation tripwire sends the agent back to the full standards when a change
outgrows lite: more than one file or ~50 lines, any public interface, untrusted
input/auth/secrets/deserialization, or anything being pushed or released. The
human picks the tier; the agent only escalates, never downgrades.
## What's inside
| Section | What it does |
|---|---|
| Hard Rules | 9 rules; 1–5 non-negotiable (read-before-write, baseline-before-change, run-before-done, TDD, no secrets), 6–9 overridable with acknowledgment (challenge bad specs, checkpoint before risk, stay in scope, no wasteful operations) |
| Evidence Format | Anti-fabrication: exact command + verbatim counts line + all failures in full; only per-test PASS spam may be collapsed |
| The TDD Loop | Red → watch it fail on the assertion → minimal green → refactor → widen against the baseline. Bug fixes start with a failing reproduction test |
| Roles | Engineer / UI designer / QA lenses, applied only where the task involves them |
| Workflow | Numbered before-building checklist, build discipline (stdlib-first, doc sync), communication rules, task-type-switch rule |
| Verification Report | Scaled report: files read, baseline vs. end state, TDD evidence, a falsification pass (try to break your own change), commit evidence, a security checklist with per-item answers |
| Release Gate | Push = release event. Three tiers so a weekend utility doesn't get flagship ceremony |
## Design principles
- **Written for the weakest agent that might read it.** The document assumes the
host harness provides no other guidance — a bare local model gets the same
scaffolding a flagship one does. Rules come with reporting hooks (you must
*list* what you read) because a rule a model can't be caught violating is a
wish. Nothing is redundant by accident.
- **Tests must be real, not merely present.** "Write a test" is a rule an agent can
satisfy with a test that asserts nothing. Watching it fail on its assertion is
the only cheap guarantee it's wired to the behavior. That's why TDD is the core,
not an add-on.
- **Evidence, not assertions.** Verbatim counts and complete failures are an
anti-fraud forcing function — summarized output is where fake greens hide.
- **Falsify before sign-off.** A self-report only surfaces the gaps the
self-reporter looks for. The rules require an adversarial pass against the
agent's own change.
- **Baseline first.** Red→green is meaningless if the suite was already red when
the agent arrived. Pre-existing failures are recorded and tracked separately.
- **Ceremony scales with stakes.** Every public repo gets a secrets scan and
hygiene files; only published packages get packaging checks; only flagship
projects get manuals and landing pages, and only when asked.
- **Each rule stated once.** No duplication between sections — later sections
reference, never restate. The one sanctioned duplication — lite's copy of the
core — is machine-enforced: `check_sync.py` fails CI if the copies drift, if a
required block goes missing, if a new rule is added without deciding its lite
fate, or if lite's safety tripwire is deleted.
## Requirements
None. It's a markdown file. Any agent that reads instructions can use it.
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md).
## License
[MIT](LICENSE)