Agent Engineering bei Netresearch

Aus realer Reibung wird dauerhaftes Engineering-Wissen.

Q: Welche Rolle spielt AGENTS.md?

AGENTS.md ist ein kompakter Index zur autoritativen Projektwahrheit. Architektur, Commands, Dependencies und Details bleiben in den tatsächlichen Quellen wie docs, composer.json, Makefile, DDEV-Konfiguration und Scripts. Der Harness prüft, dass Referenzen und dokumentierte Commands stimmen.

Skills sind nicht das System. Sie sind eine mögliche Ausgabe eines geschlossenen Lernkreislaufs, der Erfahrungen aus echten Agenten-Sessions klassifiziert, materialisiert, überprüft, technisch durchsetzt und versioniert in die nächsten Projekte trägt.

System verstehen

ProblemgetriebenLearnings entstehen retrospektiv aus echter Arbeit.

Authority firstJede Wahrheit wandert zu ihrem Owner; prüfbare Regeln werden zu Gates.

Source of truthProjektwissen bleibt im Projekt und wird referenziert.

Geschlossener LoopMaterialisieren, prüfen, verteilen, erneut lernen.

Das Gesamtbild

Ein Lern- und Enforcement-System, keine Prompt-Sammlung.

Der wichtigste Perspektivwechsel: Fachskills sind sichtbare Ergebnisse. Die eigentliche Architektur liegt in dem Prozess, der entscheidet, was aus einer Erfahrung werden soll, wo sie dauerhaft gehört und wie ihre Wirkung überprüft wird.

Kurzantwort: Reale Arbeit erzeugt Friction und Learnings. Retro routet sie in die passende Persistenzform. Skill-Repo standardisiert Skill-Artefakte. Assessment prüft Anforderungen. Der Harness verankert Enforcement im Projekt. Distribution bringt die Ergebnisse versioniert in weitere Projekte.

Reale Agentenarbeit

Ein Coding Agent arbeitet in einem echten Repository, mit echten Constraints, Tools, CI und Fehlermodi.

Friction & Learning

Fehler, unnötige Schleifen, gute neue Muster oder fehlende Regeln werden als Lernsignal sichtbar.

Retro klassifiziert

Nicht jedes Learning gehört in einen Skill. Bestimmt werden Authority, Enforceability und Reach – in dieser Reihenfolge.

Materialisieren

Skill, Checkpoint, Projektregel, Harness-Artefakt, Upstream-Patch oder persönliche Regel.

Verifizieren

Validatoren, Evals, Assessment, CI, Hooks und Review machen Wirkung sichtbar.

Reconcile & Prune

Sobald ein Fakt bei seinem kanonischen Owner angekommen ist, schrumpft die lokale Kopie zum Verweis. Ein System, das nur hinzufügen kann, wird schlechter.

Versionieren & verteilen

Skills und Regeln werden als Engineering-Abhängigkeiten reproduzierbar verfügbar.

Nächste Session

Der nächste Agent startet bereits mit der konservierten Erfahrung.

Feedback Loop: Neue Arbeit erzeugt neue Evidenz – das System lernt weiter.

Memory

Skills sind unsere konsolidierte Erfahrung.

Ein Coding Agent hat über Sessions hinweg kein Gedächtnis. Die Frage ist deshalb nicht, wie eine Session gespeichert wird, sondern welche Form eine Erfahrung bekommen muss, damit die nächste Session sie schon mitbringt. Ein Skill speichert nicht die Session – er speichert die aus Sessions destillierte, wiederverwendbare Verhaltensänderung.

          Roh-Erfahrung · episodisch, an eine Session gebunden

            ↓

          Retro = Konsolidierung

            ↓

          Skill  ·  Regel  ·  Gate

            ↓

          konsolidiertes Erfahrungs- und Prozedurwissen

Session-Transkript

Roh-Erfahrung: vollständig, unsortiert und normalerweise vergänglich. Rohstoff, nicht Ergebnis.

