A first-principles, hierarchical knowledge base for Python development — from empty folder to production-ready, maintained application. About 300 files across 6 levels of detail.
- How to Use This KB (Lines 24-26)
- 1. Use the Python KB Agent (recommended) (Lines 29-31)
- 2. Grep the Manifest (quick shortcut) (Lines 34-66)
- 3. Navigate the Tree Manually (Lines 69-73)
- For Human Developers (Lines 76-85)
- What's Inside (Lines 88-88)
- Levels of Detail (Lines 91-104)
- Stages (Lines 107-120)
- Philosophy Foundations (Lines 123-138)
- Notation and Related Files (Lines 141-147)
Three methods, in order of preference:
For any question about Python development, invoke the Python KB Agent via the Task tool with subagent_type="python-kb-agent". The agent greps the manifest, navigates the tree, prunes irrelevant branches, and returns a shaped answer with vertical context. This is the preferred path — it handles everything below automatically.
For a quick, targeted lookup when you already know what keyword to search for. The manifest is a YAML file that maps every file, heading, and line number in the KB. It is ~4k lines — never read it, only grep it.
Step 0 — generate the manifest if absent. The manifest files are regenerated on demand, not committed (they are gitignored). If doc_manifest_sections.yaml is not present, generate both manifest files first, from the repo root:
md-doc-tree-full dev_guidelines/python_guidelines/ -o dev_guidelines/python_guidelines/doc_manifest --heading-depth 3Then:
Grep(pattern="testing|pytest", path="python_guidelines/doc_manifest_sections.yaml")
This returns the exact files and line ranges that cover your topic. Then read only those sections:
Read(path="python_guidelines/LOD_2_phases/2.4_testing.md", offset=30, limit=20)
For tracing which files link to each other:
Grep(pattern="2.4_testing", path="python_guidelines/doc_manifest_cross_refs.yaml")
| File | Lines | Content | Access |
|---|---|---|---|
doc_manifest_sections.yaml |
~4k | Every file + headings + line numbers + word counts | Grep only (generated, not in repo) |
doc_manifest_cross_refs.yaml |
~1k | Outgoing links per file | Grep only (generated, not in repo) |
Regenerate after adding/removing files or restructuring headings, using the same command as Step 0 above.
Follow the rough-to-fine method described in CLAUDE.md: start at LOD_1 (stages), identify the right stage for your task, drill into LOD_2 phases only if the stage-level answer isn't enough, then into LOD_3/4/5 only when you need specifics. Use each file's TOC line numbers for surgical reads. Stop as soon as you have enough information.
The two index files provide the map: LOD_0_philosophy/0_index.md (principles) and LOD_1_stages/0_index.md (stages and transitions).
- Start at LOD_1 — find your current stage
- Drill down via links to LOD_2 phases, then LOD_3 domains
- Return to LOD_0 when decisions feel arbitrary
- Use TOCs — every file has a Table of Contents with
_(Lines X-Y)_ranges
Line navigation: VS Code Cmd+G, Vim :42, or click the line number gutter.
The KB is organized as a tree with 6 levels. Start at LOD_1, drill down only as needed. Go deeper for specifics, go up (LOD_0) when decisions feel arbitrary.
| LOD | Name | Depth | Purpose |
|---|---|---|---|
| LOD_0 | Philosophy | Full prose | First principles — the "why" behind decisions |
| LOD_1 | Stages | Full prose | Development pipeline — where you are in the process |
| LOD_2 | Phases | Full prose | Lifecycle phases within each stage |
| LOD_3 | Domains | Expanded outlines | Topic-specific rules (e.g. testing, packaging) |
| LOD_4 | Practices | Short | Patterns and how-to |
| LOD_5 | Details | Minimal | Edge cases and deep specifics |
About 300 files total.
Each stage maps to a development goal. Find your goal, go to the stage.
| Goal | Stage | Phases |
|---|---|---|
| Understand the philosophy | LOD_0: Philosophy | First principles, axioms |
| Define the problem before solving it | 1 Understand | Requirements, Design |
| Prepare environment and structure | 2 Setup | Environment, Project Structure |
| Write code, test it, document it | 3 Build | Implementation, Testing, Documentation |
| Package, validate, deploy | 4 Ship | Packaging, Quality, Deployment |
| Optimize, secure, debug | 5 Operate | Performance, Security, Debugging |
| Iterate and collaborate | 6 Evolve | Iteration, Collaboration |
| Build specific app type (CLI, web, API, data) | 7 Specialize | Application-specific guidance |
Each stage traces back to foundational principles in LOD_0:
| Philosophy | Primary Impact |
|---|---|
| 0.1 Intentionality | Stages 1, 3 |
| 0.2 Structure Primacy | Stages 1, 2 |
| 0.3 Rough-to-Fine | Stages 1, 6 |
| 0.4 Data-Centricity | Stages 1, 3 |
| 0.5 Communication as UX | Stage 3 |
| 0.6 Reproducibility | Stages 2, 4, 6 |
| 0.7 Polyglot Pragmatism | Stages 1, 3 |
| 0.8 Defensive Design | Stages 1, 5 |
Cross-references in KB files use: ↑ parent, ↓ child, → sibling/forward, ← back.
- CLAUDE.md — LLM navigation protocol (rough-to-fine, token budget, anti-patterns)
- intent_graphs/ — IntentGraph representation (philosophy + guidelines/style)
- ../software_development_guidelines/ — stack-neutral principles (ownership, assurance, change flow, operation, evolution); this KB keeps only the Python realization
- ../ — index of all development guidelines