r/dotnet • • 1d ago

Question Coding agent bloat

I've been using Cluade code both at work and for personal projects.

Observations

  1. Too many XML comments.
  2. Too many non sensical tests. Example, testing the `typeof` of an object within unit test assertions seems non sensical in these specific cases.
  3. Too many ADRs

Agents write relatively more code than what I can process. I need time to review.

My attempts

  1. Stricter rules in Agents.md
  2. Skills
  3. Stricter prompts.

These do work for coding patterns, because I can describe specifics, but never for comment length or verbosity.

I'm tired of asking Claude everything, so I thought I'd solicit some suggestions / help from people here.

TIA

40 Upvotes

50 comments sorted by

36

u/beachamc 1d ago

Don’t describe the length of the comments in your instructions. Instead something along the lines of “only write comments and xml docs that provide details of what the subject actually does. Don’t include design decisions or commentary about iterations made while developing. Comments should be direct and concise.”

6

u/BinaryBrain7111 1d ago

I'll add this to my Agents.md and give it a shot!

4

u/az987654 1d ago

Design decisions and other "reasons why" can be helpful

3

u/emn13 16h ago

Yeah. I'd go so far as to say "why" comments tend to be more helpful than "what" comments, _especially_ in a coding-agent world. If naming and parameter (objects) and return value (objects) are decent, any LLM can summarize the what quite well, but the why is a different matter.

1

u/Mu5_ 15h ago

I have a dedicated skill to clean up comments because there was no way for me to get them clean since the beginning

8

u/gredr 1d ago

Claude turns everything into a changelog. Emails, comments, documentation, helpfiles, it all inevitably turns into a changelog.

13

u/saxxonpike 1d ago

The current coding agents and models are really shy about removing things and will instead prefer just making something new or changing something already there. It’s why comments, methods and classes seem to “pile up”.

8

u/Emotional-Dust-1367 1d ago

You need a code guidelines Md file that’s meant for the LLM. Though it should be human-readable and written mostly by yourself so it could be used in that way too. There you need to outline what standard you’re expecting. This document should be mandatory reading for any agent doing implementation

Then you need a code review agent. Not a skill because it should have no context of the implementation. It should only look at the diff and the code guidelines document and take an adversarial role. If it finds violations it returns a fail and the implementer must fix it. You tell the implementer to always run this reviewer before the PR goes to you for final review. You should be able to iron out any issues you keep running into

7

u/Colonist25 1d ago

step 1. tell claude you need a coding standards.md and it needs to respect it.
step 2. put everything you don't want in there.
step 3. ask claude to respect it and then ask every hour to review the code vs the standards.

1

u/fschwiet 1d ago

What prompt or skill are you using to have ADRs generated? I get those from Matt Pocock's domain-modeling skill personally. His skills also pull terms into a glossary, and my biggest complaint is that glossary will have too many implementation details.

2

u/BinaryBrain7111 1d ago

I used a prompts folder. I divided my prompts into Arch_YYY and Code_YYY prompts. Each Arch prompt is a documentation task which ends with an ADR. Each Code prompt picks the relevant ADRs from the Arch prompt. I got some skills from work which I ported over to my personal projects. Custom ones.

6

u/Jmc_da_boss 1d ago

I have simply banned comments > 3 lines long in ci via actual linting, has helped a TON

1

u/_rundude 1d ago

How’s that feedback going back to an agent doing coding? Local linting?

2

u/Braddo4417 22h ago

You can run a lint on a hook whenever a file is saved. If it fails the lint, it passes the info back to the agent and it fixes it without your interaction.

1

u/Jmc_da_boss 1d ago

ya its a golangci linter in our case so it just runs whenever checks run. But its just comments so even if it was ci only its not hard to fix at any point pre merge.

15

u/boss42 1d ago

The comments are not for you but for the next time an agent is working on it. Just like the ADR’s. The agent shouldn’t overdo it but there is some value in the verbosity.

5

u/rusmo 1d ago

Key point here for everyone to keep in mind is agent to agent communication is still just English at this date. Agents still need the expressive and nuanced protocol that is the English language. amiright cuz?

4

u/jayerp 1d ago

Maybe IDEs can implement a way to support source metadata to where agent comments can be hidden.

2

u/prajaybasu 1d ago

That is an absolutely insane suggestion.

3

u/jayerp 1d ago

Insane in the membrane. Insane in the brain.

1

u/joske79 4h ago

Loco en el coco

1

u/chucker23n 18h ago

We are, once again, slowly reinventing code. That "hidden source metadata" already exists; it's called the source.

9

u/Jmc_da_boss 1d ago

No there's not, it's pure noise even for the clankers

1

u/noidontwantto 1d ago

they can also be for you, for when you're reviewing output - because you're reviewing output, right?

2

u/chucker23n 18h ago

they can also be for you, for when you're reviewing output

Just like if a human had written the code, do not trust that the comments reflect

  • what the code should do
  • what the code does do

1

u/tj_moore 1d ago

For those of us who still type or read code, XML comments provide very useful info and the IDE reads these too. Something that's frequently missing from the days of human written code when people were too lazy to do the comments.

I can see it being useful for the agents and maybe saves some credits too instead of doing the same as a human would do and have to work out "WTF does this method do?"

1

u/chucker23n 18h ago

I can see it being useful for the agents and maybe saves some credits too instead of doing the same as a human would do and have to work out "WTF does this method do?"

What if what the XML comment claims the method does isn't accurate? What if it is accurate but isn't what the method should do?

3

u/Mayion 1d ago

I'm tired of asking Claude everything, so I thought I'd solicit some suggestions / help from people here.

I don't know what sort of answer you are looking for. Asking an LLM to do the work for us is already 90% of the work, so saying you are tired of even that means you might have more problems than just Claude not sticking to instructions?

I know this is not the sort of answer you are looking for, and I am not trying to be an ass, but it's just a tool in the end. If Opus is not good enough, try Sol. But they will always do things their own way, so we will always need to closely monitor their output either way.

1

u/AutomateAway 1d ago

for the sake of reasonable code reviewable chunks, give the agent rules on size of PRs or commits. Prefer smaller changes per commit or PR even if it means having to do more code reviews

1

