Understanding Claude.md: A Guide to Spec-Driven Development

6 min read

This blog was originally published on Medium.

With AI, the way we write code and scaffold projects is evolving. Instead of relying solely on manual implementation, many teams are adopting spec-driven development (SDD) alongside AI coding assistants.

In this blog, we'll explore how to set up a project using Claude. Claude offers several configuration options, including claude.md, skills.md, agents, and rules, plugins. This is the part 1, where we will go through claude.md and followed by the rest.

1. What is Claude.md

claude.md is a markdown (md) file and acts as a central context file for your project. It can include information about your project's architecture, coding style, conventions, and important notes or tasks. Think of it as a shared reference that helps Claude understand how to work effectively within your codebase.

You can often generate an initial version using an init command, and then refine it over time.

2. Why we need claude.md?

Claude.md makes AI tools aligned with the team or personal standards & preferences, to guide your AI tool — what to do eg: do not say — "as an expert..", or "ask before any destructive action" and so on.

3. Types of Claude.md

In many workflows, claude.md can exist at multiple levels:

1. Enterprise Level

Your organisation enforced guidelines. This is an effective way to enforce the coding rules, guidance architecture, etc org level. e.g: use camelCase for variables, do not commit credentials.

# Enterprise Claude Instructions

- Never suggest committing secrets, tokens, passwords, or API keys.
- Follow the company secure coding standard.
- Prefer TypeScript over plain JavaScript for new frontend code.
- Do not generate code that logs PII, access tokens, or customer data.
- Use camelCase for variables and PascalCase for classes/types.
- For production code, include tests and error handling.

2. Project Level

Your project specific overall architecture, standards, and guidelines. This is project specific guidelines. Eg: your project's tech stack, architecture, commands, etc.

# Project Claude Instructions

## Tech stack
- Frontend: Next.js 15, React, TypeScript, Tailwind.
- Backend: Node.js with Fastify.
- Database: PostgreSQL using Prisma.

## Architecture
- Keep API routes thin.
- Put business logic in `src/services`.
- Put database access in `src/repositories`.
- Do not call Prisma directly from React components.

## Commands
- Run tests with `pnpm test`.
- Run linting with `pnpm lint`.
- Run type checks with `pnpm typecheck`.

## Coding standards
- Use Zod for request validation.
- Use server actions only for simple mutations.
- New features must include unit tests.

3. Personal Level

Your general preferences and coding style. This is your personal rules, your style, your preferences.

# My Personal Claude Instructions

- Explain trade-offs before making large architectural changes.
- Prefer simple, boring solutions over clever abstractions.
- Use concise comments only when the code is not obvious.
- When editing code, show a brief summary of changed files.
- Prefer pnpm over npm.
- Use British English in documentation.
- Ask before introducing a new dependency.

4. Local Project-Personal Level

This is worth adding. It is personal to you inside one project, usually stored in ./CLAUDE.local.md or local settings and not committed to Git.

# Local Claude Instructions

- Use my local test user: test.user@example.com.
- My local API runs on http://localhost:4000.
- My local frontend runs on http://localhost:3000.
- Use the staging database only when I explicitly ask.

5. Folder/Module Level

Specific instructions for a particular part of the codebase. Folder-level claude.md files are especially useful for large projects, where different modules may follow different patterns, frameworks, or constraints.

4. Good and bad examples of rules

As a beginner you will be tempted to put everything in claude.md but this will bloat your claude.md and should be avoided.

// BAD

write best code
follow best practices

// Good

use TypeScript for strict mode
Use appropriate HTTP status codes.
Do not read process.env
Return consistent error responses.

5. Common mistakes to avoid

  1. Do not make your claude.md too long
  2. Keep your rules focused and not vague rules
  3. Do not duplicate the same rule in many places. It will create conflicts.
  4. Avoid creating conflicts between personal and project rules
  5. Do not treat CLAUDE.md as security enforcement & do not add security credentials.
  6. Forgetting to update it as the project changes

6. What will happen if there are conflicting instructions or rules?

We have 4 levels of claude.md — if a rule is present in all 4 then how will the priority of rules work?

These instructions are loaded together as context; they do not behave like a strict override system where one file fully replaces another.

More specific instructions generally take priority over broader ones. eg, project rules should take priority over personal preferences, and organization rules should not be contradicted by project or user rules.

If the same rule appears at multiple levels with conflicting guidance, Claude may choose based on context, specificity, and the order in which the instructions are loaded. It may not always ask which rule to follow. To avoid unpredictable behaviour, keep rules consistent, avoid duplicate instructions, and place each rule at the correct level.

Use organization-level instructions for company-wide policy, project-level instructions for repository standards, user-level instructions for personal preferences, and local instructions for machine-specific setup.

For hard enforcement, use managed settings, permissions, hooks, CI checks, or pre-commit checks. CLAUDE.md should guide Claude, not replace enforcement.

eg: In this case, Claude should follow the project-level rule because it is more specific to the repository.

# User-level CLAUDE.md
- Prefer npm for JavaScript projects.

# Project-level CLAUDE.md
- This project uses pnpm. Always use pnpm commands.

7. How to keep updating Claude.md?

Keep CLAUDE.md updated as the project evolves. Add rules when Claude repeats the same mistake, when code review catches something Claude should already know, or when new teammates would need the same context.

You can update CLAUDE.md in several ways:

  • Edit the file manually.
  • Use /memory to inspect and edit memory files.
  • Ask Claude directly to update it.
  • Use the # shortcut to quickly add a memory or instruction.

8. Claude.md vs Memory

There may be files people casually call memory.md, but in Claude Code's official docs the main documented file is CLAUDE.md, while the second system is called auto memory.

CLAUDE.md contains what the team already knows and wants Claude to follow; auto memory (memory) contains what Claude learns while working. Both are loaded as context, not as strict enforcement.

In next blog, we will learn agents. You can connect me at X or LinkedIn.

← Back to home