Claude Code Process & Best Practices

This document collects processes and best practices for working with Claude Code.

Best Practices

Token Efficiency

File Operations

When to Use Agents

Rule: Use agents for multi-step exploration; use direct tools for specific known targets.

Project Documentation Structure

project/
├── CLAUDE.md              # Instructions for Claude (checked in)
├── .claude/
│   ├── settings.json      # Permissions (local or checked in)
│   └── agents/            # Custom agent definitions
├── README.md              # Human documentation
└── PROCESS.md             # Workflow documentation (optional)

CLAUDE.md tips:

• Put most important instructions at the top
• Include architecture overview for complex projects
• Document conventions (naming, structure, patterns)
• Link to detailed docs rather than duplicating

Permission Management

Structure .claude/settings.json with:

{
  "permissions": {
    "allow": [
      "Bash(safe-command:*)",
      "Bash(scoped-command:/project/path/*)"
    ],
    "deny": [
      "Bash(dangerous-command:*)",
      "Bash(rm:/protected/path/*)"
    ]
  }
}

Tips:

• Allow read-only commands globally: ls, grep, find, git status
• Scope write commands to project: rm:/project/*, mv:/project/*
• Deny system-wide destructive commands
• Deny access to sensitive directories

Task Management with TodoWrite

When to use:

• Multi-step tasks (3+ steps)
• Complex features requiring tracking
• User provides multiple tasks

When NOT to use:

• Single straightforward task
• Quick fixes or trivial changes
• Pure Q&A or research

Best practices:

• Mark task in_progress before starting
• Mark completed immediately when done (don’t batch)
• Only one task in_progress at a time
• Remove irrelevant tasks entirely

Code Quality Principles

1. Read before edit - Never modify code you haven’t read
2. Minimal changes - Only change what’s requested
3. No over-engineering - Avoid premature abstractions
4. No unnecessary additions - Skip docstrings/comments for unchanged code
5. Delete unused code - Don’t comment out or rename to _unused
6. Security awareness - Watch for injection, XSS, SQL injection

Parallel vs Sequential Operations

Parallel (single message, multiple tool calls):

• Independent file reads
• Independent searches
• Checking multiple things at once

Sequential (wait for result):

• Write file → then git add
• Create directory → then create file inside
• Any operation where result determines next step

Project Organization

Repository Structure

finanza1000/
├── api/                      # FastAPI service (data aggregation)
│   └── CLAUDE.md             # API-specific dev guidance
├── icarus/                   # Flask service (content management)
│   └── CLAUDE.md             # Icarus-specific dev guidance
├── .claude/
│   ├── agents/               # 5 consolidated custom agents
│   │   ├── python-debugger.md
│   │   ├── backend-developer.md
│   │   ├── frontend-developer.md
│   │   ├── database-expert.md
│   │   └── financial-analyst.md
│   └── settings.json         # Claude Code permissions
├── _features/                # Detailed implementation plans
│   ├── api_*.md              # API-only features
│   ├── icarus_*.md           # Icarus-only features
│   └── both_*.md             # Cross-service features
├── CLAUDE.md                 # Root-level project guidance
├── TODO.md                   # Active tasks (41 items)
├── DONE.md                   # Completed work log (with timestamps)
└── README.md                 # Public project documentation

Task Tracking Workflow

Workflow:

1. Add item to TODO.md with link to feature file
2. Create detailed plan in _features/[layer]_[name].md
3. When complete, move from TODO.md → append to DONE.md

Feature File Naming

Documentation Hierarchy

1. README.md - Public-facing, quick start for users
2. CLAUDE.md (root) - Monorepo overview, architecture, conventions
3. api/CLAUDE.md - API endpoints, external data sources
4. icarus/CLAUDE.md - Database schema, Flask routes

Git Commit & Push Process

When asked to commit and push, Claude follows this workflow:

1. Check Current State (parallel)

git status                    # See untracked/modified files
git diff --stat               # Summary of changes
git log --oneline -5          # Recent commit style

2. Stage and Commit

git add -A && git commit -m "$(cat <<'EOF'
Short summary of changes

- Detail 1
- Detail 2

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
EOF
)"

Commit message conventions:

• First line: imperative mood, ~50 chars (e.g., “Add feature”, “Fix bug”, “Update docs”)
• Blank line, then bullet points for details
• Always include Co-Authored-By trailer

3. Push to Remote

git push

Permissions Required

In .claude/settings.json, these permissions enable the workflow:

{
  "permissions": {
    "allow": [
      "Bash(git status:*)",
      "Bash(git log:*)",
      "Bash(git diff:*)",
      "Bash(git add:*)",
      "Bash(git commit:*)",
      "Bash(git push:*)"
    ]
  }
}

Recording Completed Work

Never read DONE.md to add entries - use bash append to save tokens:

echo "---

## $(date '+%Y-%m-%d %H:%M') | Brief Title
**What:**
- First accomplishment
- Second accomplishment
**Benefit:** Business value delivered
**Commit:** \`$(git rev-parse --short HEAD)\`" >> DONE.md

Entry format:

• Title: Date/time + brief description
• What: Bullet points (business-readable)
• Benefit: Why this matters
• Commit: Git short hash for reference

To read recent entries:

tail -50 DONE.md