Best Obsidian Folder Structure for Developer Projects in 2026

Mar 23, 2026

I opened Obsidian and stared at 847 notes. I couldn’t find the decision we made three months ago about why we chose PostgreSQL over MongoDB. I searched for “database decision” and got 23 results, none of which had the answer.

When I asked Claude to help me understand my project context, it had no idea where to look. My folder structure was a mess - some notes in projects/, some in ideas/, and decisions scattered across random daily notes.

After trying at least five different organizational schemes, I found one that actually works for developers: a three-layer architecture that separates identity (permanent context), knowledge (growing insights), and workflow (daily operations).

The Two Traps I Kept Falling Into

Trap 1: The Flat Structure

Everything went into one folder. Simple, right? Until I had 100+ notes and finding anything became archaeology.

Trap 2: The Over-Engineered Hierarchy

projects/
├── active/
│   ├── frontend/
│   │   ├── react/
│   │   │   ├── components/
│   │   │   │   └── notes/
...

Four clicks just to create a note. I stopped using it within a week.

Both approaches fail for the same reason: they don’t account for how developers actually work, and they definitely don’t work with AI assistants that need quick context.

The Three-Layer Architecture

Here’s the structure that finally stuck:

obsidian-vault/
├── projects/
│   └── [project-name]/
│       ├── soul.md              # Identity: what, who, why
│       ├── heart.md             # Identity: how I work
│       ├── decisions.md         # Knowledge: decision log
│       ├── learnings.md         # Knowledge: patterns
│       └── intel.md             # Knowledge: gotchas
│
├── daily/                       # Workflow: daily notes
├── goals/                       # Workflow: active goals
├── people/                      # Workflow: contacts
├── standup/                     # Workflow: auto-generated
├── learning/                    # Reference: reusable insights
├── decisions/                   # Reference: archived decisions
└── templates/                   # Setup: templates

Let me explain each layer and why it matters.

Layer 1: Identity (The “Who” and “Why”)

These files rarely change, but they’re essential. When I start working with Claude on a project, or when a new team member joins, these files provide immediate context.

soul.md - What the Project Is

# Project: Payment Service

## What It Is
A microservice handling all payment processing for the platform.
Processes ~50k transactions daily with 99.9% uptime requirement.

## Who It Serves
- Primary: E-commerce checkout flow
- Secondary: Subscription management, refund processing

## Where It's Going
- Current state: Stable, handling current load
- North Star: Real-time fraud detection integration
- Next milestone: Multi-currency support (Q2 2026)

## Key Constraints
- Technical: Must complete transactions under 500ms
- Business: PCI-DSS compliance required
- Team: Two backend engineers, part-time support

heart.md - How I Work

# How I Work: Payment Service

## My Preferences
- Code style: Prettier with team config
- Review process: Two approvals for payment logic
- Communication: Slack for quick questions, async for decisions

## My Non-Negotiables
- [ ] All payment code needs tests (unit + integration)
- [ ] No direct commits to main branch
- [ ] Security review for any new payment provider integration

## AI Assistant Context
When Claude helps with this project:
- Always check decisions.md first
- Use conventional commits format
- Follow existing error handling patterns
- Never suggest skipping PCI compliance steps

I tried skipping these files at first. “I’ll remember,” I thought. Six months later, I couldn’t explain why we chose Stripe over Braintree. Now I never start a project without soul.md and heart.md.

Layer 2: Knowledge (The “What We Learned”)

These files grow over time. The key insight: they’re append-only. I don’t reorganize or delete - I just add.

decisions.md - Why We Did What We Did

# Decision Log

## 2026-01-15: Use PostgreSQL over MongoDB

**Context:** Need reliable transactions for payment records

**Options Considered:**
1. PostgreSQL - Strong ACID guarantees
2. MongoDB - Flexible schema
3. SQLite - Simple, but scaling concerns

**Decision:** PostgreSQL

**Rationale:** Payment records require ACID compliance.
A failed transaction must never leave partial data.
Schema flexibility less important than data integrity.

**Consequences:**
- Need migrations for schema changes
- More upfront design required
- Better reporting capabilities with SQL

---

## 2026-02-20: Implement Idempotency Keys

**Context:** Duplicate payments from network retries

**Options Considered:**
1. Client-side deduplication only
2. Server-side idempotency keys
3. Both layers

**Decision:** Both layers

**Rationale:** Defense in depth. Client-side catches obvious
duplicates, server-side is the source of truth.

**Consequences:**
- Need to store idempotency keys for 24 hours
- API documentation update required
- Reduced payment disputes by 95%

The decision log has saved me so many “why did we do this?” conversations. When someone questions a past decision, I point to the log instead of digging through Slack history.

learnings.md - Patterns Worth Remembering

# Learnings: Payment Service

## WHEN deploying to production
**DO:** Run full test suite with `npm run test:ci`
**NOT:** Skip tests because "it worked locally"

