stop making ai agents memorize your entire codebase.
people thought that throwing more markdowns file into the codebase and calling it SDD whatsoever will help. or installing some shitty memory plugins will.
trust me, I've been there...
every markdown you add is another potential source of stale truth.
want an agent-friendly codebase?
- shallow, feature-based modules
descriptive filenames
- comments explaining why, not what
- tests as executable specifications
- explicit, enforceable boundaries
- code search before vector search
your agent doesn’t need a better memory.
it needs a codebase that’s easier to understand, navigate, and verify.
sometimes the best context engineering is just good software engineering.
what a plot twist 😁
Some mistakes you might be making:
Your effort level is too high
Your skills are too long
You're not aligning before you start work
You're aligning too often, and too hard
Your automated checks are too lax
Your custom tooling is too token-inefficient
You aren't doing enough automated review
You aren't reviewing previous coding sessions (with an agent)
You're doing too much human review
You aren't vibe coding enough prototypes
Your agent can't verify its own work
You're babysitting the agent too much
You've overloaded your global steering files
Your codebase is hard to navigate
You aren't building a shared language
Your codebase architecture allows bad tests to be written
You aren't thinking strategically enough
You aren't thinking enough
This quote from Steve Jobs lives rent free in my head...
"People who are genuinely great at something don't compete. They don't care about being compared to others because they're so deep in their own lane that comparison would be a waste of time. They just do their thing."
1. Oh shit, AI can do my job better than me
2. Software engineering is dead!
3. I can vibe code as much slop as I want!
4. Oh, things are not going well. Fable/Sol/Opus all suuuck
5. But what if I constrain the agent? Put it in a straitjacket?
6. Oh, the results are pretty good now. How do I go deeper?
7. *Orders 12 software engineering books from Amazon*
8. Software engineering is alive!
I am surprised that people are surprised this is how I prompt Claude.
Talk to Claude the way you would a coworker. There's no secret to prompting. There's no need to be overly scaffolded or prescriptive for most tasks -- give Claude a goal, and it will figure it out.
Back in the Sonnet 3.5 days, your prompt mattered a lot. Nowadays, it's much more important to communicate to the model:
1. What you want it to do
2. How much effort you want it to spend
3. How it should verify that it did the right thing
I've published a new, general-purpose terminal specification that gives any program a way to tell the terminal what it's doing: idle, working, waiting, finished, or failed, and why. It is easy to implement on both sides. I've written more about why: https://t.co/2FfzNC3F8T
The problem this solves is generic and applies in compelling ways to all sorts of use cases (e.g. package managers, build tools), but it really rears a hideous head when it comes to AI and the "agentic inbox" problem.
I found over 250 different agent orchestrators (with various goals) that all individually implement a heuristic based approach to detecting whether things like Claude Code are working, blocked, done, etc.
If you look at @herdrdev's commit history, you can see around 10 compatibility changes to detect Claude Code within just the past 3 months. (This isn't a dig at Herdr! They're doing great work with what they have, and everyone else is doing the same thing).
Heuristics are not the way. And over-indexing on agentic use cases isn't the way, because this problem is really interesting for other tools too: Homebrew, Terraform, Cargo, etc. etc.
Proprietary protocols and out of band APIs are not the way. They have an O(N) integration problem and require extra work to work over SSH or within local VMs/containers.
The program status specification (OSC 7501) solves this in a reliable, deterministic way that is general-purpose and can be easily adopted by the entire industry.
Read more: https://t.co/2FfzNC3F8T
Say hello to Rexie, our mascot for Rex! Superlogical public testing is beginning. We’re working through our mailing list in the order people signed up. Initial testing is limited to macOS but that’ll expand quickly. Welcome, new testers. https://t.co/qNfJnhjnQn