Conversation
|
I've been trying to avoid adding AGENTS.md files so far because I wanted to create a good one and add it to the template. The thing is this is not happening, and agents are already doing a decent job in writing AGENTS.md files, so I guess it is better to have some OK now that something perfect and reusable never. |
Add condensed agent instructions in AGENTS.md with: - Quick reference for common commands - Project structure overview - Code style patterns with examples - Cookiecutter workflow summary Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
|
|
||
| ```sh | ||
| # Setup | ||
| pip install -e .[dev] # All dev dependencies |
There was a problem hiding this comment.
I would do that only when we switch the official docs and CI.
| pip install -e .[dev-noxfile] # Just noxfile deps | ||
|
|
||
| # Test | ||
| nox -s pytest_max # Full test suite |
There was a problem hiding this comment.
Or even uv run nox -s pytest_max without any pre-installation? I've seen claude use this a lot.
There was a problem hiding this comment.
Same. This should be in sync with the README, I don't think it would be a good idea to have diverging agents and readme files.
|
A few more thoughts: The file is aimed at AI agents, but most of this is generic Python/nox info that agents already know. The real value in AGENTS.md is project-specific quirks and decisions that aren't obvious from the code. Missing stuff that would actually help agents:
The code style section is fine but agents can infer most of that from existing code. What they can't infer is "why" decisions and gotchas. |
Without reading the readme, the agent doesn't know if you use poetry or pip or uv or whatever, so some guidance should remove ambiguity.
True.
It is there "Python package (3.11+) providing repository configuration and scaffolding for Frequenz projects: cookiecutter templates (actor, api, app, lib, model), nox sessions, protobuf/gRPC utilities, MkDocs and pytest utilities."
Not sure what do you have in mind, but yeah, might be worth adding, but these are also useful for humans. I tried to add most of the comprehensive instructions in docs for humans and keep the agents file as a quick cheat-sheet, and mention in the agents file to consult the full docs (readme and contributing files) for details. I don't think it makes sense to duplicate all the current docs in the agents file. I guess something else that's important in the agents file is that info is very condensed, to minimize the usage of the context window. Reading the whole readme and contributing might take too many tokens. In any case, this is just a first version, we can always improve it in the future. |
|
BTW, about commits I'm finding myself always having to give extra instructions for getting decent commit messages that are not super AI-weird. It might be worth having some common instructions we somehow copy&paste on every project's custom instructions. I guess we need to update #390 and continue there if we want to discuss big plans ™️ |
Add condensed agent instructions in AGENTS.md with: