FIDES: AI-Human Native Architecture

FIDES is an open software architecture paradigm that structures code so people and AI agents can create software together, and both can keep working in it safely. It organizes a codebase by what the code does and who owns it, not by what kind of code it is. Every feature lives in one folder. Every rule has one owner. Dependencies point in one direction. A short list of rules, published as an AGENTS.md file, tells any developer or any AI agent exactly where new code goes, and an automated check fails the build when the rules are broken.

FIDES is built for co-creation. A person and an agent work on the same feature, in the same folder, and each can read what the other wrote. That cuts both ways by design: the agent gets the complete context it needs to generate correctly, and the person gets code they can review in one sitting, extend without archaeology, and maintain years later. Readability and maintainability are not documentation goals in FIDES; they are what the structure is for.

FIDES is language independent. The same structure has been built in PHP and in C#, from the same specification. Its motto: every unit keeps its word.

The problem: legacy structure fights the context window

Most codebases are organized by kind of code. Controllers sit in one folder, services in another, then repositories, DTOs, mappers, events, listeners and templates. Understanding one feature, such as enrolling a student, means opening a dozen folders. Inheritance chains add more places to look.

That shape was already expensive for people. Maintenance meant archaeology: find the six places a change touches, keep them consistent, and hope nothing else quietly depended on the piece you moved. Code nobody can hold in view is code nobody can safely maintain, and code an agent wrote is hardest of all to maintain when it lands scattered.

For AI generation it is worse. An AI agent works inside a limited context window. Asked to build a feature in a scattered codebase, it cannot hold the whole feature in view, so it guesses at the pieces it cannot see. The output comes back brittle, partly hallucinated, and spread across six directories in a shape no one chose.

The industry's current answer is better prompts. FIDES is a different answer: give the agent a better target. Design the architecture so that one feature fits in one read, the rules an agent may use are visible in one constructor, and the correct shape is the nearest example to imitate.

The paradigm in one minute

FIDES code lives in five zones:

Zone Holds Example
Features One use case per folder, with its view and assets features/enroll/
Integrations How the app reaches the world: database, email, external APIs integrations/database/
Delivery How the world reaches the app: web, API, CLI, worker delivery/web/
Entities The rules that are true everywhere, and each concept's own settings entities/course/
Shared Contracts that no single entity owns shared/unit_of_work

The rules that hold the shape:

  • One concept, one place. A use case lives in one folder: its logic, its view, its assets.
  • One owner. Every piece of data has exactly one owner, and only the owner changes it. An entity owns what it must keep consistent and saves it in one write.
  • Dependencies point inward, toward the rules that are true everywhere. The outside world stays at the edges. Only the wiring code knows which integrations exist.
  • No inheritance. Small units are composed, never extended. Nothing extends anything.
  • Messages are recorded, not sent inline. An entity records what happened in the same transaction that saves it. A worker delivers the message only after the commit succeeds.
  • Configuration is declared, then overridden. Each entity declares its settings, defaults and validation in its own folder. A config tree holds overrides only, in YAML. The database stores transactional and reporting data, not configuration. Secrets come from environment variables, never from config files.
  • Rules are required; tools are examples. FIDES states what must be true. It does not mandate a framework or a library.

The test of a FIDES codebase: a new developer, or an AI agent, understands any feature in five minutes, and you can come back after six months and find your way.

Why people and AI build better together in a FIDES codebase

  • Small, complete context, for both readers. A feature folder plus the entities it names is everything an agent needs to read, and everything a person needs to review the agent's work. Neither searches a dozen layers to find the pieces; neither invents the pieces they cannot find.
  • Readable in one sitting. A feature reads top to bottom, the way it runs. Reviewing a change means reading its folder, not tracing a call graph across the codebase.
  • Maintainable because changes stay local. Fixing or extending a feature touches its folder and the entities it names, so the reach of a change is visible before anyone makes it, whichever side of the partnership makes it.
  • Contracts say what is possible. A feature's constructor lists exactly which stores and services it may use. The agent works inside boundaries it can see, and the person can see them too.
  • One obvious place for new code. Something a user does is always a new feature folder. Agents stop inventing new layers.
  • Good code to imitate. Agents copy the nearest example. When every feature has the same shape, the nearest example is a correct one.
  • Rules a machine can check. The import rules and the ban on inheritance are enforced by a check that fails the build. The agent can run the check itself and fix what it broke before a person ever sees it.

