docs(repo): add contributor orientation guides#652
Conversation
Add subsystem READMEs, architecture and setup docs, glossary, code map, and a feature brief template. Update agent and editor guidance to use pnpm commands and avoid implicit git mutations during push checks.
| @@ -0,0 +1,47 @@ | |||
| # Backend | |||
There was a problem hiding this comment.
If this is for agents, why is it in the README.md and not in AGENTS.md?
On the other hand:
I'm not a big fan of listing files and directories in markdown files, because it often confuses the agent when stuff changes and document goes stale. And even if it stays up to date, it would often hallucinate something because it would rely on the docs instead of checking the actual code.
In my experience with Claude, Codex, and Kimi, no amount of asking to keep docs up to date reliably keeps them up to date.
The code itself + per-folder AGENTS.md when necessary works pretty good for me. Some additional tools that would index the code and search for it more quickly also help:
- https://github.com/dmtrKovalenko/fff
- https://github.com/glommer/memelord
- https://github.com/tobi/qmd
- There's lots of them...
| @@ -0,0 +1,129 @@ | |||
| # Code map | |||
There was a problem hiding this comment.
Same comment here: I'm very reluctant to duplicating stuff that's already clear from the file-system layout into markdown files.
This file in particular looks very overwhelming. I can't see how this could help us save tokens or drive the agent better. I wouldn't be surprised if it was actually harming — causing the agent to read unnecessary files, and blowing up the context window with irrelevant information.
Summary
pnpm, web, and repo workflow guidance.Breaking Changes
None.