8 ms·
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 "ju
by CharlesW 1y 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".
- asabla 1y agoBeen 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.
- riffic 1y ago.well-known/
- echelon 1y agoThis. Projects need to stop inventing their own root level files and directories. Stop polluting the root dir. I'm not a fan of the name "well-known", but at least it's a convention [1]. I think it'd be great if we took something like XDG [2] and made it common for repositories, build scripts, package managers, tooling configs, etc. [1] https://www.rfc-editor.org/rfc/rfc8615 https://www.rfc-editor.org/rfc/rfc8615 [2] https://wiki.archlinux.org/title/XDG_Base_Directory https://wiki.archlinux.org/title/XDG_Base_Directory
- vinnymac 1y ago.config is a good name, and has a small following https://dot-config.github.io https://dot-config.github.io
- echelon 1y agoThis has my vote. Thank you for sharing.
- edoceo 1y agoAnd 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)
- binarysneaker 1y agoReminds me of https://xkcd.com/927/ https://xkcd.com/927/
- soraminazuki 1y agoOr just config with no dots.
- oblio 1y agoI've been in IT for a long time and configured Apache, Nginx, even IIS a bit back in the day, but I actually didn't know about well-known. I guess I was one of the lucky 10000 :-) https://xkcd.com/1053/ https://xkcd.com/1053/
- riffic 1y agoin that case it's .not-so-well-known/
- eadmund 1y agoI 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/.
- jitix 1y agoI like this idea. Do you have any middleware in your current setup that added the contents of this directory to the agent prompt?
- tortilla 1y agoI'm building a little tool like this for myself. It's almost ready to be open-sourced. Just need to clean up some code and write better documentation.
- CharlesW 1y agoI'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.```
- lemontheme 1y agoThere’s also [.claude/agents/](https://docs.anthropic.com/en/docs/claude-code/sub-agents https://docs.anthropic.com/en/docs/claude-code/sub-agents), which doesn’t contain docs for agents but separate sub-agent definitions.
- p1necone 1y agoI'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 1y agoWould you be open to sharing this here?
- p1necone 1y agoHere 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.
- skybrian 1y agoExcept 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?
- animal_spirits 1y agoIt's so it doesn't clash with any project that actually has a functional `agents/` directory
- globular-toast 1y agoAnother reason to use a src/ directory for the actual source code.
- ceejayoz 1y agoThat won't save you if you want actual example.com/agents/foo routing and an (say, real estate) agents list at example.com/agents.
- onion2k 1y agoI 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.
- ceejayoz 1y agoThat'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.
- meander_water 1y agoThere 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 https://github.com/apache/airflow/blob/main/AGENTS.md
- setopt 1y agoThe 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.
- meander_water 1y agoI don't see the point of having it hidden though. Having it "in your face" means you can actively tune it yourself, or using the LLM itself.
- createaccount99 1y agoAnti-feature if you ask me. An agent should be able to pick the stuff it needs from the AGENTS.md, and not blindly use everything.
- barrkel 1y agoEverything the agent has to read to pick out stuff costs $.
- theshrike79 1y agoContext is not infinite. Saving context for what matters is key in working with LLMs.
- _ache_ 1y agoContext is not infinite yet. New standard for something that maybe false very soon is just a bad idea.
- theshrike79 1y agoWe 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 =)
- cyanydeez 1y agoI 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.
- awbraunstein 1y agoYou 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.
- bryanrasmussen 1y agoso 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 1y agoPretty 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"
- verdverm 1y agoCopilot 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`" Still lots of DX to do in this space
- thayne 1y agoKind of, but for any given directory you can't separate out instructions for building from instructions for naming conventions, for example.
- __alias 1y agoWith 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.
- lelele 1y agoCould you please provide an example `index.md`? Thanks.
- nivertech 1y agoThis 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 1y 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 1y agoClaude Code globs and greps files, while Sourcegraph Amp uses RAG. But yes, naive coding agents will fill the context with the entire large file.
- PriNova 1y agoFor the sake of clarity, Sourcegraph: Cody did RAG-style context fetching. However, Amp does not use RAG for context fetching.
- irthomasthomas 1y agoThis 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.
- xmorse 1y agoYou can put your docs in folders and reference them in AGENTS.md Or use urls in your main AGENTS like I do for https://gitchamber.com https://gitchamber.com
- deleted 1y ago[deleted]
- zimbatm 1y agoThis 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 1y agoThe 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.
- esafak 1y agoThey understand it just fine; they are acting selfishly, because it does not benefit them. Helping the coding agent does.
- zahlman 1y agoThey really might not understand it fully. That's very much in line with my understanding of how autism works.
- organsnyder 1y agoIt'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.
- Western0 1y agobot.md not index.md
- verdverm 1y agoThis 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
- deleted 1y ago[deleted]
- deleted 1y ago[deleted]