A CLAUDE.md Template for QA Work

A CLAUDE.md file for QA work tells Claude Code how your team writes bug reports, which environments are in scope for testing, what evidence a report requires before it is filed, and what "done" means for a test pass. Without those rules, an assistant will write reports in whatever format it guesses is standard — and that format may not match what your developers need to act on the report.

Tools like fenbs are a natural place to keep the defects that are currently open, lessons from past test cycles, and decisions about which issues to fix now versus defer. Your CLAUDE.md stays focused on the process rules that apply to every test session. This page gives you a template to copy and adapt.

What belongs in a CLAUDE.md for QA

Good QA instructions are concrete and checkable. Avoid describing an ideal in general terms like "write clear reports." Instead, describe the exact fields a report needs, the steps for capturing a screenshot or a log, and the sentence that confirms a test has passed. Claude Code follows specific rules reliably; it interprets vague guidance differently each time.

• Bug report format: the required fields, the steps to reproduce pattern, and where reports are filed.
• Test environments: which URLs, devices, or versions are in scope for each test type.
• Evidence requirements: what a screenshot, log file, or network trace must show before a defect is filed.
• Completion criteria: the specific check or observable outcome that confirms a test case passed.
• Out-of-scope items: features, environments, or edge cases that are not part of the current test plan.

The template

Copy this into a CLAUDE.md at your project root or in a dedicated QA folder. Fill in the bracketed sections for your specific project.

# [Project name] — QA instructions

## Bug report format
File reports in [your issue tracker / fenbs / GitHub Issues].

Required fields for every defect:
- **Title**: [Component] Short description of what is wrong (not what is expected)
- **Environment**: Browser/device/OS + application version or build number
- **Steps to reproduce**: Numbered, starting from a fresh state
- **Actual result**: Exactly what happened, with a screenshot or log if visible
- **Expected result**: What the specification or acceptance criteria says should happen
- **Severity**: Critical / High / Medium / Low (see definitions below)

Severity definitions:
- Critical — blocks core functionality; no workaround exists
- High — significant feature broken; workaround is difficult
- Medium — feature impaired; workaround exists
- Low — cosmetic or minor inconvenience

## Test environments
- **Browser smoke tests**: Chrome latest, Firefox latest on Windows 11
- **Mobile**: Safari on iOS 17+, Chrome on Android 14+
- **API tests**: Staging endpoint at [URL]; use the test account [describe]
- **Do not test against production** unless the test plan explicitly permits it.

## Evidence requirements
Before filing a defect, capture:
1. A screenshot showing the actual result, taken in the environment listed above.
2. The browser console (F12 → Console tab), copied as text if errors appear.
3. The network request and response for the failing call, if the defect is API-related.
4. The full steps to reproduce, verified to be repeatable from a clean state.

## Completion criteria
A test case is complete when:
- The pass criterion in the test case document is observed, or
- A defect is filed that blocks the pass criterion and linked to the test case.

Do not mark a test case as passed until you have confirmed the observable outcome,
not just that no errors appeared.

## Out of scope for this cycle
[List features, environments, or browsers excluded from the current test plan.]

## What Claude Code must not do
- File a defect without the required evidence.
- Mark a test case as passed without confirming the completion criterion.
- Access production systems unless the test plan explicitly permits it.

Writing reproducible steps

The hardest part of a bug report is the steps to reproduce. An assistant will write steps that reflect what it observed, but those steps may skip a prerequisite state or assume knowledge the developer does not have. In your CLAUDE.md, add a rule like "Steps to reproduce must start from a signed-out browser with no stored cookies" or "Steps must begin from the application's home screen."

That one constraint forces Claude Code to include the sign-in step, the navigation path, and any test data setup that the developer needs to repeat the defect. A report that skips those steps generates a follow-up question before any investigation begins.

Evidence standards reduce back-and-forth

Requiring a screenshot and a console log as standard evidence cuts the number of "can you reproduce this?" replies your team receives. When Claude Code writes a report, it can describe what evidence it found and flag cases where the evidence is missing or incomplete. Add a short note about what the evidence must show — "the screenshot must include the error message text, not just the surrounding page" — to avoid screenshots that fail to capture the actual defect.

When a defect comes back after a fix, the evidence from the original report becomes part of the investigation. A CLAUDE.md rule like "Include the console log output for any defect involving an API call" means that evidence is captured the first time rather than requested after the fact. That single habit saves one round trip per bug that involves a backend call.

Lessons from past test cycles

Some defects recur in a slightly different form each release. Others reveal a pattern in how a feature was built that produces related issues elsewhere. When a test cycle ends, the useful lessons — which areas produced the most defects, which evidence type was most often missing, which reproducibility step was hardest to write — belong somewhere the next cycle can use them.

A project's Lessons learned in fenbs stores those facts outside any one chat session. A connected assistant reads them before starting a new test cycle, so it approaches the riskiest areas first and asks for the evidence that was hardest to capture last time.

How to do this with fenbs

1. Create a free account. Start a fenbs project for this product and add open defects as Bug tasks.
2. Add QA rules — severity definitions, evidence requirements, out-of-scope decisions — as Decisions and rules so every connected assistant sees them first.
3. Connect Claude Code to fenbs from Integrations. At the start of a test session, ask it to read the project context to get the current rules and open defects.
4. After a test cycle, record what the cycle taught as lessons in fenbs, linked to the tasks they relate to.
5. Copy the CLAUDE.md template above into your project root and update the bracketed sections for your environments, severity definitions, and tracker. Revisit it after each test cycle to add any new rules that emerged.

See CLAUDE.md examples for how other teams structure their instruction files, including examples from development and documentation projects. For troubleshooting when Claude Code does not follow a QA rule, see CLAUDE.md not working for the most common causes.