Everyone suggesting maintaining an agent.md file haven’t met the majority of their coworkers who refuse to document anything or read documentation. Perhaps train a model that can generate these agent files for them?

▲

theshrike79 a day ago | parent | next [-]

IMO the best possible outcome of this AI hype is better documentation.

It's proven that (agentic) LLMs work better and more efficiently when they have the proper context for the project (AGENT(S).md), the documentation is accessible and up to date (docs/ directory with proper up to date markdown) and the tooling is smooth (git hooks that prevent secrets from being pushed, forced style checking and linting).

...surprise! All of this makes things easier for actual humans too!

▲

righthand a day ago | parent [-]

I think we’ll just get more documentation not better documentation. There never was a problem generating documentation from code. It’s the business context and use case documentation that’s hard to generate.

▲

alain94040 a day ago | parent [-]

There never was a problem generating documentation from code

That doesn't match my experience at all. Before AI, generating documentation from code was either getting some embedded comments for a function call, or just list a function's arguments.

AI reads the implementation, reads the callers and callees, and provides much smarter documentation, with context. Something sorely lacking from previous solutions. Is it sometimes not completely accurate? Probably. But still a giant step forward.

	▲	righthand a day ago \| parent [-]
		I think it depends on how good your documentation generator was before. Finding all the callers and callees is not a new idea to LLMs.

▲

codazoda a day ago | parent | prev | next [-]

Don’t most of these tools create them for you? Just run “/init” and the AI makes the initial agents.md file.

Dunno how helpful that is, but they shouldn’t have to write it from scratch.

	▲	a day ago \| parent \| next [-]
		[deleted]
	▲	a day ago \| parent \| prev [-]
		[deleted]

▲

eagerpace a day ago | parent | prev [-]

I love maintaining my agent file. Yeah, it doesn’t always listen to the instructions, but neither does anyone else.

	▲	hopelite a day ago \| parent [-]
		You are touching on a critical point that I have been amused by at times in these types of conversations; people are hating on AI for doing all the things that people have done and still do. Poor planning, check. No/inadequate documentation, check. Sloppy and janky code, check. Poor practices and methods, check. Poor and miscommunication, check. Poor technical choices, check. What am I missing? Maybe this is just a matter of some of the top tier 100x devs and teams clutching pearls in disgust at having to look at what goes on below Mt Olympus, but this is also not any different to how code quality cratered and is still really poor due to all the outsourcing and H-1B (sorry, all you H-1B hopefuls) insourcing of quantity over quality. I say that without any judgement, but reality simply is that this issue has long been a quantity over quality argument even before AI, and mostly for non-dev reasons as the recent de-qualification of R&D funding revealed and had a marked impact on dev jobs because the C-suite could don't use R&D funding for financial shenanigans. If people want to hate AI, go ahead. People hated and hate on the H-1B abuses and they hate on AI now. I would hope that we can just move beyond griping and mean-girling AI, and get to a point where proper practices and methods are developed to maybe make the outcomes and outputs better. Because again, AI is not going anywhere less than even H-1B and I am sure the C-suite will find some new way to abuse and play financial shenanigans, but it's simply not going away and we need to learn to live with it since it will seemingly only get "better" and faster as it changes at breakneck speeds.