leaving the codebase cleaner than you found it IS creating maximum value to the company because large changes are almost never walking on the knife's edge between "making the codebase better" and "making the codebase worse". Your codebase either gets better over time, or it gets worse. If it's getting 0.01% worse with every PR, that tech debt accumulates at 1.0001*(# of PRs) which grows faster than you'd think.
Having a maintainable codebase is of MASSIVE LONG-TERM value to a company - far too many orgs are paralyzed by mountains of tech debt.
Doing the minimal work possible is fine for 1-off hotfixes or tweaks or small features, but your argument assumes "maximum value to the company" is measured in the span of of a sprint, and it's not.
Cleaning up the codebase incrementally does deliver value to the company as long as you understand "cleaning up" as "making it easier and faster to contribute to, change, or debug in the future" rather than something adjacent to a form of performance art.
This is an excellent point - LLMs are autoregressive next-token predictors, and output token quality is a function of input token quality
Consider that if the only code you get out of the autoregressive token prediction machine is slop, that this indicates more about the quality of your code than the quality of the autoregressive token prediction machine
If you find it works for you, then that’s great! This post is mostly from our learnings from getting it to solve hard problems in complex brownfield codebases where auto generation is almost never sufficient.
Yep it is opinionated for how to get coding agents to solve hard problems in complex brownfield codebases which is what we are focused on at humanlayer :)
I imagine it’s highly-correlated to parameter count, but the research is a few months old and frontier model architecture is pretty opaque so hard to draw too too many conclusions about newer models that aren’t in the study besides what I wrote in the post
Yes README.md should still be written for humans and isn’t going away anytime soon.
CLAUDE.md is a convention used by claude code, and AGENTS.md is used by other coding agents. Both are intended to be supplemental to the README and are deterministically injected into the agent’s context.
It’s a configuration point for the harness, it’s not intended to replace the README.
Some of the advice in here will undoubtedly age poorly as harnesses change and models improve, but some of the generic principles will stay the same - e.g. that you shouldn’t use an LLM to do a linter &formatter’s job, or that LLMs are stateless and need to be onboarded into the codebase, and having some deterministically-injected instructions to achieve that is useful instead of relying on the agent to non-deterministically derive all that info by reading config and package files
The post isn’t really intended to be super forward-looking as much as “here’s how to use this coding agent harness configuration point as best as we know how to right now”
tbh I think the thing that's making this new approach so hard to adopt for many people is the word "vibecoding"
Like yes vibecoding in the lovable-esque "give me an app that does XYZ" manner is obviously ridiculous and wrong, and will result in slop. Building any serious app based on "vibes" is stupid.
But if you're doing this right, you are not "coding" in any traditional sense of the word, and you are *definitely* not relying on vibes
In many cases (though not all) it's the same thing that makes for great engineering managers:
smart generalists with a lot of depth in maybe a couple of things (so they have an appreciation for depth and complexity) but a lot of breadth so they can effectively manage other specialists,
and having great technical communication skills - be able to communicate what you want done and how without over-specifying every detail, or under-specifying tasks in important ways.