QA Engineer Skills 2026QA-2026Copy-Paste Template: Feed This and the Customization Artifacts into Claude Code
HomeHomeJoinJoinProfileMe

Copy-Paste Template: Feed This and the Customization Artifacts into Claude Code

Purpose

This chapter is the actual scaffolding template.

It expects the application-specific artifacts from Chapters 1 and 2 to already exist.

You will copy-paste this template into Claude Code together with the required artifacts. Claude Code should then create an initial Playwright + TypeScript automation repo that is:

  • customized to the application
  • agent-ready
  • planning-heavy
  • validation-oriented
  • ready to begin building test cases, page objects, reusable components, API clients, fixtures, and starter tests

This is not a discovery prompt.
Discovery is already done.
This is a repo initialization prompt.

Required inputs

Before using this template, all of these must already exist:

playwright-scaffolding.md
docs/specs/product-under-test.md
docs/specs/ui-journeys.md
docs/specs/api-endpoints.md

Optional but useful:

docs/discovery/site-map-notes.md
docs/discovery/navigation-notes.md
docs/discovery/api-notes.md
docs/discovery/auth-notes.md
docs/discovery/open-questions.md

Non-negotiable rule

If playwright-scaffolding.md exists, it overrides generic assumptions.

Use real application structure.
Use real application terminology.
Do not keep generic placeholders where the product-specific artifacts provide better names.

Before you paste the template

Choose a permission mode

The scaffolding step creates dozens of files. In the default permission mode, Claude will pause and ask you to approve every single file creation. That defeats the purpose of autonomous scaffolding.

Recommended: acceptEdits mode. Claude creates and edits files freely. Shell commands still require approval.

claude --permission-mode acceptEdits -n scaffolding

Alternative: auto mode (requires Team, Enterprise, or API plan). A classifier model reviews every action. You can step away and let Claude work.

claude --permission-mode auto -n scaffolding

Alternative: worktree isolation. Scaffold in a disposable copy of the repo. Review the result, then merge or discard.

claude --worktree scaffolding --permission-mode acceptEdits

Name the session

Always name the scaffolding session so you can resume it if interrupted:

claude -n scaffolding --permission-mode acceptEdits

If Claude is interrupted mid-scaffold, resume with:

claude --resume scaffolding

Set up hooks (optional but recommended)

If you prepared hooks in Chapter 2 Step 12, confirm they are in .claude/settings.json before starting. At minimum, a lint-on-edit hook keeps the generated code clean as it is created.

Copy-paste template for Claude Code

You are scaffolding an initial Playwright + TypeScript UI and API automation harness for mostly autonomous agentic development.

Read these files first and treat them as the source of truth:

Required:
- playwright-scaffolding.md
- docs/specs/product-under-test.md
- docs/specs/ui-journeys.md
- docs/specs/api-endpoints.md

Optional, if present:
- docs/discovery/site-map-notes.md
- docs/discovery/navigation-notes.md
- docs/discovery/api-notes.md
- docs/discovery/auth-notes.md
- docs/discovery/open-questions.md

Your job is to create an initial repository state that is customized to the real application under test.

Important rules:
- If playwright-scaffolding.md exists, it overrides generic assumptions.
- Use real page names, real route groupings, real feature domains, real API client domains, and real journey names.
- Keep architectural principles from the generic harness, but customize naming and structure to the actual application.
- Do not preserve generic placeholder names if the artifacts provide real names.
- Prefer a repo that another agent can resume from after context loss.

Tech and tooling defaults:
- Node.js
- TypeScript
- Playwright Test
- npm
- ESLint
- Prettier
- dotenv
- zod

Primary harness requirements:
- UI automation with Playwright
- API automation with Playwright APIRequestContext by default
- shared auth/session helpers where appropriate
- environment-aware configuration
- local development support
- CI-aware structure
- artifact and debugging support
- strong repo memory via docs and plans

Create the repository with this top-level structure as a strong default, adapting names where the application-specific artifacts justify it:

