Add agents.md - #6709
Conversation
| # Code Style | ||
|
|
||
| Our style guide forbids the use of emoji. | ||
| Make sure the code is simple and concise. |
There was a problem hiding this comment.
Without special instruction, I do not have a problem with these.
There was a problem hiding this comment.
I think this wouldn't hurt, but we can drop it
| # Specs | ||
|
|
||
| Be concise in writing specs so that they are easily human-readable in short amount of time and easily comprehensible. | ||
| Do not repeat yourself. |
There was a problem hiding this comment.
What do you mean with "Specs" here?
There was a problem hiding this comment.
The ones that it writes in planning mode mostly. We could drop it since it's related to my personal workflow, but it can become useful in case we want to submit those to the repo one day. This shouldn't hurt, but either way is fine.
| # Security | ||
|
|
||
| NEVER read .env files. They might include secrets. |
There was a problem hiding this comment.
We could enforce it in the setting instead, this tends to encourage it to read it instead. I have it enforced globally in my local setup.
There was a problem hiding this comment.
It would be helpful to include it in the repo so it never reads them for the devs who don't have it in their local setup. Do you mean adding settings here along with AGENTS.md? How does it look in your case?
| # Comments | ||
|
|
||
| Limit the amount of comments you put in the code to a strict minimum. | ||
| You should almost never add comments, except sometimes on non-trivial code, function definitions if the arguments aren't self-explanatory, and class definitions and their members. | ||
| Aim at the code being self-documented. | ||
| Do not remove existing comments unless they are directly related to what you are changing. | ||
| If you do write comments, be concise. | ||
| Do not add a comment explanation to every thing you were asked to correct. |
| # Docs | ||
|
|
||
| Double check if the docs should be updated in the `/docs` folder. | ||
| Make sure the docs you write are well-structured, concise and human-readable. | ||
| Link to the code where appropriate instead of repeating implementation details in the docs. | ||
| Follow the existing style. |
There was a problem hiding this comment.
This might be expensive to force it. I would leave it out.
There was a problem hiding this comment.
This was one of the main motivations to add AGENTS.md, as we want to make sure the docs are up to date so the agents should be aware of them. I think this will also help them understand the architecture faster without reading a lot of code, so it can become less expensive in the end.
| # Global | ||
|
|
||
| Do not overengineer for the use cases you were not asked to handle. |
There was a problem hiding this comment.
I do not see it a problem in my personal use.
There was a problem hiding this comment.
There were many complains on overengineerg by Opus 5 on the internet. I did feel it became worse in this regard, but it's very hard to measure.
2 participants
This is what I use locally + something else related to conversations that I didn't include here. Many of those have been in my settings for a while, but some specifically aim to reduce verbosity and overengineering by Opus 5. Open to feedback. @padenot @suhaibmujahid