MCAF Concepts

Managed Code Coding AI Framework

Developed and sustained by Managed Code
March 2026

21 min read

1. What MCAF Is

MCAF is a framework for building real software with AI coding agents.

It defines how to:

The goal of MCAF:

Use AI to build real products in a way that is predictable, safe, and repeatable.

MCAF has three core elements:

These concepts define the framework (the “what” and “why”).
TUTORIAL.md is the bootstrap procedure (the “how”).
Repository AGENTS.md files apply both to a specific solution.

1.1 Bootstrap Surface

v1.3 is skill-first.

Bootstrap stays minimal:

Canonical install entry point:

Optional direct shortcuts:

2. Context

Context is everything needed to understand, change, and run the system.

2.1 Repository Context

In MCAF, repository context includes:

Anything that materially affects development, verification, or operation belongs in the repo.

2.2 Documentation Layout

A typical MCAF repo keeps durable docs under docs/:

This is a reference layout, not a rigid folder law. The important part is that the repo has clear homes for architecture, behaviour, testing, development, and operations.

2.3 Bootstrap Templates

Public bootstrap templates are intentionally minimal:

Authoring scaffolds for architecture docs, feature specs, ADRs, governance, and maintainability do not live in docs/templates/. They live in skills under references/ or assets/.

2.4 Skills

Skills are small, versioned workflow packs that make repetitive agent work predictable.

A skill contains:

Recommended target locations in a consuming repo:

The public skill catalog lives on the Skills page:

Platform-specific bundles can stay small and still be explicit. .NET skills are maintained outside this repository in the Managed Code Skills catalog. Install the .NET skills you need from that catalog, then document the exact dotnet build, dotnet test, dotnet format, analyze, complexity, coverage, and other quality-gate commands in the consuming repo’s AGENTS.md. For .NET code changes, the task is not done when tests are green if the repo also configured formatters, analyzers, complexity checks, coverage, architecture tests, or security gates. Agents should run the repo-defined post-change quality pass before completion, and any external .NET helper should still include a Bootstrap When Missing section so agents can detect, install, verify, and first-run the tool without guessing.

2.5 Context Rules

The canonical contract is MCAF-ARCH-001.

2.6 Vertical-Slice Architecture for AI Coding

A vertical slice is one end-to-end business capability or use case, not one technical layer. A slice such as Orders owns its affected UI, API or backend behaviour, contracts, persistence or integrations, tests, infrastructure, and feature documentation.

In this policy, the solution is the complete product delivery boundary—not merely a .sln or .slnx file and not merely the backend. Its solution-owned frontend, backend, contracts, tests, infrastructure, and docs live and evolve together.

For an AI coding agent, the slice is the default unit of context and delivery. The agent starts from docs/Architecture.md, reads the applicable root and local AGENTS.md files, opens docs/Features/<SliceName>.md, and then works only in the matching slice paths. This lets the agent find the full behaviour without scanning the repository or guessing which generic service, controller, component, or test folder belongs to the feature.

The solution remains one repository, while toolchains may keep separate projects. Reuse the exact same slice name and internal convention across those roots:

src/Backend/Features/Orders/
src/Frontend/Features/Orders/
src/Contracts/Features/Orders/
tests/Features/Orders/
docs/Features/Orders.md

With this structure, a request such as “add order cancellation” has one deterministic scope: read the Orders feature doc and applicable governance, then update the affected Orders backend, frontend, contract, test, and documentation surfaces together.

Do not organize feature ownership primarily as repository-level Controllers/, Services/, Repositories/, Components/, or generic test buckets. Technical subfolders may exist inside a slice, but the business capability remains the owner.

To structure a solution:

  1. Inventory backend, frontend, contract, test, infrastructure, and documentation roots.
  2. Choose one canonical <SliceName> naming and casing convention.
  3. Choose colocated slices or mirrored Features/<SliceName>/ paths.
  4. Record the convention and slice-to-surface map in root AGENTS.md and docs/Architecture.md.
  5. Add one docs/Features/<SliceName>.md behaviour and verification source for every feature.
  6. Keep feature-owned code in the slice; move only genuinely multi-slice code into shared building blocks.
  7. Require every change to name its slice and keep all affected surfaces aligned.

2.7 Executable Feature Requirements and ADR Implementation

MCAF-REQ-001 makes requirements the input to architecture, agent tasks, code, and verification—not a prose artifact written afterward.

Every non-trivial docs/Features/<SliceName>.md contains:

Create an ADR before implementation when a feature changes boundaries, public contracts, data, dependencies, security, deployment topology, cross-cutting standards, or migration architecture. The ADR must include an executable implementation contract: ordered stages, exact slice/file ownership, dependencies, migration/rollout/rollback, agent roles, tests, pass conditions, and join evidence. Accepted means the decision is approved; Implemented means the implementation and verification evidence actually exist.

Canonical contract: MCAF-REQ-001.

3. Verification

Verification is how the team proves that behaviour and code quality meet expectations.

3.1 Test Levels

MCAF expects layered verification:

The goal is not “one test per feature.”
The goal is enough automated evidence to trust the change.

Integration tests are the backbone because they prove that a slice works through real boundaries, not just isolated units.

3.2 Verification Rules

3.3 Verification Artifacts

Under MCAF-REQ-001, non-trivial feature docs and architecture-affecting ADRs MUST point to:

