paulund
#ai #claude #instructions #agents

CLAUDE.md File

Project instructions in Claude work similarly to GitHub Copilot's instruction files. You create a CLAUDE.md file (or language-specific variants such as php.instructions.md or typescript.instructions.md) and check it into your repository's root.

Claude automatically reads and applies these instructions when working within your project. A well-structured CLAUDE.md file should include:

  • Clear project overview
  • Complete tech stack list
  • Project structure explanation
  • Coding conventions and standards
  • Language and localisation preferences
  • Development workflow commands
  • Integration points documented
  • Claude-specific instructions
  • Known issues and technical debt
  • Environment setup requirements
  • Concise and actionable content
  • Regular update schedule planned
  • Referenced detailed documentation where needed
  • Examples for complex conventions
  • No sensitive information included

These instructions override default Claude behaviour and ensure that Claude works consistently with your project's conventions and requirements. Language-specific instruction files allow you to provide tailored guidance for different parts of your codebase.

Treat CLAUDE.md as an iterative document. Update it regularly as your project evolves to keep Claude aligned with your current practices.

Claude Terms

  • Instructions (CLAUDE.md) define your project's standards, conventions, and common commands
  • Skills (.claude/skills/) are reusable reference material: guidelines, frameworks, and expertise
  • Agents (.claude/agents/) are focused workflows that reference skills to accomplish specific tasks
  • Commands (.claude/commands/) are shortcuts you invoke directly
  • Models provide the reasoning capability behind agents and skills

Together, they create a cohesive development workflow tailored to your specific project needs.

How Agents and Skills Work Together

Skills answer the question: "What are our standards and best practices?"

  • Write a compelling hook for social media posts
  • Design a REST API following our conventions
  • Structure a technical article for our audience
  • Evaluate trade-offs in architecture decisions

Agents answer the question: "How do I automate a workflow using those standards?"

  • Draft a LinkedIn post using the professional brand guidelines skill
  • Create a blog article using the technical writing principles skill
  • Review code using the code review skill
  • Design an API using the API design patterns skill

A well-structured project has:

  • Clear, focused agents that handle one responsibility each
  • Reusable skills that agents reference (avoiding duplication)
  • Instructions (CLAUDE.md) that capture project-wide conventions and commands
  • Commands that invoke common workflows

Why You Need CLAUDE.md

Without CLAUDE.md, Claude Code starts each session with no memory of your previous instructions. You'll find yourself repeatedly explaining:

  • Your coding style preferences
  • How to run tests or build the project
  • Which libraries or patterns to use
  • Project-specific terminology
  • Known issues or gotchas

A well-crafted CLAUDE.md solves these problems by providing:

  • Consistency: Ensures all Claude Code agents follow the same coding standards and practices
  • Efficiency: Eliminates the need to repeat project context in every session
  • Quality: Reduces errors by providing clear guidance on project-specific conventions
  • Team Alignment: Serves as living documentation for development practices
  • Context Preservation: Claude Code reads this file at the start of every session
  • Onboarding: Helps new team members understand project conventions