Skip to content

Move contributor instructions from CLAUDE.md to AGENTS.md (and slim them) #1938

Closed

Description

@pzfreo

Part of the code-health epic.

Problem

CLAUDE.md is 322 lines and has turned into a mix of three things:

  • a module map that duplicates _LAYERS and has drifted from it (it is missing audit.py and view_plan.py);
  • working practices;
  • dated benchmark numbers, which it admits are historical (159–172 s, 358 s against 348 s, the 8,760-test census).

AGENTS.md already exists as the usage guide for agents that drive draftwright (137 lines, checked by tests/test_agents_guide.py). The maintainer wants the contributor instructions to live in AGENTS.md, the tool-neutral convention.

Proposal

  • Move the engine-contributor content of CLAUDE.md into AGENTS.md.
  • Resolve the collision with the existing usage guide. Either:
    • move the usage guide to docs/using-draftwright.md and link to it from AGENTS.md; or
    • make AGENTS.md two clearly headed parts.
  • Delete CLAUDE.md. Since 2.1.277, Claude Code reads AGENTS.md in a project that has no CLAUDE.md; this is the default "Project instructions" setting in /config. That support is behind a feature flag and not yet available on Bedrock or Vertex. Anyone who hits one of those limits needs either a one-line @AGENTS.md stub or the setting changed.
  • While moving it, slim it down:
    • replace the module list with a pointer to _LAYERS and docs/architecture.md;
    • remove the historical timing figures.
  • Update everything that references either file: CONTRIBUTING.md, CHANGELOG.md, docs/*, tests/test_adr_corpus.py, tests/test_agents_guide.py, and the handful of src comments.

Acceptance

  • Claude Code and other agents both load the same instructions.
  • test_agents_guide and test_adr_corpus pass.
  • The new file is under about 200 lines.

Activity

  1. added
    documentationImprovements or additions to documentation
    area:docsDocumentation and published references
    on Sep 28, 2026
  2. added a commit that references this issue on Sep 28, 2026
    44f5084
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:docsDocumentation and published referencesdocumentationImprovements or additions to documentation

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions