Mastering Claude Code · Part 1

Mastering Claude Code: Foundation and Philosophy

•
5 min read
# claude-code # ai-tooling # developer-tools # productivity # cli-tools

Introduction: From Tool to Partner

Claude Code out of the box is impressive. But with the right configuration, it transforms from a capable tool into something far more powerful: a personalized engineering partner that understands your workflow, enforces your standards, and adapts to your project’s unique requirements.

This series documents my complete Claude Code setup after months of refinement. We’ll cover:

  1. Foundation & Philosophy (this post) - Core principles, configuration files, and terminal customization
  2. Custom Commands & Workflow - 9 slash commands that encode best practices
  3. Specialized Agents & Skills - 10 agents and 19+ skills for every situation
  4. MCP, Plugins & Integration - Connecting Claude Code to your entire toolchain
  5. Memory Management - Hierarchical memory system and context persistence
  6. Chrome Browser Automation - Live debugging, testing, and browser workflows

Let’s start with the foundation that makes everything else possible.

CLAUDE.md: Your Engineering Constitution

The CLAUDE.md file is where you establish the ground rules. Claude Code supports two levels of configuration:

Global Configuration (~/.claude/CLAUDE.md)

This file applies to every Claude Code session, regardless of which project you’re in. Here’s my global configuration:

- every time before implementation create a complete plan and
  checklist and ask me to verify it, if I verified then go
  ahead and implement it.
- every time after delivering the result give a summary of
  what you have done.
- do not commit files and word unless I ask you directly.
- always follow SRP (single responsibility) either classes,
  components or functions. it can help keep function (any units)
  smaller and more understandable

These four principles encode my development philosophy:

  1. Plan before implementation - Forces structured thinking and prevents Claude from jumping straight into code
  2. Summarize results - Creates accountability and makes it easy to review what was done
  3. Explicit commit control - Prevents accidental commits; I control when changes are committed
  4. Single Responsibility Principle - Keeps generated code clean and maintainable

Project-Level Configuration (./CLAUDE.md)

Each project can have its own CLAUDE.md that overrides or extends the global settings. Here’s an example from my Astro blog project:

CLAUDE.md
This file provides guidance to Claude Code when working
with code in this repository.


## Commands


\`\`\`bash
# Development
npm run dev          # Start dev server (localhost:3000)
npm run build        # Build for production
npm run preview      # Preview production build


# Content tooling
npm run mermaid      # Generate SVG diagrams from mermaid blocks
\`\`\`


## Architecture


### Content System


**Two-collection model** using Astro Content Collections:


1. **Posts** (`src/content/posts/*.md`) - Blog articles
   - Required: `title`, `description`, `pubDate`
   - Filename convention: `YYYY-MM-DD-slug.md` -> URL: `/YYYY/MM/slug/`


2. **Series** (`src/content/series/*.json`) - Multi-part metadata
   - Links posts together via `series.name` in frontmatter

The project-level file provides Claude with context about the specific codebase, its conventions, and available commands. This dramatically improves the relevance of Claude’s suggestions.

How Configuration Files Merge

When both files exist, Claude sees both. The global file establishes your personal standards, while the project file provides context-specific guidance. Think of it as:

  • Global: “How I work”
  • Project: “How this codebase works”
Mermaid diagram

Terminal Customization: Information at a Glance

Claude Code supports a custom status line that displays in your terminal. I’ve configured mine to show everything I need at a glance.

The Status Line Script

Here’s my ~/.claude/statusline.sh:

#!/bin/bash
input=$(cat)


# Define colors as actual escape sequences
GREEN=$'\033[0;32m'
YELLOW=$'\033[0;33m'
RED=$'\033[0;31m'
BLUE=$'\033[0;34m'
CYAN=$'\033[1;36m'
MAGENTA=$'\033[0;35m'
WHITE=$'\033[0;37m'
RESET=$'\033[0m'


eval "$(echo "$input" | jq -r '
  @sh "MODEL=\(.model.display_name)",
  @sh "DIR=\(.workspace.current_dir)",
  @sh "COST=\(.cost.total_cost_usd // 0)",
  @sh "STYLE=\(.output_style.name)",
  @sh "SESSION=\(.session_id)",
  @sh "VERSION=\(.version)",
  @sh "CTX_PCT=\(.context_window.used_percentage)",
  @sh "CTX_REMAINING_PCT=\(.context_window.remaining_percentage)",
  @sh "CTX_SIZE=\(.context_window.context_window_size)"
')"


# Calculate remaining in k
CTX_REMAINING=$(( CTX_SIZE * CTX_REMAINING_PCT / 100 / 1000 ))k


# Color based on usage
if [ "$CTX_PCT" -ge 80 ]; then
    CTX_COLOR="$RED"
elif [ "$CTX_PCT" -ge 60 ]; then
    CTX_COLOR="$YELLOW"
else
    CTX_COLOR="$GREEN"
fi


# Git branch in workspace directory
GIT_INFO=""
if git -C "$DIR" rev-parse --git-dir > /dev/null 2>&1; then
    BRANCH=$(git -C "$DIR" branch --show-current 2>/dev/null)
    [ -n "$BRANCH" ] && GIT_INFO=" ${GREEN} $BRANCH${RESET}"
fi


SESSION_SHORT="${SESSION:0:8}"


printf "%s[%s]%s %s %s%s%s %s %s%% (%s left)%s %s\$%.4f%s %s%s%s %sv%s%s %s#%s%s\n" \
    "$CYAN" "$MODEL" "$RESET" \
    "$BLUE" "${DIR##*/}" "$RESET" "$GIT_INFO" \
    "$CTX_COLOR" "$CTX_PCT" "$CTX_REMAINING" "$RESET" \
    "$YELLOW" "$COST" "$RESET" \
    "$MAGENTA" "$STYLE" "$RESET" \
    "$WHITE" "$VERSION" "$RESET" \
    "$WHITE" "$SESSION_SHORT" "$RESET"

