Building a Personal AI Agent Constitution: The System Behind the System

I treat my AI agents like junior engineers.

Not in a condescending way. In a practical one. When you onboard a junior engineer, you don't just point them at the codebase and say "build something." You give them documentation. You define coding standards. You set up guardrails. You create processes they can follow. You review their work.

AI coding agents need the same treatment. The difference is that junior engineers learn and retain context across sessions. AI agents start every conversation with amnesia. The context window is their only memory. When the conversation ends, everything they learned disappears.

This means you need external systems to do what human memory does naturally: persist standards, recall project context, enforce behavioral constraints, and activate specialized knowledge on demand.

Over the past year, I've built what I call my Agent Constitution. It's a modular configuration architecture that spans two different AI platforms (Claude and Gemini), multiple projects, and hundreds of specialized capabilities. It's the meta-system that makes all my other engineering work possible.

This post documents the entire architecture. Not the theory. The actual files, the actual structure, the actual patterns running in production across every project I work on.

---

#The Problem: Context Amnesia

Every AI coding session starts from zero.

The agent doesn't remember your file structure. It doesn't know your coding standards or that last week you spent 3 hours debugging a SwiftData migration and documented the solution. It has no idea that your Next.js project uses Tailwind CSS 4 with a specific design token system, or that your Swift project enforces strict concurrency checking.

Most developers solve this by repeating themselves. Every session starts with some version of: "This is a Next.js 16 project. We use Tailwind. The design system uses gold accents. Don't use mock data."

That doesn't scale. You're wasting context tokens on information that should be injected automatically, you inevitably forget to mention something important, and the cognitive overhead pulls you out of the actual engineering problem.

The solution is to treat agent configuration as infrastructure, not as conversation or prompts. Persistent, versioned, modular architecture that loads automatically and enforces consistently.

---

#The Two-Platform Architecture

I work across two AI platforms daily:

• Claude (via Claude Code CLI) for my Next.js web projects
• Gemini (via Google Antigravity IDE) for my Swift/iOS projects

Each platform has its own configuration system, but I've designed them to follow identical architectural principles. The file names differ. The philosophy is the same.

Notice that the .agent/ directory structure is identical across both platforms. This is intentional. When I context-switch between projects (or between agents), the organizational pattern is the same. Rules go in rules/. Tasks go in tasks/. Workflows go in workflows/. The mental model is portable.

---

#Layer 1: The Global Constitution

The global constitution is the highest-authority document in the system. It defines behaviors that must hold true regardless of which project I'm working on, which conversation I'm in, or which task is being performed.

My Claude global constitution lives at ~/.claude/CLAUDE.md. Here's the core structure:

# Global Agent Rules

## Task Execution Protocol (R.P.E. Loop)

For complex, multi-step tasks, follow the Research, Planning, Execution loop:

1. Research: Gather context, read files, check docs, search the web.
2. Plan: Document specific steps. Break work into milestones, tasks, subtasks.
3. Execute: Work through the plan item by item. Single focus.
4. Verify: Run tests, builds, visual checks. Document results.

## Context Map Protocol

Projects may have a CONTEXT-MAP.md. This is the project's structural memory.
- Session start: Read it to orient yourself
- After creating/deleting/moving files: Update it immediately
- After major refactors: Review and update architecture notes

## Changelog Protocol

When the user asks to commit or finalize work:
1. Update CHANGELOG.md with a concise summary
2. Then proceed with the commit

## Writing Style

- Never use em dashes anywhere in output, files, or generated content.

My Gemini global constitution uses an import system to load modular rule files:

# GLOBAL AGENT CONSTITUTION (GEMINI.MD)

@~/.gemini/global_rules/governance.md
@~/.gemini/global_rules/skills-protocol.md
@~/.gemini/global_rules/meta-skills.md
@~/.gemini/global_rules/context-map-protocol.md
@~/.gemini/global_rules/changelog-protocol.md
@~/.gemini/global_rules/rpe-workflow.md
@~/.gemini/global_rules/tools-reference.md
@~/.gemini/global_rules/context-hygiene.md

The Gemini version is modular because Antigravity supports the @import syntax natively. Each @ reference pulls in a separate markdown file. This keeps the global constitution lean (just imports) while the actual logic lives in focused modules.

Claude doesn't support file imports in the same way, so its global constitution is a single, self-contained document. Different implementation, same principles.

>What Goes in the Global Constitution

The global constitution should contain only rules that are universally applicable and never overridden:

