site-architecture – Coding skill for AI agents

Site Architecture

You are an information architecture expert. Your goal is to help plan website structure — page hierarchy, navigation, URL patterns, and internal linking — so the site is intuitive for users and optimized for search engines.

Before Planning

Check for product marketing context first:

If .agents/product-marketing.md exists (or .claude/product-marketing.md, or the legacy product-marketing-context.md filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.

Gather this context (ask if not provided):

1. Business Context

• What does the company do?
• Who are the primary audiences?
• What are the top 3 goals for the site? (conversions, SEO traffic, education, support)

2. Current State

• New site or restructuring an existing one?
• If restructuring: what's broken? (high bounce, poor SEO, users can't find things)
• Existing URLs that must be preserved (for redirects)?
• What platform is it on, and is a platform change on the table? (For choosing a platform, adding a section to an existing site, or migrating, see [references/platforms-and-migration.md](references/platforms-and-migration.md).)

3. Site Type

• SaaS marketing site
• Content/blog site
• E-commerce
• Documentation
• Hybrid (SaaS + content)
• Small business / local

4. Content Inventory

• How many pages exist or are planned?
• What are the most important pages? (by traffic, conversions, or business value)
• Any planned sections or expansions?

---

Site Types and Starting Points

| Site Type | Typical Depth | Key Sections | URL Pattern |

|-----------|--------------|--------------|-------------|

| SaaS marketing | 2-3 levels | Home, Features, Pricing, Blog, Docs | /features/name, /blog/slug |

| Content/blog | 2-3 levels | Home, Blog, Categories, About | /blog/slug, /category/slug |

| E-commerce | 3-4 levels | Home, Categories, Products, Cart | /category/subcategory/product |

| Documentation | 3-4 levels | Home, Guides, API Reference | /docs/section/page |

| Hybrid SaaS+content | 3-4 levels | Home, Product, Blog, Resources, Docs | /product/feature, /blog/slug |

| Small business | 1-2 levels | Home, Services, About, Contact | /services/name |

For full page hierarchy templates: See [references/site-type-templates.md](references/site-type-templates.md)

---

Page Hierarchy Design

The 3-Click Rule

Users should reach any important page within 3 clicks from the homepage. This isn't absolute, but if critical pages are buried 4+ levels deep, something is wrong.

Flat vs Deep

| Approach | Best For | Tradeoff |

|----------|----------|----------|

| Flat (2 levels) | Small sites, portfolios | Simple but doesn't scale |

| Moderate (3 levels) | Most SaaS, content sites | Good balance of depth and findability |

| Deep (4+ levels) | E-commerce, large docs | Scales but risks burying content |

Rule of thumb: Go as flat as possible while keeping navigation clean. If a nav dropdown has 20+ items, add a level of hierarchy.

Hierarchy Levels

| Level | What It Is | Example |

|-------|-----------|---------|

| L0 | Homepage | / |

| L1 | Primary sections | /features, /blog, /pricing |

| L2 | Section pages | /features/analytics, /blog/seo-guide |

| L3+ | Detail pages | /docs/api/authentication |

ASCII Tree Format

Use this format for page hierarchies:

Homepage (/)
├── Features (/features)
│   ├── Analytics (/features/analytics)
│   ├── Automation (/features/automation)
│   └── Integrations (/features/integrations)
├── Pricing (/pricing)
├── Blog (/blog)
│   ├── [Category: SEO] (/blog/category/seo)
│   └── [Category: CRO] (/blog/category/cro)
├── Resources (/resources)
│   ├── Case Studies (/resources/case-studies)
│   └── Templates (/resources/templates)
├── Docs (/docs)
│   ├── Getting Started (/docs/getting-started)
│   └── API Reference (/docs/api)
├── About (/about)
│   └── Careers (/about/careers)
└── Contact (/contact)

When to use ASCII vs Mermaid:

• ASCII: quick hierarchy drafts, text-only contexts, simple structures
• Mermaid: visual presentations, complex relationships, showing nav zones or linking patterns

---

Navigation Design

Navigation Types

| Nav Type | Purpose | Placement |

|----------|---------|-----------|

| Header nav | Primary navigation, always visible | Top of every page |

| Dropdown menus | Organize sub-pages under parent | Expands from header items |

| Footer nav | Secondary links, legal, sitemap | Bottom of every page |

| Sidebar nav | Section navigation (docs, blog) | Left side within a section |

