Every working day we record what we decided and why. It started as a memory aid. It has become infrastructure.

We used to lose the why. It doesn’t take long after commits are pushed and PRs are merged to forget why certain decisions were made. That can cost an afternoon (or more) of re-litigating a decision nobody can quite remember.

Best practice is to record the why in code comments and commit messages. But commit comments get lost quickly, and with agent-written code, they are best treated as breadcrumbs for future agents rather than the primary record.

Every working day, everything we build gets logged in plain markdown: what we did, what we decided, and why.

A daily file, not a status report

The log started as a daily file in an Obsidian vault. We have since moved to Notion. One page per working day. Not a diary of who sat in which meeting, but the decisions and trade-offs made while building features and fixing bugs. Something that is easy for you (or your agent) to look back on six months later and understand. More and more it is session context summaries for your agent to reference later.

I used to keep this in physical notebooks. The quality and discipline varied. I’d have detailed daily notes for a few weeks, then go a month with zero entries. Then I moved to Obsidian and finally Notion.

Earlier this year we stopped manually maintaining a dev log. It’s now a tool for our agents while still being something we can review and reference.

The log is auto-captured from Claude Code session context by a skill. The agent records what was built and why as a byproduct of the work. I can also push specifics mid-session without leaving the terminal.

The best documentation habit turns out to be one that requires almost no habit.

Ask for a summary at six o'clock and you get a clean recap from all of your sessions: what was tried, what was rejected, which trade-off we picked, what we deferred.

Agents Forget

Agents have no memory between sessions. Tuesday's context does not survive to Wednesday unless we put it somewhere they can read.

The daily log serves as a richer memory system than a MEMORY.md file in a project. It cuts across projects, is dated, and is more detailed. It shouldn’t replace a more condensed project memory, though.

A good prompt for a feature or enhancement normally includes a solid why. This helps the agent. With the latest frontier models we have today (Opus 5.5 is my favorite, currently), less prescription is better. What the agent needs most of all is the business context, which includes a healthy dose of “why” along with guardrails and constraints.

Example: What happened to freight calculations?

One example of how this system has saved us a lot of time and provided clarity is making adjustments to our freight rules. Estimating freight for one of the Southeast’s largest custom fertilizer blenders is no simple feat. There are a lot of variables that have changed over time.

Recently we had an enhancement request to tweak how we considered freight for a report, and it wasn’t clear what we should do because the evolution of the freight rules was fuzzy at best.

Instead of combing through old notebooks, email threads, and having conversations trying to jog memories of different employees, we could prompt Claude:

looking through the devlog summarize decisions we've made about how we should handle freight

Within seconds we had a response compiled from over a year of dev log entries summarizing code locations, the rules, and the decisions contributing to those rules.

What compounds

One automated capture feeds four outputs: an internal weekly digest, this blog's editorial calendar, code review context, and onboarding. The marginal cost of each is near zero because the raw material already exists.

We don't go hunting for "blog ideas." We have an agent that reviews the dev log and suggests topics we can write about, then posts short outlines as Linear tickets. No more racking our brains for ideas to share.

A new person on the team, or a new agent session, can read why a constraint exists instead of guessing from the code. Git has the what. The log has the why.

How to start

Keep it cheap. Automate the capture so it costs nothing: a skill or a hook in your agent tooling, fired at the moment of decision or the completion of a task (for example a PR), not at the end of a long day when the why is gone or muddy from a mixed contexts. Push the specifics while they're fresh.

I’ve published the capture skill we use at github.com/paltman/devlog. Take it and make it your own. I’d love feedback on any improvements that you have in the form of issues or pull requests.

We write more than ever

We stopped writing code by hand and, in so doing, the volume of our code production has gone through the roof. This requires extra care to keep track of what we are doing lest we drown in code that owns us rather than us owning the code.

Matt Pocock made the point in a recent podcast interview with Network Chuck that software engineering is part tactical coding and part strategic coding. The tactical is what we used to do by hand, hammering out code for a specific feature and diving deep into the zone. The strategic is the 30,000-foot thinking and implementation of longer-view items that ensure the health of your code and architecture for long-lived software.

Agents do nearly all the tactical coding now. That leaves us able to do more strategic “coding.” Having a solid log of decisions and reasoning is a key component to supporting that long-term thinking.