How to Write a CLAUDE.md That Works

As AI coding agents become a standard part of the software engineering workflow, providing them with clear project context is essential for accuracy. Knowing how to write a CLAUDE.md that works is the difference between an agent that constantly breaks your build and one that autonomously solves complex bugs. This file serves as a memory bank and rulebook for tools like Claude Code, allowing the agent to understand your specific architectural patterns, build commands, and testing requirements without constant manual prompting.

The Purpose of CLAUDE.md

A CLAUDE.md file is a specialized documentation format designed for machine consumption. While traditional README files are written for humans to understand high level project goals, CLAUDE.md focuses on operational details. It acts as a bridge between your local source code and the LLM context window.

By maintaining this file in your root directory, you give the agent a persistent reference point. This reduces the need for the agent to explore the entire file tree to figure out how to run a simple test or find where the types are defined. It is particularly useful in large or non standard codebases where automated discovery might fail.

Essential Components of a Working CLAUDE.md

To ensure your agent performs reliably, your CLAUDE.md should follow a structured format. An effective file typically includes several key sections that cover the lifecycle of a development task.

Build and Run Commands

The agent must know exactly how to compile or start your project. Specify the precise commands for different environments. If you use a specific package manager like pnpm or bun, make that explicit.

Testing Patterns

One of the most common failures for AI agents is running tests incorrectly. List the commands for running the full suite, individual files, and specific test patterns. Include information about any required environment variables or sidecars like databases.

Coding Style and Standards

Every team has different preferences for linting, naming conventions, and architectural patterns. Use this section to enforce rules such as using functional components over classes or preferring specific libraries for state management.

Improving Agent Performance with Better Context

Writing a great CLAUDE.md is only half the battle. The environment where the agent runs also dictates its success. Tools like Claude Code thrive when they have access to a rich set of capabilities.

When using an infinite canvas like Deska, you can run multiple agent instances side by side. This allows you to test different instructions in your CLAUDE.md simultaneously. You might have one panel running a stable version of your project while another panel uses an agent to refactor a component based on new rules you just added to your documentation.

Integrating CLAUDE.md into Your Workflow

The best way to maintain a CLAUDE.md is to update it as your project evolves. If you find yourself repeatedly telling an agent to "use this specific utility function instead of the built in one", that instruction belongs in the markdown file.

In a local-first environment, these files remain on your machine. This is critical for security and speed. Since your files and sessions stay local, the agent can quickly parse the CLAUDE.md without significant latency. If you use coding agents within a dedicated workspace, the agent can read these rules at the start of every session to ensure alignment with your current goals.

Using Deska to Manage AI Agents

Deska provides a specialized workspace for developers who want to leverage AI agents effectively. Instead of a single chat window, you get a layout of panels including terminals, code editors, and browsers.

You can run coding agents like Claude Code directly in a terminal panel. Because Deska is an infinite canvas, you can zoom out to see your CLAUDE.md in one panel, the terminal where the agent is working in another, and a browser widget showing the live application in a third.

The Ask Deska assistant can also help manage these sessions. You can use voice commands to ask the assistant to open your CLAUDE.md for editing or to clear the terminal history if the agent gets stuck in a loop. This multi panel approach makes it easier to verify that the agent is actually following the instructions you wrote.

Best Practices for Rule Definition

When writing rules for your agent, be specific. Instead of saying "write clean code", say "ensure all functions have TypeScript return types and do not exceed 50 lines".

• Use absolute paths for critical configuration files.
• List common pitfalls or known issues the agent should avoid.
• Define the project structure clearly so the agent knows where to find components, hooks, or assets.
• Include a "Checklist for PRs" that the agent must verify before finishing a task.

Remote and Mobile Monitoring

If you are running a long refactoring task using an agent and need to step away from your desk, the mobile app allows you to monitor the progress. Through a secure relay, your phone pairs directly with your desktop. You can check the terminal output to see if the agent is following the CLAUDE.md rules or if it has hit an error that requires human intervention. This setup ensures your data and storage remain private while giving you the flexibility to move around.

FAQ

How to write a CLAUDE.md for TypeScript projects?

For TypeScript projects, focus on specifying the build tool and the location of the tsconfig file. Explicitly state whether the agent should use interfaces or types and how to handle strict null checks. This prevents the agent from generating code that fails the compilation step.

Can I use CLAUDE.md with other agents?

While the naming convention is specific to Claude, many modern agents can be instructed to read this file as a primary source of truth. It is a good practice to include a general section at the top that summarizes the project for any AI tool that might interact with the directory.

Where should I put the CLAUDE.md file?

The file should always be placed in the root directory of your project. This ensures that when an agent is initialized in that folder, the file is immediately visible and accessible for the agent to parse before it begins any operations.

Get Started with Better AI Workflows

Optimizing your project for AI agents is a continuous process of refining instructions and choosing the right tools. By mastering how to write a CLAUDE.md that works, you significantly increase the utility of your AI assistants.

If you want a powerful, local environment to run these agents side by side, try Deska. It is a free desktop app for Mac, Windows, and Linux that lets you build your own workspace with terminals, notes, and AI tools. You can download the app today and start organizing your development environment on an infinite canvas.