Knowledge Folder: Gestructureerde Context voor AI Agents

Het Probleem: Inconsistente Agent Context

AI agents hebben toegang tot je complete codebase, maar missen vaak cruciale context. Ze kennen je architectuur niet, weten niet welke externe APIs je gebruikt, en kunnen geen onderscheid maken tussen belangrijke en bijzaak documentatie. Dit leidt tot inefficiënte workflows en inconsistente code kwaliteit.

De knowledge folder lost dit op door gestructureerde, intelligente context te bieden die agents automatisch kunnen vinden en laden.

Het Knowledge Folder Framework

Een volwassen knowledge folder bestaat uit vier hoofdonderdelen die samen een complete context vormen:

Praktische Indeling per Folder:

Folder	Doel	Belangrijkste Content	Index File
`codebase/`	Project kennis	Architectuur, domein concepten, data modellen	✅ 01-index.md
`external/`	Externe systemen	API docs, library specs, service handbooks	❌ Geen index
`implementation-guidelines/`	Code schrijven	Patterns, testing, setup procedures	✅ 01-index.md
`review-guidelines/`	Code reviewen	Review proces, conventies, standaarden	✅ 01-index.md

1. codebase/ - Project Kern Kennis

Doel: Fundamentele kennis over jouw project die agents nodig hebben om context te begrijpen.

Typische structuur volgens specs:

codebase/
├── 01-index.md                 # Navigatie systeem
├── 02-architecture.md          # Systeem architectuur 
├── 03-processes.md             # Business processen (sequence diagrams)
├── 04-data-models.md           # Data modellen (mermaid ERD)
└── 99-domain-concepts.md       # Domein-specifieke concepten

De 01-index.md werkt als intelligent navigatiesysteem:

markdown

### System Architecture
**File:** @knowledge/codebase/02-architecture.md
**Keywords:** architecture, system, components, services, modules
**When to use:** Understanding overall system design and component relationships

### Business Processes  
**File:** @knowledge/codebase/03-processes.md
**Keywords:** workflow, process, business, sequence, flow
**When to use:** Understanding business workflows and process sequences

### Data Models
**File:** @knowledge/codebase/04-data-models.md  
**Keywords:** data, model, schema, database, entity, relationship
**When to use:** Understanding data structures and database relationships

2. external/ - Externe Diensten & Libraries

Doel: Documentatie van externe systemen die je project gebruikt.

Belangrijke eigenschap: Geen index bestanden - agents refereren direct naar specifieke documentatie.

Voorbeeld uit powertrader-intraday:

external/
├── mermaid/
│   ├── flowchart.md
│   └── sequenceDiagram.md
└── nordpool/
    ├── developers.nordpoolgroup.com_reference_creating-orders.md
    ├── developers.nordpoolgroup.com_reference_rest-api.md
    └── [25+ meer API documentatie bestanden]

3. implementation-guidelines/ - Implementatie Richtlijnen

Doel: Concrete richtlijnen voor het schrijven van nieuwe code.

Voorbeeld uit powertrader-intraday:

implementation-guidelines/
├── 01-index.md
├── 02-nest-api-openapi-setup.md
├── 03-database-migrations.md
├── 04-cron-jobs.md
├── 05-observability.md
├── 06-sentry-integration.md
└── 07-unit-testing.md

De index gebruikt intelligent keyword matching:

markdown

### NestJS API & OpenAPI Setup
**File:** @knowledge/implementation-guidelines/02-nest-api-openapi-setup.md
**Keywords:** nestjs, api, openapi, swagger, setup, bootstrap, main.ts
**When to use:** outlines the standard approach for creating NestJS API setup classes

4. review-guidelines/ - Code Review Standaarden

Doel: Richtlijnen voor het reviewen van code en het handhaven van kwaliteit.

Voorbeeld uit powertrader-intraday:

review-guidelines/
├── 01-index.md
├── 02-review-process.md
├── 03-structure.md
├── 04-architecture.md
├── 05-code-conventions.md
├── 06-data-model-consistency.md
├── 07-nestjs-api-design.md
├── 08-observability.md
└── 09-restful-api-design.md

Speciale variant: Procesbeschrijvingen

Naast review richtlijnen kan deze folder ook procesbeschrijvingen bevatten. Dit zijn uitgebreide execution instructions die agents stap-voor-stap vertellen hoe ze een specifieke taak moeten uitvoeren. Deze bestanden bevatten gedetailleerde workflows onder het kopje "Execution instructions" in de index, in plaats van alleen keywords en context.

Bijvoorbeeld: Een volledig review proces dat agents instrueert welke guidelines te laden, hoe file patterns te analyseren, en in welke volgorde de review uit te voeren. Zie dit voorbeeld van een code review proces voor een complete procesbeschrijving.

Intelligent Index Systeem

Hoe Keyword Matching Werkt

Agents analyseren je verzoek en laden automatisch relevante documentatie:

Scenario 1: API Development

Jouw verzoek: "Help me een nieuwe trading endpoint implementeren"
Agent analyse: Extracteert implement, api, endpoint, trading
Geladen guidelines: implementation-guidelines/02-nest-api-openapi-setup.md + review-guidelines/07-nestjs-api-design.md

Scenario 2: Code Review

Jouw verzoek: "Review deze pull request"
Agent analyse: Analyseert gewijzigde bestanden en code content
Geladen guidelines: Relevante review guidelines gebaseerd op code wijzigingen

Index File Structuur

