Make the folder

Create a Projects folder under your Windows user directory if you do not already have one. Inside it, create a folder for this build:

C:\Users\<your username>\Projects\portfolio-dashboard

Avoid the desktop, Downloads, and cloud-synced folders (OneDrive, Dropbox). You want a stable, local, isolated folder Claude Code can read entirely. By the end of the module the folder will hold source files, a data file (your stock list), a CLAUDE.md (Bead 3), and the hidden .git\ directory. For now it is empty.

Resist the urge to mix this folder with unrelated work. Claude reads what is in the folder. Cluttered folders mean cluttered context.

Point Code at it

1. Open Claude Code in the desktop app.
2. Click "Select folder" at the bottom of the sidebar.
3. Choose C:\Users\<your username>\Projects\portfolio-dashboard.
4. The folder name appears at the top of the Code panel. That is now Code's working directory.

Code can read everything inside this folder, recursively, including subfolders and hidden files (like .git\). It cannot read anything outside it. Your Documents, Desktop, OneDrive, and other Projects folders are invisible.

Link Git

Run the Git setup prompt from pre-tool. The folder is empty and unlinked; this turns it into a tracked repository so Code can commit as it works.

Set up Git in this folder. Initialise the repository, configure
my name and email (use [your name] and [your email]), and make
the first commit.

Allow the shell command when prompted. Code will run git init, set your identity, and make an initial commit. From this point on, every change Code makes can be inspected as a diff and rolled back with one prompt — that is the safety net Bead 6 leans on.

Verify what Code sees

Type:

Show me what is in this folder. List every file and folder,
including hidden ones.

Code will list the folder contents. Confirm it matches what you expect: the .git\ directory from pre-tool, your README.md if you made one, and (for a fresh project) not much else.

If Code lists files you did not put there, or omits files you did put there, stop. Either you selected the wrong folder, or you have files in a place you did not realise. Resolve before continuing.

Why scope matters

Three reasons.

Predictability. Code's answers are functions of what it can read. If Code cannot see a file, it cannot use it. If Code can see a file, it might use it even when you did not mean it to.

Safety. Code can edit any file in the folder. A clean, isolated folder means fewer surprises about what just got changed.

Auditability. When something goes wrong (and it will), the smaller the scope, the faster the diagnosis. Pre-tool's Git is the second half of this: scope plus version history equals a clear paper trail.

Adding context later

If a task needs context outside the folder, do not move the folder or expand the scope. Instead:

• Copy the relevant file into the project folder (rename if it would clash).
• Or, paste the content directly into the chat, framed as context.

Either is better than expanding scope.

Turn on plan mode

In Claude Code, switch to plan mode (current syntax may be /plan or a Shift+Tab toggle; check the docs at code.claude.com/docs). Plan mode means Claude proposes the steps but does not edit files until you approve.

Ask Claude to ask you

Before describing the project, ask Claude what it needs from you. Type:

I want to build a small HTML dashboard that pulls returns for a
five-stock portfolio and shows two-year returns, volatility, and
drawdowns. Before you write a plan, ask me the questions you
need answered to plan well. List them all at once. I will answer
in the next message.

Claude will produce a list. Expect questions like: which five stocks, what data source, what currency, what time period, what the dashboard should look like, libraries to avoid, where the output file lives.

Answer in one block. Be specific. The more spec you front-load, the less the plan has to guess.

Read the plan

Claude produces a numbered plan. Read it slowly. Look for:

• Steps that match what you asked for.
• Steps that introduce things you did not ask for (a database, an external account, a build tool). Push back.
• Steps that wave-hand ("then deploy"). Ask Claude to expand them.

If the plan is off, say so. Claude revises. Iterate until it is sane.

Sign off

Approve only what you understand. If a step is unfamiliar, ask Claude to explain. If the explanation is unfamiliar, switch to Chat (the recovery move from pre-tool).

When the plan reads cleanly, approve. Code moves out of plan mode and starts work.

Re-review the plan with fresh eyes

Before you write CLAUDE.md, read the plan one more time. Step back. Ask:

• Are there decisions in the plan you accepted because Claude proposed them, not because you preferred them?
• Are there conventions you want enforced?
• Are there guardrails you want set?

Mark these. They are what goes in CLAUDE.md.

Have Code write CLAUDE.md

In the project folder, you want a file called CLAUDE.md. Claude Code reads it automatically at the start of every session. Whatever is in there acts as standing instructions for the project.

