Workflow

Claude.md

Use Claude.md as a leverage point for consistent behavior.

Overview

Claude Code can read project instructions from a Claude.md file in your repository. This becomes a leverage point for consistent behavior across all interactions. Instead of repeating the same instructions in every prompt, you codify your team's conventions, architecture decisions, and preferences once. Claude automatically references this file, ensuring every response aligns with your project standards.

When to use

Use this workflow when onboarding new team members, enforcing coding standards, documenting architectural decisions, preventing repeat mistakes, or establishing project-specific conventions.

Step-by-step process

Capture project-specific rules

Document conventions that Claude should follow: coding style, library preferences, file organization patterns, and architectural constraints.

"Create a Claude.md file with: 1) We use functional React components with hooks, never classes, 2) All API calls go through src/api/client.ts, never fetch directly, 3) Error handling must use our ErrorBoundary pattern, 4) Component files must export a single default component."

Explain why each rule exists

Rules with context are followed better than arbitrary mandates. Explain the reasoning behind each convention so Claude understands the intent.

"Add rationale to each rule: We avoid classes because hooks provide better code reuse. Centralized API calls ensure consistent authentication and error handling. ErrorBoundary pattern prevents white screens for users."

Update when repeat mistakes occur

When Claude makes the same mistake twice, add a rule to Claude.md. Treat it as a living document that evolves with your project.

"Claude keeps using lodash despite us wanting to minimize dependencies. Add to Claude.md: Don't import lodash. Use native array methods or our utils/array.ts helpers instead. This keeps bundle size small."

Reference it in complex prompts

For critical tasks, explicitly remind Claude to check Claude.md. This reinforces the importance of following project conventions.

"Implement user authentication following the patterns in Claude.md. Pay special attention to the API client usage and error handling sections."

Example prompts

Creating initial Claude.md

"Analyze our codebase and create a Claude.md file documenting: tech stack, directory structure conventions, naming patterns, prohibited dependencies, common gotchas. Format it as clear rules with brief explanations."

Enforcing consistent patterns

"We keep getting inconsistent component structure. Add a section to Claude.md showing our standard component template: imports order, prop types definition, hooks usage, helper functions, then JSX return. Include an example."

Preventing security issues

"Add security guidelines to Claude.md: Never log user passwords or tokens, always sanitize user input before database queries, use parameterized SQL only, require authentication on admin routes. Explain why each matters."

Team-specific conventions

"Document our PR conventions in Claude.md: Commits must follow conventional commits format, PRs need tests before approval, no direct pushes to main, use feature flags for incomplete features."

Expected outputs

Consistent behavior

Claude follows your team's conventions automatically without needing reminders in every prompt

Fewer corrections

Reduced back-and-forth fixing style violations or pattern mismatches because rules are clear upfront

Faster onboarding

New team members and new Claude sessions start with full context about project conventions

Documented decisions

Claude.md serves as living documentation of architectural decisions and team agreements

Best practices

Start simple with 5-10 critical rules—don't overwhelm with hundreds of guidelines initially

Focus on rules that prevent mistakes or enforce important patterns, not personal style preferences

Keep rules concise and scannable—Claude should be able to quickly find relevant guidance

Update Claude.md proactively when you catch repeated mistakes or misunderstandings

Review and refine periodically as your project evolves—delete outdated rules to prevent confusion

Common pitfalls

Writing too many trivial rules

Solution: Focus on rules that matter: security, architecture, breaking change prevention. Skip formatting minutiae—use automated tools like Prettier for that.

Not explaining the 'why' behind rules

Solution: Add brief rationale to each rule. 'Don't use X' is less effective than 'Don't use X because it causes Y problem in our deployment.'

Letting Claude.md get stale

Solution: Set a quarterly review. Remove rules that are no longer relevant and add new patterns as your codebase evolves.

Pro tips

Include anti-patterns with examples

""In Claude.md, show both correct and incorrect patterns: ❌ BAD: fetch('/api/users') ✅ GOOD: apiClient.get('/api/users') — This makes expectations crystal clear.""

Link to existing code as examples

""Reference actual files: For authentication flow, see src/auth/login.ts as the canonical example. Follow that pattern for all auth-related code.""

Version your Claude.md

""Add a version and last updated date to Claude.md. When rules change significantly, note it in the git commit message so team members know to re-read it.""

Related workflows

Prompt Specificity Think First Context Management