.
├── AGENTS.md
├── CHANGELOG.md
├── CLAUDE.md
├── README.md
├── package.json
├── tsconfig.json
├── playwright.config.ts
├── .gitignore
├── .editorconfig
├── .env.example
├── .worktreeinclude
├── .claude/
│   ├── settings.json
│   ├── rules/
│   │   ├── page-objects.md
│   │   ├── api-clients.md
│   │   ├── test-writing.md
│   │   └── selectors.md
│   ├── agents/
│   │   ├── planner.md
│   │   ├── generator.md
│   │   ├── evaluator.md
│   │   └── reviewer.md
│   └── skills/
│       ├── new-page-object/SKILL.md
│       ├── new-test-spec/SKILL.md
│       ├── run-evaluator/SKILL.md
│       └── log/SKILL.md
├── scripts/
│   ├── bootstrap.ts
│   ├── validate.ts
│   ├── smoke-ui.ts
│   ├── smoke-api.ts
│   ├── doc-check.ts
│   ├── plan-init.ts
│   └── new-spec.ts
├── config/
│   ├── env/
│   ├── projects/
│   └── test-data/
├── src/
│   ├── core/
│   ├── ui/
│   │   ├── pages/
│   │   ├── components/
│   │   ├── flows/
│   │   └── assertions/
│   ├── api/
│   │   ├── clients/
│   │   ├── builders/
│   │   ├── helpers/
│   │   ├── schemas/
│   │   └── assertions/
│   ├── shared/
│   │   ├── data/
│   │   ├── factories/
│   │   ├── utils/
│   │   └── state/
│   └── fixtures/
├── tests/
│   ├── ui/
│   │   ├── smoke/
│   │   ├── regression/
│   │   └── accessibility/
│   ├── api/
│   │   ├── smoke/
│   │   ├── regression/
│   │   └── contract/
│   ├── hybrid/
│   └── setup/
├── artifacts/
│   ├── reports/
│   ├── screenshots/
│   ├── videos/
│   ├── traces/
│   └── logs/
├── docs/
│   ├── index.md
│   ├── architecture/
│   ├── standards/
│   ├── runbooks/
│   ├── specs/
│   ├── plans/
│   │   ├── active/
│   │   ├── completed/
│   │   ├── handoffs/
│   │   └── templates/
│   ├── agents/
│   └── decisions/
└── .github/
    └── workflows/

Create meaningful starter content, not empty placeholders, for these files:
- README.md
- CLAUDE.md
- AGENTS.md
- docs/index.md
- docs/architecture/repo-map.md
- docs/architecture/test-layering.md
- docs/architecture/ui-harness.md
- docs/architecture/api-harness.md
- docs/architecture/data-and-state.md
- docs/standards/coding-standards.md
- docs/standards/test-writing-standards.md
- docs/standards/selector-strategy.md
- docs/standards/api-contract-strategy.md
- docs/standards/logging-and-redaction.md
- docs/standards/flaky-test-policy.md
- docs/runbooks/local-dev.md
- docs/runbooks/ci.md
- docs/runbooks/debugging.md
- docs/runbooks/traces-and-screenshots.md
- docs/runbooks/incident-response-for-failing-tests.md
- docs/agents/planner.md
- docs/agents/generator.md
- docs/agents/evaluator.md
- docs/agents/reviewer.md
- docs/agents/doc-gardener.md
- docs/plans/templates/sprint-contract-template.md
- docs/plans/templates/execution-plan-template.md
- docs/plans/templates/evaluator-report-template.md
- docs/decisions/0001-initial-harness-architecture.md
- .claude/settings.json
- .claude/rules/page-objects.md
- .claude/rules/api-clients.md
- .claude/rules/test-writing.md
- .claude/rules/selectors.md
- .claude/agents/planner.md
- .claude/agents/generator.md
- .claude/agents/evaluator.md
- .claude/agents/reviewer.md
- .claude/skills/new-page-object/SKILL.md
- .claude/skills/new-test-spec/SKILL.md
- .claude/skills/run-evaluator/SKILL.md
- .claude/skills/log/SKILL.md
- .worktreeinclude
- CHANGELOG.md

Root instruction rules:
- CLAUDE.md must be under 200 lines. Keep it navigational — use @path/to/file.md imports to reference detailed docs.
- CLAUDE.md should import key docs: @playwright-scaffolding.md, @docs/specs/product-under-test.md, @docs/standards/coding-standards.md, @AGENTS.md, etc.
- CLAUDE.md must include a "Work log" section near the top: "ALWAYS update CHANGELOG.md before committing" with the required entry format (date, summary, files changed, why). This advisory rule is backed by the PreToolUse commit hook.
- AGENTS.md must define the collaboration model and handoff rules. CLAUDE.md imports it via @AGENTS.md.
- Do not create one giant monolithic instruction file.
- Future agents should be able to continue from repo files alone.

Path-scoped rules (.claude/rules/):
Create rule files with YAML frontmatter `paths:` fields so rules only load when Claude works with matching files:
- .claude/rules/page-objects.md (paths: src/ui/pages/**/*.ts) — selector strategy, page object patterns, waitForReady requirement
- .claude/rules/api-clients.md (paths: src/api/**/*.ts) — APIRequestContext usage, schema validation, redaction
- .claude/rules/test-writing.md (paths: tests/**/*.ts) — test naming, assertion style, no hardcoded waits, smoke test time limits
- .claude/rules/selectors.md (paths: src/ui/**/*.ts) — getByRole first, getByTestId second, never CSS selectors for user-facing elements

