Claude Code Deep Dive Part 1: Setup and Configuration

In the spirit of Mostly Copy and Paste, this article is primarily notes to myself — and anyone else interested — on how I currently use Claude Code across my professional and personal workflows. Things are moving fast in this space, with new capabilities appearing almost daily, so parts of this may be outdated before it’s even posted. I’ll do my best to keep it updated as my local setup evolves.

This is Part 1 of a four-part series:

1. Setup and Configuration (this article) — CLAUDE.md hierarchy, rules, skills
2. Development Workflows — planning, TDD, the verify-commit loop, parallel instances
3. SRE, Documentation & Team Management — incident response, runbooks, team onboarding
4. Personal Life & Knowledge Management — Obsidian integration, daily workflows

If you’re new to Claude Code and Obsidian, my Quick Start: Using Claude Code with Obsidian covers the basics. This series goes deeper.

The Configuration Hierarchy

Claude Code reads CLAUDE.md files at the start of every session and again after context compaction. This makes them functionally different from prompts — they’re persistent memory. They define what Claude knows about you and your project across every interaction, surviving even when the conversation context gets summarized.

The configuration loads from three tiers: global, project, and rules. Each tier adds specificity without overriding the others.

Global: ~/.claude/CLAUDE.md

Your global config applies to every project. This is where personal preferences live — tone, tool conventions, context management strategy. Things that are true regardless of what codebase you’re in.

Here’s a trimmed version of my actual global config:

# Claude Code Configuration

## Tone and Behavior
Criticism is welcome.
  - Tell me when I am wrong or mistaken
  - Tell me if there is a better approach
  - Tell me if there is a relevant standard I appear unaware of
Be skeptical.
Be concise.
  - Do not flatter, and do not give compliments unless specifically asked
Feel free to ask many questions. If in doubt of my intent, don't guess. Ask.

## Context Management
Context is a limited resource. Manage it aggressively:
  - Use subagents (Task tool) for exploration and research
  - After compaction, re-read project-level CLAUDE.md and rules files
  - Suggest /clear if conversation is wandering
  - Keep git status clean

## Tool Usage
Prefer specialized tools:
  - Use skills for repetitive workflows
  - Use subagents for context-heavy research
  - Use Read/Edit/Write instead of cat/sed/echo

## Code Style
Variable and function names should be complete words, as concise as
possible while maintaining specificity in context.

## Language-Specific Guidelines
Available rules (import in project-level CLAUDE.md):
  - ~/.claude/rules/python.md
  - ~/.claude/rules/javascript.md
  - ~/.claude/rules/terraform.md
  - ~/.claude/rules/go.md
  - ~/.claude/rules/testing.md
  - ~/.claude/rules/security.md
  - ~/.claude/rules/git-workflow.md

A few things to note. The tone section is there because Claude defaults to agreeable and verbose. Left unconfigured, you get a lot of “Great question!” and three paragraphs where one sentence would do. The context management section exists because context windows are finite — explicit instructions to use subagents and manage state aggressively prevent the “lost context” problem that plagues long sessions.

The last section references rules files. More on those below.

Project: ./CLAUDE.md

Your project-level config lives in the repo root. Think of it as an onboarding document for your AI pair programmer — the same things you’d tell a new team member on day one.

Here’s a trimmed version of the CLAUDE.md for this blog itself (yes, it’s meta):

# Mostly Copy & Paste

Technical blog: Hugo Extended + Pagefind search, deployed to AWS S3/CloudFront.

- **Site:** https://mostlycopyandpaste.com
- **Hugo root:** hugo-site/

## Commands
cd hugo-site && hugo server -D        # Dev server
./scripts/build.sh                    # Production build + Pagefind index
./scripts/deploy.sh                   # Deploy to S3 + invalidate CloudFront

## Content
Articles in hugo-site/content/articles/ by category.
Permalink pattern: /articles/:year/:month/:slug/

## Pitfalls
1. Always use ./scripts/build.sh — running hugo directly skips Pagefind
2. Future dates don't build — --buildFuture is not enabled
3. Hugo Extended required — standard Hugo won't compile SCSS
4. Never hardcode URLs — use .Permalink, relURL, absURL
5. Image processing needs page bundles — static/ images can't be processed

The pitfalls section is critical. These are the mistakes that Claude (and humans) make repeatedly without explicit warnings. A CLAUDE.md that only describes what things are misses the point. It needs to describe what goes wrong.

A good project CLAUDE.md covers: what the project is, how to build and run it, key architectural decisions, and the non-obvious things that cause problems. If you find yourself correcting Claude about the same thing twice, that correction belongs in CLAUDE.md.

