Guide · Portfolio
A team of AI agents that writes your case study.
Setup-focused. By the end you will have Claude Code installed, a Figma connection, three context docs that teach it your voice, and a repeatable workflow that ends in a finished markdown file saved to your computer.
What this guide is about.
This guide doesn't write the case study for you. It gets the infrastructure in place, teaches you what context to feed the AI, and walks through the workflow so the agents produce something in your voice from your actual decisions.
By the end you will have
- Claude Code installed and running on your machine.
- A Figma connection so Claude can read your design files.
- Three context docs in a folder: your voice, your preferences, your rules.
- A repeatable workflow for running a team of AI agents on any project.
- A finished case study in markdown, saved to your computer.
What this guide does not cover
- Designing the case study visually — that's a separate step after the text is done.
- Saving to Notion. Separate guide.
- The Claude Code desktop app. This guide is terminal only.
The final output is a markdown file in a folder on your computer. What you do with it after (design in Figma, paste into a portfolio builder, turn into a deck) is a separate step.
What would you need
- A Mac or Windows machine with a terminal app. Both come pre-installed.
- An Anthropic account (Claude Pro, Max, Team, Enterprise, or API credits).
- A Figma file of one finished project you want to turn into a case study.
- Two focused hours. Not twenty minutes between meetings.
- Willingness to answer questions. The AI will ask. If you skim, the draft suffers.
Good news
No coding experience. No Node.js. No Git. No prior terminal use. If you can open Terminal and paste a line, you can run this flow.
Install Claude Code.
Claude Code runs in your terminal. The terminal is a window where you type commands instead of clicking buttons. On Mac it's called Terminal. On Windows it's PowerShell. Both come pre-installed.
Open the terminal
On Mac: Cmd + Space, type terminal, press Enter. On Windows: Start menu, type powershell, press Enter. A window opens with a blinking cursor. That's where commands go.
Install
Copy the one line that matches your machine. Paste it, press Enter.
Mac or Linux
$ curl -fsSL https://claude.ai/install.sh | bash
Windows PowerShell
PS> irm https://claude.ai/install.ps1 | iex
This downloads Claude Code from Anthropic's official site. It's safe. Paste it exactly, don't change anything.
Paste shortcut
On Mac, paste with Cmd + V. Right-click paste doesn't always work in Terminal. On Windows, Ctrl + V works fine.
Success looks like: a green message saying "Claude Code installed" and a new prompt. If you see red errors, scroll to the first one and check the troubleshooting section.
Log in
Type claude, press Enter. A browser tab opens so you can sign in to your Anthropic account. Log in, return to the terminal. A prompt waits for input.
Connect Claude to Figma.
MCP servers are plugins that let Claude read your other apps. For this flow you only need Figma.
$ claude mcp add --transport http figma https://mcp.figma.com/mcp --scope user
Paste exactly. Don't edit the --transport or --scope parts. The first time Claude reads a Figma file, a browser tab opens to authorize. Click Allow, return to the terminal.
If later you see a figma is not defined error, check the troubleshooting section.
Create your context folder.
Context is what makes the draft sound like you, not like generic AI. You will store context docs in a single folder on your computer. Claude reads them every session.
Pick a folder. Somewhere memorable. Example path: ~/Documents/case-study-context/.
On Mac, in terminal
$ mkdir -p ~/Documents/case-study-context
On Windows PowerShell
PS> mkdir $env:USERPROFILE\Documents\case-study-context
Quick note on the squiggle
~ is shorthand for your home folder. You don't type the full path, the terminal fills it in.
Generate your context docs.
Three docs. Generate them once, reuse forever. Each interview takes 5 to 10 minutes.
How you write and sound. Sentence length, tone, words you like, words you hate.
How you want case studies structured. Section order, emphasis, word count, NDA handling.
What the AI must never do. Invent metrics, use banned words, ignore the [TO CONFIRM] rule.
If you already have these, skip ahead. If not, generate them now using Claude Code.
Start a session from inside your context folder
$ cd ~/Documents/case-study-context $ claude
cd means "change directory". It tells the terminal to work inside that folder. Important here: Claude saves the docs into whichever folder you ran claude from.
Generate the voice doc
Paste into Claude Code
Interview me to build a voice doc for my portfolio writing. Ask one question at a time. Cover sentence length, tone, words I like, words I hate, level of formality, first person or third, how technical to get, preferred rhythm, how I handle confidence vs humility. Ten questions max. Then write the doc as markdown and save to voice.md in the current folder.
Answer honestly. Be specific. "Casual" is vague. "I write like I'm explaining the work to a senior designer over coffee" is usable. When Claude is done, voice.md sits in your folder.
Generate the preferences doc
Paste into Claude Code
Interview me to build a preferences doc for portfolio case study structure. Ask about section order, how much context to give upfront, how to frame problems, what to emphasize (decisions, craft, outcomes, collaboration), word count targets, how to handle constraints and trade-offs, how to handle confidential clients. Eight questions max. Save as preferences.md.
Generate the hard rules doc
Paste into Claude Code
Interview me to build a hard rules doc. These are things an AI writer must never do for me. Ask about banned words, how to handle unverified facts, whether to invent metrics or quotes, how to handle NDA or confidential project names, formatting rules, rules on em dashes or other punctuation. Six questions max. Save as rules.md. Always include the rule that unverified facts get marked [TO CONFIRM] and are never invented.
Optional: merge into one file
Some people prefer a single CLAUDE.md. Claude Code auto-reads CLAUDE.md in the working directory, so merging makes context loading automatic.
Paste into Claude Code
Merge voice.md, preferences.md, rules.md into a single CLAUDE.md in this folder. Keep every section. Use clear headings: About me, Voice, Preferences, Hard rules.
Decide your design output upfront.
Before you assemble the team, decide where the case study lives visually. Tell Claude at the start — the workflow shifts depending on the answer.
Claude writes and saves a .md file to your context folder. Design the page later in Figma, a deck, or a portfolio builder.
Claude writes the case study and builds the layout in your Figma file. Needs branding assets attached — logo, colors, type, components.
Claude writes the markdown, you design in Framer, Webflow, Pitch, Keynote. Same setup as A, different destination.
This guide covers Option A. Save to folder, design later.
Run the case study flow.
The main event. Open a fresh terminal session from your context folder, paste the instruction prompt, answer the questions.
$ cd ~/Documents/case-study-context $ claude
Instruct Claude Code
Paste this prompt. No edits needed.
Paste into Claude Code
Read all markdown files in this folder. These are my voice, preferences, and hard rules. Use them as context for everything you write from here on.
Goal: write one portfolio case study. Final output is a markdown file saved to this folder.
Before you start, ask me for the Figma file URL and any other context I have: project notes, research, interviews, PRDs, screenshots, user feedback, retros. Wait for me to provide them.
Then propose three team shapes. Explain what each one does, how long it takes, and token cost roughly. I pick one.
Once I pick, show me the full plan: which agents run, in what order, what each one does, where I answer questions. Wait for me to say go before executing.
As agents run, ask me questions when you need decisions, constraints, scrapped features, or details not in the Figma file. Mark every unverified fact as [TO CONFIRM]. Never invent metrics, names, dates, or quotes.
When the draft is final, save to this folder and print the full file path.
Claude asks for context
Claude will ask for:
- The Figma file URL.
- Any other docs you have. Paste content or give file paths.
- Short project background: who the user was, what the constraint was, what shipped, what you learned.
Answer each one. If you don't have something, say so. Claude adapts to what's available.
Pick a team
Claude proposes three team shapes. Yours may differ:
Research Analyst, Writer, Editor.
Research, Creative Director, Writer, 2 reviewers, Editor.
Two writer tracks race for the best draft.
Review the plan, then go
Claude prints the full plan before running. Every agent, their role, the order, where you answer questions. Read it. If something is missing or wrong, tell Claude what to change. It updates the plan. When it looks right, reply go.
The team works
Agents run in sequence. Between phases Claude pauses and asks you questions. Example questions you might get:
- "What was the hardest constraint on this project?"
- "What did you cut that you wish you had shipped?"
- "Was there a decision a reviewer pushed back on that you held the line on?"
- "Who was the primary user, and what were they doing before your tool existed?"
Review the draft
The reviewers score the draft. If scores come back low (under 6/10 on the Design Lead rubric), the research layer was shallow. Tell Claude:
If scores are low
Go back to research. Dig deeper on [specific area]. Then rerun the writer and reviewers.
Final edit
The Editor polishes the draft and inserts [TO CONFIRM] for every fact it can't verify. Open the draft. Find every [TO CONFIRM]. Answer honestly.
Example: if the Editor wrote dashboard load time improved by [TO CONFIRM]%, replace with the real number, a range you're confident in, or delete the claim if you don't know. Same rule for dates, team sizes, customer names (especially under NDA), and quotes.
Save and locate your case study.
The final markdown lands in your context folder. To confirm exactly where, ask Claude.
Paste into Claude Code
Save the final case study as markdown to this folder. Print the full file path and filename.
Claude responds with something like:
Saved to /Users/yourname/Documents/case-study-context/project-name-case-study.md
Open the folder in Finder (Mac) or File Explorer (Windows). The file is there. Open in any text editor, Notion, Craft, Bear, or paste into your portfolio tool.
Common questions.
Most failures are one of these. If yours isn't listed, scroll your terminal to the first red line and read that.
Does this burn my Claude Pro subscription or API credits?
Pro or Max covers Claude Code. No separate API account needed. If you only have an API account, you pay per-use from credits.
What does markdown or .md mean?
Plain text with simple rules. # Heading is a heading. **bold** is bold. Most editors and design tools understand it.
The install command failed.
Scroll up, read the first red error line. Usually a network or permissions issue. On Mac, try prefixing the command with sudo and entering your password.
claude doesn't work after install.
Close the terminal, open a new one. If still broken, run which claude on Mac or where claude on Windows. If nothing prints, the install didn't finish. Reinstall.
figma is not defined error.
You don't have edit permissions on that Figma file. Make a branch or use a file you own. If still failing, open any Figma plugin once on the file, then retry.
Claude ignores my voice doc.
Start sessions from inside your context folder (cd ~/Documents/case-study-context before claude). Claude auto-reads CLAUDE.md in the working directory. If you kept three separate files, tell Claude to read them explicitly at the start of the session.
The draft sounds generic.
Your voice doc is thin. Rerun the voice interview, give more specific examples, be blunt about what you hate. Rerun the case study.
The draft invented a number.
Your rules doc is missing the "never invent metrics" rule. Add it. Rerun.
Running out of tokens.
Pick Small Studio instead of Full Agency. Three agents use roughly a third of what six use.
I want Claude to build the page in Figma, not just write the text.
That's Option B in the output choice section. Separate guide. You'll need branding assets and component library access.
Pick one project. Run it once.
The first case study is a learning run, not a final piece. The second one will be better because you'll know what your voice doc was missing.
The value is not the draft. It's the questions the team asks you — the decisions you had forgotten, the scrapped features you never thought to mention, the constraints that made you design the way you did. The [TO CONFIRM] placeholders stop you from hand-waving.
run it.
Save the output. Come back for the design step. If you try it, tell me what the agents pulled out of you — the moments you had forgotten, the decisions that surprised you.
— Kate