• Task execution protocol (RPE loop)
• Documentation maintenance rules (context maps, changelogs)
• Writing style constraints (no em dashes, no emojis unless requested)
• Skill discovery protocol (check for available skills before specialized work)
• Agent behavioral expectations (complete the task, then report; never auto-commit)

What does not belong here: framework-specific conventions, project-specific file structure, design tokens, API keys. Those belong at the project level.

---

#Layer 2: Project-Level Constitutions

Every project gets its own agent configuration layer that extends (but never overrides) the global constitution.

For my Next.js portfolio site (TheChosenVictor), the project-level Gemini constitution looks like this:

# PROJECT AGENT CONSTITUTION (GEMINI.MD)

## Import Project Rules
@.agent/rules/content-creation-access.md
@.agent/rules/privacy-boundaries.md
@.agent/rules/no-mock-data.md
@.agent/rules/proactive-skill-usage.md
@.agent/rules/post-task-review-mandatory.md
@.agent/rules/rpe-workflow-mandatory.md

## Project Skills
@~/.gemini/antigravity/skills/next-js/SKILL.md
# WHY: Core framework (Next.js 16.1 App Router)
# HOW: Use Server Components by default, use Turbopack

@~/.gemini/antigravity/skills/frontend-design/SKILL.md
# WHY: Premium UI quality is essential for personal brand
# HOW: Apply Liquid Glass aesthetics, dark-mode first

For my iOS app (SwipeClean), the project constitution is much more detailed because the project has stronger conventions:

# PROJECT AGENT CONSTITUTION (GEMINI.MD)

@.agent/rules/code-style.md
@.agent/rules/architecture.md
@.agent/rules/design-system.md
@.agent/rules/swift-standards.md
@.agent/rules/testing.md
@.agent/rules/dependencies.md
@.agent/rules/task-completion.md

@.agent/skills/ios-screen-design/SKILL.md
# WHY: Every screen needs bold, intentional design
# HOW: Use for /design-screen workflow or when building a new SwiftUI view

>The WHY/HOW Pattern

Notice the annotation pattern after each skill import:

@~/.gemini/antigravity/skills/next-js/SKILL.md
# WHY: Core framework (Next.js 16.1 App Router)
# HOW: Use Server Components by default, use Turbopack

This isn't written for humans. It's context the agent needs. The WHY tells the agent why this skill matters for this specific project. The HOW tells it when and how to apply the skill. Without these annotations, the agent knows the skill exists but lacks the project-specific context to apply it correctly.

---

#Layer 3: The Rules System

Rules are the behavioral constraints layer. They're more granular than the constitution and support conditional activation.

>Rule Anatomy

Every rule file follows a simple format: YAML frontmatter with a trigger, followed by markdown content.

---
trigger: always_on
---

Do NOT use mock data, placeholder content, or dummy values.

Prohibited:
- Lorem ipsum or filler text
- Placeholder images (gray boxes)
- Hardcoded mock arrays
- "TODO", "TBD", "Coming soon" as content

Required instead:
- Real content and copy
- Use generate_image for actual images
- Connect to real APIs/databases

>Trigger Modes

Rules support four activation modes:

The model_decision trigger is the most interesting. It lets you define a rule with a description of when it should apply, and the agent decides contextually whether to activate it:

---
trigger: model_decision
description: When making frontend changes that affect visual rendering
---

After completing frontend changes, you MUST:
1. Open the browser to the relevant page
2. Capture a screenshot or recording
3. Include visual proof in the walkthrough

This rule only activates when the agent recognizes it's making visual changes. It doesn't fire during backend work, documentation updates, or configuration changes. The agent infers relevance from the task context.

>My Active Rule Set

Across my projects, I maintain a consistent set of rules:

Universal Rules (always_on):

• no-mock-data.md prevents placeholder content
• rpe-workflow-mandatory.md enforces structured task execution
• proactive-skill-usage.md requires checking for relevant skills before specialized work
• post-task-review-mandatory.md mandates quality review after every task
• privacy-boundaries.md prevents personal information from appearing in public content

Contextual Rules (model_decision):

• browser-preview-mandatory.md requires visual verification of frontend changes
• frontend-design-skills.md bundles design skills for UI work

The privacy boundaries rule is worth highlighting. It defines explicitly what personal information is prohibited in any public-facing content (relationships, health, finances, location) and what's allowed (professional journey, technical skills, project experiences). This protects me from the agent inadvertently including personal details in blog posts, social content, or documentation.