4. Instructions and AGENTS.md

Instructions define how AI agents behave in the repository and how they improve over time.

4.1 Root and Local AGENTS.md

Every MCAF repo has a solution-root AGENTS.md.

In multi-project solutions, each project or module root also has a local AGENTS.md.

Root AGENTS.md owns:

Local AGENTS.md owns:

4.2 Rule Precedence

Agents follow this order:

  1. Read the root AGENTS.md.
  2. Read the nearest local AGENTS.md.
  3. Apply the stricter rule if both apply.
  4. Do not silently weaken root policy in a local file.

4.3 Required Content

Root AGENTS.md stays current with:

Project-local AGENTS.md files stay current with:

4.4 Maintainability Limits

MCAF requires a Maintainability Limits section in AGENTS.md with stable keys:

These values are repo policy, not framework constants.

MCAF may show starter values, but the active limits live only in the consuming repo’s AGENTS.md.

4.5 Self-Learning

Chat is not memory.

Stable corrections, preferences, and recurring mistakes should become:

If the same mistake happens twice, the framework expects the rule to be made durable. Self-learning is a cornerstone of the framework, not an optional habit.

4.6 Hard Rules for Instructions

5. Coding and Testability

MCAF coding rules exist to keep systems changeable and testable.

5.1 Design Policy

5.2 Maintainability Policy

5.3 Constants and Configuration

Meaningful literals are not scattered through the codebase.

Extract shared values into:

Hardcoded values are forbidden.

String literals do not belong in implementation logic. If a string matters, define it once as a named constant, enum value, configuration entry, or dedicated type and reference that symbol everywhere else.

5.4 Hard Rules for Coding and Testability

6. Perspectives

MCAF describes responsibilities using four perspectives.

6.1 Product

6.2 Dev

6.3 QA

6.4 AI Agent

Humans still own approval and merge decisions.

7. Development Cycle

7.1 Describe

Before heavy coding:

  1. update or create feature docs
  2. update or create ADRs if architecture changes
  3. align test expectations
  4. identify the right skills

7.2 Brainstorm

For non-trivial work, start with a root-level <slug>.brainstorm.md and keep it concise. The brainstorm records:

Brainstorm first, think through the task, then convert the chosen direction into a working plan. Do not create a brainstorm for simple, short, or obvious work where the path is already clear.

7.3 Plan

For non-trivial work, create a root-level <slug>.plan.md after the brainstorm direction is chosen, and keep it current. The plan records:

Before implementation starts, run the full relevant test baseline. If anything is already failing, add each failing test to the plan with its symptom, suspected or confirmed root cause, and intended fix path.

7.4 Implement

7.5 Verify

Run verification in layers:

  1. changed tests
  2. related suite
  3. broader required regressions and the full relevant suite
  4. analyzers, formatters, and any configured architecture, security, mutation, or other quality gates
  5. complexity checks and any other configured code-quality tools
  6. coverage comparison against the pre-change baseline

7.6 Update Durable Context and Close the Task

After implementation:

8. AI Participation Modes

MCAF supports three common AI participation modes.

8.1 Delegated

The agent executes scoped work under current docs, skills, and AGENTS.md.

8.2 Collaborative

The agent and engineer iterate together on design, code, tests, and docs.

8.3 Consultative

The agent reviews, critiques, or drafts options while humans retain implementation control.

8.4 Mandatory Model-Tier Orchestration

For non-trivial implementation work, MCAF separates expensive reasoning from bounded code production:

The mandatory run protocol is:

  1. finish MCAF-REQ-001 feature requirements and every required ADR implementation contract
  2. build a task graph with stable IDs, dependencies, disjoint write ownership, artifacts, tests, completion states, and join conditions
  3. use strong reasoning for architecture, ambiguity, security, and final review; use the least expensive capable models for bounded exploration, implementation, test work, and documentation
  4. spawn only independent workstreams; serialize same-file work and give shared contracts or migrations one integration owner
  5. monitor native task status, steer or replace stuck agents, and wait for all required results
  6. accept only explicit complete, blocked, failed, or cancelled states with evidence; idle and unverified summaries are not completion
  7. have the planning model inspect every result and diff, then run integrated repository verification

For Codex, official guidance supports read-heavy explorer, execution-focused worker, and project custom agents with per-agent model/reasoning configuration; Codex can wait for all requested agents and consolidate their results. For Claude Code, choose subagents for bounded delegation, background sessions for human-monitored independent work, and experimental agent teams only when workers need shared tasks or messaging. Claude Code exposes current-session work through /tasks and background sessions through claude agents. See the official Codex subagents, Claude Code parallel agents, Claude Code subagents, and Claude Code agent teams documentation.

Simple work does not require delegation when orchestration overhead exceeds the task. For non-trivial work, failure to delegate routine coding must have a concrete recorded reason such as unavailable model routing, insufficient worker capability, inseparable high-risk decisions, or unsafe ownership overlap.

The canonical contract is MCAF-AI-001.

The repo may choose different modes per task, but the same verification and governance rules still apply.

9. Adopting MCAF in a Repository

Use the tutorial as the canonical install flow:

  1. Open Tutorial.
  2. Follow the tutorial flow to fetch templates and install the needed skills.
  3. In multi-project solutions, add project-local AGENTS.md files using the governance skill.
  4. Restart the agent so it reloads the installed skills.

Adoption is complete when: