Designing projects for AI agents

I’ve been thinking about this question: how do I structure a project so AI agents can actually work on it effectively?

A conversation between Peter Steinberger (OpenClaw creator) and Lex Fridman helped crystallize some ideas. Here’s what stood out.

The “agentic trap”

Peter calls it the agentic trap: when you try to force a feature through rather than stepping back and letting the agent find its own path.

The trap looks like this:

You have a specific implementation in mind
The agent keeps going a different direction
You keep correcting it, fighting the approach
Frustration builds on both sides

The escape? Don’t fight the names they pick. Don’t fight the architecture they gravitate toward. If the agent consistently wants to structure something a certain way, that’s often a signal that the existing codebase is guiding it there.

Empathy toward the agent

This sounds strange, but Peter emphasizes being empathetic toward the AI. Not because it has feelings, but because empathy helps you debug communication failures.

When the agent does something unexpected, ask:

What did it see in my prompt that led here?
What context was it missing?
How could I have set up the codebase to make this clearer?

This reframe shifts blame from “the AI is dumb” to “I didn’t communicate well enough.” More productive, and usually more accurate.

Don’t read the boring code

“I don’t read all the code. I don’t read the boring parts of code.”

Most software is data moving from one shape to another. It comes in, transforms, stores, retrieves, displays. The agent handles the boring parts. Your job is to:

Review the interesting parts (business logic, edge cases, security)
Trust the boilerplate. If tests pass, the glue code is probably fine
Use diffs, not full file reads. Focus on what changed

This requires letting go. But it’s the only way to scale your attention across a larger codebase.

Structure for agent success

Based on these ideas, here’s what makes a project agent-friendly:

Clear conventions. Consistent file naming. Predictable folder structure. Standard patterns that repeat.

Good documentation at decision points. README files in complex directories. Comments explaining why, not just what. Architecture decision records.

Fast feedback loops. Quick test suites. CI that runs in minutes. Linting that catches issues immediately.

Small, focused files. Agents work better with bounded context. One concept per file when possible. Avoid mega-files that exceed context windows.

Explicit over implicit. Reduce magic and metaprogramming. Prefer verbose but clear over clever but obscure. Type hints and schemas everywhere.

The new workflow

Peter’s workflow evolved to:

Multiple terminal windows running agents in parallel
Very rare IDE use (mostly just for diff viewing)
Seven API subscriptions running at peak usage
“All CLI, all terminal”

The IDE becomes a viewer, not an editor. The terminal becomes the cockpit. The agent becomes the hands on the keyboard.

It’s okay to mourn the craft

In another conversation, Peter gets more personal about what this shift means:

“I read this article about someone saying it’s okay to mourn our craft, and a part of me very strongly resonates with that. In my past, I spent a lot of time tinkering, being really deep in the flow, cranking out code, finding really beautiful solutions… It’s sad because that will go away.”

He compares it to knitting — eventually, writing code by hand might be something people do because they love it, not because it’s the most practical way to build software.

But here’s the reframe that matters:

“I don’t think you’re just a programmer. That’s a very limiting view of your craft. You are still a builder.”

Programming was always a means to an end: building things. The act of typing code was never the point. The architecture, the product decisions, the feel of the thing you’re making — those remain yours.

And there’s this: programmers are uniquely positioned for this moment. They understand how to communicate with machines. They know how to structure problems. They can “feel the CLI,” as Peter puts it. The skill translates; it just expresses differently.

“You’ll still be a programmer. It’s just the activity of a programmer is different.”

I find that reassuring. Not because the change is comfortable — it isn’t. But because there’s still a place for people who understand how to build things. The demand doesn’t go away; it shifts.

And yet, while I don’t write every line of code anymore, I very much feel like I’m in the driver’s seat. The work is different, but it’s still work I recognize.

Takeaways

Avoid the agentic trap. Don’t fight their direction
Be empathetic. Debug your communication, not the AI
Don’t read boring code. Trust tests, review diffs
Structure for clarity. Conventions, docs, small files
It’s okay to mourn. The craft is changing. Acknowledge it

The question isn’t whether AI will change how we code. It’s whether our codebases are ready for the collaboration — and whether we’re ready to let go of the parts we loved while holding onto what matters.

Inspired by: How to code with AI agents - Peter Steinberger and Lex Fridman and Will AI replace programmers?