This transcript is generated by parley.nvim.

← Agentic state management

Question

The log.md is trick as it depends on how base model behave. doesn’t seems like something easy for me to plugin. right?

🤖:[Claude-Code-Opus]

🧠: The user is pointing out that log.md depends on the agent’s behavior - the agent needs to actively write to it during execution. This isn’t something the user can easily enforce or plug in from the outside. It’s a valid concern. The log.md requires the agent to have discipline about appending to it, which depends on the base model’s system prompt compliance, tool use patterns, etc. The user can’t just set up a file structure and expect the agent to maintain a log. This is different from issue.md (written by human), plan.md (can be written at start), deps (static), status (simple state change). Log.md requires continuous, disciplined writes during execution. Let me think about practical alternatives - maybe log.md should just be git history, or maybe the orchestration layer handles it, or maybe it’s just not worth the complexity.

You’re right, and this is an important practical point.

The problem with log.md

log.md requires the agent to voluntarily and consistently write structured notes mid-execution. That means:

  • You need the system prompt to instruct it
  • You need the model to actually comply throughout a long session
  • Different models behave differently — some will dutifully append, others will forget after a few steps
  • If the agent is using tool calls (file edits, shell), adding a “write to log” step between every meaningful action is fragile

It’s the least controllable file in the structure. Everything else is either human-authored or a simple state marker.

What actually works instead

The durable trace you want from log.md already exists in two places:

  1. Git history — if the agent commits incrementally (which it should), the commit messages are the log
  2. Conversation transcript — most agent frameworks (Claude Code, Cursor, Aider) already persist the session

So rather than asking the agent to maintain a separate log file, a more robust approach:

issues/
  00001/
    issue.md
    plan.md       ← agent updates this (checked items, revised steps)
    deps
    status        ← open | blocked | done

And the “log” is just:

  • plan.md diff over git history — you can see how the plan evolved
  • commits on the working branch — what actually happened

Plan.md as the only mutable file

This simplifies the agent’s job to one thing: keep plan.md honest.

  • Check off steps as done
  • Cross out steps that turned out wrong
  • Add new steps discovered during work
  • Commit plan.md changes alongside code changes

That’s a much more natural fit for how models actually behave — they’re already editing files and committing. You’re just asking them to edit one more file as part of their normal flow.

When you truly need a log

If you hit a case where you need to understand why something was tried and abandoned, you can reconstruct it from:

git log --follow -p -- issues/00001/plan.md

That gives you the full evolution of thinking, tied to real commits, without requiring the agent to maintain a separate file.

The honest answer

log.md is a good idea in theory but a compliance burden in practice. Drop it. Let git be your log. Put all the agent’s mutable state into plan.md and keep the contract simple: one file to read, one file to update, commit often.

📝: You asked about log.md being impractical given base model behavior, I answered that you’re right — it’s the least controllable file, drop it, let git history and plan.md diffs serve as the log instead, keep the agent’s contract to a single mutable file (plan.md) alongside commits.

Question