# Plan in Obsidian, build with Claude Code: the PRD-to-tasks loop

> How practitioners on r/hermesagent run projects: requirements and task lists in an Obsidian vault, small tasks handed to a coding agent, every diff reviewed by a human.

- **Category:** [Coding](https://stepgleam.com/categories/coding)
- **Difficulty:** Intermediate
- **Time:** ~45 minutes
- **Tools:** Obsidian, Claude Code, Hermes Agent, VS Code, Git
- **Reliability score:** 74/100
- **Steps:** 6
- **Last updated:** 2026-10-26
- **Published:** 2026-10-26

## Tools used

- [Obsidian](https://obsidian.md) — Notes vault for the PRD, tasks and decisions
- [Claude Code](https://code.claude.com/docs) — Coding agent that reads, edits and tests the repo
- [Hermes Agent](https://hermes-agent.nousresearch.com/docs) — Optional orchestrator for research, PRD and task hand-off
- [VS Code](https://code.visualstudio.com) — Where you review and hand-edit the diff
- [Git](https://git-scm.com) — Checkpoints and small commits

## What you'll get

A vault with a PRD, an architecture note, a task list and a changelog, plus a repeatable loop: pick one task, have the agent write, test and document it, then review the diff yourself.

## Who this is for

Developers and builders who already use a coding agent and find that bigger projects drift, lose context or end up as one huge diff.

## Before you start

This guide mirrors workflows that people described in two r/hermesagent threads. Their main point: they don't start by typing "build this". They write the requirements down, split the work into small tasks, and keep the project knowledge in notes the agent reads before each task. Hermes is optional here. One person used it to write the PRD and hand tasks to the coding agent, and another used OpenCode in the same role. The habits matter more than which tools you pick.

## Steps

### Step 1: Write the four planning documents before any code

**Tool:** Obsidian

Create a folder in your Obsidian vault for the project with four notes: **PRD**, **Architecture**, **UI Specification** and **Tasks**. Fill in the PRD first: what you are building, who it is for, and what is out of scope. The author of the source post says the biggest lesson was *"Don't start coding immediately. Spend more time defining what you're building."*

**Why this works:** Agents fail when requirements live only in your head or in a long chat history.

[Open step 1](https://stepgleam.com/guides/plan-in-obsidian-build-with-claude-code#step-1)

### Step 2: Collect UI references before the agent designs anything

**Tool:** Obsidian

Add screenshots, mockups and reference links to the UI Specification note. The same author found that when the AI designs everything by itself, *"most apps end up looking strangely similar"*. Setting the visual direction first improved their results.

**Why this works:** The agent copies whatever direction you give it, so give it one on purpose.

[Open step 2](https://stepgleam.com/guides/plan-in-obsidian-build-with-claude-code#step-2)

### Step 3: Break the PRD into phases and small tasks

**Tool:** Hermes Agent

Turn the PRD into phases, then into small tasks in the Tasks note or on a kanban board. One commenter has Hermes build the PRD, features, modules and subtasks, then parse them into phases on a Hermes kanban, in *"logical small chunks with memory/changelog/code rules in Obsidian"*. If you don't use Hermes, do the same split by hand or ask your coding agent to propose it in plan mode.

**Why this works:** Small tasks keep each agent session focused, and they produce diffs a person can actually review.

[Open step 3](https://stepgleam.com/guides/plan-in-obsidian-build-with-claude-code#step-3)

### Step 4: Put the project rules where the agent reads them every session

**Tool:** Claude Code

Write the build, test and lint commands, conventions and "never do X" rules into `CLAUDE.md` (or `AGENTS.md`, which Claude Code, Codex and Cursor can all read). Keep it short. Anthropic's guidance is that if Claude already does something correctly without a line, delete the line. In the thread, Obsidian holds the code rules and changelog so that *"context and knowledge is read before each task."*

**Why this works:** Persistent rules stop you from re-explaining the same conventions in every session.

[Open step 4](https://stepgleam.com/guides/plan-in-obsidian-build-with-claude-code#step-4)

### Step 5: Hand one task to the agent: write, test, document

**Tool:** Claude Code

Take the top TO DO task and give it to Claude Code with the relevant notes referenced (for example `@docs/PRD.md`). Ask for code, tests and a short note in the changelog. For anything that touches several files, start in plan mode (Shift+Tab until the status bar shows plan mode on) and approve the plan before edits.

Another commenter in the same thread had Hermes delegate every coding task to OpenCode and act as the coordinator, with OpenCode implementing, testing and fixing each feature until the MVP was done.

**Why this works:** Each task is small, testable and logged, so the next session starts with accurate context.

**Prompt:**

```
Implement the task "<task name>" from @docs/Tasks.md. Follow @CLAUDE.md. Write tests for it, run the test suite, and add one line to @docs/CHANGELOG.md describing the change.
```

[Open step 5](https://stepgleam.com/guides/plan-in-obsidian-build-with-claude-code#step-5)

### Step 6: Review the diff yourself in your editor

**Tool:** VS Code

Open the changes in VS Code (or your editor's source control view) and read the diff before you commit. Fix things by hand where that is faster. The commenter's loop ends with *"Manual edits and reviews are via VS Code."* Then commit, tick off the task and move to the next one.

**Why this works:** The agent stops when the work looks done. You are the check that it actually is.

[Open step 6](https://stepgleam.com/guides/plan-in-obsidian-build-with-claude-code#step-6)

## Pro tips

- Treat model choice as secondary. The source author found a well-organized workflow with a good model consistently beat a chaotic workflow with a great model.
- Keep the vault as the single place for decisions, so a fresh agent session and a future you read the same thing.
- Commit after every task. That gives you a clean point to revert to if the next task goes wrong.

## Common mistakes

- Saying "build this", then "continue, continue". The source author says this broke down as soon as projects got bigger.
- Letting the notes go stale. If the PRD no longer matches the code, the agent follows the wrong one.
- Making tasks so big that the diff can't be reviewed in one sitting.

## FAQ

### Do I need Hermes for this?

No. In the thread Hermes did the PRD and task hand-off, but the same loop works with Obsidian notes and Claude Code alone, or with OpenCode or Cursor as the coding agent.

### Why Obsidian instead of a README?

Practitioners use it as a persistent knowledge layer: ideas, research, decisions and lessons. A README works too; what matters is that the agent reads it before each task.

### Is there a way to run Cursor inside Obsidian?

A community plugin (obsidian-cursor-plugin) runs the Cursor CLI agent with the vault as its workspace. It describes itself as early development.

---

Canonical guide: https://stepgleam.com/guides/plan-in-obsidian-build-with-claude-code
Read this guide as Markdown: https://stepgleam.com/guides/plan-in-obsidian-build-with-claude-code.md