Building a Portfolio with an AI Agent

What it is

This portfolio runs on a small system for capturing design thinking and publishing it safely. I keep detailed notes about my work in private, Claude drafts each case study under written rules for my voice and for what must never go public, and I make every borderline call before a static site publishes the result.

As AI produces more of the interface, the main thing a designer contributes is the judgment behind it: which problem to solve, which options to weigh, and which tradeoffs to accept. That judgment is hard to reconstruct from memory months later, so it is worth recording while the work is fresh. This page covers what each part does, how the voice keeps improving, and how to set up your own in an afternoon.

Why I built it

Many designers are unable to publish their strongest work because of an NDA. I built this system so I can record the full detail in private, then publish a generalized version that shows how I worked without exposing anything that is not public. Other designers in the same position can set up the same system.

What it does

The system is a handful of files in one repository, plus a private notes folder that is never committed or published. Each part has one job.

Together they run as one loop: notes in, a draft out, my calls in between.

Gathering the context, also with AI. The notes are where most of the time used to go, so I hand the first pass to Claude. When I finish a project, I ask it to look back over the session and write the capture note: the goals of the feature, the key decisions and why, and how I worked with AI, including the prompts that worked, where I overrode it, and what it got wrong. I read the note, correct it, and add the context it could not see, such as conversations with the team and what users said. It makes capture much faster, and it records the AI side of the work while it is still fresh, which is the part I used to forget and the part people increasingly ask about.

We just finished this project. Before I close the session, write a
capture note to capture/PROJECT-NAME.md. Include:

- The goals of the feature and the problem it solved.
- The key decisions, the options we considered, and why we chose.
- How I worked with AI: what I asked you to do, the prompts that
  worked best (quote them), where I overrode your suggestion, and
  where you got something wrong.
- Anything still open.

Keep the real specifics; this file stays private. Mark anything you
are unsure about, and leave a section at the end for context you
could not see, so I can fill it in.

What it produced

Standing up the whole system took a couple of hours instead of the weekend I had budgeted, and a new case study now goes from notes to a reviewed draft in a single sitting. At that cost, keeping the portfolio current fits inside a normal week.

Choose your template

Every case study on this site answers the same ten questions in the same order, from the problem through the outcome. Readers get a consistent story each time and can compare studies side by side, and each new draft starts from a structure Claude already follows.

Decide on the template before you write the first case study, since every later one uses it. I chose questions for the Staff, Principal, Director, and Founding Designer roles I was pursuing: they ask about constraints, tradeoffs, the role I played, and how UX, engineering, and business strategy met, which is the judgment hiring managers at that level look for. Start from the roles you want next, and pick the questions that show what those roles require.

Teach it your voice

An agent’s first drafts sound like everyone. The voice guide in CLAUDE.md fixes that, and it gets better every time you use it:

1. Start from your own writing. Claude interviews you and reads two or three of your essays, then drafts a short Do and Don’t list.
2. Name what you dislike. When a line does not sound like you, fix it and say why.
3. Write it down as a rule. The reason becomes a rule with a before-and-after example, so the next session does not repeat it.

Mine has grown to about forty rules this way, and each draft needs less editing than the last. A few that came from lines I rewrote:

When I dislike a line, I use this prompt to fix it and record the rule:

That line sounds generic. Name the pattern that makes it sound that
way, add a rule for it to the voice section of CLAUDE.md with this
line as the before-and-after example, then rewrite the line using
the new rule.

The same habit works for everything else in CLAUDE.md. A correction made in chat is gone next session; one written into a rules file applies every time after.

Keep it safe

The charter is one page: what never ships, one rule for turning specifics into general language, and the Public Test. Would my manager, legal counsel, a future employer, and the original company all agree this shows my contribution without exposing anything private?

# Portfolio charter (excerpt)
Never publish: source code, internal screenshots, non-public
metrics, roadmaps, customer or employee names, internal docs.

Transform rule (specific becomes general):
  "Project Atlas"     ->  "an internal platform initiative"
  "cut latency 42%"   ->  "a meaningful performance gain"
  a real screenshot   ->  a recreated conceptual sketch

Public Test: would my manager, legal, a future employer, and
the original company all agree this shows my contribution
without exposing IP? If unsure: generalize, abstract, or cut.

