Comment by CharlesW

That's just an argument for having a more distinctive name.

Another reason to use a src/ directory for the actual source code.

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.

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.

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.

If it isn’t being read by humans, then it shouldn’t be written by them either.

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.

They understand it just fine; they are acting selfishly, because it does not benefit them. Helping the coding agent does.

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

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.

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.

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"

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.

I 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.

.config is a good name, and has a small following

https://dot-config.github.io

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/.

I'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/

Claude supports slash commands, this might be better for you: https://docs.anthropic.com/en/docs/claude-code/slash-command...

As well as custom agents: https://docs.anthropic.com/en/docs/claude-code/sub-agents

There’s also [.claude/agents/](https://docs.anthropic.com/en/docs/claude-code/sub-agents), which doesn’t contain docs for agents but separate sub-agent definitions.

So just the remaining 80%

Context is not infinite yet.

New standard for something that maybe false very soon is just a bad idea.