CLAUDE.md Best Practices

CLAUDE.md serves as the persistent "memory" and operating manual for Claude Code within your repository. By maintaining this file, you ensure that every session starts with a clear understanding of your project's architecture, commands, and coding standards, reducing the need for repetitive prompting.

Core Structure

A well-optimized CLAUDE.md should be concise but comprehensive. Focus on the following four areas:

1. Project Context: What is this project and what is the tech stack?
2. Guide Rails: What are the non-negotiable coding standards?
3. Command Reference: How do you build, test, and lint?
4. Skill Discovery: How should Claude leverage specialized knowledge?

Command Reference

Claude Code looks for specific Markdown sections to understand how to interact with your build system. Provide clear, copy-pasteable commands for the following:

## Build and Test Commands
- Install dependencies: `npm install`
- Build project: `npm run build`
- Run all tests: `npm test`
- Run specific test: `npm test -- <path_to_file>`
- Linting: `npm run lint`
- Type checking: `npx tsc --noEmit`

Code Style & Standards

Define your project's "personality" and technical requirements. This prevents Claude from introducing patterns that would fail a code review.

• Language Specifics: (e.g., "Always use TypeScript strict mode," "Prefer functional components over class components.")
• Naming Conventions: (e.g., "Use PascalCase for components and camelCase for hooks.")
• Error Handling: (e.g., "Always wrap asynchronous API calls in try/catch blocks with specialized error logging.")
• State Management: (e.g., "Use Zustand for global state; avoid Redux.")

Example configuration:

## Coding Standards
- **TypeScript**: Use interfaces for public APIs and types for internal data structures.
- **UI Components**: Follow the Atomic Design pattern located in `src/components`.
- **Imports**: Use absolute paths starting with `@/`. Group external libraries above internal modules.
- **Documentation**: All new utility functions must include JSDoc comments.

Leveraging Skills and Agents

The boraoztunc/claude-code configuration utilizes a Skill Evaluation Engine. You should use CLAUDE.md to point the agent toward these specialized resources.

• Skill Triggers: List available skills in .claude/skills/ so Claude knows when to "activate" them.
• Automation Hooks: Mention the existence of pre-edit or post-edit hooks (like .claude/hooks/skill-eval.js) so Claude understands that certain checks happen automatically.

## Project Skills
This repository uses a skill-based architecture. Before implementing new features, refer to:
- **Core Components**: `.claude/skills/core-components/SKILL.md` (Design system rules)
- **Testing Patterns**: `.claude/skills/testing-patterns/SKILL.md` (Jest and Playwright guides)
- **GraphQL**: `.claude/skills/graphql-schema/SKILL.md` (Schema evolution rules)

Best Practices for Maintenance

• Keep it Updated: Treat CLAUDE.md like code. If you switch from Jest to Vitest, update the file immediately.
• Be Specific, Not Verbose: Claude prioritizes information based on relevance. Use bullet points and code blocks rather than long paragraphs.
• Use the /config Command: Use the Claude Code CLI to ask Claude to "Update CLAUDE.md based on our recent changes to the testing suite" to automate documentation maintenance.
• Contextual Linking: Use relative file paths (e.g., ./src/types/index.ts) so Claude can quickly jump to the source of truth if the CLAUDE.md summary isn't enough.