CLAUDE.md Convention¶

Purpose¶

Every repo in the Archon Platform has a CLAUDE.md at root. This file is read automatically by Claude Code at session start. It provides: 1. Pointer to the canonical AI context file (_context.md) 2. Repo-specific scope and constraints 3. Key operational rules for that repo

Standard template¶

# {Repo Name} — Claude Code Context

Read first:
- ~/homelab/repos/archon-docs/docs/_context.md — full platform AI context

This repo: {one-line scope description}

Branch policy active — always PR to main.
Work items required on all PRs.
Ansible service account: ansible-svc-account (never operator).

Repo-specific additions¶

Add repo-specific constraints after the standard template: - archon-platform: Ansible FQCN required, ansible-lint production profile, ansible-svc-account only - archon-docs: sanitize.py runs on build — never add real IPs/hostnames/ports - archon-apps: IT trunk-based, OT GitFlow (feature/* → develop → main) - archon-cloud: Free tier only — no paid resources without explicit approval - archon-web: Translation Worker at peries-ca-translator.benito-1d7.workers.dev

Global CLAUDE.md¶

~/.claude/CLAUDE.md provides platform-wide baseline: - Platform identity (Archon, CanEast public alias) - Key constraints (Trivy avoided, ansible-svc-account only, SSH port REDACTED on IT nodes) - Pointer to _context.md

Update cadence¶

Update CLAUDE.md files when: - New repos added to the platform - Key constraints change (new service accounts, ports, naming conventions) - _context.md location or structure changes

Never put secrets, IPs, credentials, or PATs in any CLAUDE.md file.

DEV-0001: Developer environment — Claude Code, WSL CanEast AI Node, MCP strategy
docs/_context.md: auto-generated platform AI context