tools: add first draft of AGENTS.md (tested with Gemini, edited by Claude, and Codex)

[spytheman]

No description provided.

[spytheman]

I think it works well enough as a first draft. codex works well with it, following the instructions to use v -o ./vnew cmd/v and then only the new compiler for checking stuff, and already managed to fix 2 bugs today with that workflow, without significant intervention or too verbose prompts.

See #26505 and #26508 .

[spytheman]

@medvednikov what do you think?

[fleximus]

Great job. I'd also add that it should generally avoid the unsafe keyword and give proper guidance when it's okay to be used.

[enghitalo]

Seems great. Let's see how it behaves and perhaps in the future it will be interesting to include information about cstrict, file naming (.c.v, .js.v, _linux.v, etc, compile-time code (IA still making mistakes about it 😓)

[medvednikov]

LGTM

[hungrybluedev]

Good start. Let's keep an eye on how it performs as it goes beyond compiler tasks.

[spytheman]

Related paper: https://arxiv.org/abs/2601.20404

On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents
Jai Lal Lulla, Seyedmoein Mohsenimofidi, Matthias Galster, Jie M. Zhang, Sebastian Baltes, Christoph Treude
AI coding agents such as Codex and Claude Code are increasingly used to autonomously contribute to software repositories. However, little is known about how repository-level configuration artifacts affect operational efficiency of the agents. In this paper, we study the impact of AGENTS md files on the runtime and token consumption of AI coding agents operating on GitHub pull requests. We analyze 10 repositories and 124 pull requests, executing agents under two conditions: with and without an AGENTS md file. We measure wall-clock execution time and token usage during agent execution. Our results show that the presence of AGENTS md is associated with a lower median runtime (delta 28.64%) and reduced output token consumption (delta 16.58%), while maintaining a comparable task completion behavior. Based on these results, we discuss immediate implications for the configuration and deployment of AI coding agents in practice, and outline a broader research agenda on the role of repository-level instructions in shaping the behavior, efficiency, and integration of AI coding agents in software development workflows.

[JalonSolov]

Just hit this one... need a rule to tell the agent to put all v command line options between v and the rest of the command. Otherwise, it does what it just did to me...

v test vlib/<a module> -count 1

Which fails... will also help with v run, when the V options have to come between the v and the run, etc.

I wish V had always enforced this, but... we are where we are.

[kbkpbot]

### Compiler Development
Backup working V binary: `cp v v_ok` first.
When fixing V compiler bugs, use the existing v_ok binary to avoid rebuilding:
```bash
# Copy v_ok to v, then rebuild with debug symbols
cp v_ok v && v self -g

This avoids rebuilding the old compiler from scratch each time.

[JalonSolov]

The current rules say to build vnew and use it for everything after that. No need to copy the current v to v_ok then copy it back.

[kbkpbot]

The current rules say to build vnew and use it for everything after that. No need to copy the current v to v_ok then copy it back.

I think some apps may hardcoded os.execute("v ...") in their code