Every team has conventions. Use this selector pattern. Put files here. Never do that. Import from this file, not that one.
The problem is that conventions live in people's heads. A new team member, human or AI, doesn't know them until they make a mistake. With humans, you do a code review and explain. With AI, you get the same mistake every single time, because it resets to zero with every new conversation.
CLAUDE.md solves this. It's a file that the AI reads at the start of every session, every time, before generating a single line of code.
🤔 What Is CLAUDE.md?
It's a markdown file at the root of the project, but it's not documentation for humans. It's an instruction set for an AI agent.
When Claude Code (or any Claude-based agent) opens your project, it reads CLAUDE.md first. Everything in that file shapes how the agent behaves throughout the session. What patterns it follows, what it checks before writing, what it refuses to do.
Think of it as onboarding documentation that actually gets read.
Not just for Claude. The scaffold provides the same rules in three formats:
CLAUDE.mdfor Claude Code,.cursor/rules/for Cursor, and.github/copilot-instructions.mdfor GitHub Copilot. Same architecture, different file paths. This article usesCLAUDE.mdas the example, but the pattern applies regardless of which AI tool you use.
🏛️ The Constitution Pattern
The scaffold organizes CLAUDE.md around three tiers of rules, a structure borrowed from how legal systems separate mandatory law from guidance to prohibition:
MUST → Mandatory. No exceptions, no debate.
SHOULD → Recommended. The agent prefers this unless there's a reason not to.
WON'T → Forbidden. The agent refuses to do this regardless of what's asked.
This three-tier structure is important. If everything is mandatory, the agent has no room to exercise judgment. If everything is flexible, the agent defaults to its own habits, which may not match yours. The tiers give the agent a clear mental model of what's negotiable and what isn't.
✅ The MUST Rules
These are non-negotiable. The scaffold's mandatory rules cover the things that, if violated, break the architecture:
| Rule | Requirement |
| -------------------- | ------------------------------------------------------------- |
| Dependency Injection | Never use `new PageObject(page)` in tests |
| Imports | Import `test` and `expect` from fixtures/pom/test-options.ts |
| Selectors | getByRole() > getByLabel() > getByPlaceholder() > getByText() |
| Type Safety | Use Zod schemas in fixtures/api/schemas/, no `any` type |
| Strict Schemas | Always use z.strictObject(), never z.object() |
| Assertions | Web-first assertions only, never waitForTimeout() |
Notice how specific these are. "Use semantic selectors" is too vague. The agent has to interpret what that means. "Use getByRole() before getByLabel() before getByPlaceholder()" is unambiguous. The agent follows a decision tree.
💡 The SHOULD Rules
These are recommendations for when the agent has a choice:
| Rule | Recommendation |
| --------------- | ------------------------------------------------------------- |
| Explore First | Navigate to the page or endpoint before generating code |
| Data Generation | Use Faker via factories for all happy-path test data |
| Test Isolation | Tests should be independent. Use beforeEach, not shared state |
| Test Steps | Use Given/When/Then structure with test.step() |
"Explore First" is here rather than in MUST because there are legitimate cases where you've already provided the element structure. The agent uses its judgment.
🚫 The WON'T Rules
These are hard blocks, things the agent should refuse to do even if you ask nicely:
| Rule | Violation |
| -------------------- | ---------------------------------------------- |
| No XPath | Never use XPath selectors |
| No Hard Waits | Never use page.waitForTimeout() |
| No `any` | Never use TypeScript's any type |
| No Multiple Tags | Each test has exactly ONE tag |
| No Hardcoded Content | Never hardcode test strings. Use Faker instead |
| No Loose Schemas | Never use z.object(), always z.strictObject() |
The WON'T list is where institutional knowledge lives. These are the mistakes your team has made (or seen others make) and decided to never repeat. Writing them down here means the AI inherits that hard-won experience.
🗺️ The Workflow Section
Beyond rules, CLAUDE.md also defines a step-by-step workflow the agent follows for every code generation task:
1. Read this file (always loaded)
2. Explore the application (navigate or make API requests)
3. Find existing code to follow as a pattern
4. Use fixtures, never manual instantiation
5. Generate data with factories
6. Check against the WON'T rules
7. Run the tests. Don't report done until they pass
Step 7 is particularly important. Without it, the agent might generate code that looks right but fails at runtime. With it, the agent runs the tests and confirms they pass before telling you the task is done.
📁 The Skills Index
CLAUDE.md also acts as a map to the skills files. Rather than cramming every detail into one file (which would be overwhelming), it tells the agent: "When you're working on page objects, read the page-objects skill. When you're working on API schemas, read the api-testing skill."
| Skill | Read When Working On |
| -------------- | ---------------------------------- |
| selectors | pages/\*\* |
| page-objects | pages/\*\* |
| fixtures | fixtures/\*\* |
| test-standards | tests/\*\* |
| api-testing | fixtures/api/**, tests/**/api/\*\* |
| data-strategy | test-data/\*\* |
This keeps CLAUDE.md focused and fast to parse, while the detailed expertise lives in dedicated skill files. That brings us to the next article.
✍️ Writing Your Own CLAUDE.md
You don't have to start from scratch. The scaffold's CLAUDE.md is a template. To adapt it to your project:
- Change the file paths to match your actual folder names
- Add your team's specific WON'Ts: the anti-patterns you've personally seen cause problems
- Update the workflow if your project has a setup step or a specific CI check to run
- Keep it honest: don't add rules you don't actually enforce, or the agent will contradict your existing codebase
The goal isn't a perfect document on day one. It's a living file that gets better every time you catch the agent doing something you don't want.
🙏🏻 Thank you for reading! CLAUDE.md is the file that turns a general AI into a specialized team member. But rules alone aren't enough. The agent also needs deep expertise for specific tasks. That's what skill files provide. See you in the next one.
You can find the Public README.md file for the scaffold on GitHub: Playwright Scaffold
You can get access to the private GitHub repository here: Get Access
Top comments (0)