This is Part 2 of the Agentic Engineering series. In Part 1, I made the case for why we need an engineering discipline for agent-driven development. This post introduces the first and most foundational pattern: generating a complete knowledge store before writing any code.
I have been trying to build with AI agents for almost all of 2025, and the one lesson that keeps coming back to haunt me is this: the quality of what you build is directly proportional to the quality of what the agent knows before it starts building.
Simply said — if you hand an AI agent a vague prompt and say “build me an app,” you will get a vague app. And then you will spend three times as long fixing it as you would have spent planning it.
This realization led me to a practice I now call Knowledge-First Development — a core principle of what I think of as Agentic Engineering. The idea is straightforward: before an AI agent writes a single line of application code, it first generates a complete knowledge store — 44 documents across 8 directories — that serves as the shared understanding for everything that follows.
Think of it as the agent equivalent of an architect drawing blueprints before the construction crew shows up.
Why Not Just Start Coding?
Here is the thing — when you ask an AI to code something from scratch, it makes assumptions. Lots of them. About your data model, your error handling strategy, your naming conventions, your testing approach. And each assumption compounds on the previous one.
By Step 5 of a complex build, the agent has made so many micro-decisions that the codebase starts to feel like it was written by a committee that never met. Because in a way, it was — each decision was made in isolation without a shared understanding of the system.
Knowledge-First Development flips this entirely. Instead of code-first, it is knowledge-first. The agent builds its understanding of the system — architecture, quality attributes, product values, technical decisions — before it writes any implementation code.
The Knowledge Store Generator
The tool that makes this work is what I call the Knowledge Store Generator — a meta-prompt that runs Claude Code through 10 sequential steps, each with a specific persona:
| Step | Persona | What Gets Generated |
|---|---|---|
| 1 | Product Architect | CLAUDE.md, DESIGN.md, PLANS.md, directory structure |
| 2 | Product Strategist | PRODUCT_SENSE.md — personas, beliefs, guardrails |
| 3 | Systems Architect | ARCHITECTURE.md — domains, layers, data flow |
| 4 | Quality Engineer | QUALITY_SCORE.md, RELIABILITY.md, SECURITY.md |
| 5 | Domain Designer | 15+ design docs (DD-001 through DD-030) |
| 6 | Spec Writer | 7 product specifications |
| 7 | UX Designer | Design system, UX patterns |
| 8 | Test Architect | Test strategy, testing framework references |
| 9 | Reference Librarian | Library-specific guides for every dependency |
| 10 | Product Architect | Final verification pass across all documents |
The critical design choice: each step reads the output of all prior steps. Step 5 does not just generate design docs in a vacuum — it reads the architecture from Step 3, the product strategy from Step 2, and the quality requirements from Step 4. This creates a coherent knowledge graph where every document inherits decisions from its predecessors.
I will go deeper into the persona-based approach in Part 3 and the verification pass in Part 6.
What Does “44 Documents” Actually Look Like?
Here is the output breakdown:
| Directory | Files | Purpose |
|---|---|---|
| Root | CLAUDE.md, ARCHITECTURE.md | Agent entry point, system decomposition |
| docs/ | 9 core docs | Product sense, quality, reliability, security, UX |
| docs/design-docs/ | 15 design docs | Every technical decision documented |
| docs/product-specs/ | 7 specs | Feature-level specifications with acceptance criteria |
| docs/references/ | 8 reference docs | Library-specific guides (Playwright, Pydantic, etc.) |
| docs/generated/ | 2 reports | Verification and validation reports |
| docs/exec-plans/ | 1 tracker | Technical debt tracking |
That is 44 files across 8 directories, generated in a single session, before a single def or class keyword is written.
The Result That Surprised Me
When Step 10 ran its verification pass across all 44 documents, it found:
- 0 broken cross-references out of 47 links checked
- 0 terminology inconsistencies across 10 domain names
- 0 numerical mismatches across 7 SLO chains
- 20/20 PRD requirements covered
The terminology consistency was the part that impressed me most. Domain names, persona names, component names — identical everywhere they appear. That is the benefit of sequential generation with dependency ordering. Each step does not invent its own vocabulary because it has already read the vocabulary established by prior steps.
(Though as I will discuss in Part 6, a perfect score from a self-verifying system deserves healthy skepticism.)
Is This Overkill?
Honestly? It depends on what you are building. For a weekend side project, absolutely — just start coding. But for a production application with multiple domains, AI pipelines, browser automation, and document generation? The 44-document knowledge store paid for itself within the first day of implementation.
The agent knew exactly what to build, in what order, following what conventions. No guessing. No backtracking. No “oh wait, that naming convention conflicts with what I did in the other module.”
What Is Coming in This Series
This post is the foundation — the “why” behind Knowledge-First Development. The rest of the series dives into the specific Agentic Engineering patterns that make it work:
- Part 3: Role-based agent personas — why specialization beats generalization
- Part 4: The agent entry point — designing CLAUDE.md as a table of contents
- Part 5: Traceability chains — connecting product values to code enforcement
- Part 6: Forensic verification — catching what unit tests miss
- Part 7: Dual quality gates — separating validation from testing
- Part 8: Decision classification — one-way doors vs two-way doors
- Part 9: Product guardrails — turning values into mechanical checks
Each pattern is independent — you can adopt any of them without the others. But together, they form a coherent discipline for building reliable software with AI agents.
Hope you find this useful. What do you think — is 44 documents overkill, or is it the minimum viable knowledge for a complex system? I would love to hear how others are approaching the knowledge-first question.