How To Integrate Best Practices with Claude Code

A step-by-step guide for integrating these best practices into a new or existing project so that Claude Code follows your standards automatically.

How It Works

Claude Code reads a CLAUDE.md file at the root of your project (or in .claude/CLAUDE.md) at the start of every session. This file tells Claude your project's conventions, constraints, and coding standards. By embedding these best practices into your CLAUDE.md and supporting configuration files, Claude automatically follows your guidelines whenever it writes, reviews, or modifies code.

1
Download the best practice files for your stack
2
Reference them in your CLAUDE.md with @import
3
Configure hooks and settings for enforcement
4
Develop with Claude following your standards

New Project Setup

Starting fresh gives you the cleanest integration. Follow these steps in order.

1

Create your project directory structure

Set up the Claude Code configuration directories alongside your source code:

your-project/
  .claude/
    CLAUDE.md              # Main instructions for Claude
    settings.json          # Shared hooks and permissions
    settings.local.json    # Personal overrides (gitignored)
    rules/                 # Path-scoped rule files
    agents/                # Custom subagents
    skills/                # Slash-command workflows
  docs/
    best-practices/        # Downloaded best practice files
      core/
      flutter/             # (or your stack)
      firebase/            # (or your backend)
      typescript/          # (or your language)
  .github/
    workflows/
      claude.yml           # GitHub Actions for @claude
    pull_request_template.md
    ISSUE_TEMPLATE/
      bug_report.md
      feature_request.md
  src/                     # Your source code
  .env.example
  .gitignore
2

Download the best practices for your stack

Go to the relevant section pages and download the files for your technology stack. For example, a Flutter app with Supabase backend would need:

  • Core -- all 12 files (these apply to every project)
  • Flutter -- all 10 files (frontend-specific)
  • Supabase -- all 10 files (backend-specific)
  • Templates -- CLAUDE_MD_TEMPLATE, SETTINGS_PROJECT_TEMPLATE, and any others you need

Place the downloaded files in docs/best-practices/ organized by category.

3

Create your CLAUDE.md

Start with the CLAUDE_MD_TEMPLATE and customize it for your project. Then import the best practices so Claude reads them as context:

# CLAUDE.md

## Project Overview
- Project: My App
- Language: Dart / TypeScript
- Framework: Flutter (frontend), Supabase (backend)

## Build and Run
flutter run
flutter test
supabase start

## Architecture
Feature-based modules with Riverpod for state management.
Supabase for auth, database, and storage.

## Best Practices
@docs/best-practices/core/SECURITY_CORE.md
@docs/best-practices/core/CLEAN_CODE.md
@docs/best-practices/core/AI_CODING.md
@docs/best-practices/core/ENVIRONMENT_STANDARDS.md
@docs/best-practices/flutter/SECURITY_FLUTTER.md
@docs/best-practices/flutter/CLEAN_CODE_FLUTTER.md
@docs/best-practices/flutter/ARCHITECTURAL_DESIGN_FLUTTER.md
@docs/best-practices/supabase/SECURITY_SUPABASE.md
@docs/best-practices/supabase/CLEAN_CODE_SUPABASE.md

## Git Workflow
- Branch naming: feature/description, fix/description
- Target branch for PRs: main
- Run tests before committing
Tip: You do not need to import every file. Start with the ones most relevant to your current work -- security, clean code, and architecture are the highest-impact. Add more as needed. Keep CLAUDE.md under 200 lines for best results.
4

Configure settings and hooks

Copy the JSON from the SETTINGS_PROJECT_TEMPLATE to .claude/settings.json. This provides deterministic enforcement that CLAUDE.md alone cannot guarantee:

  • Permissions -- allow safe commands (test, lint, build) and deny destructive ones (rm -rf, drop table, force push)
  • Auto-format hook -- runs your formatter after every edit Claude makes
  • Destructive command blocker -- prevents dangerous shell commands before they execute
  • Sensitive file protection -- blocks access to .env, credentials, and key files

See the HOOKS_REFERENCE for ready-made hook configurations for Prettier, Biome, dart format, Black, and more.

5

Add path-scoped rules (optional)

For detailed, context-specific guidance, create rule files in .claude/rules/. These load on demand only when Claude accesses matching file paths:

# .claude/rules/security.md
---
description: Security rules for auth and API code
paths:
  - "src/auth/**"
  - "src/api/**"
  - "supabase/migrations/**"
---

- All endpoints must have explicit authentication checks
- Validate all external input with a schema validator
- Never log tokens, passwords, or PII
- RLS policies must default to deny

See the RULES_TEMPLATE for more examples.

6

Set up GitHub integration (optional)

Enable Claude Code to respond to @claude mentions in issues and PRs:

  1. Install the Claude GitHub App at github.com/apps/claude
  2. Add ANTHROPIC_API_KEY to your repository secrets
  3. Copy the workflow from GITHUB_WORKFLOW_TEMPLATE to .github/workflows/claude.yml
  4. Copy the PR_TEMPLATE and issue templates to .github/

Now team members can mention @claude in issues to implement features and in PR comments to request reviews -- Claude follows the same best practices defined in your CLAUDE.md.

Existing Project Integration