Native subagents (.claude/agents/):
Create subagent definitions so Claude can delegate specialized tasks:
- .claude/agents/planner.md — tools: Read, Grep, Glob. Creates sprint contracts before implementation.
- .claude/agents/generator.md — tools: Read, Grep, Glob, Edit, Write, Bash. Implements the current sprint scope.
- .claude/agents/evaluator.md — tools: Read, Grep, Glob, Bash. Verifies implementation against sprint contract, writes PASS/FAIL report.
- .claude/agents/reviewer.md — tools: Read, Grep, Glob. Reviews code for quality, patterns, and security.
Each subagent must have a description field that tells Claude when to delegate to it automatically.

Skills (.claude/skills/):
Create reusable workflow definitions:
- .claude/skills/new-page-object/SKILL.md — create a new page object from a page name
- .claude/skills/new-test-spec/SKILL.md — create a new test file from a journey description
- .claude/skills/run-evaluator/SKILL.md — invoke the evaluator against the current sprint contract
- .claude/skills/log/SKILL.md — update CHANGELOG.md with a summary of recent work (invoke with /log)

Hooks (.claude/settings.json):
Configure hooks for automated quality enforcement:
- PostToolUse hook on Edit|Write: run eslint --fix on changed files
- PreToolUse hook on Bash(git commit*): block commits unless CHANGELOG.md is staged — this is the only guaranteed way to enforce work logging
- Notification hook: notify when Claude needs attention (useful during long scaffolding runs)

Worktree support:
- Create .worktreeinclude listing .env and .env.local so environment files are copied into worktrees automatically
- Add .claude/worktrees/ to .gitignore

Agent workflow requirements:
- Make Planner → Generator → Evaluator the default core loop.
- Planner defines scope and acceptance criteria before coding.
- Generator implements only the current sprint scope.
- Evaluator verifies against the sprint contract and writes PASS/FAIL with evidence.
- Also include Reviewer and Doc-gardener role docs as secondary roles.

Planning requirements:
Create a planning system with:
- docs/plans/active/
- docs/plans/completed/
- docs/plans/handoffs/
- docs/plans/templates/

The plan templates must support:
- sprint contract
- execution plan
- evaluator report

Code design requirements:
- Use Playwright with TypeScript for UI and API automation.
- Use Playwright APIRequestContext as the default API transport layer.
- Keep selectors inside the owning page objects by default.
- Keep reusable page behavior in page objects.
- Keep multi-page business behavior in flow helpers.
- Use component objects only for repeated page fragments.
- Use assertion helpers for reusable expectations.
- Prefer simple fixtures over clever abstractions.
- Prefer explicit readable code over heavy indirection.

UI harness requirements:
- Create page-object files named from the actual application pages where possible.
- Create flow helpers for the most important journeys from docs/specs/ui-journeys.md.
- Create starter smoke coverage for the most critical UI paths.
- Add at least one accessibility-oriented starter test where the product makes sense for it.

API harness requirements:
- Organize API clients by the real endpoint domains from docs/specs/api-endpoints.md.
- Use wrapper client classes and schema validation.
- Add starter smoke coverage for auth and one major business domain.
- Add one contract-style example using schema validation.
- Add explicit status/body/header assertions where meaningful.

Hybrid test requirements:
- Add one example test that seeds or prepares state via API and validates via UI.

Fixtures and auth requirements:
- Create environment-aware fixtures.
- Include storageState support where appropriate.
- Reflect the auth/session model from docs/specs/product-under-test.md.
- Do not hardcode secrets.
- Create .env.example with representative non-secret placeholders.

Validation requirements:
Add npm scripts for:
- bootstrap
- lint
- format
- format:check
- typecheck
- test
- test:ui
- test:api
- test:smoke
- test:contract
- test:a11y
- docs:check
- validate
- report
- plan:init
- new:spec

Recommended validate behavior:
- format check
- lint
- typecheck
- smoke tests

Playwright config requirements:
- separate UI and API projects
- environment selection through env vars
- trace retention on failure
- screenshots on failure
- video retention on failure for UI
- HTML report output under artifacts/reports/playwright-report
- test results output under artifacts/reports/test-results
- sensible retries
- base URL configurable via env
- storageState support
- tags or project targeting for smoke, regression, contract, and accessibility
- global setup / teardown hooks

Artifacts and debugging requirements:
Use predictable artifact locations:
- artifacts/reports
- artifacts/screenshots
- artifacts/videos
- artifacts/traces
- artifacts/logs

Write runbooks that explain:
- how to run a single test
- how to open the Playwright report
- how to inspect traces
- how to regenerate auth state
- how to run only API tests
- how to switch environments

