A manifesto for building with AI

Understand before
you accelerate.

AI helps us write code faster. Understanding helps us build the right thing. A shared approach to planning, reviewing, and delivering software with intention.

Read the manifestoPut it into practice

By Carlos Santana Roldán

UNDERSTAND FIRST

The order matters.

  1. 01

    Understand

    The outcome. The context. The unknowns.

  2. 02

    Decide

    Shared evidence. Clear responsibility.

  3. 03

    Build

    AI-assisted. Human-owned. Verified.

Better questions. Clearer decisions. Better software.

Time reserves attention. Evidence establishes readiness.

01 / The manifesto

A shared way to work.

Faster implementation makes understanding more valuable. These are the principles we choose to work by.

  1. 01

    Start with the outcome.

    Understand who benefits, what needs to change, and how success will be recognized. Make the problem clear before choosing a solution.

  2. 02

    Connect purpose and implementation.

    Bring the business goal and the technical plan together. Make scope, behavior, dependencies, and acceptance examples explicit.

  3. 03

    Make understanding visible.

    Explain the plan in your own words. Compare interpretations, test critical assumptions, and use evidence to reveal gaps before they become rework.

  4. 04

    Match review to risk.

    Keep simple changes lightweight. Give consequential decisions the attention and expertise they need. The process should help the work move.

  5. 05

    Let AI assist. Keep people accountable.

    Use AI to explore, draft, and implement. People verify important claims, own decisions, and remain responsible for the result.

  6. 06

    Resolve blockers before moving forward.

    Record concerns and obtain informed consent on the current plans. Readiness means enough evidence to proceed, with no known material blocker.

  7. 07

    Learn from what you deliver.

    Validate behavior, inspect rework and waiting, and improve the next plan. Revisit affected decisions when new evidence changes the picture.

Three different questions

Time spent is not proof of understanding.

01

Review effort

How much attention do we need?

Reserve and record time for reading and review. It consumes real team capacity.

02

Readiness

Do we understand enough to begin?

Look for compatible interpretations, testable examples, evidence, and resolved blockers.

03

Delivery forecast

When might we deliver?

Use comparable delivery history, available capacity, queues, and dependencies.

Review minutes do not convert into coding hours or a delivery date.

02 / In practice

From a request to a result.

A practical loop, scaled to the change. Start with two short plans, then use evidence to move forward.

Goal PlanProduct / ticket owner

What and why

The user outcome, boundaries, business rules, and concrete acceptance examples.

SSD PlanImplementing developer

How it will work

Software Specification and Design: behavior, dependencies, failure scenarios, tests, and recovery.

  1. 01

    Define & classify

    Clarify the outcome and boundaries. Identify the risk and the perspectives the review needs.

  2. 02

    Design & verify

    Prepare a proportional technical plan. Gather evidence for important claims and unknowns.

  3. 03

    Read & explain

    Protect reading time. Review independently, explain the plan in your own words, and compare interpretations.

  4. 04

    Resolve & consent

    Resolve contradictions, update both plans, and record consent with any remaining concerns.

  5. 05

    Build & validate

    Pull work when capacity exists. Build with AI, review the code, test, and verify delivery.

  6. 06

    Measure & adapt

    Inspect rework, missed blockers, and waiting. Use what you learn to improve the next cycle.

How much review is enough?

Match depth to risk. Unknowns may need a timeboxed prototype whose evidence goes back into the plan.

Trivial
Copy or layout changes: an independent check.
Low
The owner, implementer, and reviewer; short plans and asynchronous review.
Standard
Product, implementer, peer, and QA perspectives.
High
Standard review plus relevant specialists, especially for payments, permissions, migrations, or sensitive data.
What does “ready” look like?

Check six dimensions: goal, scope, behavior, dependencies, risk and recovery, and verification.

Red
A blocking gap. Resolve it; never average it away.
Amber
A recorded concern. Give it an owner and a response.
Green
Sufficient evidence to proceed in this dimension.

Proceed with current plans and no unresolved blockers. A material discovery reopens only the affected decisions and participants.

A small example: a refund

“Refund requested” and “refund completed” describe different states. If the provider times out, it may still have processed the request.

Keep the refund pending until the provider confirms completion.

Normal
Confirmation of completion updates the refund status.
Duplicate
Repeated requests cannot refund twice.
Timeout
Keep it pending and reconcile the original request.

Start small

Try it. Learn. Keep what helps.

  1. 01

    Calibrate

    Look back at 5–10 completed tickets.

  2. 02

    Observe

    Try the review without blocking delivery.

  3. 03

    Apply

    Use the readiness gate for standard and high-risk work.

  4. 04

    Simplify

    Inspect outcomes and remove unnecessary steps.

03 / The author

Principal Engineer

Carlos Santana
Roldán.

Carlos Santana Roldán is a Senior Web Developer with 20 years of hands-on experience delivering high-impact web products. As Lead Full-Stack Engineer at Universal Music Group, he designs and ships scalable systems, guides engineering best practices, and mentors developers across React, Node.js, and TypeScript. He is also an author of React books, with five publications.

UnderstandFirst brings those ideas together: make understanding a shared responsibility, use AI with intention, and learn from real delivery.

Go to Carlos Santana’s ProfileView the presentation

Go deeper

The ideas behind the manifesto.

Explore the Understanding Estimation series by Carlos Santana Roldán.

Part 01

Understanding Estimation for the AI Coding Era

Rethinking planning when AI changes implementation effort.

LinkedInPart 02

From Review Time to Readiness

Making understanding visible through evidence and informed consent.

LinkedInPart 03

From Readiness to Team Delivery

Connecting readiness with capacity, delivery, and learning.

LinkedIn
View the original presentation