AGENTS.md feedback

[JPadovano1483]

@ted-ross @fgiorgetti @pierpman I'm opening this discussion for ongoing feedback for the AGENTS.md files and overall agent output quality moving forward. Feel free to add any comments or questions about this in this discussion. Some topics that could be of value are:

1. where there seem to be gaps/things you need to keep explaining to agents or correcting them on,
2. agents pulling context unrelated to the task at hand,
3. excessive token usage
4. undesirable output (e.g. bad comments, over-complicated fixes, trying to "fix" code that is unrelated to the task, etc.)

Anything that stands out about agent output/workflows as undesirable or anything that you feel could be useful to add can be brought up here.

[pierpman]

Hi James, I had a look through the file and I think it is a great starting point. The development guidelines, constraints, and sources of truth sections are particularly useful.
One thing that may be worth making more explicit later is that agents should check the current implementation before suggesting changes, and avoid treating design ideas or assumptions as existing functionality.
I think it makes sense to use the guide for a while and evolve it based on the team’s experience and any recurring issues we notice.

[JPadovano1483]

Thanks Pier, I think those good suggestions. I will make note to look at adding those once we've spent a bit of time with the current implementation.

[pierpman]

I also noticed that the repository, along with the other Skupper repositories, is available through DeepWiki. It could be a useful secondary resource for agents to understand the architecture and find relevant files. Since the content is AI-generated, I am not sure how reliable or current it is, so it would need some review. It is probably not something we need now, just a thought for the future.

[JPadovano1483]

This is an interesting idea. As far as how current the content is, it looks like the last time the vms DeepWiki was indexed was three months ago (I just manually re-triggered a re-index, so it should be current now), but there is a way to have it auto-index the repo every week by adding a badge to the README. I agree though that the reliability would need to be vetted. I am curious to see how efficiently is can pull relevant context or if it will just flood the agent window with unnecessary context. It looks like its easy to set up the DeepWiki MCP server though, so I think it could be worth playing around with at some point and seeing if it helps/hurts.

[Trevor2Maxwell]

I find that generally when I set up and agent file the first promt I send or even the first 3 are inline with what I outlined.

However I find very quickly the agent making mistakes that I explained how to do in great detail in the agent file.
I think this is caused by compression and if that is the case I dont think agent files should ever get compressed.

Has anyone found a way to exclude agent md files from conversation compression?