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).
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".
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.
These files also generally work in a nested fashion, like .gitignore and the like. So you want something that can be injected into the namespace of any directory in your project with relatively low likelihood of conflicts.
I feel bad that you're getting downvotes. The reason is that pretty much every modern web stack decouples the URL routing from the source code directory structure these days. It was a nice hack back in the day, but there are so many problems with it no one really does it any more.
Some frameworks (Laravel, NextJS, etc) map from the directory structure to routes, but that's just a mapping rather than actually exposing the directories on the server. You can have /src/agents accessible as /agents. Or you could have /alice/bob/agents accessible through /agents. It's all just build tooling and web server config at the end of the day.
That's my point. Having your code in `/src` doesn't mean some of that code doesn't still have routing at `example.com/agents`. It doesn't have to be a real directory.
A `.agents` directory (or routing pretending to be one) is nice because you are fairly unlikely to ever have user-facing `example.com/.agents` as a URL.
Or accept the fact that we're in 2025 and not follow Unix conventions from when paper and printer ink were expensive and they were printing out listings, and just name the thing "source".
I've gotten used to it, obviously - as someone with a career in IT for 20 years - but /etc & co. annoy me to no end. I know it will never change, I know why it won't change, I know GoboLinux will be just an interesting experiment, but it's still annoying.
Have you considered that there are other metrics people are optimizing for nowadays? Perhaps typeability, screen real estate, familiarity/convention, etc.? Do you really want /User Files/Bob's Files/Coding Projects/Python Projects/Bob's Cool Python Library/Source Code/Model Files/SomeObject.py?
Depends on the WinAPI used... I still use C:/src instead of C:/Users/MyUser/src for that reason when working in windows all the same though. Too many unixy utils don't leverage the apis with the longer path, not to mention not supporting the internal certificate store and proxy config.
Anything with a capital letter requires hitting two keys: Shift and then the desired letter. Thus /Programs requires 10 keystrokes rather than 9. Even worse, since the capital letter is at the beginning of the directory name, I have to type it and am unable to rely on tab-completion.
/Programs with its ten keystrokes is over twice the keystrokes of /bin and its four. Short names are quicker to type and require less effort. Given that to a first approximation I spend my entire life typing on a keyboard, I very much wish to optimise that experience.
That's really more the fault of the tab completion. There's no reason why it couldn't complete `prog` to `Programs`. It's just Unix tradition that they don't. I would prefer if they did.
Great tip! Apparently that's readline's config file, so this will affect a lot of things. That's great news for me; after switching to zsh I got used to case-insensitive tab completion, and now it annoys me when other tools don't work that way. This should help a lot.
The first shell listing starts with `cd` and `ls`, the former being run in `~`. What does that weird `~` mean? Very strange.
More seriously, their file system is still case-sensitive, and inside /Programs they have `Iptables` and `Fontconfig`, naively capitalized, but also `OpenOffice` and `HTTPD`.
Not to mention that inside each program folder are `man` and `bin` as usual. I'm going to suggest the point of that article is structure and organization, not naming.
Nobody reasonable complains about a three-letter abbreviation you can type with one hand. For a path you're either accessing a lot or never at all, it makes complete sense.
/usr -> Program Files (hello spaces my old friends, you've come to break my apps again)
/var -> ProgramData (but no spaces here)
/home -> Documents and Settings
/etc -> Control Panel
Spaces are avoided on base Linux systems because they're clunky for terminals more than fear of outright breaking things. To the extent spaces there do break things, that also happens on Mac and Windows for the same reasons (hence ProgramData being conspicuously space-less).
The abbreviations I wrote are unambiguous. When I first learned about Unix, I basically guessed - I assume as most first timers do - that the folder is basically the location of miscellaneous files ("et caetera").
Oh, let alone the fact that a bunch of the abbreviations are utterly non-intuitive to first timers.
/bin - binaries - nobody born after circa 1980 calls them that anymore. Executables, applications, apps, etc.
/boot - from a lame Baron Munchausen joke from 1970. Should probably be /startup.
/dev - dev is SUPER commonly used for "development". Easy enough to solve as /devices.
/home - okish, probably one of the best named that are actually in there. I'm shocked it's not /ho or /hm.
/lib - reasonable. Though these days in the US it might trigger political feelings :-p
> The abbreviations I wrote are unambiguous. When I first learned about Unix, I basically guessed
They're completely ambiguous to someone who doesn't speak English.
> /mnt - the whole metaphor of "mounting" is... debatable
What? Have you never heard of mounting a picture on a wall? Mounting an engine? That's the metaphor.
> Anyway, a lot of people have done this criticism better than me and it's boring at this point.
Your original complaint was about "src", suggesting calling it "source", which is still ambiguous by your own standard. Source of what? How is someone going to know what "source" means if they've never heard of booting a computer? Who is the audience for this change?
Some of your suggestions aren't meritless, but your jumping-off point certainly was.
Call it whatever you like. I don't care and that clearly wasn't the point of my comment.
One thing I've learnt, though, is unless you have a very good reason to try to change language you should just talk the same language as everyone else. I don't like the American short billion. It makes no sense and it's less useful. But that's what I use because I speak English and that's what we use now. If I see a src/ directory I know exactly what it is. If I see source/ it will give me pause. Get over it IMO.
While the meaning of "source" may be intuitively obvious, it's still relatively unfamiliar as "src" is far more prevalent than "source" when referring to source files. While "id est" may be equivalent to "i.e.", you'd still naturally pause when reading text using the former instead of the latter, because the latter is far more prevalent in usage than the former.
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.
If that is the case then why call it Agents.md instead of integrating it with already existing documentation files or calling it something like "Summary.md"?
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/`.
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.
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.
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
Well... Yah. For the record I'm saying this to trick humans into making better comments for humans. It is very difficult to convince people to do this otherwise, in my experience.
buuut...
I will also mention that these agent files are typically generated by agents. And they're pretty good at it. I've previously used agents to dissect unfamiliar code bases in unfamiliar languages and it has worked spectacularly well. Far far FAR better than I could have done on my own.
I have also been shocked at how dumb they can be. They are uselessly stupid at their worst, but brilliant at their best.
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.
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.
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.
>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
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.
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?
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"
Copilot does globs too, but if you dig into the actual prompt sent out...
They are not doing this mechanically (read file, compare to globs to add more context), they try to rely on the model to notice and do another read. It has been unreliable. I have had better results by adding instructions like...
"If the user asks about X, Read `./path/to/inst.md`"
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.
# 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.
And is also used in my $HOME directory - I like repeating good patterns, or at least well known patterns. (I still have ./etc and ./lib directories in my projects)
I believe with direnv or a similar tool (e.g. Emacs’s directory-local feature) one can append $REPO/.config to XDG_CONFIG_HOME, $REPO/.local/bin to PATH and so on so that when in the context of a particular directory everything Just Works.
I think all this agentic stuff could live quite happily in $REPO/.config/agents/.
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
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.
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.```
We all want to move to local models eventually for privacy and reliability.
They don't (and won't) have infinite context without trickery or massive €€€ use.
The current crop of online LLMs are just running on VC money slightly tapered with subscriptions - but still at a loss. The hype and money will run out, so use them as much as possible now. But also keep your workflows so that they will work locally when the time comes.
Don't be that 10x coder who becomes a 0.1x coder when Anthropic has issues on their side =)
I don't see how anyone could make a successful product build on cloud LLMs, even if you get a perfect workflow, you'll either be gouged with price rises, or lose out to model changes and context/prompt divergence. All this "prompt" nonsense is simply trying to play to the LLM audience, and no amount of imprecise prompt will negate the fundamental instability.
So yeah, you have to use a localLLM if you think there's a viable product to be had. Anyone whose been programming knows that once you get to the mile mark of a complete & finished project, it can be mothballed for decades generating utility and requiring limited maintenance. All that goes out the window if you require a cloud provider to remain stable for a decade.
Until LLMs deal with context as a graph and not just a linear order of vectors, it won't matter the amount of context you shove down it's processors, it's always going to suffer from near-sighted processing of the last bits. To generate true intelligence it needs to be able to jump to specific locations without the interceding vectors affecting it's route.
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).
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".