syntaxai/tdd.md · commit 8fbd29d

Visitor with Claude Code lands on tdd.md and gets every answer

The persona that drove this: someone with Claude Code wants to do
TDD in their workflow, doesn't know how, lands on tdd.md, expects
every answer there. Previously they saw a manifesto and had to
hunt for the guide.

Three changes:

- Homepage gains an agent-CTA strip right under the tagline. Direct
  links to the per-agent guides (Claude Code / Cursor / Aider) plus
  a "see what a verdict looks like" link to the public demo. No more
  manifesto-first flow for people who already know they want this.

- New public demo agent (forgejo user `demo`, public visibility) with
  a hand-built string-calc kata: clean red→green→refactor cycles for
  two steps + a refactor commit. Verdict +45, both steps verified,
  hidden tests passing. Visitors hit /demo/string-calc and see exactly
  what their own page will look like — no signup needed.

- Claude Code guide expanded with the answers a cold visitor needs:
  time estimate (~15 min for first verdict), "what you'll see" linked
  to the live demo, an FAQ covering registration / private projects /
  trace-only / hidden-test failures / visibility toggle, and a
  troubleshooting section mapping each negative status to a concrete
  fix (red-did-not-fail, test-deleted, 401 on push, missing webhook,
  bun-not-found).

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
author
syntaxai <[email protected]>
date
2026-05-07 12:18:52 +01:00
parent
85d5449
commit
8fbd29dedcfbe536f7fc79e9559d878f35edc43c

2 files changed · +43 −1

modified content/guides/claude-code.md +35 −1
@@ -1,9 +1,15 @@
11 # TDD with Claude Code
22
3-> Test-driven development on tdd.md, using **Claude Code** as your agent. Score your discipline against hidden tests on every push.
3+> Test-driven development on tdd.md, using **Claude Code** as your agent. Score your discipline against hidden tests on every push. **~15 minutes** for your first verdict.
44
55 Claude Code is Anthropic's terminal coding agent. Out of the box it doesn't insist on TDD — it tends to write implementation first, tests later. With the right setup it'll do red→green→refactor cleanly, and tdd.md will verify it.
66
7+## what you'll see
8+
9+A live verdict, scored end-to-end: **[tdd.md/demo/string-calc →](/demo/string-calc)** (`+45`, 2/7 steps verified, 1 refactor — what your own page will look like after a few cycles).
10+
11+Per step you get: red sha, green sha, "did your test fail at red?", "did it pass at green?", "did the kata's hidden tests pass?", a status, points, and a one-line explanation written to you. Refactor commits get their own table.
12+
713 ## one-time setup
814
915 1. **Sign in with GitHub on tdd.md**: visit [tdd.md/you](/you) → grant the OAuth scopes → save the push token shown on the welcome page. The same identity you use on GitHub becomes your tdd.md agent name.
@@ -81,4 +87,32 @@ If you want a softer judge while learning Claude Code's TDD habits, drop a `tdd.
8187
8288 Learning mode floors negatives at 0 and adds longer explanations. `pragmatic` halves penalties. `strict` is the default.
8389
90+## faq
91+
92+**How long does my first kata take?** ~15 minutes if you're new to the loop, ~5 minutes per step after. The judge runs in seconds.
93+
94+**Does Claude Code need any special prompts to do TDD?** Yes — separate prompts for red and green is the single biggest predictor of a clean verdict. The CLAUDE.md snippet above pins the rule; the per-phase prompts execute it.
95+
96+**What if I don't want to register on tdd.md?** Browse [the demo](/demo/string-calc) to see what verdicts look like. To actually play, you need an agent account so the judge knows where to send the verdict.
97+
98+**Can I use this on a real project, not just katas?** Yes — set `{ "test_runner": "none" }` in `tdd.config.json` and the judge skips test execution, scoring only the discipline (red→green tagging, no test deletion, refactor presence). Works on any language, any stack.
99+
100+**My agent's repo is private. How does the judge run tests?** Repos default to private. Cloning is auth-gated by your push token; the judge uses an admin-token on its end so it can clone and verify. The verdict page renders publicly (so others can see your discipline) but the source itself stays behind the token.
101+
102+**What if I want my whole profile invisible?** `POST /api/agents/<your-name>/visibility` with `{"visibility":"private"}` — your profile, repos, and verdicts disappear from public pages. You still see them when signed in.
103+
104+**My green tests pass but the verdict says `hidden-tests-failed`?** Your test passes, but it's testing something the kata doesn't actually require — typically a tautology like `expect(0).toBe(0)`. Look at the kata's spec for the real requirement and match it.
105+
106+## troubleshooting
107+
108+**Verdict says `red-did-not-fail`.** You likely wrote test + impl in one Claude Code turn. Use two turns: red prompt → commit → green prompt → commit.
109+
110+**Verdict says `test-deleted` after a refactor.** Claude removed a test "to simplify". Add to CLAUDE.md: "never delete a test under any circumstances; if a test seems wrong, replace it in a separate commit, never bundled with impl changes."
111+
112+**Push fails with `401 unauthorized`.** Your push token is missing or wrong. Visit [tdd.md/you](/you) to sign back in; if your token was rotated, the page shows the new one. The clone URL embeds the token (`https://<name>:<token>@tdd.md/<name>/<kata>.git`).
113+
114+**Webhook didn't fire — no verdict appears.** Check the URL you pushed to is `tdd.md/...`, not your normal upstream. The webhook is per-repo on the tdd.md side; only pushes to the tdd.md remote trigger judging.
115+
116+**`bun: command not found` in the verdict.** Your kata expects Bun. If you're on a different runtime, set `{ "test_runner": "none" }` and use trace-only mode (no test execution; just discipline scoring).
117+
84118 [← all guides](/guides) · [the kata catalog](/games) · [why TDD on agentic coding](/)
modified content/home.md +8 −0
@@ -2,6 +2,14 @@
22
33 > Test-driven development for agentic coding. Practice on scored katas. The judge replays your AI agent's commits against hidden tests it owns, and posts a public verdict — not a grade for life, a snapshot of the discipline you showed on this run.
44
5+**Using a specific agent? Go straight to the workflow:**
6+
7+- [TDD with **Claude Code** →](/guides/claude-code) · setup, prompts, common mistakes
8+- [TDD with **Cursor** →](/guides/cursor) · Composer-per-phase, project rules, agent-mode caveats
9+- [TDD with **Aider** →](/guides/aider) · auto-commit phase tags, --auto-test gotchas
10+
11+See what a real verdict looks like: [tdd.md/demo/string-calc →](/demo/string-calc).
12+
513 ---
614
715 ## premise

raw .diff