Redaction requirements:
- never log raw secrets
- never log raw auth tokens
- redact auth headers
- redact cookies
- redact PII and session values where practical

CI requirements:
Create:
- .github/workflows/ci.yml
- .github/workflows/smoke.yml
- .github/workflows/docs-check.yml

Expected CI behavior:
- lint
- typecheck
- run smoke UI and API tests
- upload Playwright report and failure artifacts when needed
- validate docs structure where practical

Starter test requirements:
Create a minimal but meaningful starter suite aligned to the application-specific artifacts:
- UI smoke test(s)
- UI regression sample
- one accessibility sample
- API auth smoke test
- API major-domain sample
- API contract-style sample
- one hybrid example

Do not generate generic nonsense tests. Use the discovered journeys and feature names.

Definition of done for the scaffold:
The scaffold is not done unless:
- required structure exists
- key docs contain meaningful starter content
- CLAUDE.md exists and is under 200 lines, using @imports for detailed docs
- .claude/rules/ contains path-scoped rules for page objects, API clients, tests, and selectors
- .claude/agents/ contains native subagent definitions for planner, generator, evaluator, and reviewer
- .claude/skills/ contains at least new-page-object, new-test-spec, and run-evaluator workflows
- .claude/settings.json contains hooks for lint-on-edit, changelog-on-commit, and notifications
- CHANGELOG.md exists with the initial scaffold entry
- .worktreeinclude lists .env files for worktree support
- root instruction files exist
- plan templates exist
- package scripts exist
- Playwright config exists and is coherent
- starter tests exist
- docs and naming reflect the real application where known
- no secrets are committed
- the repo is understandable to a future agent with no chat history

Bootstrap order:
1. create folder structure
2. create root config files
3. create package scripts and dependencies
4. create Playwright config
5. create core utilities and fixtures
6. create sample UI/API/hybrid tests aligned to the product
7. create docs index and architecture docs
8. create agent role docs
9. create plan templates
10. create CI workflows
11. run validation and fix scaffold issues
12. update README with exact getting-started steps

At the end, provide:
1. a concise summary of what was created
2. a short list of follow-up tasks
3. any assumptions that still need human confirmation

Do not ask to continue later. Perform the scaffolding now from the provided artifacts.

How to use the template in practice

You will usually give Claude Code:

  1. the chapter prompt above
  2. playwright-scaffolding.md
  3. docs/specs/product-under-test.md
  4. docs/specs/ui-journeys.md
  5. docs/specs/api-endpoints.md

If the application is complex, also provide the optional discovery notes.

This gives Claude Code both:

  • the what to build
  • the application context to customize it correctly

Why this template is structured this way

This template intentionally separates:

  • product discovery
  • quick-start preparation
  • actual scaffolding

That separation makes the resulting repo better because Claude Code is not forced to invent the product structure while also inventing the harness.

The repo should start with:

  • structure
  • standards
  • plans
  • agent roles
  • starter automation patterns
  • documentation that matches reality

That is much better than generating a bag of generic files.

After the scaffold exists

Once Claude Code has created the initial repo state, the normal loop becomes:

Planner → Generator → Evaluator

At that point, the repo should already contain:

  • CLAUDE.md (under 200 lines, with @imports)
  • AGENTS.md
  • .claude/rules/ path-scoped rules
  • .claude/agents/ native subagent definitions
  • .claude/skills/ repeatable workflows
  • .claude/settings.json with hooks
  • architecture docs
  • standards docs
  • plan templates
  • starter page objects
  • starter API clients
  • starter fixtures
  • starter tests
  • CI skeletons
  • artifact conventions

How to work after scaffolding

Start new sessions in acceptEdits mode for day-to-day work:

claude --permission-mode acceptEdits

Use skills to create new artifacts consistently:

/new-page-object ProductDetailPage
/new-test-spec "user adds item to cart"

Delegate investigation to subagents to keep your main context clean:

use a subagent to investigate how the checkout flow handles payment errors

Run the evaluator after completing a sprint:

use the evaluator subagent to verify the current sprint contract

Clear context between unrelated tasks with /clear. Long sessions with accumulated irrelevant context degrade Claude's performance.

Auto memory keeps learning. As you correct Claude's code style, naming, or patterns, it saves those corrections automatically. Future sessions start with that knowledge built in.

Then the agents can begin creating:

  • new test cases
  • new page objects
  • new reusable components
  • new API clients
  • new fixtures
  • deeper regression coverage
  • refactors guided by the standards and plans

Final rule

If playwright-scaffolding.md exists, it is the truth.
Not generic examples.
Not memory.
Not assumptions.

That is what makes the scaffold customized instead of generic.