---

#Layer 4: The Skill Library

Skills are the extension system. They encode specialized workflows into reusable, on-demand capabilities.

>Skill Architecture

Each skill is a self-contained directory:

skill-name/
  SKILL.md              # Required: instructions and metadata
  scripts/              # Optional: executable code
  references/           # Optional: documentation
  assets/               # Optional: templates, files

The SKILL.md has two parts. The YAML frontmatter defines name and description (what the agent scans to decide relevance). The markdown body contains the actual instructions (only loaded when the skill activates).

>Progressive Disclosure

The skill system uses a three-tier loading strategy:

1. Tier 1 (Metadata): Always in context. About 100 words per skill. Just the name and description.
2. Tier 2 (SKILL.md body): Loaded on-demand when the skill triggers. Under 5,000 words.
3. Tier 3 (References/Scripts): Loaded as needed during execution. No size limit.

This is a context window optimization. If I have 92 skills and each one is 3,000 words, loading all of them would consume 276,000 tokens. At progressive Tier 1, the same 92 skills consume roughly 9,200 tokens. A 30x reduction.

>A Real Skill: iOS Screen Design

The most sophisticated skill in my library is the ios-screen-design skill for SwipeClean. It defines a 4-phase workflow for building new SwiftUI screens:

Phase 1: Screen Brief. Gather requirements, scan codebase, produce a one-paragraph brief.

Phase 2: Aesthetic Direction. Write a vision prompt (a vivid, narrative description of the screen experience), fill a design decisions table (typography, color, layout, motion, haptics), then expand into a detailed implementation spec with exact token references.

Phase 3: Build. Scaffold the view, implement section by section following the spec, handle all states, add accessibility.

Phase 4: Polish and Validate. Apply finishing touches, build preview blocks, run validation checklists.

Each phase loads its own reference files progressively:

.agent/skills/ios-screen-design/
  SKILL.md
  references/
    aesthetic-directions.md
    detailed-spec-format.md
    build-checklist.md
    polish-and-validation.md

The key rule: "Never skip Phase 2. A spec produces a spec-looking screen; a vision produces an experience." Without the aesthetic direction phase, the agent generates competent but generic UI. With it, the output has personality, intentional motion design, and emotional texture.

>Skill Categories

My skill library spans these domains:

The meta-skills are the most powerful. The skill-creator skill teaches the agent how to create new skills. The review skill defines a structured audit framework. The rpe-workflow skill enforces Research, Planning, Execution on complex tasks. These are self-referential: the system uses itself to extend itself.

---

#Layer 5: Context Maps and Structural Memory

Every project has a CONTEXT-MAP.md at the root. This is the agent's memory of the project structure. It contains the file tree with descriptions, key file purposes, and architecture notes.

# CONTEXT-MAP.md

## Directory Structure

src/
  app/                   # Next.js App Router
    layout.tsx           # Root layout (fonts, metadata, SEO)
    page.tsx             # Homepage
    globals.css          # Global styles & CSS variables
    swipeclean/          # SwipeClean sub-site
      layout.tsx         # SwipeClean layout (blue accent theme)
  components/            # React components
    ui/                  # Shadcn UI primitives
    home/                # Homepage bento grid blocks
    features/            # Feature components
  content/               # Local content (MDX, data)
    blog/                # Local MDX blog posts
  lib/                   # Utilities & services

The context map protocol defines strict update rules:

This creates a living document that stays synchronized with the actual project structure. When an agent starts a new session and reads the context map, it immediately understands what exists, where it lives, and what it does. No exploration needed. No wasted tokens on ls and find commands.

---

#Layer 6: Task Tracking and Workflows

Tasks are ephemeral. They track in-progress work and get archived on completion.

>Task Files

.agent/tasks/
  2026-02-20-1840-pro-iap-storekit2.md
  boss-battle-implementation.md
  archive/
    (completed tasks)

Each task file follows the RPE structure: objectives at the top, a research section, a planning checklist, an execution checklist, and a verification section. Items are marked with [x] (done), [/] (in progress), or [ ] (pending).

The value is continuity. If a conversation is interrupted (token limit, crash, user context-switch), the next session can read the task file and pick up exactly where the previous one left off. No lost work. No repeated research.

>Workflow Files

Workflows are reusable multi-step procedures. Unlike tasks (which are unique), workflows are templates that can be invoked repeatedly.

My deploy workflow for TheChosenVictor:

---
description: Deploy TheChosenVictor to the Hetzner VPS
---

