Maybe robot_docs?
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.
I've -> I have
& -> and
co. -> company
won't -> will not
it's -> it is
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
/media - new and reasonable.
/mnt - the whole metaphor of "mounting" is... debatable.https://www.neowin.net/forum/topic/144012-unix-sex/
/opt - what does this even do? Optional? Optional WHAT? Absolutely 0 semantic info provided by the name.
Anyway, a lot of people have done this criticism better than me and it's boring at this point.
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.
The baseline is English and that's life. I'm not a native English speaker.
/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 /home -> Users (it's not 1998 anymore)2. I don't want to fight extreme positions which I did not make. Read this:
https://gobolinux.org/at_a_glance.html
I didn't say paths have to have spaces, etc. Just be reasonable and <<use full words in the year of our lord 2025>>.
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.
/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.
set completion-ignore-case on
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.
Pause for what, coffee? How does this even make sense?
What could possibly be inside source/, if not the exact same thing as in src/?
$HOME/accept/the/fact/that/were/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/main.cSome 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.
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.
> Agents automatically read the nearest file in the directory tree, so the closest one takes precedence
I don't really care what's inside.
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.
# 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. YOU CAN DO IT, LLM SLOP BOT!
I BELIEVE IN YOU! NEVER GIVE UP!
YOU CAN SHIT OUT THE RIGHT TOKENS!
YOU CAN DO IT!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.
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.```As well as custom agents: https://docs.anthropic.com/en/docs/claude-code/sub-agents
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.
I guess I was one of the lucky 10000 :-)
I think all this agentic stuff could live quite happily in $REPO/.config/agents/.
You can just use the AGENTS.md file as an index pointing to other doc files.
This example does that -
Having an in-your-face file that links to a hidden file serves no purpose.
New standard for something that maybe false very soon is just a bad idea.
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 =)
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.
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"
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
``` // 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.
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.
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
But yes, naive coding agents will fill the context with the entire large file.
Or use urls in your main AGENTS like I do for https://gitchamber.com
The content of the AGENTS.md is the same as what humans are looking for when contributing to a project.
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.
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
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.
Also, you don’t even address their point.
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".