Skill

Konsolidierte, wiederverwendbare Erfahrung. Workflow, Entscheidungen und Failure Patterns, destilliert aus realen Sessions.

Checkpoint / Harness

Ausführbare bzw. erzwingbare Erfahrung. Die Lektion steckt nicht mehr im Text, sondern in einem Check, der auch ohne Agenten fehlschlägt.

AGENTS.md

Projekt-Instruktion und Index. Was in diesem Repository gilt und wo die autoritativen Quellen liegen.

Docs / Code / Config

Kanonische Fakten. Sie gehören dem Projekt oder dem Upstream und werden referenziert, nicht kopiert.

personal-rule

Nutzerspezifische dauerhafte Instruktion – eine persistente Anweisung, kein Gedächtnis über vergangene Sessions.

consolidation

Konsolidieren heißt auch löschen.

Ein System, das nur hinzufügen kann, wird schlechter. Deshalb gehören Reconcile & Prune, Outcome-Bewertung und Audit zum Loop: eine Erfahrung, die überholt, widerlegt oder bei ihrem kanonischen Owner angekommen ist, wird zum Verweis reduziert oder entfernt. Dass ungefiltert wiederverwendete Erfahrung Fehler weiterträgt und selbst korrekt aussehende Läufe als Erfahrung irreführend sein können, ist empirisch beschrieben.

no memory store

Nicht alles heißt Memory.

Es gibt keine Vektordatenbank, keine Ähnlichkeitssuche über alte Sessions und keine Ablage vollständiger Lösungswege „für alle Fälle“. Jede Form wird nach ihrer Wirkung benannt – Instruktion, Prüfung, Fakt – statt alles unter eine gemeinsame Speicher-Metapher zu stellen.

Abruf gehört zum Problem: Eine perfekt konservierte Erfahrung, die im richtigen Moment nicht aktiviert wird, ist wertlos. Deshalb wird zweimal gemessen – ob ein geladener Skill hilft, und ob der Agent von selbst erkennt, dass er ihn braucht. Siehe Prüfung.

Entstehung

Retro ist der Learning Router.

Neue Skills entstehen nicht, weil ein Thema groß oder interessant wirkt. Sie entstehen, wenn reale Arbeit eine wiederverwendbare Lücke zeigt. Und selbst dann ist ein Skill nur eine von mehreren möglichen Zielarten.

personal-rule

Persönliche Regel

Eine stabile Präferenz oder Arbeitsweise, die projektübergreifend nur für eine Person gilt. Eine dauerhafte Instruktion – deshalb nicht länger user-memory, der Name bleibt nur als Alias gültig.

project-rule

Projektregel

Eine Konvention oder ein Command, der genau zu diesem Repository gehört und in dessen Agentenindex verankert wird.

skill-update

Skill-Update

Ein bestehender, wiederverwendbarer Skill hat eine echte Lücke, falsche Anleitung oder ein fehlendes Failure Pattern.

new-skill

Neuer Skill

Die Friction offenbart eine neue, wiederkehrende Capability-Kategorie, die kein bestehender Skill sinnvoll besitzt.

checkpoint

Prüfbare Invariante

Eine Regel lässt sich mechanisch oder als definierter LLM-Review gegen ein Projekt prüfen.

harness-artefact

Technisches Enforcement

Die richtige Antwort ist ein Hook, CI-Gate, Linter, Ruleset, Template oder anderes selbsttragendes Projektartefakt.

canonical-source

Kanonische Quelle

Der Fakt gehört einem Artefakt außerhalb des Agent-Systems – offizieller Dokumentation, Code oder einem Schema. Der Fix geht als Patch dorthin; der Skill behält nur den Verweis und das agentenspezifische Delta.

1. Authority

Wem gehört diese Wahrheit? Ein Fakt über die Welt wandert zu seinem kanonischen Owner – oft außerhalb des Agent-Systems. Ein Skill besitzt nur Agentenverhalten und die eigene Prozedur.

2. Enforceability

Kann die Regel als Gate, Check oder Artefakt technisch erzwungen werden? Dann ist das stärker als eine Erinnerung in Prosa.

3. Reach

Erst danach wird entschieden, ob das Learning persönlich, projektlokal oder organisationsweit wiederverwendbar ist.

Paired materialization: Wenn eine Regel im aktuellen Repository technisch enforceable ist und dasselbe Gate in Schwesterprojekten gebraucht wird, kann ein Learning zweigleisig materialisiert werden: das konkrete Gate im Projekt plus eine Skill-Änderung mit dem Installationsrezept für weitere Projekte. Dieselbe Paarung setzt auch upstream an: der Patch an den kanonischen Owner plus der Skill-Cleanup, der die lokale Kopie auf einen Verweis reduziert, sobald der Patch angenommen ist.

Projektkontext

Das Projekt beschreibt sich selbst.

AGENTS.md ist ein kompakter Index, keine zweite Dokumentation. Der Agent wird von dort zu den autoritativen Quellen geführt. Dadurch bleibt Wissen dort, wo es ohnehin gepflegt wird – und ist unabhängig von einem bestimmten Agenten-Client oder zentralen Wissensdienst.

docs/ARCHITECTURE.md

Architektur, Grenzen, wichtige Flows und langfristige Strukturentscheidungen.

composer.json / composer.lock

Deklarierte Commands, Pakete, Constraints und reproduzierbarer Dependency-Zustand.

Makefile / scripts/

Tatsächlich ausführbare Projektoperationen statt kopierter Command-Listen.

.ddev/config.yaml / Docker

Lokale Entwicklungsumgebung, Services und technische Runtime-Konfiguration.

CI / Hooks / Rulesets

Der überprüfbare Teil der Projektverfassung: was wirklich blockiert oder bestanden werden muss.

Wichtig: Projektkontext muss nicht in jeden Skill kopiert werden. Der Skill weiß, wo er nachsehen soll; das Repository besitzt die Wahrheit. Der Harness prüft unter anderem, dass Referenzen auflösen und dokumentierte Commands zu den realen Targets passen.

Skill-Qualität

Skill-Inhalt muss seinen Kontextpreis verdienen.

Ein Skill ist kein Sammelbecken für alles, was zum Thema bekannt ist. Er trägt genau die Information, deren Präsenz zum richtigen Zeitpunkt das Verhalten des Agenten messbar verbessert.

Organisations- und projektspezifisches Wissen

Konventionen, Tooling und Entscheidungen, die ein allgemeines Modell nicht aus öffentlichem Wissen ableiten kann.

Version- oder Ökosystemfakten, die Modelle zuverlässig falsch haben

Vor allem neue, nischige oder bewegliche Fakten – solange ein besserer dynamischer Owner nicht existiert.

Retro-born Failure Patterns

Symptom → Ursache → erforderliches Verhalten → Verifikation. Reale Minenkarte statt generischer Best Practice.

Ausführbare Validatoren

Deterministische Checks gehören bevorzugt in Scripts oder Checkpoints statt in Prosa, die bei jedem Lauf neu interpretiert wird.

Inference Suppression

Regeln wie „lies Quelle X, rate Y niemals“, wenn genau dieses Raten in realen Sessions zu Fehlern oder Schleifen geführt hat.

Anti-Rationalization Guards

Klare Schranken gegen bekannte Abkürzungen: keine Erfolgsbehauptung ohne ausgeführte Prüfung, kein Überspringen eines Gates.

canonical ownership

Ein Fakt, ein Owner.

Fakten und Triggerphrasen sollen eine kanonische Heimat haben – oft außerhalb des Agent-Systems, in offizieller Dokumentation oder Code. Andere Skills referenzieren den Owner, statt denselben Fakt zu kopieren und später auseinanderzudriften.

eval evidence

„Das Modell vergisst es“ ist ein Test-Claim.

Wenn Skill-Inhalt nur damit begründet wird, dass ein Modell etwas zwar weiß, aber nicht zuverlässig aktiviert, sollte ein A/B-Eval den Nutzen sichtbar machen. Der gemessene Delta gilt dann für eine Skill-Version unter einem Modell, einem Harness und einem Eval-Set – ein stärkerer Actor kann denselben Schluss selbst ziehen, dann bleibt nur der Kontextpreis.

          BEHALTEN  workflow · failure pattern · org policy · decision rule · verification

          REFERENZIEREN  lange Beispiele · API-Tabellen · Templates · Detail-Checklisten

          NICHT DUPLIZIEREN  Fakten mit anderem canonical owner · Projektzustand · generische Lehrbuchtexte

Prüfung

Aus Anleitung wird eine prüfbare Spezifikation.

Checkpoint-enabled Skills definieren Anforderungen, die ein Assessment systematisch gegen ein Repository prüfen kann. Qualität beginnt dadurch nicht mit manueller Fehlersuche, sondern mit einem strukturierten Gap-Report.

01Skills entdecken

Passende Skills und ihre Preconditions bestimmen den relevanten Prüfbereich.

02Mechanisch prüfen

Dateien, Inhalte, Regex, JSON/YAML, Commands und Plattformzustände deterministisch bewerten.

03LLM Reviews

Nur dort, wo echte semantische Beurteilung nötig ist; gruppiert nach Domäne.

04Gap Report

Fehler und Warnungen werden zur priorisierten Task-Liste statt iterativer Discovery.

05Fix & Re-Verify

Fixes können an den verantwortlichen Skill geroutet und anschließend erneut geprüft werden.

Mechanical checkpoint

Für stabile, deterministisch messbare Invarianten. Schnell, reproduzierbar, ohne Interpretation.

LLM review

Für Architektur-, Dokumentations- oder Qualitätsurteile, die Kontextverständnis brauchen.

Harness gate

Für Regeln, die vor einer Aktion blockieren müssen – etwa Hook, CI, Branch Protection oder Linter.

Zwei Ebenen von Evals

per-skill A/B eval

Hilft der Skill, wenn er geladen ist?

Derselbe Prompt mit und ohne Skill-Kontext. Gemessen wird der Delta gegen eine No-Skill-Baseline – gebunden an Skill-Version, Modell, Harness und Eval-Set, nicht als universelle Eigenschaft des Skills.

system eval

Merkt der Agent, dass er ihn braucht?

Ein realistischer, absichtlich unterspezifizierter Auftrag – ohne Angabe von Skill, Tool oder Methode. Discovery und richtige Aktivierung sind damit Teil des Tests, nicht seine Voraussetzung.

Warum beides: Ein Eval, das dem Agenten die Methode vorgibt, misst Prompt-Befolgung. Erst der Open Forward Review in agent-system-evals prüft, ob der Agent den Auftrag selbst richtig rahmt – mit mehrdimensionalem Scoring statt einer Kennzahl, weil ein Lauf, der gut untersucht und nichts Brauchbares berichtet, und ein Lauf, der richtig rät, beide Fehlschläge sind.

Enforcement

Der Harness macht Agent-Readiness selbsttragend.

Der Harness installiert nicht bloß Hinweise für den Agenten. Er schafft Artefakte, die danach durch CI, Hooks, Branch Protection und Repository-Konventionen unabhängig vom Skill-Lauf weiterwirken.

LEVEL 1

Basic

AGENTS.md existiert als kompakter Index und dokumentiert die zentralen Projekt-Commands.

LEVEL 2

Verified

CI prüft Harness-Integrität; Referenzen lösen auf; dokumentierte Commands stimmen mit Targets; Architektur ist auffindbar.

LEVEL 3

Enforced

Required Checks, Hooks, PR-Templates und Drift Detection machen wichtige Regeln technisch schwer umgehbar.

