Making TYPO3 AI-Ready: Clear Structures, Better Agents

AI agents rarely fail in TYPO3 projects for want of computing power. They fail because they lose context: to TCA branches, Extbase boilerplate, implicit side effects, and rules that only exist in people's heads. This is exactly where it is decided whether an agent implements a change cleanly or triggers expensive review loops.

The idea that architecture counts for more than the choice of model is not just a gut feeling. LangChain raised the success rate of its coding agent from 52.8% to 66.5% without a single model upgrade. Only the environment changed: better verification loops, clearer context, tighter feedback loops. Same model, different results.

The architecture of a codebase determines the quality of the agent – not the other way around.

This article keeps two perspectives apart: what has the TYPO3 Core already done to make code more machine-readable, and what can you, as an extension developer, add to your project?

Table of Contents  

Why AI Readability Matters Now  

In traditional projects, code was structured for humans who had time to familiarise themselves with historical decisions. AI agents work differently: with limited context, they have to spot the relevant signal quickly. In 2023, Liu et al. showed in "Lost in the Middle" that language models exhibit a U-shaped attention curve over long contexts: they favour information at the beginning and the end, while the middle loses up to 20% of its effectiveness. Larger context windows make this worse rather than better.

For TYPO3, this means the more boilerplate, repetition, and implicit rules an extension contains, the higher the risk of imprecise patches, wrong shortcuts, and needless queries. If a TCA file runs to 400 lines of nested arrays, an agent sees a lot of syntax and very little business signal.

What the TYPO3 Core Already Provides  

For several versions now, the TYPO3 ecosystem has been modernising in a direction that directly benefits AI agents, even if that was never the original intent. Once you know these Core changes, it becomes clear why TYPO3 projects today can be structurally better placed for agentic workflows than many other PHP systems.

Schema API and Record API replace raw TCA arrays  

Since v13.2, the Schema API has offered a typed, object-oriented approach to TCA structures. Instead of accessing $GLOBALS['TCA'] directly, developers use an API that provides fields, types, and relations as objects. The accompanying Record API (v13.3) automatically transforms raw database values into typed objects: Record, FileReference, DateTimeImmutable. Relations are resolved via lazy loading.

For agents, this means less array navigation, clearer types, and a predictable object model. Note that the Schema API is currently marked as internal and may still change during the development of TYPO3 v13. The move to the Schema API is an ongoing Core initiative: the Core is gradually phasing out TCA as a PHP array.

Strict types and PHP attributes in Extbase  

TYPO3 v13 enforces strict typing in Extbase core classes: ActionController, PersistenceManager, ObjectStorage, and domain model base classes are consistently strictly typed. Anyone extending Extbase classes must adapt their signatures.