This displays:

  • Model name (Opus 4.5, Sonnet, etc.)
  • Current directory and git branch
  • Context usage with color-coded warnings (green < 60%, yellow 60-80%, red > 80%)
  • Session cost in USD
  • Active output style
  • Claude Code version
  • Session ID (first 8 characters)

Enabling the Status Line

In ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 0
  }
}

macOS Notifications

I also have notifications configured to alert me when Claude needs input:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

This is invaluable when Claude is working on a long task and I’m focused elsewhere.

Always Thinking Mode

One critical setting I always enable:

{
  "alwaysThinkingEnabled": true
}

This ensures Claude uses extended thinking for all responses, leading to more thorough and accurate results. The quality difference is noticeable.

The Thoughts Directory Pattern

For complex projects, I use a thoughts/ directory to persist context across sessions:

thoughts/
├── shared/
│   ├── plans/
│   │   └── 2026-01-15-feature-auth.md
│   └── research/
│       └── 2026-01-10-auth-patterns.md
└── local/
    └── scratch.md

This pattern provides:

  1. Session persistence - Plans and research survive beyond a single session
  2. Historical context - Past decisions inform future work
  3. Separation of concerns - Shared knowledge vs. personal notes

My /research_codebase command (covered in Part 2) automatically saves findings to thoughts/shared/research/.

Output Styles: Adapting Claude’s Voice

Claude Code supports output styles that change how responses are formatted. I’ve created three styles for different situations:

Enhanced Readability

For quick tasks where I need scannable output:

---
name: Enhanced Readability
description: Improved visual hierarchy for better readability
---


## Response Structure


### Overview
Brief summary of what I'm about to do or explain


### Implementation
- **Key Actions**: What specific steps I'm taking
- **Files Modified**: Clear list of affected files
- **Commands**: `formatted as code` for easy copying


### Results
Success: What was accomplished
Warnings: Any issues to be aware of
Errors: Problems that need attention

Mentor Mode

When I’m learning something new or onboarding onto a codebase:

---
name: Mentor
description: Senior engineer mentoring with deep explanations
---


When responding:
- **Explain the "why"**: Don't just provide solutions;
  explain the reasoning
- **Connect concepts**: Show how different parts relate
- **Anticipate questions**: Address common concerns proactively
- **Use teaching moments**: Turn every task into learning

Principal Architect

For architectural decisions and system design:

---
name: Principal Architect
description: Comprehensive architectural analysis with trade-offs
---


## Response Structure


### 1. Architectural Context & Problem Analysis
- Define the problem space clearly
- Identify key constraints (technical, business, organizational)


### 2. Technical Decision Framework
- **Primary Recommendation**: Lead with your preferred approach
- **Trade-off Analysis**: What you're optimizing vs. sacrificing
- **Alternative Approaches**: 2-3 viable alternatives with pros/cons


### 3. System Design Implications
- Scalability, Performance, Maintainability, Operational Complexity

Switching between styles is as simple as using the /output-style command.

Core Settings Summary

Here’s the complete ~/.claude/settings.json with the key configurations:

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 0
  },
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  },
  "alwaysThinkingEnabled": true,
  "verbose": true,
  "includeCoAuthoredBy": false
}

The includeCoAuthoredBy: false setting prevents Claude from adding itself as a co-author on commits, keeping your git history clean.

Conclusion

The foundation we’ve established here—CLAUDE.md configuration, terminal customization, the thoughts directory pattern, and output styles—creates the framework for everything that follows. These aren’t just settings; they’re the principles that transform Claude Code from a capable tool into a personalized engineering partner.

Key takeaways:

  • Global CLAUDE.md encodes your development philosophy across all projects
  • Project CLAUDE.md provides context-specific guidance for each codebase
  • Status line gives you real-time visibility into cost, context usage, and session state
  • Output styles adapt Claude’s communication to your current needs

What’s Next

With the foundation in place, Part 2 will dive into the 9 custom commands that make my workflow sing:

  • /research_codebase - Document and understand any codebase
  • /interview - Deep dive into edge cases and assumptions
  • /commit-all - Git workflow enforcement
  • /explain - Code explanation with ASCII diagrams
  • And 5 more commands that encode best practices

The configuration files we’ve set up here provide the context that makes those commands work effectively. Together, they transform Claude Code from a generic assistant into a specialized engineering partner that understands your standards, respects your workflow, and produces consistently high-quality results.

Next in series: Custom Commands and Workflow - Building a powerful command library

Written by

Farshad Akbari

Software engineer writing about Java, Kotlin TypeScript, Python, data systems and AI

Keyboard Shortcuts

Navigation

  • Open search ⌘K
  • Next article j
  • Previous article k

Actions

  • Toggle dark mode d
  • Toggle table of contents t
  • Show this help ?
  • Close modal Esc

Shortcuts are disabled when typing in inputs or textareas.