Skip to content

[FEATURE] Skip instructions in CLAUDE.md when already deployed to .claude/rules/ #1138

@tillig

Description

@tillig

Is your feature request related to a problem? Please describe.

After running apm install followed by apm compile --target claude, instructions end up in two places that Claude Code reads:

  1. .claude/rules/*.md — deployed by apm install in Claude's native format (with paths: frontmatter for scoping)
  2. The "Project Standards" section of CLAUDE.md — generated by apm compile

Claude Code loads both locations, so it sees the same instructions twice. This isn't harmful, but it adds noise to the context window and could be confusing for users who aren't sure which source of truth to look at.

This is understandable — .claude/rules/ support was added later (PR #527/#542) as the native integration path, while CLAUDE.md compilation predates it. The two features just haven't been reconciled yet.

Describe the solution you'd like

When .claude/rules/ is being populated by apm install, apm compile --target claude could skip emitting the "Project Standards" (instructions) section in CLAUDE.md, since the native rules format is strictly more capable — it supports per-file scoping via paths: frontmatter, which CLAUDE.md's flat aggregation cannot express.

CLAUDE.md would still be generated for its other content (the Dependencies section with @import paths and the Constitution block), which isn't deployed elsewhere.

Alternatively, a configuration option in apm.yml to control whether instructions are included in CLAUDE.md would also work, letting users opt out of the duplication while keeping the default non-breaking.

I noticed in #94 there was discussion about eventually deprecating compile in favor of a single install command that handles all deployment — if that's still the long-term direction, this could be addressed as part of that effort.

Describe alternatives you've considered

  • Status quo with documentation: Just document that both paths exist and that instructions will appear in both places. Simple but doesn't reduce the duplication.
  • Gate on .claude/rules/ presence: Only include instructions in CLAUDE.md if no .claude/rules/ directory exists (i.e., the user hasn't opted into native integration). This would be automatic but might surprise users who expect the current behavior.
  • Configuration flag: An apm.yml option like compilation.claude.skip_instructions: true to opt out explicitly. Most flexible but adds config surface area.

Additional context

  • The .claude/rules/ format is better for Claude Code instructions because it uses native paths: frontmatter for file-scoped context, while CLAUDE.md aggregates everything flat under headings.
  • apm compile only writes CLAUDE.md; it does not touch .claude/rules/. Similarly, apm install only writes .claude/rules/; it does not generate CLAUDE.md. The duplication arises when both commands are run (which is the normal workflow).
  • CLAUDE.md still serves a purpose for dependencies (@import paths) and the constitution block — those aren't deployed to .claude/rules/ by install. The request is specifically to deduplicate the instructions, not to remove CLAUDE.md entirely.
  • Claude Code's context window is finite — doubling instructions unnecessarily reduces space for other context.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    Status

    Todo

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions