When you hand work to AI agents like Claude Code or Codex, the instructions go into a chat box and the results scroll away in the terminal. A few days later, you can't remember what you asked for or why something was changed.
The fix is simpler than you'd think. Write your instructions in a markdown note instead of a chat, and have the agent write its results into the same note. If you already use Obsidian, you don't need any new tools.
One Note = Instructions + Work Log#
Make each task a single note. The top holds your instructions, and the bottom holds the agent's results.
---
status: todo
agent: claude
created: 2026-10-01
---
## Goal
Fix the password error message showing up twice on the login screen
## Context
- Related file: `src/auth/LoginForm.tsx`
- Seems to have started after last week's form validation change
## Done when
- The error message shows only once
- Existing login tests pass
## Don't
- Do any big refactoring, like swapping the form library
## Result
(written by the agent)It takes a bit more effort than tossing off a one-liner in chat. But the moment you write Done when and Don't, your instructions get much sharper, and the agent wanders off in the wrong direction less often.
Handing It to the Agent#
Just give it the note's path. Agents can read files directly.
Read tasks/login-error-message.md and do the work. When you're done, summarize it under ## Result in the note.This works the same whether you run the agent inside your Obsidian vault or just point it at the vault path.
Set Rules for Recording Results#
Explaining how to write up results every time gets tedious. Write it once in the instruction file your agent reads every session: CLAUDE.md for Claude Code, AGENTS.md for Codex.
## Task note rules
- When you get a task note, fill in `## Result` with the following when done:
- List of changed files
- Why you made the change (and any approaches you ruled out)
- How you verified it (tests or commands you ran)
- Remaining work or anything you couldn't confirm
- Set `status` in the frontmatter to `done` or `failed`.The key item is why you made the change. Code changes stay in git, but the reasoning disappears unless someone writes it down.
Treat
statusas a supporting hint only. If the agent stops halfway, the value might never change, so it isn't reliable as a live status board. It's good enough as a marker for sorting out finished and failed tasks later.
Reuse the Notes You've Collected#
As notes pile up, they become a work log on their own. This is where Obsidian really shines.
- Search — find the original instructions and results together with a keyword like "login error"
- Links — for follow-up tasks, link the previous note like
[[login-error-message]]to carry the context forward - Templates — save the structure of notes that worked well as a template and reuse it for the next task
If you use the Dataview plugin, you can even gather failed tasks into a list to hand out again.
LIST
FROM "tasks"
WHERE status = "failed"
SORT created DESCWhen This Doesn't Fit#
It's not for every situation. If you run several agents at once and need to track exactly who holds what, a dedicated tool like GitHub Issues is more reliable. Frontmatter isn't a lock, so two agents could pick up the same note at the same time.
On the other hand, it fits well if you work solo, switch between a few agents, and already organize your thinking in Obsidian. You can write the work order right in the note where you were planning, and read the results in the same place.
Start with Your Next Task#
You don't need a big setup. Next time you hand something to an agent, write it as a note instead of a chat. Filling in just three sections, Goal, Done when, and Don't, changes the quality of your instructions, and once the results land in the note, that task becomes a record you can find again.
The reasonable man adapts himself to the world; the unreasonable man persists in trying to adapt the world to himself. Therefore, all progress depends on the unreasonable man.
— George Shaw
