Engineering Knowledge Compounds When Claude Code Is the Runtime

You decide something in February. By April, three people had re-debated it because the context lived in a Slack thread that nobody can find. The meeting where you agreed on the approach is a fading memory. The trade-offs you weighed have vanished. You re-discover the same constraints, make a slightly different call, and six months later someone asks why the system works the way it does. Nobody knows.

This is the first article in a series on building a Knowledge OS where Claude Code acts as both the interface and the runtime for your engineering knowledge. Knowledge accumulates as a side effect of daily work, becomes searchable in natural language, and compounds over time so past decisions inform current ones.

flowchart LR
    WORK["Your daily work"] --> CC["Claude Code"]
    CC --> CAP["Captures knowledge"]
    CAP --> IDX["Searchable index"]
    IDX --> DEC["Informs decisions"]
    DEC --> WORK

    style WORK fill:#2a5f8f,stroke:#4a9eed,color:#ffffff
    style CC fill:#1e6e45,stroke:#4ae68a,color:#ffffff
    style CAP fill:#1e6e45,stroke:#4ae68a,color:#ffffff
    style IDX fill:#7a5c2e,stroke:#e6b44a,color:#ffffff
    style DEC fill:#5a2e7a,stroke:#b44ae6,color:#ffffff

The idea started with Obie Fernandez's article on building a personal CTO operating system with Claude Code. He showed the pattern: trust Claude with structured Markdown, define your role, let the system grow. I documented engineering work in markdown for two years before building on that pattern. The Knowledge OS is the infrastructure that makes the notes useful: semantic search across 2,500+ documents, automated meeting transcript integration, custom subagents for performance, and 872 searchable Claude Code session histories. The gap between "I wrote this down somewhere" and "Claude, what did we decide about event-driven architecture last October?" is what the system closes.

The system launched as a structured daily-driver OS in February 2026, built on 22 months of problem discovery. The initial build took roughly 40 hours of engineering time across two weeks. Daily knowledge capture now takes under a minute per artifact because Claude handles the templating, linking, and indexing.

Why Engineering Knowledge Decays Without a System

You spend a week evaluating options, talking to stakeholders, weighing trade-offs. A decision gets made. Two weeks later, the context has decayed.

Three forces drive this:

1. Decisions scatter across tools. No single system holds the chain from problem to decision to outcome.
2. Documentation is a separate activity. The incentive to document is weakest at the exact moment the context is freshest.
3. Search fails across boundaries. Semantic connections ("this caching decision relates to that performance workstream") are invisible to keyword search.

Institutional knowledge ends up in people's heads. When someone leaves, joins, or forgets, you are not building on past decisions. You are re-making them.

Obsidian and Notion vs. a Claude Code Knowledge OS

You could store the same markdown files in Obsidian. What you cannot replicate is the runtime.

The Knowledge OS is not a better note-taking app. This is an AI-powered operating system where Markdown is the storage format and Claude Code is the execution engine. Obsidian gives you a vault. This gives you a copilot that reads the vault, fetches live GitHub and Google Meet data, reconciles it against your knowledge index, and flags what needs attention.

Lower friction is why I still use this daily at week 10. Every knowledge tool I tried before lasted about three weeks.

How Commands, Skills, and Agents Compose

flowchart LR
    CMD["/dashboard, /weekly-review"] --> SKL["Sync, Search, Fetch"]
    SKL --> KS["Knowledge Store"]
    KS --> IDX["index.yaml + QMD"]

    style CMD fill:#2a5f8f,stroke:#4a9eed,color:#ffffff
    style SKL fill:#1e6e45,stroke:#4ae68a,color:#ffffff
    style KS fill:#7a5c2e,stroke:#e6b44a,color:#ffffff
    style IDX fill:#5a2e7a,stroke:#b44ae6,color:#ffffff

Three tiers of active components, one shared data substrate:

Commands (6) are what you type. /dashboard shows current priorities, active workstreams, recent decisions, and a checklist of your weekly rhythms. /weekly-review walks you through planning. /update-outcome tracks decision results after implementation. /give-feedback and /assess-engineer run structured feedback workflows with evidence from GitHub and meetings. Commands are entry points for gated, interactive workflows.

Skills (14) are what Claude invokes. Document creators (create-decision, create-workstream, create-task, create-handoff, create-edr) write files from templates and register them in the index. Lifecycle skills (update-task, update-context, add-to-index, index-validator) keep artifacts current. Search and sync skills (qmd-search, sync-sessions, sync-meetings) connect external data. Commands call skills; skills do not call commands.

Agents (4) are background specialists with narrow tool access. Haiku-class agents handle slow I/O (GitHub MCP, Google Drive) in parallel so the main conversation stays responsive: github-pr-fetcher, meeting-syncer, feedback-evidence-gatherer. One Sonnet agent (meeting-processor) structures raw transcripts into linked meeting notes.

The Knowledge Store holds structured Markdown with YAML frontmatter: decisions, tasks, workstreams, architecture docs, handoffs, meeting notes. Each file follows a template with fields for linking to related artifacts. Two years of Markdown documentation crystallized into this structure in February 2026.

The Index and Search layer has two components. index.yaml is a YAML file that holds metadata for every artifact: IDs, paths, status, teams, tags, summaries. Claude reads it in full when you ask structured questions ("show me all active workstreams for the platform team"). QMD, Tobi Lütke's local semantic search engine for markdown, indexes the full content of 2,500+ documents across 8 repositories and returns results ranked by relevance in under 2 seconds. Together, they make years of accumulated context queryable in natural language.

