Add AGENTS.md for AI assisted coding #1257
Conversation
There was a problem hiding this comment.
Hello! Sorry for the delay, we've all been on a conference. This is (perhaps?) a good idea, but needs some major cleanup. I also must say, I've been using Claude for a few months now, and I never had to tell it such trivialities. Out of interest, what are you using?
The things I'm usually telling it are about avoiding DRY, compressing and refactoring excessively verbose code, or completely useless error handling. But that's mostly "just" shortcomings of current versions, and hopefully they'll get a bit better at this over time. What's your experience there? Do you work on an actual starter-kit based project?
Thanks!
|
|
||
| ## Project Structure | ||
|
|
||
| - **Upstream Website**: [Cockpit Project](https://cockpit-project.org/) |
There was a problem hiding this comment.
This is somewhat true, but not specific for the forked project. It's also not useful for AI agents.
| ## Project Structure | ||
|
|
||
| - **Upstream Website**: [Cockpit Project](https://cockpit-project.org/) | ||
| - **Upstream Code Repository**: [Cockpit Project Git](https://github.com/cockpit-project/) |
There was a problem hiding this comment.
This doesn't belong here, but into README. Also, a forked project usually does not live under the cockpit-project org.
|
|
||
| - **Upstream Website**: [Cockpit Project](https://cockpit-project.org/) | ||
| - **Upstream Code Repository**: [Cockpit Project Git](https://github.com/cockpit-project/) | ||
| - **Upstream Starter Kit**: [starter-kit](https://github.com/cockpit-project/starter-kit) |
There was a problem hiding this comment.
Again, README and wrong for a forked project.
| - **Upstream Website**: [Cockpit Project](https://cockpit-project.org/) | ||
| - **Upstream Code Repository**: [Cockpit Project Git](https://github.com/cockpit-project/) | ||
| - **Upstream Starter Kit**: [starter-kit](https://github.com/cockpit-project/starter-kit) | ||
| - **Language**: [TypeScript](https://www.typescriptlang.org/) |
There was a problem hiding this comment.
Redundant. If an AI cannot figure this out by themselves, they are really not worth having. (The current ones like Cursor or Claude have no problem with this).
| - **Upstream Code Repository**: [Cockpit Project Git](https://github.com/cockpit-project/) | ||
| - **Upstream Starter Kit**: [starter-kit](https://github.com/cockpit-project/starter-kit) | ||
| - **Language**: [TypeScript](https://www.typescriptlang.org/) | ||
| - **Design System**: [Patternfly](https://www.patternfly.org) |
There was a problem hiding this comment.
Might be different for some forked projects. This is an useful link, but better belongs into README.md for human devs.
| - Source code is under src, the application is under dist after build. | ||
| - Use 2 spaces for indentation. |
There was a problem hiding this comment.
Meh -- again, if that's the kind of info you have to teach your AI, then it's not worth its salt.
|
|
||
| - Source code is under src, the application is under dist after build. | ||
| - Use 2 spaces for indentation. | ||
| - Interface names should be prefixed with `I` (e.g., `IUserService`). |
There was a problem hiding this comment.
We don't do this in the cockpit.js API nor our projects like cockpit-machines. Individual projects can choose differently of course, but this doesn't seem helpful in s-k.
|
|
||
| ## Regarding Dependencies | ||
|
|
||
| - Dependencies include the packages: nodejs, npm, git, cockpit, make. |
There was a problem hiding this comment.
I don't find this useful -- what would AIs do with that information?
| - Avoid introducing new external dependencies unless absolutely necessary. | ||
| - If a new dependency is required, state the reason. |
There was a problem hiding this comment.
Common sense, not project specific.
|
|
||
| On openSUSE: | ||
|
|
||
| sudo zypper in gettext-runtime nodejs22 npm22 make |
There was a problem hiding this comment.
That is useful, but please (1) split into a separate commit, and (2) find a way to not hardcode the nodejs version. As you don't specify the opensuse version, it's probably already not true for some releases, and will also get quickly out of date.
|
Many thanks for your response. I'm happy to adjust but before I go into the details (and I'm sorry for the long comment), let's clarify a few things, should have done that initially ;-) I started to write this AGENTS.md after I saw someone vibe coding and without starter-kit (s-k). This resulted in functional applications but so far away from the standards that we wouldn't want to integrate these. I tried to prove using s-k and vibe coding that it's basically possible to stick to the standards but found results poor. E.g. it used no React or components that didn't show, it broke the CSS. I tried in particular google-code-assist with Pro and Flash models, Amazon Q with Claude Sonnet 4 was much better. So I added to the AGENTS file and started coding from scratch to the point where it felt right and produced something which looks like the existing applications. Finally I added a few more bits to make sure everything is covered. Some info is in fact redundant but it even allows to only copy that AGENTS.md file and have the coding agent clone the repo, resolve the dependencies and prepare everything. Since it's a new concept, I read https://agents.md/ and other sources but concluded that ideally the AGENTS file contains everything the AI needs to know and in a readable format. If it requires the README in addition and the agent is supposed to use it, then what's the point, we could stay with the README. This to explain why there is redundant information. About trivial information which the assistants should figure out themselves, I found it strongly depends on the model and quality, we should not assume they are super clever. The opposite, they are basically a trainee developer and what's obvious for a professional isn't obvious for them. If it's a weaker model then it ultimately needs the context, if it's average it will benefit, if it's already very good then the additional context wouldn't hurt. Again, happy to adjust but I would prefer to include more info, not less and therefore make this independent from what tools the users may utilize. Looking forward to your view and if the above explanations make a change for you. Thanks! |
2 participants
Tested with Claude and Google-code-assist. Wouldn't do any harm but improves AI code suggestions a lot.