The line I review for is public versus non-public. Company-specific detail is welcome only when it has appeared in a press release or is otherwise available to the general public, since real references help readers trust generalized work. Everything else gets generalized at one boundary, when the draft is written. Claude reads your notes in the cloud, so check your employer’s AI policy before capturing confidential work, and keep customer names and unreleased details out of the notes.

The drafting prompt keeps the agent inside the rules and makes it raise anything it is unsure about:

You are a portfolio editor working under the charter above.
Input: my private notes for one project.
Draft a case study answering, in order: problem, why it
mattered, constraints, my role, options, tradeoffs, how
UX/engineering/business intersected, how AI was used, what I
learned, the outcome.

Rules:
  - Generalize every specific per the transform rule.
  - Invent no metrics. Use relative outcomes only.
  - Generate diagrams as code; never describe a real screen.
  - Raise anything you are unsure about for my review. Do not
    decide it yourself.

Set it up yourself

This is the setup I recommend for a first build: the Claude desktop app, a free GitHub account, and a private notes folder on your own computer. You don’t need coding experience. Plan on an afternoon. My own setup differs in a few details (I work in Conductor, my repository is private, and my notes live on a separate machine), but the parts and the loop are the same.

Open each step as you go.

gh auth login

I want to build a personal portfolio website with a built-in system for
writing case studies about confidential work safely. Please set it up in
this folder. I'm new to coding tools, so explain what you're doing in
plain language as you go.

What to build:

1. A static site using Astro, Tailwind CSS, and MDX, with pages for Home,
   Work (case studies), About, and Resume. It should look good on phones
   and pass accessibility checks (WCAG 2.1 AA).

2. Case studies as MDX files in src/content/case-studies/. Each one
   answers these 10 questions as headings, in this order:
   - What problem existed?
   - Why did it matter?
   - What constraints existed?
   - What role did I play?
   - What options were explored?
   - What tradeoffs were considered?
   - How did UX, engineering feasibility, and business strategy intersect?
   - How was AI used in the process?
   - What was learned?
   - What was the outcome?
   Reasoning sections are short paragraphs; constraints, options, and
   outcome are bulleted lists. Aim for 600-900 words. Every case study
   gets a simple illustrative visual made in code, never a real
   screenshot of a product.

3. A CLAUDE.md file with the rules any AI agent must follow when editing
   this site: my writing voice (as a Do list and a Don't list), the
   case-study structure above, and accessibility and mobile rules.
   Before writing the voice rules, interview me about how I like to
   write and ask me for 2-3 samples of my writing.

4. A portfolio-safety-charter.md file listing what must never appear
   publicly (employer source code, internal documents, roadmaps,
   customer and coworker names, non-public metrics, internal
   screenshots) and how to turn specifics into general, portfolio-safe
   language. Include a "Public Test": if my manager, a lawyer, a future
   employer, and the original company all read this, would they agree
   it shows my contribution without exposing anything private?

5. A private capture/ folder for my raw notes about real work. Add it to
   .gitignore so it is never uploaded.

6. A pre-push git hook that blocks an upload if it includes capture
   files or any banned words I give you (ask me for my work email domain
   and any internal project names), and prints the Public Test as a
   reminder. Make it turn on automatically when someone runs npm install.

7. An "npm run a11y" command that checks every page for accessibility
   problems.

8. A GitHub Actions workflow that publishes the site to GitHub Pages
   whenever I push to the main branch.

Start by checking that Git, Node.js, and the GitHub CLI are installed.
Then build everything, and when it's ready, run the site so I can
preview it.

Draft a case study from capture/project-notes.md. Follow CLAUDE.md and
the safety charter. Then list anything in the draft that might not be
safe to publish, and let me decide each one before you change it.

My GitHub username is YOUR-USERNAME. Check that nothing from capture/
will be uploaded, then create a public GitHub repository called
"portfolio", set the site's address to YOUR-USERNAME.github.io/portfolio,
and push everything. Then walk me through turning on GitHub Pages.

What I learned

• Separate capture from transform. Record the full detail in private, then generalize once, at one boundary, where a single review can catch problems.
• Let the agent raise; you decide. The useful division of labor is the agent surfacing judgment calls and a person making them.
• Keep real references only when they are public. A product name or document stays in a case study only if it has appeared in a press release or is available to the general public. Readers trust generalized work more when it includes those references; everything else gets generalized.