Building Knowledge Systems

Resources

• Diátaxis: knowledge organized by need — This documentation framework separates tutorials, how-to guides, reference, and explanation. Use it to design personal and shared libraries with deliberate depth levels rather than one oversized document serving every task. https://diataxis.fr/

• A style guide for usable technical knowledge — Google’s developer style highlights prioritize clarity, consistency, audience, and direct language. They provide a concrete basis for extracting the essence of source material while retaining constraints and details an agent needs to act correctly. https://developers.google.com/style/highlights

• Architecture decisions that preserve the why — Michael Nygard’s original article introduces lightweight architecture decision records with context, decisions, and consequences. Use it to preserve historical reasoning and superseded choices instead of letting current specifications erase the path that produced them. https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions

• C4 maps for progressive exploration — Simon Brown’s C4 model separates system context, containers, components, and code views. It offers a principled map structure for codebase exploration, helping teachers show how an agent can navigate from a global system view to local implementation detail. https://c4model.com/

• Spec Kit’s specification-to-task pipeline — GitHub’s toolkit provides reusable conventions for constitutions, specifications, implementation plans, and tasks. Use it to inspect how global rules and scoped requirements become working artifacts, while treating synchronization with implementation as something to verify rather than assume. https://github.com/github/spec-kit

• Execution plans as living task memory — OpenAI’s ExecPlan example uses self-contained plans, milestones, progress, discoveries, decisions, and acceptance evidence. It directly supports stage splitting and resumption: a task record should explain its source, scope, current state, and observable completion conditions. https://developers.openai.com/cookbook/articles/codex_exec_plans

• A shared library built from Markdown — MkDocs documents Markdown pages, navigation, internal links, and documentation structure. It supplies a practical reference for turning a versioned personal library into browsable HTML without making the generated website the source of truth. https://www.mkdocs.org/user-guide/writing-your-docs/

• Executable knowledge with Quarto — Quarto combines narrative Markdown with Python execution and rendered outputs. Use it to distinguish source documents, executable generators, captured output or logs, and generated artifacts, including the need to know whether published results were actually recomputed. https://quarto.org/docs/computations/python.html

• Diffs as a knowledge-maintenance tool — Git’s diff reference covers comparisons between working files, staged changes, and commits, including word-oriented views. It anchors a concrete strategy for reviewing changed meaning in specifications and libraries instead of repeatedly rereading the entire knowledge base. https://git-scm.com/docs/git-diff

• Contextual retrieval — Anthropic explains enriching chunks with document context and combining embedding retrieval, BM25, and reranking. Use it to connect file organization with retrieval quality, while keeping the reported experimental results distinct from guarantees about a teacher’s own corpus. https://www.anthropic.com/engineering/contextual-retrieval

• Autonomous research with attributable sources — OpenAI’s deep-research guide documents research models, source tools, and citations. It provides an implementation reference for discovery and source capture, with a clear teaching boundary: a generated synthesis still requires source inspection and freshness checks. https://developers.openai.com/api/docs/guides/deep-research

• Context providers through MCP resources — The MCP resource specification defines discoverable, URI-addressed content, resource templates, and update mechanisms. Use it to separate a knowledge provider from an action tool and to discuss how libraries expose scoped, identifiable context to different clients. https://modelcontextprotocol.io/specification/2025-06-18/server/resources

• An agent-facing index with llms.txt — This proposal describes a concise Markdown entry point linking to deeper website resources. It is useful for designing layered library indexes and generated agent-facing views, but should be presented as a proposal rather than a universally supported discovery protocol. https://llmstxt.org/