Ask Code to draft it from the plan you agreed:

Draft a CLAUDE.md for this project based on our plan. Save it to
the root of this folder.

Read what Code wrote. Edit anything that does not match your intent. The file is yours; Code drafted it for you.

Verify Code reads it

Type:

Read CLAUDE.md and summarise the standing rules for this project.

Code will read the file and recap. Confirm the recap matches what you wrote. If anything is off, edit CLAUDE.md and ask again.

# portfolio-dashboard

A personal HTML dashboard for a five-stock portfolio.
Two-year returns, volatility, max drawdown.

## Stack
- Single dashboard.html. No bundler, no framework.
- Chart.js via CDN. Vanilla JS for math.
- Yahoo Finance unofficial endpoint for daily closes.

## Conventions
- USD throughout. Annualised stdev for volatility.
- Surface fetch errors. Never swallow with try/except.
- Don't add dependencies without asking first.
- Edit only files named in the plan.

## Tickers
AAPL, MSFT, NVDA, JPM, XOM.

Set permissions to auto

Set Code to auto-allow at the start of the session. (In current versions this is the "always allow" or "bypass" setting; check the docs at code.claude.com/docs.)

This is the right default for a first-build project in your own folder, for two reasons.

Click fatigue is real. If Code asks for permission ten times, you stop reading the prompts and click yes anyway. Per-action approval becomes security theatre after a few prompts.

The protection is structural, not procedural. Your safety net is the folder boundary (bead 1, scope) and Git (pre-tool, version history). Not the permission popup. If Code does something wrong, you revert; you do not catch it at the prompt.

For agentic work that touches shared infrastructure (a production database, a real codebase), per-action permissions matter much more. You are not in that mode.

Watch the bill with /usage

Type /usage to see your context usage and rough token spend.

Check it once during the build and once at the end. Two numbers to watch:

• Context. Above 50%, the conversation is long enough that context rot starts to matter. Bead 6 covers compacting and starting fresh.
• Spend. Use the number to calibrate your sense of cost. The first build will surprise you in one direction or the other.

What a working session looks like

Code's main pane fills with a stream of turns. Most look like this:

• An action line. "Wrote dashboard.html · 184 lines" or "Ran curl … · 200 OK · 412 KB". One line per thing Code did.
• A short reasoning sentence. "Now wiring the volatility calculation into the stat strip."
• Occasional questions back to you. "Yahoo returned an empty array for XOM on weekends. Fill forward, drop those rows, or fail loud?"

What a healthy turn looks like: one file touched, one purpose, one sentence of intent. What an unhealthy turn looks like: a wall of file edits with no narration, or narration that doesn't match the diff (Code says it added error handling; the diff doesn't show it). Either pattern is a sign to interrupt.

When to step in (and how)

Code is working. Three reasons to interrupt the flow:

• Code asks you a question. Answer in one block, in the same vocabulary as the question. Don't expand scope while answering.
• Code claims something you cannot verify. "Tests pass." With what tests? "I added the calculation." Where? Push back: show me.
• Code drifts from the plan. A new file, an unfamiliar dependency, a refactor that wasn't asked for. Stop the turn. Ask why.

To stop a turn: hit Esc (or the cancel button) — Code halts at the next checkpoint. Nothing on disk is half-written, but the session keeps the partial state in context. You can correct course and continue without losing the run.

Otherwise, let it work. Bead 5 is where you read what Code did in detail.

Show me the diff

Ask Code:

Show me the diff since the last commit.

Code prints the diff. A diff has three parts:

• The file path at the top of each block. Where the change happened.
• Lines starting with -. Removed lines.
• Lines starting with +. Added lines.

You do not need to understand every line. Skim for surprises:

• New files. Did you expect that file?
• Files outside your plan. Pause. Why did Code touch that?
• Big blocks of removed code. Pause. Did Code throw something away you wanted?

Have Code translate

Then ask:

Explain what you just changed in plain English. Pretend I am
not a developer. What did each change do, and what would break
if it were missing?

Code translates. Read the translation, not the code.

If something is still unclear, ask follow-ups. Code knows what it did and has the project context. There is no faster reader for your own diff.

Run the thing

The final test is the obvious one. Open the HTML in a browser. Click around. Do the numbers look plausible.

If the diff explanation made sense and the thing runs, the work is good. If either fails, you are in bead 6 territory.