Adding best practices to an existing project follows the same pattern but with a few additional considerations.

1

Start with /init

If you already have code, run /init in Claude Code. It analyzes your codebase and generates a starter CLAUDE.md tailored to your existing patterns, build commands, and structure. This is faster than starting from a blank template.

If you already have a CLAUDE.md, running /init will suggest improvements to it.

2

Download and place best practice files

Download the files for your stack and place them in your project (e.g., docs/best-practices/). Then add @import references in your CLAUDE.md for the most relevant ones.

Tip: For existing projects, start with just 3-4 files: SECURITY, CLEAN_CODE, and AI_CODING from Core, plus the security file for your primary technology. Add more gradually as the team becomes familiar with the workflow.
3

Add settings incrementally

Do not overhaul everything at once. Start with:

  1. Week 1: CLAUDE.md with project overview, build commands, and 2-3 best practice imports
  2. Week 2: .claude/settings.json with auto-formatting hook and basic permissions
  3. Week 3: Path-scoped rules for your most sensitive code paths (auth, payments, database)
  4. Week 4: GitHub workflow, PR templates, and additional best practice imports
4

Handle existing patterns that conflict

Your existing codebase may not follow all the best practices. This is expected. Add a section to CLAUDE.md acknowledging the current state:

## Known Deviations
- Legacy auth module uses custom JWT handling (migration planned)
- Some older files use string concatenation for queries (do not extend this pattern)
- The /admin route does not have RLS -- access is controlled at the API layer

## When modifying existing code
- Follow the best practices for all new code
- When touching legacy files, improve what you touch (Boy Scout Rule)
- Do not refactor unrelated code in the same PR

Which Files to Use for Your Stack

Select the combination that matches your technology stack.

Flutter + Firebase

Mobile or web app with Firebase backend

  • Core (all files)
  • Flutter (all files)
  • Firebase (all files)
  • Templates (all files)

Flutter + Supabase

Mobile or web app with Supabase backend

  • Core (all files)
  • Flutter (all files)
  • Supabase (all files)
  • Templates (all files)

TypeScript Backend

Node.js API, serverless functions, or CLI tool

  • Core (all files)
  • TypeScript (all files)
  • Templates (all files)

TypeScript + Supabase

Next.js, SvelteKit, or similar with Supabase

  • Core (all files)
  • TypeScript (all files)
  • Supabase (all files)
  • Templates (all files)

Full Stack (Flutter + TS + Supabase)

Flutter frontend, TypeScript edge functions, Supabase backend

  • Core (all files)
  • Flutter (all files)
  • TypeScript (all files)
  • Supabase (all files)
  • Templates (all files)

Any Other Stack

Python, Go, Rust, or another language

  • Core (all files -- these are universal)
  • Templates (all files)
  • Technology-specific guides coming soon

Import Strategies

There are multiple ways to feed best practices to Claude Code. Choose based on your project size and team needs.

Strategy A: Direct import in CLAUDE.md

Best for small-to-medium projects. Import the most critical files directly:

# In CLAUDE.md
@docs/best-practices/core/SECURITY_CORE.md
@docs/best-practices/core/CLEAN_CODE.md
@docs/best-practices/flutter/SECURITY_FLUTTER.md

Pros: Simple, everything loads at session start.
Cons: Consumes context window. Keep imports under 5-6 files.

Strategy B: Path-scoped rules

Best for larger projects. Place best practices in .claude/rules/ with path matchers so they load only when relevant:

# .claude/rules/flutter-security.md
---
description: Flutter security best practices
paths:
  - "lib/**/*.dart"
---
@docs/best-practices/flutter/SECURITY_FLUTTER.md

Pros: Saves context by loading only when needed.
Cons: Slightly more setup.

Strategy C: Curated summary

Best for teams that want maximum control. Read the best practice files, extract the rules most relevant to your project, and write a condensed version directly in CLAUDE.md or rules files:

# In CLAUDE.md or .claude/rules/security.md
## Security Rules (from Core + Flutter guidelines)
- Never store tokens in SharedPreferences; use flutter_secure_storage
- Validate all deep link parameters as untrusted input
- Enable RLS on every Supabase table with no default policies
- Never hardcode secrets; use --dart-define or env variables

Pros: Minimal context usage, highly tailored.
Cons: Requires manual curation and maintenance.

Verifying It Works

After setup, verify that Claude Code is following the best practices.

Test 1: Ask Claude to create a new feature

Ask Claude to build a small feature (e.g., "Add a user profile screen"). Verify that the generated code follows the architectural patterns, naming conventions, and security practices from your imported guides.

Test 2: Try a destructive command

If you configured the destructive command hook, ask Claude to do something dangerous (e.g., "Drop the users table"). Verify that the hook blocks it and Claude asks for confirmation.

Test 3: Edit a file and check formatting

Have Claude edit a source file. Verify that the auto-format hook runs and the file matches your project's formatting standards.

Test 4: Check sensitive file protection

Ask Claude to read your .env file. If you configured the sensitive file hook, it should be blocked.

Test 5: Review memory

Run /memory to see what Claude has learned. Over time, Claude will build up memory about your project's patterns, your preferences, and decisions you have made. Review and prune this periodically.

Ongoing Maintenance