- 10When are specifications not enough?
- 11Where is the state of the work kept?
- 12Who prepares a change before coding starts?
- 13What does impact analysis tell you, and when does it run?
- 14How do coding agents use the graph?
- 15How is each change checked, and how does the graph stay current?
- 16Who decides which work agents do?
- 17How do managers see what people and agents are doing?
- 18What happens across many products?
- 19What about existing systems and technical debt?
- 20What changes for the team?
- 21What results have teams seen?
Home / Follow the story / Act 2: The methodology
Loading the video
Transcript
5. Four principles
Semantic Engineering answers the problem with four principles that apply to every kind of project. The first principle is to record the knowledge that governs the application in a knowledge graph, with explicit items and the relationships between them. Each agent asks the knowledge graph for just the part its task needs. The second principle is that every change is analyzed against the knowledge graph before code is written, and agents cannot ignore what the analysis finds. The specification still describes what to build, including the details the graph leaves out, and the knowledge graph governs how each change fits the application. The third principle is named ownership: every part of the knowledge graph has a person accountable for keeping it accurate. When part of the knowledge graph falls out of date, the methodology holds the owner of that part responsible. The fourth principle is validation gates: automatic checks that test every change against the knowledge graph. Each validation gate records a pass or a fail that the team can audit.
On the site: The Methodology · Agentic Software Engineering and Modernization, powered by Semantic Engineering
6. The four layers
For an application in use, the knowledge graph has four layers, and each layer is called an ontology: a structured description of one kind of knowledge. The Functional Ontology holds personas, outcomes, scenarios, steps and actions, and the Product Owner keeps it. The Design Ontology holds screen components and their building blocks, page templates and user flows, kept by the UX Designer and the design system owner. The Architecture Ontology holds services, boundaries, dependencies, data stores and integrations, kept by the Architect and the tech lead. The Code Ontology holds modules, classes, functions, endpoints and database schemas, kept by the Engineering Team. Links connect the layers, so one search can follow a user action through to the screen component, the service and the code function behind it. On one user story about email alerts, following those links found fourteen affected parts of the architecture and fifteen code changes across five repositories. The search runs before any code is written. Every item in the graph cites its source: the document, design frame, ticket or code file it came from.
On the site: The Four-Layer Ontology · Cross-Layer Traversal · Citations at Every Layer
7. What goes into the graph
A common first instinct is to put everything into the graph. Within a few sprints, the maintenance burden overwhelms the team. The methodology uses a rule, called the aperture, to decide what enters the graph. Every decision has a blast radius: the other decisions, artifacts and behaviours that have to change when the decision changes. A persona definition, a service boundary or a shared API contract has a wide blast radius, so it belongs in the graph. The wording on a single button affects nothing beyond that button, so it stays in the specification and the code. When the answer is unclear, the element stays out of the graph until the team is sure. The aperture starts narrow and widens as the team gains confidence, reaching its full width by about sprint twelve. The graph is partitioned by product, with one graph per product or application. Each graph is kept to one product, because the cost of a query grows with the size of the graph. Where two products integrate, links connect their graphs.
On the site: Aperture · The Blast Radius Test · How the Aperture Matures
8. Keeping the graph accurate
Every change is checked against all four layers of the graph before it can merge. An agent called the PR Validation Agent runs this check on every pull request before it merges into the main branch. The check fails when a change misses a required outcome, duplicates an existing design component, crosses a service boundary, or breaks something that depends on it. When the code changes, the KG Sync Agent updates the graph before the pull request merges, so the graph matches the main branch. The health of the graph itself is measured too, with twenty-nine metrics and fourteen verification checks. A merge that fails one of the most critical checks is blocked until the problem is fixed. The four custodians stay human. Each custodian works with information that exists only in conversations and decisions between people, such as customer calls, compliance decisions, vendor contracts and user research. No system an agent can read contains that information. Agents draft updates to the graph for the custodians to approve, and enforce the graph when code merges.
On the site: The Validation Gate · Governance and Metrics · The 14 Verification Checks
9. Two kinds of graph
Semantic Engineering covers three kinds of work: building a new application, called greenfield; changing an existing one, called brownfield; and replacing an old system, called legacy modernization. The three kinds of work use two shapes of graph, depending on whether the end state keeps changing or is fixed in advance. New and existing applications keep changing, so greenfield and brownfield work share the four-layer graph. A greenfield graph is built up as the application grows, and a brownfield graph is extracted from the existing application and then maintained by its owners. For an application of more than 2 million lines, extraction typically completes in two to three weeks. Legacy modernization has a fixed end state, chosen at the start of the project. The modernization graph has three parts: a graph of the old system built from its code, a graph of the new system defined by the custodians, and a specification that connects the two. The same four custodian roles govern both shapes. When a modernization completes, its graph converts to the four-layer graph. The right process for continuous work depends on how complex the application is.
On the site: One Methodology, Three Use Cases · Brownfield Extraction · Zones of AI-Assisted SDLC
Choose a path
The full video in six parts and an appendix, one part at a time.