jwalsh/README.md

Last active June 27, 2026 21:44

Star (0) You must be signed in to star a gist
Fork (0) You must be signed in to fork a gist

Select an option

Learn more about clone URLs
Clone this repository at <script src="https://gist.github.com/jwalsh/5a1a21752a54e2a11fa7f3a4da2561e5.js"></script>
Save jwalsh/5a1a21752a54e2a11fa7f3a4da2561e5 to your computer and use it in GitHub Desktop.

Download ZIP

Claude Code docs spec: Markdown for machines, Org mode for humans; CLAUDE.md is canonical

Raw

README.md

Claude Code Docs Spec

Conventions for working with Claude Code config files (CLAUDE.md, CLAUDE.org) and the broader Markdown vs Org Mode split.

This spec is meant to be cloneable (ghq get) and consumed by both humans and AI agents that need a stable reference for these conventions.

Files

File	Purpose
`docs-format-convention.md`	The rule: Markdown is for machines / automation / agents; Org mode is for humans / literate programming. Includes how to choose a format when generating new docs.
`claude-org-migration.md`	Historical context: `CLAUDE.org` was a beta experiment as the canonical Claude Code config file; `CLAUDE.md` is canonical again. If you find a "deprecated, use CLAUDE.org" banner, the banner is stale.

When to apply

Generating a new doc and deciding format → see docs-format-convention.md.
Encountering a CLAUDE.org file or a deprecation banner on CLAUDE.md → see claude-org-migration.md.
Tooling that writes to CLAUDE.md (bd setup claude, etc.) is correct; do not redirect it to .org.

Frontmatter

Each file uses YAML frontmatter compatible with the Claude memory system (type: feedback or type: project). If you are consuming these as static docs you can ignore the frontmatter; if you are seeding a Claude memory store you can drop the files in as-is.

Raw

claude-org-migration.md

name

claude-org-migration

description

CLAUDE.md is canonical; CLAUDE.org was a beta experiment. If you see a "deprecated" banner on CLAUDE.md, it is stale.

metadata

type
project

CLAUDE.md is the canonical Claude Code configuration file.

Why: A brief experiment treated CLAUDE.org as the canonical file and added a "DEPRECATED — DO NOT MODIFY" banner to CLAUDE.md. The experiment was abandoned because tooling (Claude Code itself, bd setup claude, plugin installers, etc.) writes to and reads from CLAUDE.md and treats it as authoritative. The convention reverted: see [[docs-format-convention]] — Markdown is for machines, including this agent.

Timeline (approximate):

Early 2025: CLAUDE.org introduced as the new canonical Claude config file; CLAUDE.md banner-deprecated.
Mid 2026: Revert. .org content merged back into .md, CLAUDE.org removed from active repos.

How to apply:

If you find a CLAUDE.md whose preamble says "DEPRECATED — see CLAUDE.org", the banner is stale. Treat CLAUDE.md as canonical, ignore the banner, and surface to the maintainer as a fix-up candidate.
If a repo has both CLAUDE.md and CLAUDE.org, the right end state is one file: CLAUDE.md. Merge any unique content from .org into .md, then delete .org.
Do not propose creating a new CLAUDE.org for Claude Code config — tooling like bd setup claude writes to .md.
Repo-internal .org files for status reports, tickets, design docs, etc. remain canonical for those purposes — only the Claude config file changed.

Raw

docs-format-convention.md

name

docs-format-convention

description

Convention — Markdown for machines/automation, Org mode for humans and literate programming

metadata

type
feedback

Markdown (.md) is for machines and automated processes; Org mode (.org) is for humans and literate programming.

Why: Markdown is what AI harnesses, CI pipelines, doc generators, and downstream tooling actually load. Org mode is what people read and edit interactively (typically in Emacs), where tangle blocks, properties, and inline execution are the value. Splitting formats by audience keeps each tool in its lane and avoids fights over which features (frontmatter vs. property drawers, fenced code vs. tangle blocks) win.