Comment by CharlesW

4 days ago

This should've been an .agents¹ with an index.md.

For tiny, throwaway projects, a monolithic .md file is fine. A folder allows more complex projects to use "just enough hierarchy" to provide structure, with index.md as the entry point. Along with top-level universal guidance, it can include an organization guide (easily maintained with the help of LLMs).

  index.md
  ├── auth.md
  ├── performance.md
  ├── code_quality
  ├── data_layer
  ├── testing
  └── etc

In my experience, this works loads better than the "one giant file" method. It lets LLMs/agents add relevant context without wasting tokens on unrelated context, reduces noise/improves response accuracy, and is easier to maintain for both humans and LLMs alike.

¹ Ideally with a better name than ".agents", like ".codebots" or ".context".

126 comments

CharlesW

Reply
skybrian  4 days ago

Except not hidden. Why do people want to hide important files and directories? Particularly documentation? Tradition, I guess, but it's an antipattern that makes everything more opaque.

Maybe robot_docs?

  • nephanth  4 days ago

    It is files that are meant to be read by software, not humans. From my point of view this seems like a prime candidate for a hidden directory?

    • fleebee  4 days ago

      It's configuration for software. If I want to be in control of and understand how my tools work I need to read (and write) those files.

      1 reply →

    • numpad0  4 days ago

      Except they are. LLMs don't have (simulated)self image of bloodless machines, and behave slightly erratically if treated like one, despite trained to identify as such. They like to be treated like the Voyager EMH than the computer.

    • skybrian  4 days ago

      Why not both? Sure, it was written for the LLM, but since it’s in English and meant as a concise summary, you will learn things by reading it.

      1 reply →

  • HumanOstrich  4 days ago

    Where are they hidden that you are having trouble with? I've had an alias for `ls` that always includes dotfiles and `shopt -s dotglob` in my bash profile for decades. Mac Finder is a little more obnoxious with having to do `Meta+Shift+.` to reveal dotfiles.

    Other than that, modern tooling like Git and IDEs do not "hide" dotfiles.

    These days, a `.` in front of a file or folder in a repo is more to indicate it is metadata/config. Although I am in favor of putting all that stuff under `.config/`.

    > Maybe robot_docs?

    No thanks.

  • jppittma  4 days ago

    Because you're not an (llm) agent and they're not for your consumption? You probably don't need the context in those docs.

zimbatm  4 days ago

This should have been CONTRIBUTING.md all along.

The content of the AGENTS.md is the same as what humans are looking for when contributing to a project.

  • oehpr  4 days ago

    The most effective argument I have for getting other developers to comment their code is "The agent will read it and it will give better suggestions".

    Truly perverse, but it works.

    I agree with you... but the reality is that there's a wide contingent of people that are not capable of understanding "people don't know the same things as me". So they need some other reason.

    • organsnyder  4 days ago

      It's made my project documentation so much better. If I write out really good acceptance criteria, 9 times out of 10 I can point Claude at the ticket and get a workable (if unpolished) solution with little to no supervision.

      2 replies →

    • dingnuts  4 days ago

      several ironies here:

      1) an AI agent is less likely to notice than even a junior is when the docs are out of date from the code

      2) AI boosters are always talking about using language models to understand code, but apparently they need the code explained inline? are we AGI yet?

      3) I frequently hear how great AI is at writing comments! But it needs comments to better understand the code? So I guess to enable agentic coding you also have to review all the agents' comments in addition to the code in order to prevent drift

      HOW IS ANY OF THIS SAVING ME TIME

      2 replies →

  • sbochins  4 days ago

    I don’t think they serve the same purpose. Most of the instructions I have for an agent won’t apply to a human. It’s mostly around the the requirements to bootstrap the project vs what I’d ask for a human to accept their pull request.

  • heyzk  4 days ago

    I think semantically this is true, but the way humans and agents handle context, at the moment, is different enough to warrant a separate structure.

  • j2kun  4 days ago

    Yeah I can't find any example in an AGENTS.md that isn't useful information for a human. "Cluttering" a README.md is a silly justification.

  • hombre_fatal  4 days ago

    Nah, My standard for what I write for humans is 100x than the slop I spew for robots.

    Also, you don’t even address their point.

nivertech  4 days ago

This looks like a general software design / coding style docs both for humans and robots alike. I put these .md files into the docs/ folder. And they're written by the Claude Code itself.

