The CLAUDE.md That Ships My Entire Website

TL;DR: This is the actual CLAUDE.md powering frankx.ai. Not a template, not a hypothetical — the file that loads into every Claude Code session for a 170+ page production site. I will walk through each section, explain what it does, and tell you what mistake it exists to prevent.

What Makes a CLAUDE.md Production-Grade

Most CLAUDE.md examples online are aspirational. They are written by people who read the documentation and imagined what might be useful. Production CLAUDE.md files are written in response to pain.

Every rule in mine came from a real mistake, a near-miss, or a pattern I needed Claude to hold across 100+ sessions.

Three characteristics separate a file that ships from one that sits unused:

It is active instructions, not documentation. Documentation describes. Instructions direct. "This site uses a two-repo architecture" is documentation. "Push to .worktrees/vercel-ui-ux/ to deploy to production, not the main repo" is an instruction.

It front-loads the highest-stakes rules. Claude Code reads the entire file, but the first 500 words are processed with fresh context. Every critical constraint goes there.

It updates when Claude makes mistakes. The file is a living artifact. Every time a session goes wrong in a reproducible way, the rule that would have prevented it goes into CLAUDE.md.

Here is the section-by-section breakdown.

Section 1: Quick Reference Table

The first thing in the file. Maps actions to slash commands:

| Action               | Command                       |
| -------------------- | ----------------------------- |
| Deploy to production | `/frankx-ai-deploy`           |
| Create blog post     | `/frankx-ai-blog`             |
| Full build session   | `/frankx-ai-build`            |

Why it exists: I have 40+ slash commands in this project. Without a reference table, Claude would need to infer which command applies from context — or ask. The table is ~80 tokens that eliminate session-start ambiguity entirely.

What it prevents: Sessions where Claude either guesses the wrong command or wastes turns asking clarifying questions about workflow.

The table belongs first because every session starts with an action. Give Claude the map before it needs to navigate.

Section 2: Production Deployment (Two-Repo Architecture)

## Production Deployment (READ FIRST)

**Content must be pushed to BOTH repos to go live.**

| Repo                                | Purpose        |
| ----------------------------------- | -------------- |
| frankxai/FrankX                     | Private dev    |
| frankxai/frankx.ai-vercel-website   | PRODUCTION     |

Deploy workflow:
cp content/blog/article.mdx .worktrees/vercel-ui-ux/content/blog/
cd .worktrees/vercel-ui-ux && git add -A && git commit -m "feat: Add article"
git push origin main  # Deploys to frankx.ai

Why it exists: frankx.ai runs a two-repo architecture. The private repo (FrankX) holds development work, documentation, research, and agent configurations. The production repo (frankx.ai-vercel-website) is what Vercel deploys. They share code structure but not content history.

Without this section, Claude would commit blog posts to the private repo and they would never appear on frankx.ai. I caught this once at 11pm before a scheduled post was supposed to go live.

What it prevents: Publishing work that never reaches production. The "(READ FIRST)" in the heading is deliberate — it signals to Claude that this is load-bearing orientation, not supplementary information.

The exact copy command is in the file so Claude can run it without inferring the path structure.

Section 3: Brand Positioning (3 Lines of Rules)

The brand section in my CLAUDE.md is deliberately short:

**DO:** Lead with results. Precise technical language. Show don't tell. Confident but understated.

**DON'T:** Spiritual language. Grandiose claims. Over-explain philosophy. Self-help guru tone.

Title: "AI Architect" (never "AI Systems Architect")

That is the entire voice guide. Three lines.

Why it is short: Long brand guides in CLAUDE.md are counterproductive. The model reads them, then weights them against everything else in the prompt. Specificity beats length. "Confident but understated" is a constraint. "Write with authenticity and genuine expertise that resonates with your audience" is noise.

What it prevents: The title rule — "AI Architect" not "AI Systems Architect" — exists because Claude would occasionally reach for the longer version as if precision required more syllables. After adding the one-liner, it has not happened in 4 months.

The voice rules prevent two failure modes: content that sounds like a productivity influencer (self-help tone) and content that sounds like a press release (grandiose claims). Both undermine the practitioner credibility the site is built on.

Section 4: Anti-Patterns Table

This is the highest-leverage section in the file. Every entry is a real mistake or a real near-miss.

| Bad Instinct                      | Better Approach                  |
| --------------------------------- | -------------------------------- |
| "60% reduction sounds impressive" | Does this help users?            |
| "Shorter URLs are better"         | Keep established URLs            |
| "Consolidate everything"          | Fix navigation, not routes       |
| "Delete orphan pages"             | Unlink from nav, keep page       |
| "Rename for consistency"          | Consistency isn't worth SEO loss |

The story behind "Shorter URLs are better": In session 47 or so, I asked Claude to help tidy up site navigation. It proposed renaming /research/personal-ai-coe to /research/ai-coe for brevity. That URL had backlinks. The proposal was well-intentioned — shorter is cleaner — but it would have broken inbound links for a 0.3-character gain.

I added the rule. It has not happened again.

The story behind "Delete orphan pages": Claude once flagged four pages that had no navigation links pointing to them and suggested removing them. Three were intentionally unlinked — they existed as landing pages for specific traffic sources. Deletion would have broken those.

