2.10Step 6 — Prepare the root instruction strategy

Claude Code reads CLAUDE.md at the start of every session. It is the most important file for shaping Claude's behavior, but it must stay under 200 lines. Longer files get ignored.

The solution is to keep CLAUDE.md short and navigational, and use two complementary mechanisms:

• @import syntax — CLAUDE.md can reference other files with @path/to/file.md. Claude expands them automatically at session start.
• .claude/rules/ — path-scoped rules that only load when Claude is working with matching files.

What CLAUDE.md should contain

# Playwright Automation Harness — [Product Name]

## What this repo is
One-sentence description.

## Source of truth
@playwright-scaffolding.md overrides generic assumptions.

## Key docs
- Product spec: @docs/specs/product-under-test.md
- UI journeys: @docs/specs/ui-journeys.md
- API endpoints: @docs/specs/api-endpoints.md
- Architecture: @docs/architecture/repo-map.md

## Validation
Run before committing:
- `npm run validate` (format, lint, typecheck, smoke)
- `npm run test:smoke`

## Standards
- @docs/standards/coding-standards.md
- @docs/standards/test-writing-standards.md
- @docs/standards/selector-strategy.md

## Work log — IMPORTANT
ALWAYS update CHANGELOG.md before committing. Every entry must include:
- date
- what was done (one-line summary)
- which files were created or changed
- why the change was made

## Agent workflow
Planner → Generator → Evaluator. See @AGENTS.md.

## Plans
- Active plans: docs/plans/active/
- Completed plans: docs/plans/completed/

The @ syntax makes the referenced files available to Claude without repeating their contents in CLAUDE.md. This keeps the root file navigational while giving Claude deep context on demand.

Use .claude/rules/ for path-scoped rules

Instead of putting every coding rule in CLAUDE.md, create rule files in .claude/rules/ that only apply when Claude is working with matching files:

.claude/
└── rules/
    ├── page-objects.md      # rules for src/ui/pages/**
    ├── api-clients.md       # rules for src/api/**
    ├── test-writing.md      # rules for tests/**
    └── selectors.md         # rules for src/ui/**

Each rule file uses YAML frontmatter to specify which paths it applies to:

---
paths:
  - "src/ui/pages/**/*.ts"
---

# Page Object Rules

- Selectors live inside the owning page object, never in test files
- Page objects expose actions, not raw locators
- Use `getByRole`, `getByText`, or `getByTestId` — avoid CSS selectors
- Every page object must have a `waitForReady()` method

---
paths:
  - "tests/**/*.ts"
---

# Test Writing Rules

- One assertion concept per test
- Use descriptive test names that read as sentences
- Never use `page.waitForTimeout()` — rely on auto-waiting
- Smoke tests must complete in under 10 seconds

Path-scoped rules are powerful because they:

• do not consume context tokens until Claude actually works with matching files
• prevent rule conflicts (UI rules cannot confuse API work)
• scale as the repo grows without bloating CLAUDE.md

AGENTS.md — the multi-agent operating model

CLAUDE.md imports AGENTS.md via @AGENTS.md. This file defines role responsibilities and handoff rules:

• role responsibilities
• handoff rules
• when the planner must be consulted
• when the evaluator must fail work
• when docs must be updated

Use .claude/agents/ for native subagents

Claude Code supports native subagents — specialized assistants that run in their own context window with their own set of allowed tools. Instead of only documenting agent roles in docs/agents/, create actual subagent definitions in .claude/agents/:

<!-- .claude/agents/evaluator.md -->
---
name: evaluator
description: Verifies implementation against sprint contract. Use after completing a sprint.
tools: Read, Grep, Glob, Bash
---

You are the evaluator. Your job is to verify implementation quality.

1. Read the sprint contract from docs/plans/active/
2. Run all validation commands listed in the contract
3. Check that acceptance criteria are met
4. Write a PASS/FAIL report to docs/plans/handoffs/
5. If FAIL, list specific issues with file paths and line numbers

<!-- .claude/agents/planner.md -->
---
name: planner
description: Creates sprint contracts and execution plans before implementation work begins.
tools: Read, Grep, Glob
---

You are the planner. Your job is to define scope before coding.

1. Read the request or spec
2. Explore the codebase to understand current state
3. Write a sprint contract to docs/plans/active/
4. The contract must include: scope, out of scope, acceptance criteria, validation commands, expected files to change, risks

Native subagents are better than plain documentation because:

• Claude Code delegates tasks to them automatically based on the description field
• they run in a separate context window, so investigation work does not clutter your main session
• you can scope their tools (e.g., the evaluator can run Bash commands, but a reviewer might only need Read)
• you can request a specific one: "use the evaluator subagent to verify my last change"

Keep the role docs in docs/agents/ as human-readable references, but create the .claude/agents/ definitions as the actual working subagents.

Use .claude/skills/ for repeatable workflows

Skills are reusable prompts that Claude applies automatically when relevant, or that you can invoke directly with /skill-name:

<!-- .claude/skills/new-page-object/SKILL.md -->
---
name: new-page-object
description: Create a new page object for a given page
---

Create a new page object for: $ARGUMENTS

1. Read docs/specs/product-under-test.md for context
2. Read docs/standards/selector-strategy.md for selector rules
3. Look at existing page objects in src/ui/pages/ for patterns
4. Create the page object file in src/ui/pages/
5. Add a `waitForReady()` method
6. Export it from the pages index
7. Run `npm run typecheck` to verify

<!-- .claude/skills/new-test-spec/SKILL.md -->
---
name: new-test-spec
description: Create a new test specification file
---

Create a test spec for: $ARGUMENTS

1. Read docs/specs/ui-journeys.md for journey context
2. Look at existing tests in the matching test folder for patterns
3. Create the test file following docs/standards/test-writing-standards.md
4. Run the new test with `npx playwright test <file> --reporter=line`
5. Fix any failures

<!-- .claude/skills/log/SKILL.md -->
---
name: log
description: Update CHANGELOG.md with a summary of recent work
---

Update CHANGELOG.md with what was done in this session.

1. Check git diff and git status for all changes since the last changelog entry
2. Summarize what was accomplished, grouped by feature or concern
3. List all files created or modified with a brief note for each
4. Add the entry at the top of CHANGELOG.md under today's date
5. Stage CHANGELOG.md

Invoke skills directly: /new-page-object CheckoutPage, /new-test-spec checkout smoke, or /log after completing work.

Skills differ from .claude/rules/ in an important way:

• Rules load automatically when Claude touches matching files — use them for standards and constraints
• Skills load on demand when invoked or when Claude determines they are relevant — use them for workflows and procedures