CLAUDE.md Specs for Advanced Vibe Coding: Project Memory, Test Hooks, and Multi-Agent Coordination

1. What CLAUDE.md Actually Does

A CLAUDE.md file is a markdown document that lives at the root of your project (or in your home directory for global preferences). When Claude Code starts a session, it reads this file first and treats its contents as persistent instructions. Think of it as a combination of a project README, coding standards document, and institutional memory, all formatted so your AI coding assistant actually follows it.

The difference between a CLAUDE.md file and a regular README is behavioral. A README describes your project to humans. A CLAUDE.md file describes your project to an AI agent in a way that changes how it writes code, runs tests, and makes decisions. You can specify naming conventions, forbidden patterns (like certain CSS colors or deprecated APIs), required testing approaches, and architectural constraints. The AI agent reads these on every session start and follows them without needing to be reminded.

This matters because the biggest complaint about AI coding tools is inconsistency. The AI writes great code in one session, then ignores your conventions in the next. CLAUDE.md solves this by making your preferences persistent and explicit. Instead of hoping the AI remembers that your project uses teal instead of indigo, or that you never use em dashes in copy, you write it once and it applies forever.

2. Project Memory Across Sessions

One of the most frustrating aspects of working with AI coding tools is the cold start problem. Every new session, the AI has no memory of what you discussed yesterday, what decisions were made, or what patterns the codebase follows. You end up re-explaining your architecture, your preferences, and your constraints over and over.

CLAUDE.md files solve this at multiple levels. A global CLAUDE.md in your home directory captures your universal preferences: writing style, default accounts, authentication patterns, debugging approaches. A project-level CLAUDE.md captures everything specific to that codebase: the tech stack, deployment process, branch management rules, and testing requirements.

The practical effect is significant. Advanced practitioners structure their CLAUDE.md files with sections for different concerns. One section covers build and deployment commands. Another covers architectural decisions and their rationale. Another lists known gotchas and workarounds. When you update the CLAUDE.md after discovering a new issue or making an architectural decision, every future AI session inherits that knowledge automatically.

Some teams go further and use CLAUDE.md files to encode their entire development workflow. The file specifies that every task must be verified before it is considered done, describes how to run tests for different types of changes, and even defines lock mechanisms so multiple agents do not interfere with each other. This turns the specification file into a living operations manual that both humans and AI agents follow.

3. Programmatic Test Hooks for Verification

The second pillar of advanced vibe coding is verification. It is not enough for the AI to write code that looks correct. You need a way to confirm it actually works, ideally without manual testing. This is where programmatic test hooks come in.

A test hook is any mechanism that lets you trigger and verify a feature from the command line, without clicking through a GUI. For web applications, this might be a test endpoint or a script that exercises the feature. For desktop applications, this could be a distributed notification listener, a URL scheme handler, or a local debug endpoint.

The CLAUDE.md file is where you document the testing strategy. You can specify that every non-visual feature must include a programmatic trigger before it is considered done. You can describe how different types of changes should be verified: UI changes get screenshot verification, logic changes get programmatic tests, and mixed changes get both. The AI agent reads these requirements and builds the test hooks as part of the implementation, not as an afterthought.

This approach addresses one of the core anxieties about AI-generated code: trust. When every feature ships with a verification mechanism, you can confirm it works in seconds. When the CLAUDE.md specifies that testing is mandatory, the AI agent will not skip it. The result is AI-assisted development where verification is built into the workflow rather than bolted on afterward.

4. Coordinating Multiple AI Agents

Running multiple AI agents on the same codebase is where things get interesting, and where CLAUDE.md becomes essential. Without coordination, two agents can easily step on each other: one modifies a file while the other is reading it, or both try to run the test suite simultaneously and produce confusing failures.

The CLAUDE.md file provides the coordination layer. You can specify rules like: if you see build errors in files you did not edit, wait 30 seconds and retry (the other agent is probably mid-edit). You can define test lock mechanisms so only one agent runs the app at a time. You can assign agents to specific areas of the codebase or specific tasks to minimize conflicts.

Parallel AI agents with proper coordination can dramatically increase throughput. One agent works on the frontend while another handles backend changes. One agent refactors a module while another writes tests for a different feature. The key is that all agents read the same CLAUDE.md and follow the same rules, creating a shared understanding of how to work in the codebase without stepping on each other.

Git worktrees are another useful technique here. Each agent gets its own worktree (a separate working directory pointing to the same repository), eliminating file conflicts entirely. The CLAUDE.md can document the worktree setup and conventions so agents know how to use them. Combined with clear task assignment and lock mechanisms, multi-agent development becomes practical rather than chaotic.

5. Beyond the Editor: Desktop Automation with Specs

The same principles that make CLAUDE.md effective for coding apply to broader desktop automation. When an AI agent needs to interact with applications outside the code editor, whether that is a browser, a design tool, a CRM, or a terminal, it benefits from the same kind of persistent specifications.

Tools like Fazm (an open-source macOS AI agent) use this CLAUDE.md convention extensively. Fazm reads specification files to understand how to interact with desktop applications, which accessibility API patterns to use, and what verification steps to perform after completing actions. The specification file becomes the bridge between what you want automated and how the agent executes it.

For example, you might have a CLAUDE.md section that describes your browser automation preferences: which Chrome profile to use for different services, how to handle authentication flows, and what verification steps to perform after logging in. The agent reads these specifications and follows them consistently, session after session, without needing manual guidance.

The broader lesson here is that advanced vibe coding is not really about coding at all. It is about building a specification layer between you and your AI tools. The more precisely you encode your preferences, constraints, and workflows in CLAUDE.md files, the more reliably AI agents execute on your behalf. Whether that execution happens in a code editor, a desktop application, or across multiple tools simultaneously, the specification file is what makes it repeatable.