测试生成与规范

Ask Claude Code to "write tests for this module" with no guidance and you get tests that run but don't match your house style: wrong framework helpers, invented fixtures, assertions that mirror the implementation instead of the contract.

The fix is not a better one-off prompt. It is persistent, shared standards the model reads on every run. This lesson shows how to document fixtures and conventions so generated tests come out idiomatic, deterministic, and reviewable, in interactive sessions and in CI alike.

Test conventions belong in project-level config so every contributor and every CI runner sees them. Put them in ./CLAUDE.md or .claude/CLAUDE.md, which is shared via VCS.

Do NOT rely on user-level ~/.claude/CLAUDE.md: it is personal, NOT shared through version control, so new teammates and your pipeline simply won't have it. Anything your test generation depends on must live in project scope.

A monolithic CLAUDE.md grows unreadable and burns context. Pull the detailed testing playbook into its own file and import it with @path syntax. This keeps the root file lean while still loading the standard.

The imported file is just markdown, version-controlled like everything else, so the standard is reusable and easy to review in isolation.

Even better than always-on imports: put test conventions in a .claude/rules/ file with YAML frontmatter paths. The rule loads only when editing matching files, so you save context and tokens versus a monolithic CLAUDE.md that ships everything on every turn.

Scope a rule to your test directory and it activates exactly when Claude is generating or editing tests, and stays out of the way otherwise.

The single biggest cause of bad generated tests is invented fixtures: the model fabricates a user object or a DB stub instead of using yours. Document the real fixtures so Claude reuses them.

Spell out what each fixture provides, its shape, and when to use it. Treat this like a tool description: purpose, return value, input format, and applicability boundaries are what drive correct selection.

Prose alone leaves ambiguity. Add 2 to 4 targeted examples of a canonical test and the model generalizes the pattern, it does not merely copy it. Few-shot examples are the strongest lever for consistency, edge cases, and output format.

Show one complete, idiomatic test that uses your real fixtures. New tests will mirror its structure, naming, and assertion style.

"Write good tests" is a vague wish. Explicit criteria produce reliable output. Compare "be thorough" with "cover the happy path, one boundary value, and one error path; never test private methods directly."

Concrete, checkable rules remove the guesswork that makes generated tests inconsistent across files and contributors.

Make the workflow repeatable with a .claude/skills/ skill (project scope is shared via VCS; user scope is personal). The skill bundles your standard and can restrict tools and isolate output.

Use context: fork to isolate verbose generation output, allowed-tools to restrict what it can touch, and argument-hint to guide the caller. Now "generate tests to standard" is one reusable command instead of a re-typed paragraph.

Don't generate in a vacuum. Have Claude follow the incremental investigation pattern first: Glob for existing test files, Read a couple, Grep for how a fixture is used, then write a new test that matches what's already there.

Grounding generation in the real codebase beats reciting a style guide, because the model copies living, working conventions instead of guessing.

In a pipeline, generate tests headless with -p (required: no human is present) and --output-format json so a later step can parse the result. Then review the generated tests in a separate, isolated session.

Fresh-instance review beats same-session self-review: the author retains its own reasoning and won't challenge its own tests. A clean reviewer catches tautological assertions and missing failure cases the generator overlooked.

When you ask for tests as structured output (tool_use + JSON Schema), validate the result. If it is malformed, use retry-with-feedback: resend the original request, the wrong output, and the exact validation error. This reliably fixes format and structural mistakes.

Two cautions from the fact sheet: retry does NOT help when the needed info is simply absent from the source, and you should mark a schema field required only if it is always present, or the model will fabricate it.

Apply the lesson to a realistic standards decision.

Key takeaways:

• Put testing standards in project scope (./CLAUDE.md, .claude/rules/ with paths), shared via VCS; never depend on personal ~/.claude/CLAUDE.md in CI.
• Modularize with @path imports; rules with frontmatter paths load only when editing matching files, saving context.
• Document fixtures as the source of truth (purpose, shape, when to use) so the model reuses them instead of inventing stubs.
• Few-shot (2-4 canonical examples) plus explicit criteria beat vague instructions; the model generalizes the pattern.
• Wrap it in a .claude/skills/ skill; have Claude investigate existing tests (Glob/Read/Grep) before writing.
• In CI, generate headless with -p --output-format json, then review in a fresh, isolated session.
• Validate structured output; retry-with-feedback fixes format errors but not missing information, and require a schema field only if it is always present.