Rules: ~/.claude/rules/*.md

Rules files contain conventions for specific languages or domains. They live in your global ~/.claude/rules/ directory and get referenced from your project CLAUDE.md to load contextually.

Here’s my Python rules file:

# Python Development Rules

## Tooling
- uv for package management
- ruff for linting and formatting
- pytest as default test framework

## Code Style
- Type hints for function signatures and complex variables
- pathlib over os.path for file operations
- f-strings for string formatting (not .format() or %)
- Prefer composition over inheritance
- dataclasses or Pydantic for data structures
- logging module, not print() for production code

## Testing
- Use fixtures for shared test setup
- Mock external dependencies in unit tests

## Error Handling
- Let exceptions bubble up unless you can handle them meaningfully

The power of rules files is conditional composition. A Python project references python.md and testing.md. A Terraform project references terraform.md and security.md. A full-stack project might reference javascript.md, python.md, and git-workflow.md. Each project gets exactly the conventions it needs without carrying irrelevant ones.

Skills and Commands

What Skills Are

Skills are markdown files that extend Claude Code’s capabilities beyond conversation. They live in .claude/skills/<skill-name>/SKILL.md (or the legacy .claude/commands/ directory) and are invoked with /skill-name. Where CLAUDE.md defines what Claude knows, skills define what Claude can do as repeatable, shareable workflows.

Each skill is a directory with a SKILL.md entrypoint that contains YAML frontmatter and markdown instructions:

---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when
  explaining how code works or when the user asks "how does this work?"
---

When explaining code, always include:

1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow or relationships
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common mistake or misconception?

Skills can also include supporting files — templates, example outputs, scripts — in the same directory. Reference them from SKILL.md so Claude knows when to load them.

Practical Examples

Skills shine for workflows you repeat but don’t want to type out every time. A few patterns I use:

Planning skills that create structured documents:

---
name: dev-docs
description: Create a comprehensive strategic plan with task breakdown
argument-hint: Describe what you need planned
disable-model-invocation: true
---

Create a structured plan for: $ARGUMENTS

Include: Executive Summary, Current State, Proposed Future State,
Implementation Phases, Task Breakdown, Risk Assessment, Success Metrics.

The disable-model-invocation: true flag prevents Claude from running this skill automatically — it only fires when you explicitly type /dev-docs. This is important for skills with side effects or that kick off large workflows.

Dynamic context skills that pull in live data:

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
allowed-tools: Bash(gh *)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

Summarize this pull request...

The !`command` syntax runs shell commands before the skill content reaches Claude. The output replaces the placeholder, so Claude receives actual data rather than commands to execute. The context: fork flag runs the whole skill in an isolated subagent, keeping your main conversation clean.

Conditional Composition

Skills and rules compose naturally. A skill can reference rules implicitly (Claude loads CLAUDE.md and its referenced rules alongside any skill), or skills can be scoped to specific tool sets with allowed-tools.

The hierarchy works like this:

When skills share the same name across levels, higher-priority locations win. This lets organizations set baselines while individuals and projects add specialization.

One-Shot vs. Structured Work

One-shot prompting works when three conditions are met: the task is small, the scope is clear, and success is easy to verify. Fix a typo, add a log statement, rename a variable — these are one-shot territory.

Most real development doesn’t meet those conditions. Adding a feature involves multiple files, architectural decisions, and tradeoffs that aren’t obvious from a one-line description. When you one-shot these tasks, you get code that works but doesn’t fit — it ignores existing patterns, introduces unnecessary abstractions, or solves a slightly different problem than you intended.

The fix is structured planning. Instead of “implement user authentication,” you break it down: what auth strategy, where does the middleware go, what’s the token lifecycle, how do sessions persist. You give Claude a plan to execute rather than a goal to interpret.

Current models have implicit planning capabilities — they’ll reason through steps internally. But formalizing the plan externally gives you two advantages:

1. Review before execution. A plan is cheaper to change than implemented code. You catch misunderstandings before they become refactoring sessions.
2. Persistence across sessions. Plans survive context compaction. Internal reasoning doesn’t.

The quality of Claude Code’s output scales directly with the quality of your input plan. A vague prompt produces vague code. A specific plan with architectural decisions, file paths, and acceptance criteria produces targeted implementation.

Part 2 covers the planning methodology in depth — PRD-driven development, spec-driven development, and the verify-commit loop that ties them together.

What’s Next

The remaining parts of this series:

• Part 2: Development Workflows — PRD/planning methodology, TDD and spec-driven development, the verify-commit loop, parallel Claude instances with tmux and git worktrees
• Part 3: SRE, Documentation & Team Management — Incident response, runbook generation, documentation workflows, team onboarding
• Part 4: Personal Life & Knowledge Management — Obsidian integration, daily notes, reading logs, personal automation

Resources

• Claude Code Overview — Official documentation
• Claude Code Memory (CLAUDE.md) — How CLAUDE.md files are loaded and prioritized
• Claude Code Skills — Full skills reference with advanced patterns
• CLAUDE.md Supremacy — Why CLAUDE.md files function as system rules, not suggestions
• The Complete Guide to Building Skills for Claude — Anthropic’s skills guide (PDF)
• claude-skills on GitHub — Community skill examples
• Quick Start: Using Claude Code with Obsidian — Companion piece for getting started