Claude Code Configuration

Custom configuration for Claude Code that turns it into a disciplined engineering partner with structured workflows, strict guardrails, and domain-specific expertise.

Why

Out of the box, Claude Code is capable but generic. This configuration adds opinionated defaults - a mandatory research-plan-implement workflow, security boundaries, code standards, and 16 expert agents that activate automatically based on task context. The result is more consistent, reviewable, and safe output.

Repository Structure

CLAUDE.md                      # Core rules (workflow, security, behavioral constraints)
settings.json                  # Global settings (hooks, deny list, permissions)
agents/                        # 16 expert agent personas
commands/                      # Slash commands for frequent workflows
hooks/                         # Automation scripts (formatting, typechecking)
rules/                         # Modular instruction files (always-loaded + path-scoped)
scripts/                       # Utility scripts (notifications)
skills/                        # Reusable workflows with supporting files
docs/                          # Reference documentation
pull_request_template.md       # Default PR template
.github/workflows/             # CI (markdown linting)

Setup

Symlink the repo contents to ~/.claude/ so changes auto-sync:

# Clone the repo
git clone [email protected]:domengabrovsek/claude.git ~/dev/claude

# Symlink to ~/.claude/
ln -sf ~/dev/claude/CLAUDE.md ~/.claude/CLAUDE.md
ln -sf ~/dev/claude/agents ~/.claude/agents
ln -sf ~/dev/claude/rules ~/.claude/rules
ln -sf ~/dev/claude/skills ~/.claude/skills
ln -sf ~/dev/claude/commands ~/.claude/commands
ln -sf ~/dev/claude/hooks ~/.claude/hooks
ln -sf ~/dev/claude/scripts ~/.claude/scripts
ln -sf ~/dev/claude/settings.json ~/.claude/settings.json

# Configure smudge/clean filter to strip ephemeral state from settings.json
git config filter.strip-ephemeral-state.clean 'jq "del(.feedbackSurveyState)" 2>/dev/null || cat'
git config filter.strip-ephemeral-state.smudge cat

Note: Claude Code writes ephemeral state (e.g. feedbackSurveyState) to settings.json at runtime. The smudge/clean filter in .gitattributes automatically strips this before git sees it, so git status stays clean.

Components

CLAUDE.md

Core rules loaded every session (~50 lines). Kept lean - detailed standards live in rules/.

• 5-phase workflow: Research - Plan - Annotate - Implement - Summarize
• Security boundaries
• Behavioral constraints (scope discipline, verification gates)

Rules (rules/)

Modular instruction files. Always-loaded rules have no frontmatter. Path-scoped rules use globs: frontmatter and only load when editing matching files, saving tokens.

Agents (agents/)

16 expert agent personas across 5 categories. Each follows a 9-section structure with strict guardrails, review checklists, and red-flag detection. Loaded automatically via the routing table in rules/agent-routing.md.

See Agent Reference for the full listing.

Skills (skills/)

Reusable workflows invoked on-demand. Cost ~200 tokens when idle (metadata only) vs. full cost if in CLAUDE.md.

Commands (commands/)

Slash commands for frequent workflows. Available as /user:<name>.

Hooks (hooks/)

Automation scripts triggered at lifecycle events. Configured in settings.json (symlinked to ~/.claude/settings.json).

Scripts (scripts/)

Utility scripts referenced by skills and hooks.

State (.claude/state/ per project)

Session artifacts saved at the project level so they persist across sessions and machines.

.claude/state/
  research/    # Research artifacts from Phase 1
  specs/       # Specification documents from /spec
  plans/       # Implementation plans from Phase 2
  sessions/    # Session diary entries from Phase 5

Security

• Comprehensive deny list in settings.json blocking 35+ sensitive file patterns (env files, SSH/GPG keys, credentials, cloud configs, shell history)
• Bash command restrictions blocking destructive operations (rm -rf, git push --force, sudo, DROP TABLE)
• Lock file protection prevents edits to package-lock.json, yarn.lock, pnpm-lock.yaml
• PreToolUse gate blocks PR creation when tests fail
• PostToolUse formatting hook validates files before processing
• Agent guardrails enforce security checks across all domains

CI

Markdown linting runs on every push and PR via GitHub Actions.

Documentation

• Agent Reference - full agent listing and structure