Making TYPO3 AI-Ready: How Clear Structures Deliver Better Agent Results

AI agents rarely fail in TYPO3 projects due to a lack of computing power. They fail because of a loss of context: due 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 produces expensive review loops.

That architecture carries more weight than the choice of model is not just a gut feeling. LangChain improved 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. The same model, different results.

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

This article separates two perspectives: 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 the time to familiarise themselves with historical decisions. AI agents work differently: they must identify the relevant signal in a short time with limited context. In 2023, Liu et al. showed in "Lost in the Middle" that language models exhibit a U-shaped attention curve with long contexts – they favour information at the beginning and end, while the middle section loses up to 20% of its effectiveness. Larger context windows exacerbate this problem rather than solving it.

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

What the TYPO3 Core Already Provides  

The TYPO3 ecosystem has been modernising for several versions in a direction that directly benefits AI agents – even if that was not the original intention. Anyone familiar with these Core changes understands why TYPO3 projects today can be structurally better positioned 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. It should be noted that the Schema API is currently marked as internal and may still change during the development of TYPO3 v13. The migration 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; only native PHP attributes (#[Validate], with use TYPO3\CMS\Extbase\Attribute\Validate;) are accepted. The doctrine/annotations library is no longer necessary. For AI agents, this is a clear win: attributes are machine-readable, IDE-navigable, and statically analysable – DocBlock annotations were none of these.

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 that agents can produce in templates – the system reports 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 almost complete in v14. Events are typed classes with clearly defined properties, registered via Services.yaml. For agents, they are infinitely easier to discover and use correctly than the old hook registrations with 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 – however, the infrastructure for them 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 manually searching for outdated patterns.

What You Can Do in Your Project  

The Core modernisation provides the foundation. However, the crucial lever lies within your project: in the extension architecture, the write paths, and the rules you establish for agents.

Property Hooks instead of getters/setters  

Legacy Extbase models are often too large for agents, yet too sparse in content. An agent reads dozens of lines of trivial access methods before the actual business deviation becomes visible. PHP 8.4 Property Hooks shift relevant logic to where it belongs: directly to the property. This saves around 85% of 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 large PHP array, it is an incredibly poor workspace for agents. Content Blocks move the business definition into a declarative YAML file – TCA, SQL, and backend forms are generated automatically. Changing a content type requires 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 not take the easiest route, but the correct one. In TYPO3, this route is called DataHandler. Workspaces, permissions, the reference index, and FAL relations are only processed correctly via this path. Direct QueryBuilder updates may look faster in the short term, but they cost 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 result: persistent rules measurably reduce variance between 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 paths 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; rather, 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 demonstrated the principle in practice: a team of three (later seven) engineers used Codex agents to deliver a production system with around one million lines of code – every line written by agents, no manual coding. 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 – with identical architecture rules. Nevertheless, the agents diverged on basic decisions: whether to copy tags or not, reset status, or carry over due dates. Natural-language specifications are ambiguous, hard to scan, and untestable.

The solution: machine-readable specifications built on patterns that LLMs already know from their training data – Pact Contracts, Design by Contract, Specification by Example. In TYPO3 projects, this principle can be mapped through typed interfaces, contract-based DTOs, and explicit pre-/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 sides: for agents, because they can work more precisely with less context, and for teams, because architectural decisions become more visible and repeatable.

TYPO3 brings an advantage to the table that is often overlooked in the discussion: 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 available and ready for production use. The question is not whether the investment is worthwhile, but how quickly you can bridge the gap between the Core foundation and your 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 to see where AI is still being hindered today, a focused architecture review for TYPO3 projects is the fastest starting point.