Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions AGENTS.md
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.
Comment on lines +1 to +3

Copy link
Copy Markdown
Member

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.

Copy link
Copy Markdown
Contributor Author

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.

Copy link
Copy Markdown
Contributor

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.

Copy link
Copy Markdown
Contributor Author

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.


# 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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This might be expensive to force it. I would leave it out.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The 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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The 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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Without special instruction, I do not have a problem with these.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The 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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you mean with "Specs" here?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The 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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The 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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The 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?

1 change: 1 addition & 0 deletions CLAUDE.md