The correct behavior: "Unlink from nav, keep the page." The page exists. Its discoverability changes. Its URL does not.

Why tables work better than prose for anti-patterns: The two-column format creates a direct cognitive pairing — bad instinct on the left, correct behavior on the right. It reads in seconds. Prose explanations of the same rules would take 10x the tokens and be skimmed.

Section 5: Decision-Making Protocol

Before any structural change:

1. What specific problem are we solving?
2. What's the simplest solution?
3. What could go wrong? (SEO, data loss, irreversibility)
4. Is this reversible? If not, get explicit approval.

Why it exists: The instinct to optimize is strong. Claude — and frankly, I — will sometimes reach for an impressive-sounding restructuring when a one-line config change would do the job.

This checklist slows that down. Not every session — only sessions where I ask about architecture, routes, or "cleanup." The heading in the file signals when to invoke it: "Before ANY Structural Change."

The three production mistakes it has prevented:

1. A proposed consolidation of 12 prompt categories into 4, which would have broken URLs for 94 prompts. The checklist surfaced "irreversible" — stopped the action, used a navigation fix instead.

2. A suggested rename of /coaching to /work-with-me for "better clarity." Stopped by "never rename working URLs."

3. A plan to "archive" old blog posts to reduce site size. Stopped by "what could go wrong — SEO, data loss." The correct action was updating internal links, not archiving.

Each of these was flagged by the checklist before any file was modified.

Section 6: Content Standards and SEO Checklist

### SEO Checklist
- [ ] TL;DR in first 100 words
- [ ] Question-based H2s
- [ ] FAQ section (5+ questions)
- [ ] Schema markup (Article + FAQPage)
- [ ] 3+ internal links
- [ ] Optimized meta title/description

Why the checklist format: Claude can run this as a literal checklist against any article draft. It does not need to infer what "good SEO" means for this site — the list is explicit. When I ask "does this post meet our content standards," Claude runs each item.

The internal links requirement (3+) is the most frequently missed without the checklist. Good articles exist in isolation unless they actively connect to related content. The checklist makes that structural.

This article you are reading right now was written against this checklist. ACOS link — that is one. Prompt library — two. How to write a CLAUDE.md that works — three.

Section 7: Thinking Protocol

## Pre-Action Checklist (complex tasks)
- [ ] What problem? (specific, not vague)
- [ ] Who has it?
- [ ] What's the evidence?
- [ ] Simplest fix?
- [ ] What could go wrong?
- [ ] Reversible?
- [ ] Metrics or outcomes?

Why it exists: Complex requests — "refactor the homepage," "redesign the navigation," "restructure the research hub" — are vague enough that Claude can interpret them many ways. Without a thinking protocol, it reaches for the most impressive interpretation, which is usually the most invasive.

The checklist constrains the interpretation step. "What problem?" forces specificity. "Simplest fix?" pushes back against the instinct to restructure when configuration would suffice.

This section activates conditionally. For routine tasks (write a blog post, fix a typo, update a component), it does not apply. For architectural requests, it runs first.

The File as a Whole

The complete CLAUDE.md for frankx.ai is approximately 1,200 words. That is the ceiling I try to stay under.

Beyond 1,500 words, the file starts competing with itself. Critical rules lose weight because they are surrounded by supplementary context. The most effective CLAUDE.md files are dense and load-bearing — every line earns its place.

The maintenance pattern: after any session where Claude makes a project-specific mistake, I add a rule. After any session where Claude asks a question it should already know the answer to, I add context. The file grows only in response to real friction.

After 6 months and 180+ sessions, the frankx.ai CLAUDE.md has produced zero deployment accidents, zero URL renames, and zero page deletions. Those outcomes are the point.

If you want to build your own, start with the how-to guide. If you want the full architecture this file operates within, the ACOS framework documents how CLAUDE.md fits into a complete personal AI CoE. The ultimate AI coding agent setup covers the MCP and skills layer that sits on top.

Start with the file. Update it every session. Watch it compound.

FAQ

How long should a production CLAUDE.md be? Under 1,500 words for most projects. The goal is density — every line load-bearing. If you can remove a sentence without losing anything specific, remove it.

Should I put brand voice rules in CLAUDE.md or in a separate file? Keep the core rules in CLAUDE.md — 3-5 lines maximum. Long brand guides belong in a referenced file (/docs/brand-voice.md) that Claude reads on demand. CLAUDE.md should contain only the rules that apply to every session, every time.

What is the right cadence for updating CLAUDE.md? Update after any session where Claude makes a reproducible mistake. Not after one-off errors, but after patterns. If Claude does the same wrong thing twice, that is a CLAUDE.md gap. Add the rule. The file should grow slowly and purposefully.

Does CLAUDE.md replace good prompting in each session? No. CLAUDE.md handles persistent project-level context — architecture, anti-patterns, brand rules. Session-level prompting handles the specific task. They work together: CLAUDE.md gives Claude the map; session prompts give it the destination.

Can I see the actual file? The file shown in this article is the real production CLAUDE.md for frankx.ai — every section is from the live file. The personal AI CoE research page documents the broader system it operates within.