In v14, the clean-up continues: Extbase annotations (@Extbase\Validate) have been removed, and only native PHP attributes (#[Validate], with use TYPO3\CMS\Extbase\Attribute\Validate;) are accepted. The doctrine/annotations library is no longer needed. For AI agents this is a clear win: attributes are machine-readable, IDE-navigable, and statically analysable, none of which DocBlock annotations ever were.

Fluid 5.0 with strict type validation  

Fluid 5.0 in TYPO3 v14 validates ViewHelper arguments more strictly than before. Null values no longer generate empty HTML attributes, but rather omit the attribute entirely. Custom ViewHelpers require explicit return type declarations. Variable names with an underscore prefix are reserved.

This strictness reduces the class of errors agents can introduce in templates: the system flags type errors immediately at runtime instead of letting them slip through as silent misbehaviour.

PSR-14 Events instead of legacy hooks  

The migration from hooks and Signal/Slot to PSR-14 Events has been underway since v10 and is all but complete in v14. Events are typed classes with clearly defined properties, registered via Services.yaml. For agents, they are far easier to discover and use correctly than the old hook registrations with their magic strings and implicit parameters.

Content Blocks as a declarative alternative  

Content Blocks (v2.0 since November 2025, v14-compatible) shift the definition of content elements, record types, and page types into a single config.yaml. TCA, SQL, and backend forms are generated automatically. Core integration began in v13 with the Schema API, Record Transformation API, and automatic TCA field value transformation.

Content Blocks are not a Core extension but a community-maintained package; the infrastructure they rely on, however, has been deliberately anchored in the Core.

Rector and Fractor as community-funded migration tools  

For TYPO3 v14, 48 new Rector rules and 11 Fractor rules were created, funded by the Community Budget. Rector transforms PHP code (deprecations, breaking changes), while Fractor covers TypoScript, FlexForms, Fluid, and composer.json. For agents, this means automated migration instead of hunting for outdated patterns by hand.

What You Can Do in Your Project  

The Core modernisation lays the foundation. The decisive lever, though, lies within your own project: in the extension architecture, the write paths, and the rules you set for agents.

Property Hooks instead of getters/setters  

Legacy Extbase models are often too large for agents yet too thin on substance. An agent reads dozens of lines of trivial accessor methods before the actual business logic comes into view. PHP 8.4 Property Hooks put the relevant logic where it belongs: right on the property. This cuts roughly 85% of the boilerplate per field.

<?php
declare(strict_types=1);

final class Article extends AbstractEntity
{
  protected string $title = '';

  public function getTitle(): string
  {
      return $this->title;
  }

  public function setTitle(string $title): void
  {
      $this->title = trim($title);

<?php
declare(strict_types=1);

final class Article extends AbstractEntity
{
  public string $title = '' {
      set {
          $value = trim($value);
          if ($value === '') {
              throw new \InvalidArgumentException('Title must not be empty');
          }
          $this->title = $value;
      }
  }
}

Content Blocks instead of TCA scattering  

TCA is powerful, but as a sprawling PHP array it makes a terrible workspace for agents. Content Blocks move the business definition into a declarative YAML file, and TCA, SQL, and backend forms are generated automatically. Changing a content type now means editing one file instead of four.

name: webconsulting/faq-item
title: FAQ Item
typeName: wc_faq_item
fields:
- identifier: question
  type: Text
  required: true
- identifier: answer
  type: Textarea
- identifier: teaser_image
  type: File

DataHandler as the only write path  

As soon as an agent modifies data in TCA-managed tables, it must take the correct route rather than the easiest one. In TYPO3, that route is the DataHandler. Workspaces, permissions, the reference index, and FAL relations are only handled correctly along this path. Direct QueryBuilder updates may look quicker in the short term, but they cost you integrity later on.

<?php
declare(strict_types=1);

use TYPO3\CMS\Core\DataHandling\DataHandler;
use TYPO3\CMS\Core\Utility\GeneralUtility;

$data = [
  'tt_content' => [
      'NEW123' => [
          'pid' => 42,
          'CType' => 'textmedia',
          'header' => 'KI-fitte TYPO3-Architektur',
      ],
  ],
];

Project rules: .cursorrules, AGENTS.md and .cursor/rules  

An agent without project rules falls back on generic training patterns. An empirical study by UC Irvine (MSR 2026) analysed 401 repositories with Cursor rules and identified a clear taxonomy: Conventions, Guidelines, Project Information, and LLM Directives. The finding: persistent rules measurably reduce variance across sessions, models, and developers.

AGENTS.md has established itself as a cross-tool standard (Linux Foundation, Agentic AI Foundation). Cursor, Codex, Copilot, Windsurf, and Devin read it natively. For TYPO3 projects, the most critical rules belong in this format:

ALWAYS use TYPO3 DataHandler for write operations on TCA-managed records.
NEVER inject DataHandler via the constructor of another service.
ALWAYS prefer Content Blocks over manual TCA/SQL for new content types.
ALWAYS use PHP attributes (#[AsEventListener]) instead of Services.yaml tags.
ALWAYS run PHPStan and tests before proposing a refactoring as complete.
NEVER bypass Schema API with direct $GLOBALS['TCA'] access in new code.

Harness Engineering: The Environment is the Product  

The concept of Harness Engineering describes a fundamental shift: the code is not the product; the environment in which agents produce code is the product. A harness comprises verification loops (tests, linters, CI), context management (documentation, rules), constraints (architecture rules, dependencies), and feedback systems (logs, metrics).

OpenAI showed the principle in practice: a team of three (later seven) engineers used Codex agents to ship a production system of around one million lines of code, every line written by agents and not a single one coded by hand. The engineers designed the harness, not the code.

For TYPO3 projects, a Minimum Viable Harness consists of:

Structured specifications instead of prose  

Stefan van Egmond had 20 AI agents implement the same feature under identical architecture rules. Even so, the agents diverged on basic decisions: whether to copy tags, reset status, or carry over due dates. Natural-language specifications are ambiguous, hard to scan, and untestable.

The solution is machine-readable specifications built on patterns LLMs already know from their training data: Pact Contracts, Design by Contract, Specification by Example. In TYPO3 projects, this principle maps onto typed interfaces, contract-based DTOs, and explicit pre- and post-conditions.

Prioritised Roadmap for Existing TYPO3 Projects  

Conclusion  

Optimising TYPO3 for AI does not mean writing for machines instead of humans. It means building a codebase that works better for both: for agents, because they can work more precisely with less context, and for teams, because architectural decisions become more visible and repeatable.

TYPO3 has one advantage that is often overlooked in this debate: the Core is already modernising in the right direction. The Schema API, strict types, PSR-14 Events, and the Content Blocks infrastructure are not promises for the future; they are here now and ready for production. The question is not whether the investment pays off, but how quickly you can close the gap between the Core foundation and your own project architecture.

The three strongest levers on the project side remain: less boilerplate (Property Hooks, Content Blocks), more explicit contracts (Typed Properties, PHP attributes, Schema API), and mechanical safeguards (Harness Engineering with PHPStan, tests, and CI gates).

If you want to assess your existing TYPO3 codebase and find out where AI agents are still being held back, a focused architecture review for TYPO3 projects is the fastest place to start.