Code is no longer the primary artifact. Context is.
1. AI Has Outgrown the IDE: From an IDE to a "Cognitive Layer"
Using IntelliJ IDEA with AI plugins exposes several limitations:
- You ask a question, AI generates a code snippet, and you manually review the result.
- Previous conversations with AI are difficult to search.
- As conversations grow longer, the AI loses focus due to accumulated context. Start a new session, and its memory resets—you have to teach it the project all over again.
- A single feature often spans multiple microservices, meaning the implementation lives across several codebases.
- From IDEA's perspective, there's only code. It has no awareness of database schemas, middleware, infrastructure, or architecture documentation.
Traditional IDEs are no longer sufficient for AI-assisted software development.
2. What Is Obsidian? A Local-First Markdown Knowledge Base
Official website: https://obsidian.md/
Obsidian is a local-first knowledge management tool built entirely on plain Markdown files. Its core strengths include:
-
Local ownership. Every note is simply a
.mdfile stored on your disk. Nothing is locked inside a proprietary cloud service. Everything works offline and remains fully under your control. -
Bidirectional links (Wiki-links).
[[note-name]]connects notes into a knowledge graph, while backlinks automatically show every page that references the current one. - Graph View. Visualize the relationships between notes to understand the structure of your knowledge base at a glance.
- Rich plugin ecosystem. Community plugins extend Obsidian into a task manager, calendar, Dataview database, AI workspace, and much more.
- AI-friendly plain text. Since everything is UTF-8 Markdown, AI models can read, write, diff, and edit notes directly—without requiring the specialized plugin bridges typical IDEs need.
Looking back at the pain points of using IDEA with AI, Obsidian addresses every one of them:
| IDEA + AI Problem | Obsidian Solution |
|---|---|
| AI conversations become disposable and difficult to review | Notes are persistent documents. Every AI edit is preserved, traceable, and reviewable. |
| Conversation history is hard to search | Full-text search, backlinks, and tags turn conversations into searchable knowledge assets. |
| Context grows too large, while new sessions lose memory | Project context is explicitly stored in notes. Simply have the AI read the notes to restore context. |
| One feature spans multiple microservices | A single vault can contain documentation for Services A, B, and C, with links connecting them. |
| IDEA only understands source code | The vault can hold architecture notes, database schemas, Kafka topics, deployment diagrams, and more alongside the code. |
In other words, Obsidian is not replacing IDEA as your code editor.
It replaces IDEA as your cognitive layer.
You continue writing code inside IDEA, while everything surrounding the code—design decisions, AI conversations, database schemas, architectural diagrams, and cross-service relationships—lives permanently inside Obsidian.
3. Environment Setup: Obsidian + Claudian
- Install Obsidian and enable community plugins.
- Install the Claudian plugin from GitHub,https://github.com/YishenTu/claudian
4. The Theory: Karpathy's "Wiki as Codebase"
Source: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
Andrej Karpathy's Wiki as Codebase gist.
He summarizes the idea in a single sentence:
"Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase."
Every note you write is no longer just documentation.
Instead, it becomes part of the codebase maintained by an LLM—except that instead of executable instructions, it stores structured knowledge about your project.
4.1 The Three-Layer Architecture
Karpathy divides the system into three layers, corresponding to three types of files inside your vault.
| Layer | Definition | Example |
|---|---|---|
| Raw Sources | Immutable source material. Read-only for the LLM. | Meeting notes, PDFs, code diffs, web clippings |
| The Wiki | Markdown pages generated and maintained by the LLM | Analysis notes, architecture documentation, ADRs |
| The Schema | Rules that make the LLM a disciplined maintainer |
CLAUDE.md at the vault root |
The important insight is that CLAUDE.md is much more than project instructions.
It acts as the schema governing the knowledge base.
The schema determines whether the LLM behaves like an ordinary chatbot—or like a disciplined maintainer of a living wiki.
4.2 Three Core Operations
Within this wiki, the LLM performs three kinds of work.
Ingest
Consume new raw materials, update multiple wiki pages, and maintain cross-references.
Query
Search the wiki, synthesize answers, and write valuable results back as new knowledge pages.
Lint
Detect inconsistencies, outdated information, orphan pages, and missing links.
Most people already perform the first two.
Linting is the new capability.
Just as source code benefits from linting, so does your knowledge base.
4.3 Why This Is Finally Practical
Organizations have long abandoned internal wikis because the maintenance cost exceeded the benefit.
Keeping links updated, eliminating contradictions, and maintaining structure simply required too much human effort.
LLMs remove that bottleneck.
Humans now focus on:
- selecting high-quality source material,
- directing the analysis,
- asking good questions.
Meanwhile, the LLM performs all the bookkeeping:
- updating dozens of pages,
- maintaining links,
- synchronizing knowledge,
- resolving inconsistencies.
The breakthrough isn't that Obsidian became more powerful.
It's that the cost of maintaining a wiki has shifted from humans to LLMs.
5. Workflow: One Vault, One CLAUDE.md, Four Everyday Habits
5.1 One Vault per Project
Instead of storing everything in one giant vault, create one vault for each project.
Place a CLAUDE.md file at the root containing:
- technology stack
- repository structure
- commit conventions
- common pitfalls
- recurring project context
Claudian automatically loads this file whenever a new session starts, eliminating the need to repeatedly explain your project.
5.2 Typical Development Workflow
The traditional workflow looked like this:
Open AI sidebar → Ask a question → Copy code → Close sidebar → Lose context.
The new workflow becomes:
- Create a requirement note containing the background, objectives, and constraints.
- Have the AI read the relevant context by linking architecture docs, database schemas, and previous requirement notes with
[[...]]. - Collaboratively analyze the problem through conversation.
- Let the AI write important decisions back into the notes.
- Return to IDEA and implement the code.
- Once implementation is complete, record:
- why the design changed,
- lessons learned,
- commit hash.
- Future work simply reuses these notes as project context.
The mindset changes fundamentally.
AI output is no longer disposable conversation.
It becomes permanent project documentation.
5.3 High-Frequency Workflows
Some particularly useful habits include:
-
@-reference notes to inject documents directly into AI conversations, especially for coordinating across services. - Paste code into notes and let AI edit it, preserving the entire discussion history.
- Architecture Decision Records (ADRs) with one note per architectural decision, linked together via wiki links.
- Daily Notes for debugging and investigation, allowing AI to follow your reasoning process over time.
- Graph View to quickly identify densely connected core modules and isolated knowledge gaps.
5.4 Division of Responsibilities
| Task | IntelliJ IDEA | Obsidian + Claudian |
|---|---|---|
| Coding, debugging, testing | ✅ | |
| Breakpoint debugging, profiling | ✅ | |
| Requirements analysis | ✅ | |
| Architecture design | ✅ | |
| Database documentation | ✅ | |
| Long AI conversations | ✅ | |
| Cross-service context | ✅ | |
| Team knowledge sharing | ✅ |
In short:
IDEA writes the code.
Obsidian manages the brain.
6. Case Study: A Two-Week Refactoring Project
One local project involved:
- Six implementation phases (P1–P6)
- Four rounds of architectural refactoring
- Fifteen technical decisions (D1–D15)
- Thirteen commits
- Two weeks of continuous work
Managing this entirely inside an IDE would have been nearly impossible.
Each new AI session would require reconstructing the project's context from scratch.
Obsidian solved this in five ways:
- A master planning note guided every conversation and was continuously updated by the AI.
- All fifteen architectural decisions were documented, including background, alternatives, final choice, and rationale.
- Session continuity became effortless. On day seven, a simple "Read this note and continue" restored the entire project context.
- Commit hashes were written back into the notes, turning them into a living changelog.
-
Lessons learned were ultimately incorporated into
CLAUDE.md, allowing future sessions to begin with full project knowledge.
Without this workflow:
- Design decisions would be scattered across dozens of conversations.
- Every new AI session would waste twenty minutes rebuilding context.
- The architectural intent behind each commit would be forgotten within a few months.
The larger and longer a project becomes, the more valuable the Obsidian + Claudian workflow proves to be.
It isn't just a productivity enhancement.
It is the infrastructure that makes long-running, AI-assisted software engineering practical.
7. Practice: Linting Your Obsidian Vault
The most practical habit is to regularly let AI lint your vault.
Treat your knowledge base the same way you treat your source code.
Two simple linting tasks provide enormous value.
7.1 Dead-Link Scan
Prompt:
Scan the entire vault and find every
[[wiki-link]]whose target file does not exist. Sort the results by reference count. Output the top 30. Ignore image embeds, code blocks, and Templater variables.
The results generally fall into six categories.
| Category | Example | Action |
|---|---|---|
| Daily note navigation | [[2026-05-14]] |
Usually harmless |
| Template placeholders | [[<% after_date %>]] |
Ignore |
| Web clipping artifacts | URLs or usernames converted into wiki links | Batch cleanup |
| Missing concept pages | Frequently referenced but nonexistent notes | Create the missing note |
| Typos | Incorrect capitalization or trailing characters | Fix immediately |
| Missing MOC pages | Referenced index pages that don't exist | Create an index page |
The most valuable category is the fourth.
Frequently referenced dead links reveal concepts you've repeatedly intended to document—but never actually did.
They become a concrete to-do list generated by your own knowledge graph.
7.2 Orphan Page Scan
Prompt:
Find every note that is never referenced by another note via wiki links. Exclude daily notes, entry pages,
CLAUDE.md, and empty notes. Sort by file size, largest first.
Typical results include:
Large orphan clusters
Entire collections—such as book notes or article series—remain disconnected.
The solution isn't adding one link.
You likely need a Map of Content (MOC) to organize the entire collection.
Orphan entry pages
Pages intended as dashboards or indexes receive no incoming links.
An entrance nobody reaches isn't an entrance at all.
Empty notes
Drafts containing only a title should simply be deleted.
7.3 Why Regular Linting Matters
A single lint run provides four concrete benefits:
- A prioritized list of missing core notes
- Discovery of structural weaknesses in your knowledge organization
- Cleanup of stale data, typos, and clipping artifacts
- Validation that important entry pages are actually reachable
A practical cadence is:
- once per month, or
- after importing a large amount of new material into your vault.
Without periodic linting, most vaults eventually become graveyards of broken links and isolated notes.
With regular linting, every page remains connected, discoverable, and useful.
This is precisely what Karpathy means by treating a wiki like a codebase.
8. Conclusion: IDEA Handles the Code; Obsidian + Claudian Handle the Thinking
- IntelliJ IDEA remains an excellent code editor.
- Obsidian provides the missing cognitive layer, preserving design intent, AI conversations, architecture, database knowledge, and cross-service context.
- Claudian serves as the bridge, allowing AI to directly maintain your knowledge graph rather than acting as a disposable question-and-answer tool.
-
CLAUDE.mdfunctions as the schema that transforms an LLM from a chatbot into a disciplined knowledge-base maintainer. - Linting is the essential maintenance routine that keeps your vault healthy over the long term.
Together, they form what can truly be called an AI-native development environment.
Instead of simply embedding AI into an IDE sidebar, this workflow reimagines software development around knowledge organization, making AI a first-class participant in long-term, complex engineering projects.
Top comments (0)