Skip to content

Exclude .claude Subdirectory Content

Context

The donor reference repository contains a project-root CLAUDE.md file that articulates engineering principles (correctness over speed, modular by default, proto enums as single source of truth, air-gap first, real backends in tests, fix root causes not symptoms, no backward-compatibility burden in pre-production). It also contains a sibling .claude subdirectory with detailed operator playbooks for agentic workflows: orchestrator behaviour, multi-agent coordination, quality gates, telemetry collection, audit references, and per-language style rules. The two surfaces have very different audiences and very different lifecycles.

CLAUDE.md (project root) is the durable principles file: short, opinionated, and meant to be read by every contributor — human or agent — before touching the codebase. It articulates the kind of engineering culture an organisation aspires to and translates directly into prescriptive prose for a Discipline chapter.

The .claude subdirectory, by contrast, is operational infrastructure for a specific agentic workflow: it tells an orchestrator agent how to spawn teammates, how to coordinate handoffs, how to collect telemetry, how to audit runs. Its contents are tightly coupled to one organisation's chosen agent harness and would actively mislead a reader who is not running that harness. Copying it into the guide would create an artifact that claims to be a general technology selection guide while silently smuggling in a vendor-shaped operational layer.

This ADR records the decision to draw a hard line at the project-root CLAUDE.md and EXCLUDE every file under .claude from the guide's sources. The Discipline chapter MUST source its content from the project-root CLAUDE.md plus general industry references (Uber Go Style Guide, Google Go Style Guide, Twelve-Factor App, RFC 2119) and MUST NOT cite, quote, or paraphrase any .claude subfile.

Decision Drivers

  • The guide MUST be portable across organisations and forks; it MUST NOT smuggle one organisation's operational harness into the recommendations.
  • The Discipline chapter MUST articulate principles that translate across agent harnesses, IDEs, and human-only workflows.
  • The source selection MUST be mechanically checkable: a grep for .claude in the deliverable MUST return zero hits.
  • The decision MUST be reviewable by adopting orgs so that a future fork MAY revisit the line without re-litigating it.
  • Project-root CLAUDE.md-style files SHOULD remain in scope because they are now a widely-recognised convention for "principles every contributor reads first".

Considered Options

  • Hard exclusion: project-root CLAUDE.md IN, .claude subdirectory OUT
  • Soft inclusion: cite .claude files where they articulate a general principle, with attribution
  • Full exclusion: omit both CLAUDE.md and .claude, use only industry references
  • Full inclusion: copy everything from CLAUDE.md and .claude into the Discipline chapter

Decision Outcome

Chosen option: "Hard exclusion: project-root CLAUDE.md IN, .claude subdirectory OUT", because it is the only option that keeps the guide portable while preserving the durable principles content that adopting orgs will recognise. Soft inclusion was rejected because the line "this .claude file articulates a general principle" is editorially unstable — every subsequent contributor would re-litigate the line per file. Full exclusion was rejected because the project-root CLAUDE.md content is durable and useful. Full inclusion was rejected because the .claude subdirectory ties the guide to one specific agent harness.

Positive Consequences

  • The Discipline chapter MAY draw on CLAUDE.md content freely without scope ambiguity.
  • Forks for organisations using different agent harnesses MAY adopt the guide unchanged.
  • The exclusion is mechanically checkable: grep -rF ".claude" MUST return zero hits in the deliverable.

Negative Consequences

  • Useful general principles that happen to live inside .claude (e.g., a clearly-articulated quality gate philosophy) MUST be re-derived from industry references rather than quoted directly.
  • Contributors MUST resist the temptation to "just quote the .claude quality.md one-liner because it's better-worded than the industry version".

Consequences

After this decision, the Discipline chapter is authored from the project-root CLAUDE.md plus general industry references. Pull requests that introduce .claude-sourced content MUST be rejected at review. The CI workflow SHOULD include a grep-based check that fails the build if .claude appears in any deliverable file outside of an explicit "Sources excluded" note. The donor reference repository remains unmodified.

Pros and Cons of the Options

Hard exclusion: CLAUDE.md IN, .claude OUT

A bright-line rule with mechanical checkability.

  • Good, because the boundary is unambiguous and grep-checkable.
  • Good, because the guide remains portable across agent harnesses.
  • Good, because contributors do not re-litigate the line per file.
  • Bad, because useful .claude content MUST be re-derived from industry references.

Soft inclusion with attribution

Cite .claude files where they articulate a general principle.

  • Good, because the best content is preserved verbatim.
  • Bad, because the editorial line "is this general?" is unstable across contributors and reviews.
  • Bad, because forks inherit one organisation's operational vocabulary.

Full exclusion of both CLAUDE.md and .claude

Use only industry references.

  • Good, because the guide is maximally vendor-neutral.
  • Bad, because the durable principles in CLAUDE.md are useful and widely recognised, and discarding them weakens the Discipline chapter.

Full inclusion of both

Copy everything into the Discipline chapter.

  • Good, because no useful content is left behind.
  • Bad, because the guide becomes a vendor-shaped artifact bound to one agent harness.
  • Bad, because adopting orgs MUST strip operational content during fork.