How Knowledge Compounds: An API Framework Decision Chain

flowchart LR
    DEC["Feb: Decision adopted"] --> GAPS["Mar: 14+ gaps documented"]
    GAPS --> GUIDE["Mar: Guide workstream"]
    GUIDE --> REV["Apr: Evidence-based reversion"]

    style DEC fill:#2a5f8f,stroke:#4a9eed,color:#ffffff
    style GAPS fill:#7a5c2e,stroke:#e6b44a,color:#ffffff
    style GUIDE fill:#1e6e45,stroke:#4ae68a,color:#ffffff
    style REV fill:#5a2e7a,stroke:#b44ae6,color:#ffffff

Accumulating vs. Compounding

In February 2026, I evaluated an API framework for a new service. The evaluation produced a decision record with outcome tracking: the framework looked promising, but had gaps in authorization, testing, and documentation. I adopted it with mitigations.

Over the next six weeks, every conversation where I hit a gap generated a context log entry on the workstream. By March, the log held 14+ entries documenting specific gaps: authorization patterns that did not map, testing utilities requiring custom wrappers, error handling conventions conflicting with the main application.

By April, the context log told a different story than the original decision. The gaps required fundamental changes to authorization, testing, and error handling that workarounds could not bridge. I proposed reverting the decision. The proposal linked to the original record, the 14+ context entries, and the guide workstream that attempted to bridge the gaps. Every link in the chain was traceable.

Without the system, you get a decision record saying "we chose this framework." Two months later, someone says "yeah, we picked that a while back" from memory.

The system produced something different. The outcome tracking on the decision record flagged "Partial Success" with specific evidence. The guide workstream accumulated 14 entries of technical knowledge (caching patterns, materialized views yielding 8x improvement, 6 implementation rules). When I opened the migration workstream, it explicitly linked to the original decision. When I proposed the reversion, the documented evidence made it defensible rather than a gut call driven by sunk cost.

The difference is between "I think we tried something like this before" and "here are the linked artifacts showing exactly what we tried, what we learned, and why the current proposal will not fix the actual problem." Any engineer can take notes. The question is whether those notes are findable, connected, and actionable six months later.

A committed documenter with Confluence could theoretically build the same chain. In practice, the friction of maintaining cross-links, outcome tracking, and workstream context logs manually means it does not happen. The system automates the maintenance. That is what Claude Code adds.

After 2.5 Months: 188 Artifacts and One Dashboard

flowchart LR
    subgraph BEFORE["Before"]
        direction LR
        B1["Jira, GitHub, Calendar"]
        B2["Slack, Email, Confluence"]
        B3["GDrive Docs, Sheets, Slides"]
        B4["Markdown notes, Head"]
    end
    subgraph AFTER["After"]
        A1["/dashboard reconciles all"]
    end

    BEFORE --> AFTER

    style B1 fill:#5a2e2e,stroke:#e64a4a,color:#ffffff
    style B2 fill:#5a2e2e,stroke:#e64a4a,color:#ffffff
    style B3 fill:#5a2e2e,stroke:#e64a4a,color:#ffffff
    style B4 fill:#5a2e2e,stroke:#e64a4a,color:#ffffff
    style A1 fill:#1e6e45,stroke:#4ae68a,color:#ffffff
    style BEFORE fill:#3d1a1a,stroke:#e64a4a,color:#e0e0e0
    style AFTER fill:#1a3d2e,stroke:#4ae68a,color:#e0e0e0

Before the Knowledge OS, status lived in Jira, GitHub, Google Calendar, Slack, email, Confluence, Google Drive, scattered Markdown notes, and my head. Switching between workstreams meant reloading context from each of them.

A single /dashboard command now reconciles everything. It launches background agents that fetch live GitHub PR data and Google Meet transcripts, matches PRs to tasks by ticket ID, flags status mismatches, and renders active workstreams with inline PR state, recent meetings linked to initiatives, and rhythm checklists.

Two limitations. First, the command layer and semantic search depend on Claude Code and QMD. The knowledge store itself is plain Markdown and YAML, portable to any tool. Second, this series covers a personal system. Since the knowledge store is just files, team usage is straightforward: put the directory in Google Drive or a shared repo, and colleagues can read, search, and contribute. The series will focus on the single-engineer case.

What the Series Covers

The series is for engineers who already use Claude Code and want to turn it into infrastructure for their work, not just a code assistant.

Four articles cover the build:

1. Building a Personal Knowledge OS with Claude Code: How to set up the architecture (commands, skills, agents, store, search), and start capturing knowledge as a side effect of daily work.
2. Adding Semantic Search with QMD: How to make 2,500+ documents searchable across keyword, vector, and hybrid modes so past decisions surface in natural language queries.
3. Automating Meeting Capture: A two-phase processing pattern that turns Google Meet transcripts into linked, searchable knowledge artifacts without manual note-taking.
4. Subagents as Context Window Firewalls: How to build custom subagents that fetch data in parallel without bloating the main context window (the same orchestration pattern explored in how 764 AI agent sessions still needed 21 human interventions, applied to knowledge retrieval).

The foundation article gets you a working system in a single session. The API framework example in this article is the outcome to measure against: can you trace a decision chain across three months without dedicated documentation effort?

Available as a Service

I help engineering teams build Knowledge OS systems like this one, from architecture design through Claude Code integration, semantic search setup, and daily workflow adoption. If your team's decisions live scattered across Slack, Confluence, and people's heads, book a free 30-minute call or check my services page for details.