**Outcome:** Prevented 3 production incidents this quarter

---

## WHEN using the Stripe API
**DO:** Implement exponential backoff for rate limits
**NOT:** Assume API is always available

**Outcome:** Reduced payment failures by 40%

---

## WHEN processing refunds
**DO:** Check original transaction status first
**NOT:** Assume transaction is refundable

**Outcome:** Prevented 12 failed refund attempts

The WHEN/DO/NOT format came from a coworker. It’s specific enough to be actionable but flexible enough for any situation.

intel.md - Gotchas and Edge Cases

# Intel: Payment Service

## API Quirks

### Stripe
- Webhooks can arrive out of order
- Need to handle duplicate webhooks (idempotent processing)
- Test mode cards have specific patterns (4242...)

### PayPal
- Express checkout has a different flow
- Refund window is 180 days
- IPN notifications can be delayed by hours

## Edge Cases We've Hit

1. **Double charges on slow networks**
   - Add client-side loading states
   - Disable submit button on first click

2. **Currency conversion rounding**
   - Always round at the final step
   - Store amounts in cents to avoid floating point issues

3. **Time zone confusion in reports**
   - Store everything in UTC
   - Convert only at display time

This file started empty. Now it’s my first stop when something weird happens.

Layer 3: Workflow (Daily Operations)

The workflow layer is where the actual work happens.

daily/ - The Atomic Unit

# 2026-03-23

## Tasks
- [ ] Review PR #234 (payment retry logic)
- [ ] Add webhook logging
- [x] Fix duplicate charge bug

## Blockers
- Waiting on security review for new provider

## Learnings
- Stripe's test mode doesn't validate future expiry dates

## Tomorrow
- Start on multi-currency investigation

Daily notes are simple. I don’t overthink them. But they become incredibly useful when generating standup notes or looking back at what I was working on.

goals/ - Active Goal Tracking

# Q2 2026 Goals: Payment Service

## Primary Goal: Multi-Currency Support

### Milestones
- [ ] Research phase (Week 1-2)
- [ ] Stripe integration update (Week 3-4)
- [ ] Testing with sandbox (Week 5-6)
- [ ] Staged rollout (Week 7-8)

### Progress Log
- 2026-03-15: Started research, identified 5 currency providers
- 2026-03-20: Discussed with team, leaning towards Stripe native
- 2026-03-23: Scheduled sync with finance team

## Secondary Goals
- [ ] Reduce average transaction time by 20%
- [ ] Implement real-time fraud scoring

people/ - Contact Profiles

# John Doe

## Role
Senior Backend Engineer (Payment Team)

## What He Owns
- Payment gateway integrations
- Fraud detection logic
- Performance optimization

## Interaction Log
- 2026-03-20: Discussed multi-currency approach
- 2026-03-15: Pair programming on webhook refactor

Why This Works With AI Assistants

When I start a Claude session, I can point it to:

soul.md - Immediately understands the project context
heart.md - Knows my preferences and constraints
decisions.md - Won’t suggest things we already decided against
learnings.md - Builds on patterns that worked

Instead of explaining my project every time, the context is already there. Claude reads these files in seconds and gives me relevant help.

Common Mistakes I Made

Nesting too deep

I tried 5 levels of hierarchy once. Never again. Maximum 3 levels.

Mixing concerns

I put daily notes inside project folders. Then I couldn’t find them when switching projects. Keep workflow separate from identity/knowledge.

Skipping identity files

“It’s a small project, I don’t need soul.md.” Famous last words. Every project grows, and you’ll forget the original constraints.

Duplicating content

If something’s in learnings.md, don’t copy it to daily notes. Link to it instead.

Getting Started

Start small. Pick one project and create:

soul.md - What is this project?
heart.md - How do you work?
decisions.md - Start logging decisions

After a week, add:

daily/ folder for daily notes
learnings.md when you discover patterns

The structure should serve you, not the other way around. If a folder doesn’t feel useful after a month, remove it.

Multi-Vault Consideration

I tried keeping personal notes and project notes in the same vault. It got confusing fast. Now I use:

Work vault - Project-specific with this three-layer structure
Personal vault - Simpler structure for reading notes, journaling

Some people use a separate vault for Claude-specific context. I found that overkill - the identity layer handles AI context just fine.

The Payoff

Three months after implementing this structure:

Finding decisions takes seconds, not minutes
Claude actually understands my project context
Onboarding new team members is faster (read soul.md and heart.md)
I stop making the same mistakes (learnings.md has patterns)

The structure isn’t perfect. I still tweak it occasionally. But it’s the first one that’s stuck, and it works for both me and my AI assistant.

If you’re struggling with Obsidian organization, give the three-layer architecture a try. Start with just soul.md and heart.md for your current project. Everything else grows naturally from there.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Obsidian
👨‍💻 Claude AI
👨‍💻 Reddit Discussion on Claude + Obsidian

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!