AGENTS.md: the rules, written for agents

Every FIDES repository carries an AGENTS.md at its root: the rules on one page, written so an AI agent can follow them on the first try. It works the way a .cursorrules file does, for any agent that reads project instructions, including Cursor, Copilot and Claude. The heart of it is one short list:

Where code goes
- A rule always true for a concept       -> its folder in entities/
- Something a user or system does        -> a new folder in features/
- A new way the world reaches the app    -> delivery/
- A new way the app reaches the world    -> integrations/, behind a contract
- A contract no single entity owns       -> shared/
- Setting overrides                      -> config/, one YAML file per owner

The full template, with the checks to run before finishing, is in the FIDES repository (docs/ai.md and the example app's AGENTS.md). Adopting FIDES starts with adopting that file: teams report the shape of generated code changes as soon as the agent has a standard to aim at instead of a style to guess.

Proof: a production system, rewritten under FIDES

FIDES was not designed in the abstract. It was worked out while rewriting Business OS, the production system Subschema runs its consulting business on: time tracking, invoicing, and live integrations with QuickBooks, Google Sheets, Notion and monday.com.

The rewrite had one hard constraint: no integration could be set up again. The FIDES version runs on the same database, the same configuration file, the same encrypted tokens and the same OAuth callback address as the system it replaces, so cutover is a code swap, not a migration. The production application's own test suite was ported as the parity harness, and every feature of the running system, time, board, monday sync, money, budgets and owner draws, was rebuilt to match it: 171 source files, zero inheritance, and an architecture check that passes clean.

Smaller proofs ship with the spec. The course-enrollment example in the repository shows the canonical shape, including a filled-in AGENTS.md. A sample work-order and system-status application has been built twice from the same specification, once in PHP and once in C#, with its full test suite passing in both, because the paradigm is the structure, not the language.

Where FIDES fits

Good fit: server-side web applications and APIs; monoliths and modular monoliths with a database; the backend behind a single-page or mobile app; command-line tools and background workers that share rules with a web app; one service inside a larger system.

Poor fit: the single-page app itself and other rich clients, whose frameworks bring their own structure; libraries and SDKs; small scripts; data pipelines; game engines. Feature folders and composition over inheritance still carry over to those.

Questions and answers

What is FIDES?
FIDES is an open software architecture paradigm for structuring codebases so that people and AI agents can create software together and keep it readable and maintainable for both. It organizes code into five zones (Features, Integrations, Delivery, Entities, Shared), gives every rule and every piece of data one owner, forbids inheritance, and enforces its rules with an automated build check and a root AGENTS.md file.

How is FIDES different from Clean Architecture or hexagonal architecture?
Those architectures separate layers to protect the domain from infrastructure, and FIDES shares that instinct. FIDES differs in what it optimizes for: locality. A feature is one folder a reader, human or AI, can hold in one view, rather than a slice cut through every layer. FIDES also specifies things the layered architectures leave open: where configuration lives, how messages leave a transaction, and the AGENTS.md contract that tells an AI agent where new code goes.

Does FIDES work with Cursor, Copilot or Claude?
Yes. FIDES is tool independent. Its agent-facing surface is the AGENTS.md file, which those tools read as project instructions, and the architecture check, which any of them can run. The paradigm was developed with AI agents writing production features under its rules.

What languages does FIDES support?
Any language. FIDES specifies structure, ownership and dependency direction, not syntax. Reference material exists for PHP and C#; folder and file names follow each language's own conventions.

How do I start using FIDES?
Read the specification in the repository, starting with docs/why.md and docs/rules.md. Copy the AGENTS.md template into your repository and adapt the names to your stack. Add an architecture check that fails the build on cross-zone imports and inheritance. Then build one feature the FIDES way and compare.

Who develops FIDES?
FIDES is developed by Subschema, a consulting firm that builds and runs production systems with it, including its own business operations platform. The specification is currently at draft 0.2 and is being tested against real applications; the rules will change as that testing teaches us more.

Get the specification

The full specification, the AGENTS.md template and the examples live in the FIDES repository on GitHub:
https://github.com/Subschema-LLC/FIDES