Integration über Artefakte: Der Harness prüft die Outputs spezialisierter Skills, nicht deren interne Implementierung. Ein korrekt erzeugtes AGENTS.md, ein passender Hook oder eine valide CI-Regel ist prüfbar, unabhängig davon, welcher Agent oder Skill es erstellt hat.

Distribution

Skills sind versionierte Engineering-Abhängigkeiten.

Ein Skill ist nicht nur eine Markdown-Datei im Home-Verzeichnis. Repository-Struktur, Versionierung, Trust, Discovery und Projekt-Indexierung bilden eine reproduzierbare Lieferkette.

Source Repository

SKILL.md, References, Scripts, Checkpoints, Evals, Manifest und Validierung liegen versioniert an einer kanonischen Quelle.

Package / Direct Source

Composer-Package, Skill in einem normalen Package oder gelockte GitHub-/Projektquelle. Trust wird explizit verwaltet.

Projekt-Discovery

Das Projekt kennt seine Skills, kann sie indexieren und lädt Detailwissen progressiv nur dann, wenn es gebraucht wird.

git-workflowdocker-developmentsecurity-auditphp-modernizationgo-developmentcontext7data-toolsgithub-projectenterprise-readinessconcourse-cijiraTYPO3 domain skills

Warum es lernt

Die nächste Session muss nicht dieselbe Lektion noch einmal bezahlen.

Der Wert liegt nicht darin, möglichst viele Skills zu besitzen. Der Wert liegt darin, reale Fehlerkosten in dauerhaft bessere Ausgangsbedingungen zu transformieren.

          historisches Problem

            ↓

          Retro erkennt Friction + Learning

            ↓

          klassifiziert nach Authority, Enforceability und Reach

            ↓

          Skill / Checkpoint / Harness / Projektregel / Upstream-Patch

            ↓

          Eval + Assessment + CI/Hook

            ↓

          nächste reale Session startet besser

Das Ziel: Erfahrungswissen wird nicht nur dokumentiert, sondern in die stärkste sinnvolle Form überführt. Was sich prüfen lässt, wird geprüft. Was sich erzwingen lässt, wird erzwungen. Was Urteil und Kontext braucht, bleibt als präzise Agenten-Anleitung erhalten.

Lokales Q&A

Frag die Seite – lokal im Browser.

Der Assistent nutzt – sofern im Browser verfügbar – die eingebaute Chrome Prompt API über LanguageModel. Die Seite selbst ist die Grounding-Quelle. Es gibt keinen eigenen Q&A-Backend-Endpunkt und keine simulierten Modellantworten.

On-device Q&A mit echtem Fallback

Ist das lokale Sprachmodell verfügbar, beantwortet es Fragen ausschließlich anhand dieser Seite. Ist die API nicht verfügbar, übernimmt eine deterministische Seitensuche und zeigt die relevantesten belegten Abschnitte.

Lokale AI wird geprüft …

FAQ

Antworten auf die Kernfragen.

Was ist das Netresearch Agent Engineering System?

Ein geschlossener Lern- und Enforcement-Kreislauf für Coding Agents. Reale Arbeit erzeugt Reibung und Learnings; Retro klassifiziert sie; Skills, Checkpoints, Projektregeln, Harness-Artefakte oder Upstream-Patches an die kanonische Quelle materialisieren sie; Assessment und CI prüfen die Wirkung; die nächste Session profitiert davon.

Wie entstehen neue Skills?

Nicht aus vermuteten Themenlisten, sondern retrospektiv aus realen Problemen, wiederkehrender Reibung und wiederverwendbaren Learnings. Ein neuer Skill ist nur eine mögliche Zielart; Fakten mit fremdem Owner gehen upstream an ihre kanonische Quelle, mechanisch prüfbare Regeln werden bevorzugt als Checkpoint oder Enforcement materialisiert.

Wo liegt in diesem System das Memory?

