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

AI agents in TYPO3 projects rarely fail due to a lack of computing power. They fail because of a loss of context: due to TCA branching, Extbase boilerplate, implicit side effects, and rules that exist only in people's heads. This is exactly where it is decided whether an agent implements a change cleanly or produces expensive review cycles.

The fact that architecture carries more weight than model selection 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 within a limited context in a short amount of time. In 2023, Liu et al. demonstrated in "Lost in the Middle" that language models exhibit a U-shaped attention curve in long contexts – they favour information at the beginning and the end, while the middle section loses up to 20% in 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 follow-up questions. If a TCA file contains 400 lines of nested arrays, an agent sees a lot of syntax and very little domain 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 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 typed, object-oriented access 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. The migration to the Schema API is an ongoing core initiative – the core is gradually replacing 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 (#[Extbase\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 things.

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; instead, the attribute is omitted. 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, rather than letting them slip through as silent malfunctions.

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. The 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 was deliberately anchored in the core.

Rector and Fractor as Community-Funded Migration Tools  

For TYPO3 v14, 45 new Rector rules and 11 Fractor rules were created, funded by the Community Budget. Rector transforms PHP code (deprecations, breaking changes), whilst 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 decisive lever lies within your project: in the extension architecture, the write paths, and the rules you lay down 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 domain deviation becomes visible. PHP 8.4 Property Hooks shift relevant logic to where it belongs: directly to the property. This saves around 85% 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 exceedingly poor workspace for agents. Content Blocks shift the domain definition into a declarative YAML file – TCA, SQL, and backend forms are automatically generated. A change to the content type requires 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 most convenient path, but the correct one. In TYPO3, this path 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 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 product is not the code, but the environment in which agents produce code. A harness encompasses verification loops (tests, linters, CI), context control (documentation, rules), constraints (architecture rules, dependencies), and feedback systems (logs, metrics).

OpenAI demonstrated the principle in practice: a team of three (later seven) engineers delivered a production system with around one million lines of code using Codex agents – every line written by agents, no manual code. 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 architectural rules. Nevertheless, the agents diverged on fundamental decisions: whether to copy tags, reset status, or carry over due dates. Natural-language specifications are ambiguous, difficult to scan, and untestable.

The solution: machine-readable specifications built on patterns that LLMs already recognise 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 this 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 of 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 safeguarding (Harness Engineering with PHPStan, tests, and CI gates).

If you want to evaluate your existing TYPO3 codebase to see where AI is still being bottlenecked today, a focused architecture review for TYPO3 projects is the quickest starting point.