Registre Knowledge — Context Nexus

Que contient Knowledge ?

Domain knowledge · Glossaire métier · Architecture map · Conventions & patterns · Anti-patterns · Contraintes réglementaires · Decision Contexts · Conséquences observées des décisions passées.

Humains vs Agents IA

Humain

Se réfère pour comprendre le contexte, juger de la pertinence d'une décision, onboarder rapidement, éviter de répéter les erreurs passées.

Agent IA

S'ancre dans le domaine pour ne pas halluciner, produit du code cohérent avec l'existant et respectueux des conventions sans qu'on les lui rappelle.

Asymétrie : jugement vs cohérence.

Modes de consommation

System Prompt

Les conventions universelles et anti-patterns absolus vont dans le system prompt. Courts, sans nuance, toujours vrais.

RAG

Les Decision Contexts, l'architecture map et le glossaire métier vont dans l'index vectoriel. Trop volumineux pour le system prompt, récupérés par RAG à la demande.

Structure d'un artefact

Chaque artefact Knowledge est un fichier markdown avec un frontmatter YAML définissant son registre, niveau, owner, statut et mode de consommation.

---
register: knowledge
level: team
owner: tech-lead
status: active
consumption-mode: rag
last-validated: 2026-06-03
---

# Decision Context — Event-driven indexation

## Situation
P95 latency spikes to 1.8s during mass catalogue updates.
Cause: synchronous writes to Elasticsearch from catalog-updater service.

## Options evaluated

### CQRS with separate read model
Rejected: high maintenance cost for a 7-person team.
Reference incident: similar pattern on project X (2024), two P1s.

## Decision taken
Async event-driven indexation: catalogue updates produce Kafka events
consumed by a dedicated indexer → Elasticsearch.

## Observed consequences
(to be completed after 30 days in production)

Indexation RAG

Les artefacts Knowledge sont découpés en chunks par concept atomique, puis embarqués dans un index vectoriel.

from langchain.text_splitter import MarkdownHeaderTextSplitter
from langchain_community.vectorstores import Chroma
from langchain_community.embeddings import SentenceTransformerEmbeddings

def index_knowledge(nexus_root: str, team: str) -> Chroma:
    splitter = MarkdownHeaderTextSplitter(
        headers_to_split_on=[("##", "section"), ("###", "subsection")]
    )
    docs = []
    for level in ["org", f"intermediate/{team_bu}", f"teams/{team}"]:
        for path in glob(f"{nexus_root}/{level}/knowledge/**/*.md"):
            chunks = splitter.split_text(open(path).read())
            for chunk in chunks:
                chunk.metadata.update({"level": level, "source": path})
            docs.extend(chunks)

    return Chroma.from_documents(
        docs,
        SentenceTransformerEmbeddings(model_name="all-MiniLM-L6-v2"),
        persist_directory=f".chroma/{team}"
    )