0xblacklight

https://blacklight.sh

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.

every PR should leave the codebase cleaner than it found it

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

Same!

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.

I looked when I wrote the post but the paper hasn’t been revisited with newer models :/

It might support AGENTS.md, you could check the site and see if it’s there

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 think you’re missing that CLAUDE.md is deterministically injected into the model’s context window

This means that instead of behaving like a file the LLM reads, it effectively lets you customize the model’s prompt

I also didn’t write that you have to “prompt it just the right way”, I think you’re missing the point entirely

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

Hi, post author here :)

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”

Hi, post author here

We used cloudflare’s AI gateway which is pretty simple. Set one up, get the proxy URL and set it through the env var, very plug-and-play

Hi, post author here :)

I didn’t dive into that because in a lot of cases it’s not necessary and I wanted to keep the post short, but for large monorepos it’s a good idea

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

Maybe we need a new word

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.

Among other things; coding agents that can get feedback by running a compile step on top of the linter will tend to produce better output.

Also, strongly-typed languages tend to catch more issues through the language server which the agent can touch through LSP.

if nuclear power is so much better than coal, why do we need to learn how to safely operate a reactor just to make it work? Coal is so much easier

how does this solve it?

Context has never been the bottleneck for me. AI just stops working when I reach certain things that AI doesn't know how to do.

It's context all the way down. That just means you need to find and give it the context to enable it to figure out how to do the thing. Docs, manuals, whatever. Same stuff that you would use to enable a human that doesn't know how to do it to figure out how.

Thanks! This isn't the first time we've gotten this question. We are about to release under a source-available license with a paid self-hosting license, and a commitment to open-source under MIT if we sunset the project or the company.

Would love to learn more about your use-case! Feel free to jump into our discord, we have a channel for it: https://discord.gg/eQWf5NGj6Y

This is a project we built internally for ourselves at Naptha.ai and wanted to release to the public, it's not really part of our core business. We're about to release it under a source-available license with provisions for a purchasable license to self-host, and a commitment to re-publish it under an MIT license if we sunset the product or the company winds down.

Do you think that would adequately address your concerns?

OAuth is a pain. Anyone who’s built integrations with Slack, GitHub, or Discord knows how tedious and error-prone setting up auth flows, refreshing tokens, and securely storing credentials can be.

We built a platform that handles all of this so you don’t have to.

You get:

- A single API to initiate OAuth flows and get fresh access tokens - Bring-your-own credentials, so it's fully white-labeled - Token encryption before it even hits our system (we can't decrypt them) - No vendor lock-in, you still use each provider’s native API - Works with Slack, GitHub, Google, Discord, Notion, and others

Live demo: https://www.producthunt.com/products/onedollaroauth-com?laun...

Would love your feedback!