CLAUDE.md and the WAT Framework: Organizing Agent Work
The WAT framework separates Workflow instructions, Agent configuration, and Tool permissions into distinct concerns. CLAUDE.md carries the workflow layer. Here is how the three fit together and where fenbs handles what the file cannot.
Updated 6 min read
The WAT framework separates the three concerns that appear in every AI agent setup: Workflow (what the agent should do and how), Agent (how the agent is configured and constrained), and Tool (what tools the agent may use and with what permissions). CLAUDE.md carries the workflow layer. Tools like fenbs retain the task state, decisions, and lessons that would otherwise have to be re-explained at the start of every session.
Keeping these three concerns separate makes it easier to debug a session that behaves unexpectedly. If the agent does the wrong task, check the workflow layer. If it has access it should not have, check the tool layer. If its behavior differs from what was configured, check the agent layer.
What WAT separates
In practice, developers mix these concerns into one file and then wonder why editing a convention changes tool access, or why a permission change affects what the agent thinks it should do. WAT treats each concern as a separate layer with a separate home.
| Layer | What it covers | Where it lives in Claude Code |
|---|---|---|
| Workflow (W) | What the agent should do: project goals, task conventions, rules of thumb, what to ask before acting. | CLAUDE.md or AGENTS.md — the instruction file Claude Code reads at session start. |
| Agent (A) | How the agent is configured: model, persona, context limits, what to say when it cannot do something. | System prompt or project-level CLAUDE.md sections that configure behavior rather than describe tasks. |
| Tool (T) | What the agent may use: which commands are allowed, which are denied, which need approval. | .claude/settings.json — the permissions and hooks file. |
Claude Code does not enforce this separation—you can put everything in CLAUDE.md if you want. But the separation pays off as the project grows. A workflow instruction ("always run tests after a file change") belongs in CLAUDE.md. A tool permission ("npm run test is allowed without approval") belongs in settings.json. Mixing them makes both harder to maintain.
The workflow layer: CLAUDE.md
CLAUDE.md carries the workflow instructions: what the project is, what conventions apply, what the agent should do in common situations, and what it should ask about rather than decide. It is injected into the context window at session start, so it must be concise—every token in CLAUDE.md is a token that is not available for the task at hand.
Good workflow instructions are specific and actionable. "Use single quotes for strings" is actionable. "Write clean, readable code" is not. "Ask before deleting any file not in the current task's scope" sets a clear boundary. "Be careful" does not.
The workflow layer also points to where the state lives—not storing it directly. "Read the project context in fenbs at the start of each session" is a workflow instruction. The actual state (which task is in progress, which decision was made yesterday, what went wrong last time) lives outside CLAUDE.md in a tool that persists between sessions.
See CLAUDE.md examples for concrete workflow instructions that cover common development patterns.
The agent layer
The agent layer configures how the model behaves: which model to use, what tone to take, how to handle uncertainty, and what to say when a task cannot be completed. In Claude Code, some of this is in the project settings and some is in a CLAUDE.md section that describes the expected behavior rather than task instructions.
A useful agent-layer instruction tells Claude what to do at the boundaries: "If you are unsure whether a change is in scope, stop and describe what you would do rather than proceeding." That is not a task instruction—it is a behavioral constraint that applies across all tasks.
Keep agent-layer instructions short and separate from task-level workflow instructions. One or two sentences about behavior, one sentence about what to do when stuck, and a pointer to where the current task state lives.
The tool layer: settings.json
The tool layer is mechanical: which commands Claude Code may run without asking, which it may not run at all, and which hooks fire at which events. This belongs in .claude/settings.json, not in CLAUDE.md. Tool permissions are enforced by Claude Code's runtime; workflow instructions in CLAUDE.md are advisory—Claude Code reads them and follows them, but a clear settings.json is the harder boundary.
If you find yourself writing "Do not run rm -rf" in CLAUDE.md, also put "deny": ["Bash(rm -rf *)"] in settings.json. The CLAUDE.md instruction tells Claude why; the settings.json entry enforces the constraint.
See claude project settings json for a full walkthrough of the settings.json structure.
Keep task state outside the instruction file
CLAUDE.md tells Claude what to do. fenbs holds the current state: which task is in progress, where we left off, what was decided yesterday, what the next step is. Connect Claude Code to fenbs over MCP and add an instruction to CLAUDE.md to read the project context at the start of each session. The instruction file stays small; the state stays current.
Create a free accountFree for one person · No credit card · Works with Claude, ChatGPT, Cursor and more
How project instructions fit the WAT structure
Claude Code reads AGENTS.md natively—it recognizes the file and loads it at session start. CLAUDE.md is specific to Claude Code. Both serve as the workflow layer in WAT. If you use other agents in the same project (GitHub Copilot, Gemini CLI, Cursor), AGENTS.md reaches them too.
A practical WAT setup for a shared project looks like this: one AGENTS.md at the repo root with the workflow instructions for all agents; a .claude/settings.json for Claude Code-specific tool permissions; and a fenbs project that holds the tasks, decisions, and current state that any connected agent reads.
The CLAUDE.md not working article covers cases where CLAUDE.md loads but its instructions are not being followed, which is often a sign that the workflow instructions need to be more specific or that a tool-layer setting is overriding them.
How to do this with fenbs
Connect Claude Code to fenbs and structure your project files using the WAT separation.
- Create a free account and add a project in fenbs. Add the first tasks, any Decisions and rules that already exist, and a short description of the project goal.
- Connect Claude Code from Integrations and follow the MCP setup guide.
- Write a CLAUDE.md that covers only the workflow layer: project conventions, what to ask before acting, and an instruction to read the fenbs project context at the start of each session.
- Move tool permissions out of CLAUDE.md and into
.claude/settings.json. Add allow and deny rules for the commands that are safe or off-limits for this project. - Ask Claude Code to save progress in fenbs at the end of each session. The task state, decisions, and lessons stay in fenbs; CLAUDE.md stays as a concise workflow guide.