-
Notifications
You must be signed in to change notification settings - Fork 351
Add agents.md #6709
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: master
Are you sure you want to change the base?
Add agents.md #6709
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,33 @@ | ||
| # Global | ||
|
|
||
| Do not overengineer for the use cases you were not asked to handle. | ||
|
|
||
| # 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. | ||
|
Comment on lines
+5
to
+10
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This might be expensive to force it. I would leave it out.
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. |
||
|
|
||
| # 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. | ||
|
Comment on lines
+12
to
+19
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Nice! |
||
|
|
||
| # Code Style | ||
|
|
||
| Our style guide forbids the use of emoji. | ||
| Make sure the code is simple and concise. | ||
|
Comment on lines
+21
to
+24
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Without special instruction, I do not have a problem with these.
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. | ||
|
Comment on lines
+26
to
+29
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. What do you mean with "Specs" here?
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. | ||
|
Comment on lines
+31
to
+33
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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.
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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? |
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| AGENTS.md |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I do not see it a problem in my personal use.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I often see that, but mostly on Gecko.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We now see anecdotes about that in ai4dev, not only on the internet, so I would keep it. I've been working with this in my local settings for a while.