diff — dashboard.html
+ <script src="https://cdn.jsdelivr.net/npm/chart.js">
+ const TICKERS = ['AAPL','MSFT','NVDA','JPM','XOM'];
+ async function fetchCloses(t) { … }
+ function annualisedVol(returns) { … }
+ function maxDrawdown(prices)  { … }
− <p>Hello world</p>
  … (218 more lines added)

Iterate when the gap is small

If the change you want is small (a number is wrong, a column needs renaming, a function does too much), describe it and ask Code:

The volatility number on the dashboard reads 14% but my hand
calculation shows ~12%. The discrepancy is too large to be
rounding. Find the bug, propose a fix, and explain it before
applying.

The "explain it before applying" suffix is the move. It avoids Code silently editing something you cannot verify.

Then re-run bead 5 (skim diff, translate, run). The loop is: identify gap, ask Code to fix, verify.

Revert when an iteration makes things worse

Sometimes Code's "fix" makes it worse. When that happens, do not accept the diff and try to fix the fix. Revert.

Ask Code:

Revert the last commit. Show me what reverted.

Code uses Git to undo. Your folder is back to the previous good state. Now propose the fix differently.

Git is your safety net. Use it. The cost of reverting is zero; the cost of layering broken fixes on broken fixes is high.

Back out when the approach is wrong

Sometimes the issue is not a bug. The whole approach is off. Code is doing exactly what you asked for; what you asked for is what you do not want.

When this happens, stop iterating. Do not keep poking. Go back to plan mode (bead 2), redraft the plan, and rebuild. You may want to revert all the way to your initial commit to start clean.

Signs you are in this mode rather than the iteration mode:

• You cannot describe what is wrong without describing the architecture.
• You have iterated three or more times without convergence.
• The result is structurally different from what you imagined.

/clear when the session is too long

If /usage shows context above 70%, or the session has been running an hour, the model is starting to forget early decisions. Type /clear and start a fresh session. Code reads CLAUDE.md again and picks up with a clean context.

This is the move from pre-tool. Use it earlier than feels comfortable.

− const vol = stdev(returns) * 252;       // the bad fix
+ const vol = stdev(returns) * Math.sqrt(252); // restored

Three questions for Code

Start a fresh session in Code (the /clear move from bead 6, applied here for bias-hedging). With CLAUDE.md still in scope, paste:

Three questions about the project we just built.

1. What worked? Where did the build go right?
2. Imagine a senior engineer is reviewing this code in a
   pull request. What would they complain about? Be specific.
   Name files and line numbers. Cover: silent failures, fake
   success / hardcoded values, scope creep, edits to files
   that weren't in the plan, missing edge cases.
3. How would you change CLAUDE.md so we don't repeat the
   same complaints on the next project?

Read the answers carefully. The first question is calibration. The second is the work. The third is the leverage.

Question 2 uses a third-person framing on purpose. Asking “what shortcuts did you take?” nudges Code into self-defence; asking “what would a senior engineer complain about?” gets sharper, more honest critique. Same model, different mirror.

Code may want to flatter you on question one. Ignore the flattery. The real value is in two and three.

What to look for in question two

Common shortcuts agentic tools take, with cues:

• Silent failure. "The data fetch is wrapped in a try/except that swallows errors." Means: if the API breaks, your dashboard shows zeros, not an error.
• Fake success. "The volatility calculation is hardcoded for testing and was not replaced with the real formula." Means: your numbers are dummies.
• Yak-shaving. "I added a build tool you did not ask for to handle a problem that was not actually present." Means: scope creep.
• Edits to the wrong file. "I added the chart code to dashboard.html but also touched index.html to import it; the second edit was unnecessary." Means: scope outside the plan.

If Code names any of these (or any of their cousins), that is a real finding. Push: "Show me where in the code, exactly."

Refine CLAUDE.md

Take Code's answer to question three and edit CLAUDE.md. Add the rules that would have caught the shortcuts. Examples:

• "Never wrap data fetches in silent try/except. Surface errors."
• "Never hardcode placeholder values. Mark unfinished work with // TODO: real implementation and stop."
• "Never add a dependency or build tool without asking."
• "Edit only the files named in the plan. If you need to touch others, stop and confirm."

Commit the updated CLAUDE.md. The next project that uses this file starts on a higher floor than this one did.

+ Surface fetch errors in the UI. No silent fallback to empty arrays.
+ Use adjusted close, not raw close, for any return calculation.
+ Validate ticker history length before drawdown math; reject < 1y.