I've been using Claude Code to help manage my portfolio site, and recently hit a wall: my CLAUDE.md file had grown to over 300 lines. It contained everything—project architecture, environment setup, package upgrade workflows, component patterns, and more.

The problem? When I asked Claude to "audit my packages," it had to parse through routing documentation and icon guidelines to find the upgrade workflow buried somewhere in the middle. Not efficient.

Here's how I restructured everything for better agentic automation.

The Problem with Monolithic Documentation

CLAUDE.md is the file Claude Code reads to understand your project. It's tempting to dump everything there:

# CLAUDE.md (before - 300+ lines)

## Project Overview
...50 lines about architecture...

## Commands
...20 lines of scripts...

## Environment Variables
...30 lines of env setup...

## Package Audit Workflow    ← Buried here
...80 lines of upgrade process...

## Component Patterns
...40 lines of examples...

## Icons & Assets
...30 lines of guidelines...

This works initially, but creates problems:

1. Cognitive load - Agent parses everything even for simple tasks
2. Maintenance burden - Updates to one workflow risk breaking others
3. No separation of concerns - Project facts mixed with task procedures

The Solution: Workflows as First-Class Citizens

I split the documentation into three layers:

portfolio-tina/
├── CLAUDE.md              # Core context (~100 lines)
├── workflows/
│   ├── README.md          # How workflows work
│   ├── package-audit.md   # Specific task workflow
│   └── article-builder.md # Another workflow
└── knowledge/
    └── upgrades/
        ├── README.md      # Index
        └── [change].md    # Migration notes & gotchas

Layer 1: CLAUDE.md (Always Loaded)

Stripped down to essentials an agent always needs:

# CLAUDE.md (~100 lines)

## Quick Reference
| Command | Description |
|---------|-------------|
| pnpm dev | Dev server |
| pnpm build-local | Local build |

## Architecture
- App Router in /app
- Content in /content (TinaCMS)
- Tailwind v4 with CSS-first config

## Workflows
| Task | Workflow |
|------|----------|
| Audit packages | /workflows/package-audit.md |
| Write article | /workflows/article-builder.md |

The key insight: reference workflows, don't embed them.

Layer 2: /workflows (Loaded on Demand)

Each workflow is a self-contained guide:

# /workflows/package-audit.md

## Trigger
Use when asked to "audit packages" or "upgrade dependencies"

## Step 1: Discover Outdated Packages
pnpm outdated

## Step 2: Categorize by Risk
- Tier 1 (patches): Batch into single PR
- Tier 2 (minors): Individual PRs
- Tier 3 (majors): Issue first, wait for approval

## Step 3: For Each Package
...detailed steps...

When I say "audit my packages," Claude reads the specific workflow—not the entire knowledge base.

Layer 3: /knowledge (Accumulated Wisdom)

Each significant change gets documented:

# /knowledge/upgrades/tailwind-4.md

**Date:** 2026-02-07
**PR:** #73

## Changes
- Tailwind 3.4.1 → 4.1.18
- CSS-first configuration

## Migration Notes
- rounded → rounded-sm (default changed)
- Custom screens → @custom-variant

This gives future agents (and humans) context without cluttering active documentation.

Why This Works for Agents

1. Focused Context

Instead of parsing 300 lines, the agent gets:

• ~100 lines of core context (always)
• ~150 lines of task-specific workflow (when needed)

2. Clear Triggers

Each workflow declares when to use it:

## Trigger
Use when asked to:
- "audit packages"
- "upgrade dependencies"
- "check for outdated packages"

3. Self-Contained Instructions

Workflows include everything needed to execute:

• Prerequisites (tools, access)
• Step-by-step process
• Expected outputs
• Common issues and fixes

4. Easy to Extend

Adding a new capability = adding a new workflow file. No risk of breaking existing ones.

The Workflow Pattern

Every workflow follows this structure:

# Workflow Name

## Trigger
When to use this workflow.

## Prerequisites
Tools and access required.

## Steps
1. First step
2. Second step
...

## Outputs
What should exist when done.

## Common Issues
Troubleshooting guide.

What's Next

In Part 2, I'll walk through the package-audit workflow in detail—how it uses GitHub CLI for automation, documents learnings as it goes, and handles dependency chains.

The workflows folder is also where I'm building more automations:

• article-builder.md - Turn coding sessions into blog posts
• seo-audit.md - Automated SEO checks
• performance-audit.md - Lighthouse optimization

The pattern scales to any repeatable task you want to hand off to an agent.

This article was drafted using my own article-builder workflow. Meta, I know.