2.2.3 - Understanding the Shape of the System Before You Change It

Map the system shape: say which part owns what, what each part depends on and where the important handoff happens.

System shape

Is the system shape clear?

The call

Map the boundaries before building across them. Otherwise AI helps you connect parts that should have stayed separate.

Sharpen the system shape with AI

This is a Build idea, so there are two AI moves: first Sharpen the system shape using the prompt below, then Build it with AI, vibeCoding the thinnest working code that tests the decision. This idea also calls for Build an AI agent.

New here? Let your AI do this with you. Paste your problem into Guide me and it builds a prompt that walks you through this in ChatGPT or Claude. You do not need to know how to prompt.

Prefer to drive the AI yourself? Give ChatGPT or Claude this page and ask it to help. For skill.txt, the Claude Code plugin and other ways in, see how to use vibe2value.

Or copy this prompt into AI chat, replace the bracketed lines with your real system shape and keep the instruction exactly as visible here. It helps you put your build/system-shape.md together by refining your three lines until two people would make the same product decision from them.

You are checking whether this system shape is clear enough before you move forward.

Constraint:
The system shape must be specific enough that two people would draw the same core boundaries from it.

Example of the standard:
Vague: "The system has a few services that connect together."
Sharp: "The frontend handles the search interface and user context. The Worker orchestrates auth checks, database reads and AI search calls. The database stores preferences and history. Auth is handled externally. Each part has one job and one clear handoff to the next."
The sharp version is specific enough that two people would draw the same core boundaries. The vague one is not.

Working draft:
Part or boundary: [which part owns what]
Dependency or handoff: [where the important dependency or handoff happens]
Ownership boundary: [what each part should not own]

Task:
Decide whether this system shape is specific enough that two people would draw the same core boundaries. If it already is, say so. If it is vague, rewrite it to meet the standard in the example above.

Check:
- Would two people interpret this the same way?
- Does it stay concrete enough to guide the next step?
- Can you state which part owns what, what each part depends on and where the important handoff happens?

Return:
- Verdict: clear, or needs work
- The corrected three lines, or the original three if already clear
- What was vague, and the one change that fixed it

Copy this into AI chat. Replace the bracketed parts. Keep the rest unchanged. AI will likely suggest refinements based on what you enter. Use those to sharpen your thinking, not replace it.

There are six ways to work with AI across a build. This idea's AI moves are noted above. See Working with AI for all six and where each fits.

The same idea on a recipe card

Before cooking a big meal you picture the kitchen: which station preps, which one cooks, what gets handed from the board to the pan to the plate. Move the chopping board somewhere random without knowing what depends on it and the whole flow jams just as the orders pile up.

Understanding the shape of the system is that mental map of the kitchen. Name the boundaries between the parts, what depends on what and where one part hands off to the next, before you start moving things. See the layout first and your change helps, the way a cook who knows the kitchen does not knock the sauce off the stove reaching for a spoon.

The recipe card is just a simple example, using everyday cooking ideas everyone understands, to make the concept clear. See the recipe card.

What it really means

System shape is not an abstract architecture diagram. It is the practical boundary between parts, the dependencies they carry and the handoffs that matter. Until you can name one boundary, one dependency and one handoff between parts, design decisions stay fuzzy. AI can help sketch architecture, but it cannot decide which boundary reduces risk in your system.

Make the system shape concrete

Compare the broad version with a version you can actually test.

Too vague: The system has a few services that connect together.
Concrete enough to test: The frontend handles the search interface and user context. The Worker orchestrates auth checks, database reads and AI search calls. The database stores preferences and history. Auth is handled externally. Each part has one job and one clear handoff to the next.

The second version lets two people draw the same core boundaries from it.

Understanding the shape of the system means turning the tangle in your head into a structure you can actually reason about. Once you can see the few parts and how they connect, you can tell what a change will touch before you make it.

Check the system shape

Pass: You can say which part owns what, what each part depends on and where the important handoff happens.
Fail: If architecture still means a rough stack or a list of services, the system shape is not clear enough yet.

Do not move into system design or implementation work until this passes.

What you'll walk away with

This post is about the framing decision: the words that pin down what this idea actually means for your build, before any code. You'll come out with your own knowledge-base/build/system-shape.md written and sharpened: the system shape pinned down as a decision, three worked examples to map against your own surface and an AI prompt that pressure-tests it until two people would make the same call.

Write it down

Your system-shape.md is a real file in your project. The AI forgets everything between sessions. It reads this file each time to pick up what you already decided, on this idea or another part of the build. Write it down once instead of explaining it again.

knowledge-base/shape-build-launch/build/system-shape.md is just a suggested name and place for this information. The name and the location are just how we organise this type of documentation, not something you have to follow. Call the file and put it wherever suits your project. What matters is that it is written down in a format that is easily understood by both people and the AI.

The .md ending is markdown, a plain text format often used for documents kept in a code repository like GitHub. It is just the common way people store this kind of writing alongside their code.

Writing it down is how you keep good context for your AI. See Keep the signal, not the noise for why this matters across a whole build.

Risk and mitigation

Risk: Letting system shape drift while features expand, which creates unclear ownership and fragile behaviour under load.
Mitigation: Define one boundary decision per change and validate it against a real user-critical flow before release.

Key takeaway

Do not move forward until you can say which part owns what, what each part depends on and where the important handoff happens.

How to document your system shape

Write your system shape up in full so your AI has the whole picture: the answer, why you believe it, what you are optimising for, where you might be wrong and the standing instruction it should follow. Keep it in a file with your project like this.

# System shape

## Answer
Part or boundary: [which part owns what]
Dependency or handoff: [where the important dependency or handoff happens]
Ownership boundary: [what each part should not own]

## Evidence
Why you believe this. Conversations, examples, tickets, your own experience.

## Decision
What you are optimising for and what you are saying no to.

## Risk
Where you might be wrong and what would tell you.

## AI instruction
The standing note your AI reads on this project.

Here is one filled in so you can see what good looks like, grounded in the recipe card idea from earlier.

## Answer
Part or boundary: The chopping board station
Dependency or handoff: It hands prepped food to the pan, then to the plate
Ownership boundary: The prep cook owns the board, the line cook owns the pan

## Evidence
When the board and the pan were run by the same person under pressure, prep fell behind and the line stalled.

## Decision
Optimising for clear handoffs between stations. Saying no to blurring who owns the board and who owns the pan.

## Risk
A handoff can be missed if nobody owns the moment food leaves the board. Name the owner on each side.

## AI instruction
Map the kitchen as stations: the board hands prepped food to the pan, then to the plate. Keep the prep cook owning the board and the line cook owning the pan, and respect the handoffs between them.

What now?

Apply it. Guide me turns what you are building into a prompt that walks you through this idea.

Get all 27. The guide is a free coffee-length read with the whole method. Join free and it is yours to download.

Get a hand. Work with me and we will work out together what is worth doing. The first conversation is free.