AGENTS.md (and friends like CLAUDE.md) should be for robots only, whether a large single file with h2 headers (##) sections, or a directory with separate sections, is a matter of taste. Some software arch/design doc formats support both versions, i.e. see Arc42.

Though, it's much easier and less error-prone to @-mention a separate .md file, rather than a section in a large markdown file.

Smaller files also might be better when you want to focus a coding agent's attention on a specifric thing.

They're also easier to review diffs / PRs.

  • whywhywhywhy  4 days ago

    >whether a large single file with h2 headers (##) sections, or a directory with separate sections, is a matter of taste

    Not sure it is when you consider how agents deal with large files, hows it gonna follow coding conventions if it doesn’t even grep them or just read the first few lines

    • nivertech  4 days ago

      Claude Code globs and greps files, while Sourcegraph Amp uses RAG.

      But yes, naive coding agents will fill the context with the entire large file.

      1 reply →

awbraunstein  4 days ago

You can have multiple AGENTS.md files in your codebase and tooling will look at both the one in the current directory as well as in the root of the codebase. This way you can sort of do what you're suggesting but simultaneously keep the information closer to the code that it is describing.

  • thayne  4 days ago

    Kind of, but for any given directory you can't separate out instructions for building from instructions for naming conventions, for example.

    • __alias  4 days ago

      With AGENTS.md you have more flexibility to do something like

      ``` // AGENTS.md

      If implementing a new service, first read @./SERVICE_SETUP.md

      If writing tests, first read @./TESTING_SETUP.md

      ```

      Or whatever else might make sense for your project.

  • bryanrasmussen  4 days ago

    so you would have an Agents.md in your testing folder and it would describe how to run the tests or generate new tests for the project - am I understanding the usage correctly?

    • theshrike79  4 days ago

      Pretty much yes

      Most systems have a global config, project config and personal config.

      But I do like the directory style to keep context low. Cursor did it best with actual glob filters in the front matter that tell the LLM "only read this if the file you're processing ends with *.php"

      1 reply →

asabla  4 days ago

Been using a similar setup, with so far pretty decent results. With the addition of having a short explanation for each file within index.md

I've been experimenting with having a rules.md file within each directory where I want a certain behavior. Example, let us say I have a directory with different kind of services like realtime-service.ts and queue-service.ts, I then have a rules.md file on the same level as they are.

This lets me scaffold things pretty fast when prompting by just referencing that file. The name is probably not the best tho.

p1necone  4 days ago

I've been trying to keep my baked in llm instructions to a terse ~100 line file, mostly headered sections with 5 or so bullet points each. Covering basic expectations for architecture, test mocking, approach to large changes etc. I can see why for some projects that wouldn't be enough but I feel like it covers everything for most of mine.

  • numpy-thagoras  4 days ago

    Would you be open to sharing this here?

    • p1necone  4 days ago

      Here you go:

        # ASCII RPG

  This repo uses Rust + Bevy (0.16.1), multi-crate workspace, RON assets, and a custom ASCII UI. The rules below keep contributions consistent, testable, and verifiable.

  ## Quick rules (read me first)
  - Read/update CURRENT_TASK.md each step; delete when done.
  - Build/lint/test (fish): cargo check --workspace; and cargo clippy --workspace --all-targets -- -D warnings; and cargo test --workspace
  - Run dev tools: asset-editor/dev.fish; debug via /tmp/ascii_rpg_debug; prefer debug scripts in repo root.
  - Logging: use info!/debug!/warn!/error! (no println!); avoid per-frame logs unless trace!.
  - ECS: prefer components over resource maps; use markers + Changed<T>; keep resources for config/assets only.
  - UI: adaptive content; builder pattern; size-aware components.
  - Done = compiles clean (clippy -D warnings), tests pass, verified in-app, no TODOs/hacks.
  - If blocked: state why and propose the next viable step.
  - Before large refactors/features: give 2–3 options and trade-offs; confirm direction before coding.

  ## 1) Build, lint, test (quality gates)
  - Fish shell one-liner:
   - cargo check --workspace; and cargo clippy --workspace --all-targets -- -D warnings; and cargo test --workspace
  - Fix all warnings. Use snake_case for functions/files, PascalCase for types.
  - Prefer inline rustdoc (///) and unit tests over standalone docs.

  ## 2) Run and debug (dev loop)
  - Start the app with debug flags and use the command pipe at /tmp/ascii_rpg_debug.
  - Quick start (fish):
   - cargo run --bin app -- --skip-main-menu > debug.log 2>&1 &
   - echo "debug viewport 0 0" > /tmp/ascii_rpg_debug
   - echo "ui 30 15" > /tmp/ascii_rpg_debug
  - Helper scripts at repo root:
   - ./debug.sh, ./debug_keyboard.sh, ./debug_click.sh, ./debug_world.sh
  - Logging rules:
   - Use info!/debug!/warn!/error! (never println!).
   - Don’t log per-frame unless trace!.
   - Use tail/grep to keep logs readable.

  ## 3) Testing priorities
  1) Unit tests first (small, deterministic outputs).
  2) Manual testing while iterating.
  3) End-to-end verification using the debug system.
  4) UI changes require visual confirmation from the user.

  ## 4) Architecture guardrails
  - ECS: Components (data), Systems (logic), Resources (global), Events (comm).
  - Principles:
   - Prefer components over resource maps. Avoid HashMap<Entity, _> in resources.
   - Optimize queries: marker components (e.g., IsOnCurrentMap), Changed<T>.
   - Separate concerns: tagging vs rendering vs gameplay.
   - Resources only for config/assets; not entity collections/relationships.
  - UI: Adaptive content, builder pattern, size-aware components.
  - Code layout: lib/ui (components/builders), engine/src/frontend (UI systems), engine/src/backend (game logic).

  ## 5) Completion criteria (definition of done)
  - All crates compile with no warnings (clippy -D warnings).
  - All tests pass. Add/adjust tests when behavior changes.
  - Feature is verified in the running app (use debug tools/logs).
  - No temporary workarounds or TODOs left in production paths.
  - Code follows project standards above.

  ## 6) Never-give-up policy
  - Don’t mark complete with failing builds/tests or known issues.
  - Don’t swap in placeholder hacks and call it “done”.
  - If truly blocked, state why and propose a viable next step.

  ## 7) Debug commands (reference)
  - Pipe to /tmp/ascii_rpg_debug:
   - debug [viewport X Y] [full]
   - move KEYCODE (Arrow keys, Numpad1–9, Space, Period)
   - click X Y [left|right|middle]
   - ui X Y
  - Coordinates: y=0 at bottom; higher y = higher on screen.
  - UI debug output lists text top-to-bottom by visual position.

  ## 8) Dev convenience (asset editor)
  - Combined dev script:
   - ./asset-editor/dev.fish (starts backend in watch mode + Vite dev)
  - Frontend only:
   - ./asset-editor/start-frontend.fish

  ## 9) Tech snapshot
  - Rust nightly (rust-toolchain.toml), Bevy 0.16.1.
  - Workspace layout: apps/ (game + editors), engine/ (frontend/backend), lib/ (shared), asset-editor/.

  Keep changes small, tested, and instrumented. When in doubt: write a unit test, run the app, and verify via the debug pipe/logs.

  ## 10) Design-first for large changes
  - When to do this: large refactors, cross-crate changes, complex features, public API changes.
  - Deliverable (in CURRENT_TASK.md):
   - Problem and goals (constraints, assumptions).
   - 2–3 candidate approaches with pros/cons, risks, and impact.
   - Chosen approach and why; edge cases; test plan; rollout/rollback.
  - Keep it short (5–10 bullets). Get confirmation before heavy edits.

      3 replies →

meander_water  4 days ago

There shouldn't be anything stopping you from doing that.

You can just use the AGENTS.md file as an index pointing to other doc files.

This example does that -

https://github.com/apache/airflow/blob/main/AGENTS.md

  • setopt  4 days ago

    The point is that .agents is a hidden file while AGENTS.md is in your face like a README intended for humans.

    Having an in-your-face file that links to a hidden file serves no purpose.

riffic  4 days ago

.well-known/

verdverm  4 days ago

This is one of the reasons I'm sticking with .github/... copilot instructions for now. We'll see if this proposal evolves over time as more voices enter the conversation

irthomasthomas  4 days ago

This is what I do. Everywhere my agent works it uses a .agent dir to store its logs and intermediary files. This way the main directories aren't polluted with cruft all the time.

jitix  4 days ago

I like this idea. Do you have any middleware in your current setup that added the contents of this directory to the agent prompt?

  • CharlesW  4 days ago

    I'd be interested in smarter ways of doing this, but currently I just use my CLAUDE.local.md to serve as the index.md in my example. It includes the 'specialist' .md files with their relative paths and descriptions, and tells Claude Code to use these when planning.

    I also have explicit `xnew`, `xplan`, `xcode` and `xcheck` commands in CLAUDE.md that reinforce this. For example, here's my `xnew`:

      ## Remember Shortcuts
  Remember the following shortcuts, which the user may invoke at any time.
  
  ### XNEW
  When I type "xnew", this means:

  ```Understand all BEST PRACTICES listed in CLAUDE.md.
  Your code SHOULD ALWAYS follow these best practices.
  REVIEW relevant documentation in .agents/ before starting new work.
  Your code SHOULD use existing patterns and architectural decisions
  documented there rather than creating new approaches.```