# Fundamentals

The basic concepts you need before you create or operate an AI software factory, explained without tying you to one coding agent.

Source: https://ai-sw-factory.mellicci.dev/fundamentals

## Who it is for

You are a working developer, junior to senior. You have used a coding agent in a chat or terminal, and you have seen words like *skills*, *hooks*, *MCP* and *subagents*. You cannot yet say how they differ or when to use which. This module fixes that, one concept at a time, without hype.

## Basics first, factories later

An AI software factory applies AI automation across the software delivery lifecycle, so agents
do more of the work autonomously while people design, govern and improve the system around them.
That is where things are heading, but it is still an emerging idea with no standard design, and
this module is not about building one.

This module is about the **basics underneath**: the building blocks of the coding agent harness
that every factory is made of. You need to know them well before you can design or operate a
factory successfully, and they pay off straight away in everyday work with a single agent. Think
of it as the first step towards that future:

**Diagram:** The twelve basics of this module, grouped from foundations to autonomy. An illustration of how they relate, not a process — click any block.

- Foundations · what an agent is and what it knows:
  - How coding agents work — model + harness in a loop
  - Instruction files — always-on project knowledge
  - Skills — know-how loaded when needed
- Capabilities · what it can do and what is guaranteed:
  - MCP — reach outside systems
  - Hooks — deterministic guardrails
  - Subagents — delegate in fresh contexts
  - Plugins — share the kit
- Autonomy · running unattended, safely:
  - Headless execution — no one at the keyboard
  - Loops — keep going until done
  - Sandboxing — contain the blast radius
  - Security model — limit what it may do
- Your first feedback loop — the blocks combined into a small factory

## How the module is organised

Every concept has up to three layers. Read as far as you need:

**Diagram:** Layers 1 and 2 teach the primitive and stay vendor-neutral; only layer 3 names files and commands — so most of what you learn carries over if you switch agents.

- 1 · Concept — what it is and why it exists
- → go deeper
- 2 · Example scenario — one real problem, solved on ticket-service
- → build it
- 3 · One page per agent (files, commands, official docs):
  - Claude Code
  - Codex
  - Copilot CLI

<note>

The concept and example-scenario pages are written for any agent that has the primitive. Where an agent
lacks it or names it differently, its page says so.

</note>

## The running example

Every example-scenario page works on the same fictional repository, so the concepts stack up and the last page assembles pieces you have already seen.

| Aspect | `ticket-service` |
|---|---|
| Stack | TypeScript, Node.js 22, Fastify, PostgreSQL via Drizzle ORM |
| Tooling | pnpm, Vitest, ESLint + Prettier, GitHub Actions |
| Repo layout | `src/routes/`, `src/db/` (schema + `migrations/`), `test/`, `docs/` |
| Work tracking | GitHub Issues with labels (`bug`, `feature`, `agent-ready`) |
| Team | 4 developers, each using a different coding agent |
| Pain today | Agents guess commands (npm vs pnpm), skip migration checks, forget formatting, need babysitting, and nobody shares their setup |

Each concept adds one piece to this repository. The module ends with a working feedback loop.

## How to read it

- Read the concepts in order. Later ones assume the mental model from *How coding agents work*.
- Plan about 20 minutes per concept for the concept page and its example-scenario page.
- Keep one idea in mind throughout: the **model** is probabilistic, and the **harness** around it is deterministic. Most design decisions in a factory are about moving something from the first to the second.
- Use the learning path below to see every concept, its track and its status.