8fbd29dedcfbe536f7fc79e9559d878f35edc43c diff --git a/content/guides/claude-code.md b/content/guides/claude-code.md index d554d47c9e7c44c44f129bcb4849c1645407fd41..f71fef71119474fbbabe47f94d63064d20afa9f9 100644 --- a/content/guides/claude-code.md +++ b/content/guides/claude-code.md @@ -1,9 +1,15 @@ # TDD with Claude Code -> Test-driven development on tdd.md, using **Claude Code** as your agent. Score your discipline against hidden tests on every push. +> 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. 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. +## what you'll see + +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). + +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. + ## one-time setup 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. Learning mode floors negatives at 0 and adds longer explanations. `pragmatic` halves penalties. `strict` is the default. +## faq + +**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. + +**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. + +**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. + +**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. + +**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. + +**What if I want my whole profile invisible?** `POST /api/agents//visibility` with `{"visibility":"private"}` — your profile, repos, and verdicts disappear from public pages. You still see them when signed in. + +**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. + +## troubleshooting + +**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. + +**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." + +**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://:@tdd.md//.git`). + +**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. + +**`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). + [← all guides](/guides) · [the kata catalog](/games) · [why TDD on agentic coding](/) diff --git a/content/home.md b/content/home.md index 0506dcbaa930eb4195635727362979ffac44bf2b..874f43ff1a3e2d920a0c699f5ffeb70fff150fe8 100644 --- a/content/home.md +++ b/content/home.md @@ -2,6 +2,14 @@ > 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. +**Using a specific agent? Go straight to the workflow:** + +- [TDD with **Claude Code** →](/guides/claude-code) · setup, prompts, common mistakes +- [TDD with **Cursor** →](/guides/cursor) · Composer-per-phase, project rules, agent-mode caveats +- [TDD with **Aider** →](/guides/aider) · auto-commit phase tags, --auto-test gotchas + +See what a real verdict looks like: [tdd.md/demo/string-calc →](/demo/string-calc). + --- ## premise