Module 1: Architecture Foundation

Invariant

Bad prompts get the blame, but bad structure does the damage. Before you write a single component, you need a folder contract, a route map, and clear rules about which files belong to whom. That is what this module sets up.

Key idea

Structure is not overhead. It is what gives AI agents clear boundaries so every edit lands in the right place. Get this right and the rest of the course flows.

This module includes

Time: about 2 hours of focused work
You finish with: an architecture diagram, a folder contract, and your first Continuity Packet committed to your repo
Start by reading the intro, then work through the exercises in order

The two pillars behind every decision in this module.

Outcome

A project that doesn't fall apart when you add the tenth feature.

Deliverable

Your architecture diagram, a committed folder contract, and the first Continuity Packet for your project.

Lessons

·Why laying out the architecture before writing code saves you days later
·App Router conventions: where routes, layouts, and loading states live
·Separating pages, components, lib, and API routes cleanly
·Naming things so AI agents (and future-you) can navigate the repo
·File ownership: drawing edit boundaries agents can respect
·Writing your first Continuity Packet from a blank file
·The folder contract: one concern per directory, no exceptions
·Treating the route map as a living document you actually update
·Server vs. client code: where the line sits in App Router
·When a file should split and when it should stay whole
·Feeding architecture context into your prompts
·Stopping ad-hoc folder creation before it starts

Exercises

·Write a folder contract for your project. Compare it to the route map. Fix the mismatches.
·Use one Claude prompt to scaffold the entire directory structure. See how close it gets.
·Capture your architecture decisions and immediate next steps in a Continuity Packet and commit it.

Proof Checklist

Proof

☐Folder contract is committed and matches the actual directory tree
☐Route map reflects every page that exists in the repo
☐npm run build exits clean
☐git show --stat HEAD shows only the files you intended to change
☐git show --name-only HEAD matches your declared file targets

Anti-pattern

Letting AI create folders on the fly is the fastest way to lose control of your project. Define the structure first, then hand it to the agent as a constraint it must follow.

Your first foundation exercise

Before you write any feature code, set up the docs that will guide every AI session from here on. This exercise takes about 20 minutes and gives you a repo foundation that actually works.

1. Run the docs generator prompt.
Go to the toolkit and copy the universal docs generator prompt. Paste it into ChatGPT and answer the questions it asks about your project. It will output a set of markdown files tailored to your stack.
2. Create the docs files in your repo.
Make a docs/ folder at your repo root. Save each generated file there. Read through them once and fix anything that looks wrong. Then commit them:
mkdir -p docs # save each file from ChatGPT into docs/ git add docs/ git commit -m "docs: add project docs kit"
3. Pick your hotspot list for the next week.
Look at what you plan to build this week. List the files you expect to touch. Put them in docs/HOTSPOTS.md using the template below. Everything not on this list is off limits for AI agents. You can update the list as your plans change.
4. Define verification commands for your stack.
Open docs/VERIFICATION.md and make sure it lists the exact commands that must pass before any commit. For a Next.js project that means npx tsc --noEmit and npm run build. For Python it might be pytest and mypy. For Go, go build and go test. These commands are the proof bar. Nothing gets committed until they all pass clean.

When you finish this exercise, your repo has real structure. Every AI task from here on reads these docs before it starts, stays within the hotspot boundaries, and proves its work with your verification commands.

What good looks like

Hotspot discipline

If a file is not on the hotspot list, no agent touches it. This single rule prevents most AI-caused regressions.

Week 1 hotspot registry

Copy this template into docs/HOTSPOTS.md. Fill in the files you plan to work on this week. Update it as your focus changes.

# Hotspots

Last updated: YYYY-MM-DD

## Active hotspots (files agents may edit this week)
- [e.g. app/page.tsx]
- [e.g. app/dashboard/page.tsx]
- [e.g. app/components/Header.tsx]

## Shared files (no agent may edit without approval)
- layout.tsx
- middleware.ts
- package.json
- next.config.ts

## Staging rule
Never run git add -A.
Stage only the files listed in your hotspot.
Verify with: git diff --name-only --cached

## Multi-agent boundaries (if running parallel agents)
Agent A: [file list]
Agent B: [file list]
Agent C: [file list]

If two agents need the same file, serialize. One finishes
and pushes before the other starts.

Start small. Three to five files is enough for week one. As your project grows, this file grows with it.

All modules Next: Working with AI