Claude Code Workflow

Overview

Claude Code is a CLI-based AI coding assistant that lives in your terminal. The difference between a mediocre and a highly productive Claude Code setup comes down to three things: clear project instructions, reusable commands, and effective context management.

This guide covers the configuration patterns I use daily across multiple projects.

CLAUDE.md — Project Instructions

The CLAUDE.md file at your project root tells Claude Code how to work in your codebase. Think of it as onboarding documentation for an AI pair programmer.

Structure

## Project
- Project name and what it does
- Core constraints and boundaries
- What NOT to do (equally important)

## Technology Stack
- Framework versions and key packages
- Deprecated packages to avoid
- Build and dev commands

## Conventions
- Code style rules (immutability, file size limits)
- Performance rules (GPU-accelerated animations only)
- File organization patterns
- Naming conventions

Tips for Effective CLAUDE.md

• Keep it under 500 lines — too long and the AI loses focus on what matters
• Be specific about constraints — “never use transition-all” is better than “be careful with transitions”
• Include anti-patterns — show what NOT to do alongside what to do
• Link to external docs instead of inlining large references
• Update after each phase — CLAUDE.md should evolve with the project

Example Constraint Section

## Constraints
- **Performance**: Zero JS on static pages, island hydration only where needed
- **Architecture**: Tool hub must be separable to subdomain
- **Content**: MDX for all content — no external CMS dependency
- **Animations**: GPU-accelerated only (transform, opacity). No transition-all.

Custom Slash Commands

Create reusable commands in .claude/commands/ to standardize common workflows.

Code Review Command

# .claude/commands/review.md
Review the code changes in the current branch.
Focus on:
1. Security vulnerabilities (injection, XSS, secrets)
2. Performance issues (N+1 queries, unnecessary re-renders)
3. Error handling gaps (unhandled promises, missing try/catch)
4. Type safety (any types, missing null checks)
5. Naming clarity (functions, variables, files)

Rate each issue: CRITICAL / HIGH / MEDIUM / LOW

Debug Command

# .claude/commands/debug.md
Investigate the bug described below.
1. Find the root cause (not symptoms)
2. Explain WHY it happens
3. Propose a fix with minimal code changes
4. Check for similar issues elsewhere in the codebase

Test Command

# .claude/commands/test.md
Write tests for the specified function or component.
Follow TDD: write failing tests first, then verify they fail for the right reason.
Cover: happy path, edge cases, error cases.
Target: 80%+ coverage.

Use them with /review, /debug, /test in your Claude Code session.

Memory Management

MEMORY.md

Cross-session persistence for learnings and corrections:

# MEMORY.md
## Patterns
- Use `color-mix()` for opacity instead of rgba()
- Always lazy-load nvm for faster shell startup

## Corrections
- Don't use `transition-all` — use specific properties
- Turkish characters: use ş, ç, ğ, ü, ö, ı, İ correctly

When to Use What

Information	Where to Put It
Project architecture	CLAUDE.md
Tech stack decisions	CLAUDE.md
Personal coding preferences	~/.claude/rules/ (global)
Learned corrections	MEMORY.md
Phase-specific context	Phase planning files

Global vs Project Rules

• Global rules (~/.claude/rules/) apply to all projects: coding style, git workflow, testing preferences
• Project rules (.claude/rules/ in repo) apply to one project: architecture, domain-specific patterns

MCP Integration

Model Context Protocol (MCP) extends Claude Code with external tool access.

What MCPs Enable

• GitHub MCP — Create PRs, read issues, check CI status directly from Claude Code
• Filesystem MCP — Navigate and search codebases with enhanced context
• Database MCP — Query databases for debugging without leaving the terminal

Configuration

MCPs are configured in .claude/settings.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

Workflow Patterns

Plan-First

For tasks with 3+ steps or architectural decisions:

1. Describe the goal and constraints
2. Ask Claude to create a plan before coding
3. Review the plan — catch misunderstandings early
4. Execute step by step with verification

This avoids the “build the wrong thing fast” trap.

TDD with AI

The most reliable pattern for correctness:

1. Write the test — describe expected behavior
2. Verify it fails — confirms the test is meaningful
3. Let AI implement — with a clear target to hit
4. Verify it passes — the implementation is correct
5. Refactor — clean up with confidence

Code Review Loop

After every code change:

1. Write — implement the feature
2. Review — run /review command
3. Fix — address CRITICAL and HIGH issues
4. Verify — run tests and build

Context Management

• Compact every 15-20 turns — keeps the context window fresh
• Start fresh for new features — don’t carry stale context
• Delegate research to sub-agents — keeps the main thread focused
• Use planning files — externalizes context to disk, not the AI’s memory