Elke index volgt deze template:

markdown

# [Folder] Guidelines Index

## Execution Instructions (optional)

### [Process Name]
**File:** @knowledge/[folder]/[XX-filename.md]
**Purpose:** [Purpose description]
**When to use:** [Context description]

## Available Guidelines

### [Guideline Name]
**File:** @knowledge/[folder]/[XX-filename.md]
**Keywords:** keyword1, keyword2, keyword3
**When to use:** [Specifieke context beschrijving]

## Loading Logic
1. **Primary:** Check development request for keywords
2. **Secondary:** Analyze the type of implementation being requested  
3. **Tertiary:** Default to relevant patterns based on file types

Bestandsnaam Conventies

Genummerde Bestanden

01-index.md - Altijd eerst, navigatie entry point
Sequential numbering: 02-, 03-, 04- zonder gaten
Nooit herindexeren: Nieuwe bestanden krijgen volgend beschikbaar nummer
Stabiliteit boven logica: Consistent nummeren belangrijker dan perfecte volgorde

File Reference Patterns

Intern: @knowledge/folder/file.md (zonder backticks!)
Relatief tot knowledge root: Alle paden beginnen met @knowledge/
Consistent formatting: Geen ../ of andere relatieve paden

Praktische Implementatie

Automatische Setup met Agent

Structuur aanmaken: Gebruik /llm-driven-development:verify-agent-setup om de agent een complete knowledge folder structuur te laten aanleggen.

Content toevoegen: Gebruik daarna /llm-driven-development:prime-agent-setup om de agentic context in te laden. Vervolgens kun je de agent instructies geven om project-specifieke guidelines, architectuur documentatie, en externe API specs toe te voegen.

Zie: Je codebase klaarmaken voor agentic setup

Stap 1: Basisstructuur Creëren

bash

mkdir -p knowledge/{codebase,external,implementation-guidelines,review-guidelines}

Stap 2: Index Bestanden Aanmaken

Creëer in elke hoofdfolder (behalve external/) een 01-index.md:

markdown

# [Folder Name] Index

This index helps determine which [folder type] to load based on [context].

## Available Guidelines

### [First Guideline]
**File:** @knowledge/[folder]/02-[filename].md
**Keywords:** [relevant, keywords, here]
**When to use:** [context description]

## Loading Logic
1. **Primary:** Check request for keywords
2. **Secondary:** Analyze request type
3. **Tertiary:** Default patterns

Stap 3: Agent Configuratie

Als je de agentic codebase setup gebruikt (aanbevolen), wordt knowledge folder bewustzijn automatisch toegevoegd aan je AGENTS.md. Deze configuratie wordt dan via symlinks beschikbaar voor alle agents (Cursor, Claude Code, etc.).

Voor handmatige setup: voeg knowledge folder instructies toe aan je agent configuratie bestanden.

Stap 3: Geleidelijk Uitbreiden

Start klein: Begin met één guideline per folder
Voeg toe op basis van behoefte: Nieuwe guidelines wanneer patterns zich herhalen
Gebruik volgend nummer: Geen herindexering van bestaande bestanden
Documenteer keywords: Zorg dat index bestanden actueel blijven

Wanneer te Gebruiken

Nieuwe projecten: Implementeer vanaf dag één voor consistente agent ervaring
Bestaande projecten: Voeg geleidelijk toe wanneer je repetitieve vragen aan agents stelt
Team onboarding: Nieuwe developers krijgen automatisch de juiste context
Code reviews: Reviewers hebben toegang tot actuele standaarden
Refactoring: Agents kunnen architectuur patterns consistent toepassen

Next Steps

Nu je de knowledge folder structuur begrijpt, begin met de agentic codebase setup om alles automatisch te configureren:

→ Je codebase klaarmaken voor agentic setup

Knowledge Folder: Gestructureerde Context voor AI Agents ​

Het Probleem: Inconsistente Agent Context ​

Het Knowledge Folder Framework ​

1. codebase/ - Project Kern Kennis ​

2. external/ - Externe Diensten & Libraries ​

3. implementation-guidelines/ - Implementatie Richtlijnen ​

4. review-guidelines/ - Code Review Standaarden ​

Intelligent Index Systeem ​

Hoe Keyword Matching Werkt ​

Index File Structuur ​

Bestandsnaam Conventies ​

Genummerde Bestanden ​

File Reference Patterns ​

Praktische Implementatie ​

Stap 1: Basisstructuur Creëren ​

Stap 2: Index Bestanden Aanmaken ​

Stap 3: Agent Configuratie ​

Stap 3: Geleidelijk Uitbreiden ​

Wanneer te Gebruiken ​

Next Steps ​

Knowledge Folder: Gestructureerde Context voor AI Agents

Het Probleem: Inconsistente Agent Context

Het Knowledge Folder Framework

1. codebase/ - Project Kern Kennis

2. external/ - Externe Diensten & Libraries

3. implementation-guidelines/ - Implementatie Richtlijnen

4. review-guidelines/ - Code Review Standaarden

Intelligent Index Systeem

Hoe Keyword Matching Werkt

Index File Structuur

Bestandsnaam Conventies

Genummerde Bestanden

File Reference Patterns

Praktische Implementatie

Stap 1: Basisstructuur Creëren

Stap 2: Index Bestanden Aanmaken

Stap 3: Agent Configuratie

Stap 3: Geleidelijk Uitbreiden

Wanneer te Gebruiken

Next Steps