CLAUDE.md

Overview

CLAUDE.md is the most powerful configuration primitive in Claude Code. It defines project-level instructions that Claude reads at the start of every conversation. We use a 3-tier hierarchy: user-level (~/.claude/CLAUDE.md), project-level (CLAUDE.md at repo root), and repo-level (.claude/CLAUDE.md). This is how we encode architecture decisions, coding conventions, and workflow preferences so the team never repeats instructions.

Current Progress

• 3-tier hierarchy active: user, project, and repo CLAUDE.md
• 100+ keyword mappings defined across all products
• Component hierarchy (ui > atom > template > block) documented
• Stack preferences and coding conventions locked in

Areas of Improvement

• Arabic translations missing for keyword descriptions
• Per-repo CLAUDE.md files need audit across 14 repos
• Keyword-to-agent mappings could be auto-validated

References

Setup

1. Create CLAUDE.md at your repo root with project conventions
2. Create .claude/CLAUDE.md for shared team instructions
3. Create ~/.claude/CLAUDE.md for personal preferences
4. Add component hierarchy, stack preferences, and keyword triggers

Usage

• Define your tech stack and package manager preference
• Map keywords to workflows (e.g., 'dev' triggers server start)
• Set coding conventions — naming, file structure, import patterns
• Reference external repos and codebase lookup order
• Define component hierarchy levels (ui > atom > template > block)

Config Files