From 276a40c578735f167069a160269eee8c9c45b00b Mon Sep 17 00:00:00 2001 From: jdalton Date: Fri, 17 Apr 2026 16:43:44 -0400 Subject: [PATCH] docs(claude): clarify .claude/ markdown exception The old policy text read as if every .md under .claude/ was banned, but the Claude harness actually reads files like `SKILL.md`, `agents/*.md`, `commands/*.md`, and `hooks/*/README.md` as its own configuration. We've been checking those in all along. Updates the Documentation Policy section so the stated rule matches what we actually do: harness-config markdown under .claude/agents, .claude/commands, .claude/hooks, .claude/skills is allowed. Ad-hoc analysis/session notes dropped under .claude/ are still disallowed, same as before. --- CLAUDE.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 59affa0e3..01f96a105 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -79,7 +79,9 @@ If user repeats instruction 2+ times, ask: "Should I add this to CLAUDE.md?" ### Documentation Policy -Do NOT litter the repository with documentation files. Allowed locations: `docs/`, root `README.md`/`CHANGELOG.md`/`SECURITY.md`/`CLAUDE.md`, `packages/*/README.md`, `test/fixtures/*/README.md`, `test/*/README.md`. No `.claude/*.md` analysis docs, no ad-hoc markdown files. +Do NOT litter the repository with documentation files. Allowed locations: `docs/`, root `README.md`/`CHANGELOG.md`/`SECURITY.md`/`CLAUDE.md`, `packages/*/README.md`, `test/fixtures/*/README.md`, `test/*/README.md`. No ad-hoc markdown files. + +**`.claude/` exception**: markdown files under `.claude/agents/`, `.claude/commands/`, `.claude/hooks/`, and `.claude/skills/` are allowed because the Claude harness reads them as configuration (agent definitions, command metadata, `SKILL.md` entrypoints, skill references). These are config, not analysis docs. Ad-hoc analysis/session notes in `.claude/` are still disallowed. ---