# AI Workflow: Bruno Pintos

> How I build with Claude Code, using this site as the example

I build software with Claude Code. For this site I designed a set of agents, hooks and rules that decide how the AI works on the code, and Claude helped me write them.

This site is built with this setup, with a written record of each session.

- 8 active agents
- 5 hooks around every session
- 40+ sessions on record

## How a change gets made

1. **Triage:** A read-only agent classifies the task, names the files it touches, checks them against the path rules and picks the agent that should do the work.
2. **Gate:** A hook blocks every edit until triage has run in that session. Reading code and read-only commands pass freely.
3. **Plan on record:** Before touching a file, the agent writes its plan in a decision log: the strongest alternative it rejected, the assumption the plan rests on, and what would prove it wrong.
4. **Build and verify:** It implements, then runs the build and the type check and fetches the static HTML. The results go into the same log.
5. **Review:** Before a push, a hook suggests a review command that checks the whole branch. It only passes with zero high-severity findings.

## Agents

- **Triage:** Routes every task. Never edits.
- **Features:** Pages, components, styles and site content.
- **Debugging:** Bugs and build failures, down to the root cause.
- **Tests:** Writes and runs tests. Never touches source code.
- **Dependencies:** Package upgrades. Always asks me first.
- **Security:** Audits for secrets, XSS and unsafe links. Never edits.

Agents for APIs, databases and CI are parked, ready to come back when a project needs them. Each one has a clear area, and an agent hands off instead of crossing into another one's area.

## Rules the AI can't skip

- **Restricted:** Secrets, deploy and build config. The agent stops and asks me before writing.
- **Review required:** The page head and the content schema. The agent proceeds but flags the change.
- **Forbidden:** Build output, generated files and the lockfile. Never written by hand.
- **Destructive:** Anything that can't be undone pauses for my confirmation, wherever it happens.

## What it looks like

The gate, simplified:

```
before Edit | Write | Bash:
  read-only?    allow
  triage ran?   allow
  otherwise     block
```

A plan on record (from building this page):

- **Alternative:** Add this page as a project. Rejected: it would count as client work in the CV.
- **Assumption:** A second system app needs no layout change.
- **Disproved if:** The build fails, or the CV count changes.

## Why it matters for clients

- The AI follows the project's rules, not its own defaults, so the code stays consistent.
- Every decision has a written reason, so a reviewer can see why, not just what.
- It can't touch secrets, deploy config or dependencies without my explicit OK.

## Built for agents to read, too

Every page on this site has a Markdown version, and an llms.txt indexes them, so assistants like Claude can read the portfolio directly. https://www.brunopintos.com/llms.txt

I designed this setup and Claude helped me write it. The repository is private, so the examples on this page are simplified.

HTML: https://www.brunopintos.com/ai-workflow/