claude-md-authoring

CLAUDE.md is a project memory file that documents non-obvious architectural patterns, design decisions, and conventions. Create it using XML-style sections like <ARCHITECTURE>, <CONVENTIONS>, <GOTCHAS>, and <TESTING> to capture context that code inspection alone won't reveal, then link to relevant files with line references.

Document recurring issues, authentication token lifecycles, background job patterns, and project-specific gotchas that AI agents need to know. Use 2–4 XML sections with concrete examples: explain why design decisions were made, not what the code does, and link to existing documentation via file:line references.

Create CLAUDE.md when you have architectural decisions, non-obvious conventions, or solutions to recurring issues that span multiple files or aren't visible in isolated code inspection. It's most valuable during AI agent onboarding to prevent repeated context requests.

You can add architectural patterns or design decisions to an existing CLAUDE.md incrementally. Structure additions using the same XML-style tagging and avoid duplicating obvious information already captured in your codebase or existing documentation.

CLAUDE.md is optimised for AI agent reasoning and focuses on non-obvious context: why token refresh happens via a specific function, how background jobs interact, and project gotchas. Standard docs target human readers; CLAUDE.md prevents agents from missing tacit knowledge.

No prerequisites beyond a text editor. Follow the XML-style tagging structure (2–4 sections), use Australian English spelling, and link to existing documentation. The Skill guides content selection and organisation to capture what AI agents need.