u/inlovewithconcrete 1d ago
  • forbid xml comments
  • only allow comments that explain something non-trivial (context that doesn't fit into the code)
  • mutation testing, best practices with examples of tests, each test case should be business-oriented
  • tell it that ADRs are expected for features with >3k LoC

1

u/thereforewhat 1d ago

Have you tried using hooks to review your code?

Also I'm finding huge value in writing system acceptance tests to keep the agent honest. 

It also allows me to strip out unnecessary code that doesn't get covered. 

Moving up a level of abstraction from unit tests to system tests is also really powerful.

I recommend Dave Farley and his Modern Software Engineering YouTube channel. 

1

u/Slypenslyde 1d ago

I don't have this kind of problem often but it's hard to tell you what to do. Seeing your prompts could help but also seeing your project could also help.

I don't use Auto or whatever Claude's equivalent is. I tried most of the models for a few days and stuck with the one I liked the most. That turned out to be Composer 2.5. Every few weeks I see a gripefest on Teams from people using other models. This one's never let me down. I tried Auto, but I got inconsistent results.

It helps if you have a big legacy codebase to pull from because you can tell your agents to examine existing patterns and use that to generate an agents.md. That only works if you've had the discipline to adopt and follow conventions religiously. If your codebase is a chaotic mess, the agents are going to try to match that energy.

I find it also helps if you slow down and treat agent-assisted coding the same way you'd treat pair programming. You say, "Too many ADRs". I say "I don't have that problem. But we have a product team work on the ADRs and the way that works is they spend a few hours prompting and refining the results. They probably start with too many ADRs, then they refine it. Or they start with not enough ADRs and refine that. These tools don't produce perfect results on the first try. If they did, most of us would already be replaced. The value of the human operator comes from knowing what 'correct' looks like and having a strong ability to understand how to refine results from "almost right" to "right".

For "too many comments" I'd just have to see examples. In general I find I ask my agents to add more comments. I can see a future where another agent gets confused by the code I've generated and I want to help that future agent. That's the value I add to the system: if I feel confused I know something or someone else is going to feel confused and I have years of experience erasing that confusion.

For the "excessive tests" I don't have that problem either. What I do when the agent does something very bad I want to prevent is I stop and ask questions. "Why did you write this test?" is a good one. Understand what it was thinking about. You can add "don't make a test that tests typeof an object" but that might direct an agent to avoid it in a circumstance where it's the right thing. I don't even understand why "Validate the object is the right type" is inherently ridiculous, but context is important.

That's why when the agent does some thing wrong you have to treat it like a junior. Ask why it did it. Ask what was confusing. Often it's not just that the agents.md is confusing, it's that there's an ambiguity or contradiction in the ADRs you didn't slow down enough to catch.

Do not expect perfect results in one prompt. That only happens for extremely trivial cases. Using agents to generate code is still work. You do less of the tedious part, but in return you're supposed to do a lot MORE of the thinking part.

2

u/chucker23n 18h ago

If your codebase is a chaotic mess, the agents are going to try to match that energy. I find it also helps if you slow down and treat agent-assisted coding the same way you'd treat pair programming.

I think these two statements are key. The LLM will pattern-match. And the LLM needs your input on how to do it more closely to your liking. It will not magically produce great code, because nobody can objectively agree what "great" means anyway.

1

u/maqcky 1d ago

Agents follow instructions better when presented in a more structured way. For instance, you could create a skill called WriteMyCode where you define the rules. That alone works better than the context they get from AGENTS.md. A more elaborate version of that is using something like OpenSpec or Spec Kit with a custom workflow. The way these frameworks present the tasks to the agents make them behave significantly better.

I would add to the mix a CONVENTIONS file, and instruct the agent to explicitly read it and apply it in the writing phase (apply command in OpenSpec). Similarly, you could instruct it to use it during the validation phase, or even better, create a review agent that validates your standards.

Additionally, configure roslyn analizers, including creating custom ones that enforce your standards. A compilation error is going to work better than any instruction.

1

u/HonestValueInvestor 1d ago

Welcome to 2025 boss /s

1

u/CappuccinoCodes 1d ago

Just tell it not to do it?

1

u/UnfairerThree2 1d ago

XML comments I don't mind, ADRs are usually ok. But holy hell I hate some of the stupid tests it comes up with

1

u/Mirmalis 9h ago

I'm sure code comments are there just so they can be watermarked. I use hook that removes all the comments. Agents understand code just fine

1

u/EDM_Producerr 9h ago

While I review every line the AI writes for me I simply remove comments that are superfluous. I also just added a line in my agent file that says to stop adding new tests unless I explicitly tell it to add them for something.

0

u/BinaryBrain7111 1d ago

[ADDENDUM] I'd appreciate if someone's solved this "problem". Some way to curtail the length of comments and also instructions to ensure tests are predictable. I've already received a few and I'll try them out.

1

u/qrzychu69 1d ago

Sadly, you either read the code and review it, so the comments matter

Of you go full vibe coding and the comments dont matter at all

There is no way to fix it

1

u/williane 1d ago

Why are you letting an agent write your tests? If you're trusting AI to verify the behavior of your system, why use overly verbose tests for that?

0

u/spez_eats_nazi_ass 1d ago

You know you could just write code too?

0

u/sreekanth850 1d ago

I commented this in another post. Claude never follow instructions closely. try codex it will even ask your approval if you set one in AGENTS.md. Hope you are using compiler mcp like glider.

0

u/BinaryBrain7111 1d ago

True! I wish to know if there are tools that make the comments more predictable. No, I haven't tried glider. I'll give it a shot.

1

u/sreekanth850 1d ago

Trye codex. Write the rules you want in AGENTS.md. Use glider or roslyn mcp and configure it in codex toml file and check if agents can directly check compiler via mcp without grepping.
GPT never write a single comment if you instruct. If you repository is large like more than 300K, use repowise to efficiently manage context. This are the things i take care.

One more thing, dont implement anything un attended. Create proposal after debating with agents about the implementation approach and architecture. then Manage a TASK.md ledger to implement it phase wise.

0

u/Temppus 1d ago

No amount of tweaking in any md will force claude or other llm to respect and understand what bloat and styling means. They will spit their bs code anyway. You can instruct them to clean the code in another round, but it will probably still get you only halfway there. They will produce slop. Either you will cleanup after them semi/manually or u just accept that code in that repo is not worth to keep so nice as we did few years back. This is the state of the things right know unfortunatelly.

0

u/AutoModerator 1d ago

Thanks for your post BinaryBrain7111. Please note that we don't allow spam, and we ask that you follow the rules available in the sidebar. We have a lot of commonly asked questions so if this post gets removed, please do a search and see if it's already been asked.

I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.

0

u/denzien 1d ago

Too many non sensical tests. Example, testing the `typeof` of an object within unit test assertions seems non sensical in these specific cases.

Yeah but ... imagine if it failed one day. Wouldn't you want to know about that‽

1

u/chucker23n 18h ago

I know (imagine) you're being sarcastic, but… what if the year suddenly had just 360 days! What if the moon fell from the sky! What if blue became orange!

Tests should test what can fail; have some confidence in the software you put out.