Configuring Claude Code for QA Work

Claude Code works out of the box, but a few minutes of configuration repays itself every session. This lesson covers the settings that matter for QA: permission rules that remove friction without removing safety, model selection, and the CLAUDE.md project file that teaches Claude Code your codebase so you stop explaining it every session.

Where settings live

Claude Code has two levels of configuration:

• Global (~/.claude/settings.json) — applies to every project on your machine
• Project (.claude/settings.json) — applies only when you run Claude Code inside that project

Project settings override global settings. Check the project config into version control so your whole team uses the same defaults.

Permissions

The most impactful configuration is the permission list — which commands Claude Code can run without asking, and which are always blocked.

{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npx playwright test:*)",
      "Bash(npx cypress run:*)",
      "Bash(git diff:*)",
      "Bash(git status:*)",
      "Bash(git log:*)"
    ],
    "deny": [
      "Bash(git push:*)",
      "Bash(git commit:*)",
      "Bash(rm -rf:*)",
      "Bash(npm publish:*)"
    ]
  }
}

The pattern is: allow commands that are fast and reversible (running tests, checking status), block commands that need a human decision (pushing, committing, deleting, publishing).

This is team policy encoded in a file. Committed to version control, it means every engineer on the team gets the same approval behaviour without each person having to configure their own machine.

Model selection

Claude Code defaults to Sonnet 4.6 — fast, capable, and cost-effective for the majority of QA tasks. You can change the model per-session with /model or set it in your config:

{
  "model": "claude-opus-4-7"
}

In practice: use Sonnet for everything and switch to Opus only when working on a complex multi-file refactor where output quality has been underwhelming. The cost difference is meaningful at scale.

CLAUDE.md — your project's standing brief

CLAUDE.md is a Markdown file at the project root that Claude Code reads at the start of every session. It is the right place for:

• Test framework and language (e.g., "This project uses Playwright with TypeScript")
• Folder conventions (e.g., "Tests go in tests/, page objects in src/pages/")
• Selector rules (e.g., "Use data-testid attributes, not CSS selectors")
• Off-limits files (e.g., "Do not edit files in src/components/")
• Project-specific context (e.g., "The staging environment is at https://staging.myapp.com")

Run /init inside a Claude Code session and it generates a draft CLAUDE.md by reading your project. Edit the output to add the constraints that matter and delete the generic filler. Two focused paragraphs beat a thousand-line overview.

MCP server configuration

MCP servers connect Claude Code to external tools. The most useful for QA is Playwright MCP, which lets Claude Code navigate real pages and inspect selectors during test generation. Add it with one command:

claude mcp add playwright npx @playwright/mcp@latest

MCP servers are covered in depth in Chapter 4. For now, knowing the command exists is enough.

Useful flags and slash commands

# Continue the previous session (preserves conversation history)
claude --continue
 
# Non-interactive one-shot mode — useful in CI scripts
claude --print "Run the smoke tests and output a pass/fail summary"
 
# Resume a specific past session by ID
claude --resume SESSION_ID

Inside a session:

• /init — generate a CLAUDE.md draft for the current project
• /cost — see token usage for this session
• /clear — reset conversation history without ending the session
• /model — switch model for the rest of this session

⚠️ Common Mistakes

• Writing a CLAUDE.md that is too long. A thousand-line project overview is not useful. Two paragraphs covering the stack, the key folders, and the rules that actually matter is. Keep it scannable — Claude Code reads it on every session start.
• Not committing project settings. If .claude/settings.json is in .gitignore, every engineer starts fresh with different defaults. The file contains no secrets — commit it alongside the rest of the project configuration.
• Leaving git push in the allow list. Pushes to shared branches affect other people's work. The two-second approval prompt is worth it.

🎯 Practice Task

Configure a real project for productive Claude Code use. 20 minutes.

1. Create .claude/settings.json in a project you work on. Add allow rules for your test runner (npm test, npx playwright test, or equivalent) and deny rules for git push and git commit.
2. Run claude and use /init to generate a CLAUDE.md draft. Edit it to reflect your actual test structure and conventions.
3. Start a fresh session and ask: "What test conventions does this project follow?" Confirm Claude Code's answer comes from the CLAUDE.md you wrote.

Chapter 2 puts this configured setup to work — generating tests, refactoring existing ones, and building page objects entirely from natural language prompts.