microsoft / microsoft/agentrc

Generated monorepo AGENTS.md files contain heavy duplication and anti-patterns

Open
#45 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
TypeScript
Stars
1.1k
Forks
94
Avg merge
8d 3h
Merged PRs (30d)
7

Description

Problem

When running agentrc instructions on a large monorepo (Rust workspace with 24+ crates), the generated per-crate AGENTS.md files contain significant duplication of root-level instructions and several anti-patterns identified by Copilot review.

Findings

1. Anti-pattern: Dual file types (copilot-instructions.md + AGENTS.md)

The generator creates both a root copilot-instructions.md and 24+ per-crate AGENTS.md files. The reference docs recommend using only one type, not both. This causes ambiguity about which file takes precedence and wastes context tokens.

Expected: Either consolidate into a single root AGENTS.md (with per-crate AGENTS.md extending it), or use copilot-instructions.md + .github/instructions/*.instructions.md with applyTo globs.

2. Anti-pattern: "Kitchen sink" / Duplicating root content in per-crate files

The majority of each crate's "Key Conventions" section repeats what's already in the root instructions:

  • Workspace dependencies / { workspace = true }
  • Error types / thiserror::Error
  • Logging with tracing
  • Testing with tempfile / test_data/
  • Standard build/test commands (cargo build -p <crate>, cargo clippy-fast, cargo fmt)

The same boilerplate is copy-pasted across all 24 crate files, burning context tokens on every interaction.

3. Redundant "Monorepo Context" section

Each crate file includes git root, workspace root Cargo.toml path, toolchain, and "all cargo commands from root" — all already covered in root instructions with no crate-specific additions.

4. Title mismatch

Generated AGENTS.md files use # Copilot Instructions: <crate> crate as the heading, implying it's a copilot-instructions.md file. For AGENTS.md in a monorepo hierarchy, a simpler heading like # <crate> crate is sufficient.

Desired behavior

Per-crate AGENTS.md files should contain only crate-unique context:

  • Crate purpose / summary
  • File structure → responsibility mapping
  • Crate-specific conventions (e.g., special binary resolution, auth patterns, helper APIs)
  • Internal consumers / dependencies (only if non-obvious)

Everything that applies workspace-wide should live exclusively in the root file, not be duplicated.

Example: well-trimmed crate file

For a git crate, the ideal output is ~60% smaller than current:

# `git` crate

Git utility abstractions — binary resolution, branching, checkout, config, credentials, diffs, and remotes.

## Structure

src/
├── lib.rs         # git_command(), async_git_command(), git_binary(), git_root()
├── branch.rs      # Current branch detection, handles detached HEAD
├── checkout.rs    # Repository checkout operations
├── config.rs      # git config read/write helpers
├── credential.rs  # Bearer token headers, credential store
├── diff.rs        # Async diff stats and file comparisons
└── remote.rs      # Remote URL management

## Crate-Specific Conventions

- **Git binary resolution**: `git_binary()` checks env var first, then falls back to PATH. Use `git_command()` / `async_git_command()` everywhere — never call `Command::new("git")` directly.
- **Auth via git config**: Credentials are persisted via `git config --local`, not per-command env vars.
- **Debug helpers**: `git_debug_env_vars()` / `git_cmd_with_debug()` for diagnosing auth/network issues.

## Internal Consumers

Uses `vars` (env var constants) and `fs_utils` (filesystem helpers).

Suggested improvements

  1. Deduplicate at generation time — diff each per-crate section against the root instructions and strip anything already covered
  2. Avoid dual file types — choose one strategy per repo (root AGENTS.md + per-directory, or copilot-instructions.md + .instructions.md globs)
  3. Use appropriate headings — match the heading style to the file type being generated
  4. Add a post-generation dedup pass — or surface a warning when duplication is detected across files

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the generator path invoked by agentrc instructions and inspect how root copilot-instructions.md and per-crate AGENTS.md files are assembled. Compare generated crate files with the root instructions and the trimmed git crate example; done means workspace-wide guidance is not repeated, headings match the file type, and the selected file strategy is consistent.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.