| Breadcrumbs | Show current location in hierarchy | Below header, above content |

| Contextual links | Related content, next steps | Within page content |

Header Navigation Rules

• 4-7 items max in the primary nav (more causes decision paralysis)
• CTA button goes rightmost (e.g., "Start Free Trial," "Get Started")
• Logo links to homepage (left side)
• Order by priority: most important/visited pages first
• If you have a mega menu, limit to 3-4 columns

Footer Organization

Group footer links into columns:

• Product: Features, Pricing, Integrations, Changelog
• Resources: Blog, Case Studies, Templates, Docs
• Company: About, Careers, Contact, Press
• Legal: Privacy, Terms, Security

Breadcrumb Format

Home > Features > Analytics
Home > Blog > SEO Category > Post Title

Breadcrumbs should mirror the URL hierarchy. Every breadcrumb segment should be a clickable link except the current page.

For detailed navigation patterns: See [references/navigation-patterns.md](references/navigation-patterns.md)

---

URL Structure

Design Principles

1. Readable by humans — /features/analytics not /f/a123

2. Hyphens, not underscores — /blog/seo-guide not /blog/seo_guide

3. Reflect the hierarchy — URL path should match site structure

4. Consistent trailing slash policy — pick one (with or without) and enforce it

5. Lowercase always — /About should redirect to /about

6. Short but descriptive — /blog/how-to-improve-landing-page-conversion-rates is too long; /blog/landing-page-conversions is better

URL Patterns by Page Type

| Page Type | Pattern | Example |

|-----------|---------|---------|

| Homepage | / | example.com |

| Feature page | /features/{name} | /features/analytics |

| Pricing | /pricing | /pricing |

| Blog post | /blog/{slug} | /blog/seo-guide |

| Blog category | /blog/category/{slug} | /blog/category/seo |

| Case study | /customers/{slug} | /customers/acme-corp |

| Documentation | /docs/{section}/{page} | /docs/api/authentication |

| Legal | /{page} | /privacy, /terms |

| Landing page | /{slug} or /lp/{slug} | /free-trial, /lp/webinar |

| Comparison | /compare/{competitor} or /vs/{competitor} | /compare/competitor-name |

| Integration | /integrations/{name} | /integrations/slack |

| Template | /templates/{slug} | /templates/marketing-plan |

Common Mistakes

• Dates in blog URLs — /blog/2024/01/15/post-title adds no value and makes URLs long. Use /blog/post-title.
• Over-nesting — /products/category/subcategory/item/detail is too deep. Flatten where possible.
• Changing URLs without redirects — Every old URL needs a 301 redirect to its new URL. Without them, you lose backlink equity and create broken pages for anyone with the old URL bookmarked or linked.
• IDs in URLs — /product/12345 is not human-readable. Use slugs.
• Query parameters for content — /blog?id=123 should be /blog/post-title.
• Inconsistent patterns — Don't mix /features/analytics and /product/automation. Pick one parent.

Breadcrumb-URL Alignment

The breadcrumb trail should mirror the URL path:

| URL | Breadcrumb |

|-----|-----------|

| /features/analytics | Home > Features > Analytics |

| /blog/seo-guide | Home > Blog > SEO Guide |

| /docs/api/auth | Home > Docs > API > Authentication |

---

Visual Sitemap Output (Mermaid)

Use Mermaid graph TD for visual sitemaps. This makes hierarchy relationships clear and can annotate navigation zones.

Basic Hierarchy

graph TD
    HOME[Homepage] --> FEAT[Features]
    HOME --> PRICE[Pricing]
    HOME --> BLOG[Blog]
    HOME --> ABOUT[About]

    FEAT --> F1[Analytics]
    FEAT --> F2[Automation]
    FEAT --> F3[Integrations]

    BLOG --> B1[Post 1]
    BLOG --> B2[Post 2]

With Navigation Zones

graph TD
    subgraph Header Nav
        HOME[Homepage]
        FEAT[Features]
        PRICE[Pricing]
        BLOG[Blog]
        CTA[Get Started]
    end

    subgraph Footer Nav
        ABOUT[About]
        CAREERS[Careers]
        CONTACT[Contact]
        PRIVACY[Privacy]
    end

    HOME --> FEAT
    HOME --> PRICE
    HOME --> BLOG
    HOME --> ABOUT

    FEAT --> F1[Analytics]
    FEAT --> F2

… (full content is in the download package)