In der Form, die eine Erfahrung nach der Konsolidierung bekommt. Das Session-Transkript ist Roh-Erfahrung und vergänglich; Retro konsolidiert daraus wiederverwendbare Erfahrung als Skill, ausführbare bzw. erzwingbare Erfahrung als Checkpoint oder Harness-Artefakt, Projekt-Instruktion in AGENTS.md, kanonische Fakten in Docs, Code und Config sowie eine dauerhafte persönliche Instruktion als personal-rule. Es gibt bewusst keine Vektordatenbank und keine Ähnlichkeitssuche über alte Sessions: Konsolidieren schließt Löschen ein, weil ungefiltert wiederverwendete Erfahrung Fehler weiterträgt.

Welche Rolle spielt AGENTS.md?

AGENTS.md ist ein kompakter Index zur autoritativen Projektwahrheit. Architektur, Commands, Dependencies und Details bleiben in den tatsächlichen Quellen wie docs/, composer.json, Makefile, DDEV-Konfiguration und Scripts. Der Harness prüft, dass Referenzen und dokumentierte Commands stimmen.

Was ist der Unterschied zwischen einem Skill und einem Checkpoint?

Ein Skill trägt Workflow, Entscheidungen, Failure Patterns und nicht-mechanische Anleitung. Ein Checkpoint kodiert eine prüfbare Invariante, die mechanisch oder als definierter LLM-Review gegen ein Projekt bewertet werden kann.

Wie wird verhindert, dass Skills zu großen Wissenssammlungen werden?

Skill-Inhalt muss seinen Kontextpreis verdienen. Bevorzugt werden organisationsspezifisches Wissen, reale Failure Patterns, volatile Fakten, die Modelle zuverlässig falsch haben, ausführbare Validatoren, Inference-Suppression und Anti-Rationalization-Guards. Fakten und Trigger haben einen kanonischen Owner – oft außerhalb des Agent-Systems; Details werden on demand referenziert.

Wie werden Skills und Regeln geprüft?

Automated Assessment entdeckt passende checkpoint-enabled Skills, prüft Preconditions, führt mechanische Checks und gruppierte LLM-Reviews aus, erzeugt einen Gap-Report und kann Fixes an den verantwortlichen Skill routen. Danach wird erneut geprüft.

Wie werden Agentenregeln technisch durchgesetzt?

Wenn eine Regel enforceable ist, wird sie nicht nur als Prosa konserviert. Je nach Fall wird sie als Checkpoint, Pre-Commit-Hook, CI-Check, Linterregel, Branch Protection oder anderes Harness-Artefakt materialisiert. Das Prinzip lautet: Authority zuerst – wem gehört diese Wahrheit? –, danach Enforceability, dann Reach.

Wie werden Skills verteilt?

Skills sind versionierte Engineering-Abhängigkeiten. Sie können über Composer-Pakete, Skills in normalen Packages, direkte gelockte GitHub-Quellen sowie weitere Distributionswege in Projekte gelangen. Discovery, Trust und AGENTS.md-Indexierung bilden eine gemeinsame Pipeline.

Primärquellen

Die Architektur ist ausführbar dokumentiert.

Die Seite fasst die öffentlich versionierten Netresearch-Artefakte zusammen. Für Implementierungsdetails bleibt das jeweilige Repository der kanonische Ort.

retro-skillFriction-Erkennung, Learning-Routing und Materialisierung. agent-harness-skillAgent-Readiness, Verifikation, Bootstrap und Enforcement. skill-repo-skillSkill-Struktur, Qualitätsregeln, Release und Repository-Standards. automated-assessment-skillCheckpoint-Laufzeit, Gap Reports, Autofix und Re-Verification. agent-system-evalsOpen Forward Reviews: misst am unterspezifizierten Auftrag, ob der Agent den Job selbst richtig rahmt. composer-agent-skill-pluginDiscovery, Trust, Locking und Composer-basierte Distribution. Netresearch auf GitHubFachskills und generische Engineering-Skills als sichtbare Outputs des Systems.