Module 2: Working with AI

Outcome

You stop guessing at prompts. Outputs get predictable.

Deliverable

A prompt library you actually reuse: spec templates, execution templates, and a HANDOFF format.

Lessons

• ·Why ChatGPT is better for specs and Claude is better for execution
• ·Bounding a task: one issue, one file target, one outcome
• ·Writing spec prompts with context, constraints, and acceptance criteria
• ·Execution prompts that produce diffs instead of essays
• ·Continuing a conversation vs. starting fresh, and when each wins
• ·Assembling a reusable template kit you won’t throw away
• ·Spotting hallucinations and recovering without starting over
• ·Governor blocks: how to restrict what an agent is allowed to touch
• ·Running parallel agents without them stepping on each other
• ·The HANDOFF packet as a contract between prompt and proof
• ·Knowing when to re-spec vs. when to iterate on what you got
• ·Versioning your prompts so you can tell what changed and why
• ·Model selection, temperature, and output format in practice

Exercises

• ·Spec a feature in ChatGPT, then rewrite that spec as a Claude execution prompt. Ship the result.
• ·Create 5 prompt templates: feature, bugfix, refactor, copy change, scaffold. Commit them to your repo.
• ·Take one real task through the full Spec, Execute, Verify cycle. Log the HANDOFF output.

• ☐Prompt library committed with at least 5 usable templates
• ☐One feature shipped using the spec/execution split end-to-end
• ☐npm run build exits clean
• ☐git show --stat HEAD shows only your intended files
• ☐git show --name-only HEAD lines up with your file targets

Evolving your scripts

The scripts you started with on the start page are a baseline. As your project grows, they need to grow with it.

• ·Tighten your guardrails. Early on, broad file targets are fine. Once you have ten or twenty files, you need explicit hotspot lists so agents do not wander into code they should not touch.
• ·Define hotspot boundaries per agent. When running parallel agents, each one gets a non-overlapping set of files. If two agents need the same file, serialize the work instead of risking merge conflicts.
• ·Raise your proof requirements. Start with "must pass build." Then add typecheck. Then add specific test commands. Each project phase can demand a higher bar before a task counts as done.
• ·Let the project shape the script. A week in, you will notice patterns: the same constraint you keep adding manually, the same mistake you keep catching. Bake those into the template so they happen automatically.

Your scripts are living documents. The version you use on day 30 should look noticeably different from day 1. That is progress.

Scripts and docs evolve together. When you discover a rule that keeps preventing mistakes, it becomes an invariant. When a bug shows up twice, it becomes a checklist item. The best operating docs are not written in advance. They are extracted from real work and committed alongside the code that taught you the lesson.

Your docs are part of the prompt

As your project grows, your scripts alone are not enough context. The AI needs to know what already exists, what the rules are, and what has been tried before. That is what project docs do. They live in your repo root and the AI reads them at the start of every session.

• CLAUDE.md

  This is how you steer the agent before it writes a single line. Put your repo conventions, commit message format, build commands, and any "never do this" rules here. The agent reads it first and follows it for the entire session.

• INVARIANTS.md

  Rules that prevent regressions. Things like "billing is off by default," "never import from node_modules directly," or "all API routes return JSON." When an agent knows the invariants, it stops accidentally breaking things you already fixed.

• STATE_OF_THE_APP.md

  A short snapshot of what the app looks like right now. Which pages exist, what works, what is half-built, what is next. This stops the AI from guessing about your project and generating code that conflicts with what you already have.

• FINDINGS_LOG.md

  A running log of decisions, dead ends, and things you tried that did not work. This prevents the AI from suggesting something you already rejected, and gives future-you context on why things are the way they are.

Keep every file short. If it takes more than 60 seconds to read, it is too long. These are not documentation for humans. They are context for agents. Trim them regularly.

# CLAUDE.md (example)
Build: npm run build
Typecheck: npx tsc --noEmit
Commit format: type(scope): description
Never edit files outside your assigned hotspot.
Always return a HANDOFF PACKET when done.

# INVARIANTS.md (example)
Billing is OFF by default (BILLING_ENABLED=false)
All pages use dark theme: bg-[#0B0B0C], text-[#F6F6F6]
No new dependencies without explicit approval

# STATE_OF_THE_APP.md (example)
Pages live: landing, start, curriculum, modules 1-6, toolkit, faq, contact
Auth: Clerk, working
Payments: Stripe, wired but billing kill-switch is off
Next deploy: needs OG image and final copy pass

# FINDINGS_LOG.md (example)
2026-02-14: Turbopack ENOENT race condition. Fix: rm -rf .next before build.
2026-02-15: Clerk middleware needs clerkMiddleware(), not authMiddleware().
2026-02-16: Pre blocks must use whitespace-pre-wrap or mobile layout breaks.

Using docs in every Claude task

Having docs in the repo is only useful if you actually reference them. Here is how to wire them into your daily workflow so the AI reads them before it does anything.

• ·Start every task script with a doc reference. At the top of your Claude prompt, add: "Read CLAUDE.md, INVARIANTS.md, and STATE_OF_THE_APP.md before starting." This gives the agent rules, context, and current state in one line.
• ·Keep tasks bounded by hotspots. Your CONCURRENCY.md file lists who owns which files. Copy the relevant agent's hotspot list into the task script so the agent knows exactly what it can and cannot touch.
• ·Force proof by requiring it in the script. Do not hope the agent will verify. Put the verification commands in the task script and require a HANDOFF PACKET. If the packet is missing or the proofs are incomplete, the task is not done.
• ·FINDINGS vs. STATE: know the difference. STATE_OF_THE_APP.md is what the project looks like right now. It gets overwritten each update. FINDINGS_LOG.md is cumulative. It records what you learned and never gets trimmed. A bug fix updates STATE. The lesson from the bug goes in FINDINGS.

# Example: top of a Claude task script

CLAUDE TASK: Add pricing cards to /pricing

Before you start:
  Read CLAUDE.md for execution rules.
  Read INVARIANTS.md for project constraints.
  Read STATE_OF_THE_APP.md for current project state.
  Read FINDINGS_LOG.md for known issues.

Hotspot (from CONCURRENCY.md, Agent B):
  app/pricing/page.tsx

Do not edit anything else.

How docs evolve

Your docs are not static files you write once and forget. They grow out of real work. Here is how a piece of knowledge moves through the system.

1. 1. A rule starts as a note.

   You notice something during a build. Maybe a library needs a specific import style, or a route breaks if you forget a wrapper. You write it down in FINDINGS_LOG.md so you do not forget.

2. 2. After it saves you twice, it becomes an invariant.

   The second time that note prevents a mistake, promote it to INVARIANTS.md. Now every agent reads it automatically before starting a task. It stops being something you remember and becomes something the system enforces.

3. 3. After it breaks production once, it becomes a release checklist item.

   If something gets past your invariants and causes a real problem in production, add it to RELEASE_CHECKLIST.md. That file is the last gate before deploy. It catches the things that slipped through everything else.

This is how good operating docs get built. Not by sitting down and writing a manual, but by extracting lessons from real work and putting them where they will be read at the right moment. The docs you have after a month of building should look nothing like the ones you started with.