CLAUDE.md

PreviousNext

Project instructions that shape every response — the 3-layer hierarchy

CLAUDE.md

The most powerful configuration primitive in Claude Code. A markdown file that shapes every response, every agent, every workflow. Kun uses a 3-layer hierarchy that cascades from global preferences down to repo-specific operations.

3-Layer Hierarchy

Priority (High → Low):
1. Project-level  ~/project/CLAUDE.md         — Project context
2. Repo-level     ~/project/.claude/CLAUDE.md  — Keywords, workflows
3. User-level     ~/.claude/CLAUDE.md          — Stack, preferences
4. Pattern library /Users/abdout/codebase/     — Core patterns

Higher layers override lower ones. This means project-specific context always wins over global defaults.

Layer 1: User-Level (~/.claude/CLAUDE.md)

Global preferences that apply to every project and every conversation.

SettingValue
ModelFable 5 (claude-fable-5)
FallbacksOpus 4.8 → Sonnet 5
BillingClaude Max 5x ($100/mo), subscription-only
Package managerpnpm
StackNext.js 16, React 19, Prisma 6, TypeScript 5, Tailwind CSS 4, shadcn/ui
LanguagesArabic (RTL default), English (LTR)
PortAlways 3000
EnvironmentCentral .env only
Component hierarchyui, atom, template, block, micro

Layer 2: Project-Level (CLAUDE.md)

Project-specific context per product:

ProductContext
HogwartsMulti-tenant education SaaS, school modules, SSPL license
MkanRental marketplace, Airbnb-inspired, booking flow
KunConfiguration engine, documentation site, 3-phase roadmap

Layer 3: Repo-Level (.claude/CLAUDE.md)

Operational configuration: 160 keyword-to-action mappings, MCP trigger table, the pipeline stages, organization repository references, and React best practices from Vercel.

What It Contains

  • Keyword mappings — Say dev to start server, push to commit, deploy to ship
  • Component hierarchy — ui, atom, template, block, micro
  • MCP trigger table — Which keyword activates which MCP server
  • Slash command reference — All available / commands
  • Organization references — How to reference other databayt repos
  • React best practices — Waterfall elimination, bundle optimization, server components

Writing Effective CLAUDE.md

Do

  • Lead with preferences (model, stack, language)
  • Map keywords to actions (say X → do Y)
  • Define component hierarchy
  • Reference external repos and patterns
  • Include React/Next.js best practices

Avoid

  • Implementation details (that's what agents and rules are for)
  • Long prose (tables and lists are better)
  • Duplicating what's in rules or agents
  • Sensitive information (use secrets instead)

Installation

CLAUDE.md files are installed by the Kun setup script:

# Seeds ~/.claude/CLAUDE.md from the template only if missing — never overwritten
cd ~/kun && bash .claude/scripts/setup.sh engineer

~/.claude/CLAUDE.md is your personal global config; the kun project CLAUDE.md loads separately inside the repo and never replaces it.