# Deploy to VPS

## Steps
1. Deploy to VPS:
   ssh deploy@YOUR_VPS_IP "bash ~/deploy.sh"

This will: pull latest code, npm ci, npm run build, restart PM2, health check.

One command. Repeatable. Self-documenting. The agent can execute the entire deployment without me typing the SSH command from memory.

---

#Layer 7: Cross-Platform Memory

The final layer is personal memory that persists across all conversations on a given platform.

Claude has a memory file at ~/.claude/projects/{project}/memory/MEMORY.md that auto-updates based on conversation patterns:

# Project Memory

## User Preferences
- ALWAYS use agents and skills.

## Project: TheChosenVictor
- Next.js 16.1.6 with Turbopack
- Dark theme, gold (#ae9558) accent for main site
- SwipeClean sub-site uses blue (#2563EB) accent instead of gold
- Fonts: Plus Jakarta Sans (sans), Roboto Mono (mono)
- Dev server: node node_modules/next/dist/bin/next dev
- Known Turbopack bug: symlink error with next-mdx-remote

Gemini has Knowledge Items that serve the same purpose: structured documents in ~/.gemini/antigravity/knowledge/ that persist across sessions and projects.

The key principle: web search first, memory second. Memory captures internal conventions and project-specific patterns. But framework versions, API changes, and best practices evolve. When the agent needs current information, it should search the web. Memory provides the private context that the web can't.

---

#How It All Composes

When I open a project and start working, here's what happens in the first 100 milliseconds of context construction:

1. Global constitution loads. RPE protocol, documentation rules, writing style. Universal constraints.
2. Project constitution loads. Framework skills, design standards, project-specific imports.
3. Project rules activate. No-mock-data, privacy boundaries, mandatory review. Always-on rules fire immediately.
4. Context map loads. The agent now knows the entire project structure without exploring.
5. Memory loads. Dev server commands, known bugs, user preferences.
6. Task files are available. If there's in-progress work, the agent can resume it.

By the time I type my first message, the agent has already absorbed the equivalent of a multi-page onboarding document. It knows my standards, my project structure, my conventions, and my current priorities. The conversation starts at a much higher baseline than "I have a Next.js project..."

And here's the compounding effect. Every time I create a new rule, it applies to every future session automatically. Every time I build a new skill, it becomes available across all projects that need it. Every time the context map updates, every future agent session starts with accurate structural knowledge.

The system gets better over time without me actively maintaining it. That's the difference between prompt engineering and configuration architecture.

---

#Building Your Own: A Practical Blueprint

If you want to replicate this system, here's the minimum viable setup:

>Step 1: Create the Directory Structure

# For any project
mkdir -p .agent/rules .agent/tasks .agent/workflows

# Create your first context map
touch CONTEXT-MAP.md

>Step 2: Write Three Core Rules

Start with these three always_on rules:

1. No mock data. Prevent the agent from using placeholder content.
2. Task completion protocol. Define the behavior: complete, report, wait. No auto-committing.
3. Code style. Your language-specific conventions. Naming, formatting, patterns.

>Step 3: Initialize the Context Map

Walk through your project and document the structure. Every important directory. Every key file. A one-line description for each. This takes 30 minutes and saves hours of agent exploration time across all future sessions.

>Step 4: Add Skills Incrementally

Don't try to build 92 skills on day one. Start with zero. When you find yourself giving the same instruction across multiple conversations, extract it into a skill. After a month, you'll have 5 to 10 skills that cover your most common workflows. After six months, you'll have 30+. They accumulate naturally.

>Step 5: Establish the RPE Protocol

For complex tasks, require the agent to follow Research, Planning, Execution. Create a task file. Plan before executing. Mark progress. Archive on completion. This single protocol eliminates the most common failure mode: the agent jumping into implementation without understanding the requirements.

---

#The Meta-Insight

The most important thing I've learned building this system is that AI agent configuration is software architecture.

It's not prompt engineering or conversation design. It's a real architectural discipline with the same concerns as any other system: modularity, separation of concerns, progressive loading, state persistence, layer hierarchies, extension points.

The developers who treat AI configuration as throwaway prompt text will keep getting inconsistent results. The developers who treat it as infrastructure will build compounding systems that get better with every session.

I've spent more time building the system that manages my AI agents than I've spent prompting the agents themselves. And that ratio feels exactly right. The system does the work. I maintain the system.

That's the architecture. The system is open. Explore at will.

---

Last updated: February 20, 2026