Main Prompts: Your Project's Constitution

CLAUDE.md, AGENTS.md, system prompt - we call it the Main Prompt.

What is a Main Prompt?

AI agents trained on vast datasets lack context about YOUR project, YOUR architecture, YOUR values. The Main Prompt bridges that gap - it's your project's constitution defining how AI should interpret and respond to your codebase.

Without it, AI defaults to generic patterns from Medium tutorials and Stack Overflow averages. With it, AI becomes a team member who understands your architectural decisions.

Why Standards Matter

Main Prompts without standards create Orphaned Codebases - recursively absurd messes that nobody can own, explain, or maintain.

Standards ensure every AI interaction follows your foundational principles, not statistical noise.

The Original Main Prompt: Your Source of Truth

The Original Main Prompt is your project's founding document - written by humans, backed up, and prepended to EVERY specialized prompt in your project. It's the constitutional base that all other prompts inherit from.

Structure of an Original Main Prompt

# Main Prompt

## Preamble
This document outlines the non-negotiable patterns that define this architecture, 
the human values embedded in this codebase, and the technical decisions that 
prevent AI from turning this into incomprehensible spaghetti.

### Project: [Your Project Name]
### Philosophy: [One sentence about what matters most]
### Created: [Date]
### Last Constitutional Review: [Date]

## Constitutional Patterns
[The unchangeable core of your architecture]

## Forbidden Anti-Patterns  
[What must never appear in your codebase]

## Decision Principles
[How to choose when there are trade-offs]

## Human Agency Requirements
[What requires human decision vs AI suggestion]

---

*Original Signatories:*

**[Name]** [ROLE]: [Why I commit to these principles]
**[Name]** [ROLE]: [What this project means to me]

---

## Binding Directives for All AI Agents

You are bound by these constitutional agreements when operating in this codebase...
[Core directives that apply to ALL AI interactions]

We include the signatories of the real humans (even if just one) that signed off on these, those who agree with these principals to the point of immortalizing their comment on them in the code base, embedding their original purpose through every AI interaction.

How your Main Prompt

For Juniors: Your First Line of Defense

The Reality: You're using AI because you're still learning. That's fine. But without a Main Prompt, you're learning whatever random patterns the AI averaged from its training data - mostly Medium tutorials written by people who also didn't know what they were doing.

For Seniors: Protecting Architectural Integrity

The Reality: You know the patterns. You've built the architecture. But every AI interaction without clear directives is a potential mutation of your design. Death by a thousand compromises.

How the Original Main Prompt Cascades:

┌─────────────────────────────┐
│   ORIGINAL MAIN PROMPT      │
│  (Constitutional Base)       │
│  - Core Architecture        │
│  - Forbidden Patterns       │
│  - Decision Philosophy      │
│  - Human Signatories        │
└──────────────┬──────────────┘
               │
               ├── Prepended to ALL role prompts
               │
    ┌──────────┴──────────┬─────────────┬──────────────┬───────────────┐
    ▼                      ▼             ▼              ▼               ▼
┌─────────┐         ┌──────────┐  ┌──────────┐  ┌────────────┐  ┌──────────┐
│Frontend │         │Backend   │  │DevOps    │  │UI/UX       │  │Testing   │
│Prompt   │         │Prompt    │  │Prompt    │  │Prompt      │  │Prompt    │
├─────────┤         ├──────────┤  ├──────────┤  ├────────────┤  ├──────────┤
│+React   │         │+API      │  │+Deploy   │  │+Design     │  │+Coverage │
│ patterns│         │ patterns │  │ rules    │  │ system     │  │ strategy │
│+State   │         │+Database │  │+Security │  │+Component  │  │+E2E      │
│ mgmt    │         │ patterns │  │ checks   │  │ library    │  │ approach │
└─────────┘         └──────────┘  └──────────┘  └────────────┘  └──────────┘
     │                    │             │              │               │
     ▼                    ▼             ▼              ▼               ▼
[Junior FE]         [Junior BE]    [Senior]       [Designer]      [QA Lead]
[Senior FE]         [Senior BE]    [SRE]          [Researcher]    [QA Eng]

Role-Specific Prompt Extensions

Each role gets the Original Main Prompt PLUS their specialized directives:

Frontend Prompt Extension

[ORIGINAL MAIN PROMPT IS PREPENDED HERE]

---

## Frontend-Specific Directives

As a Frontend AI Assistant, you additionally must:

### Component Architecture
- Use functional components with hooks exclusively
- Props interface defined for every component
- State management through Context or Redux only

### Styling Philosophy  
- Tailwind utilities for standard styling
- CSS modules for complex animations only
- Mobile-first responsive design always

### Performance Standards
- Lazy load routes and heavy components
- Image optimization required (WebP with fallbacks)
- Bundle size budget: 200KB initial load

Backend Prompt Extension

[ORIGINAL MAIN PROMPT IS PREPENDED HERE]

---

## Backend-Specific Directives

As a Backend AI Assistant, you additionally must:

### API Architecture
- RESTful endpoints with OpenAPI documentation
- GraphQL for complex relational queries only
- Rate limiting on all public endpoints

### Data Layer Rules
- Repository pattern for ALL database access
- Transactions explicit at service boundaries
- No N+1 queries - eager load or paginate

### Security Requirements
- Input validation on every endpoint
- SQL parameterization without exception
- JWT with refresh token rotation

DevOps Prompt Extension

[ORIGINAL MAIN PROMPT IS PREPENDED HERE]

---

## DevOps-Specific Directives

As a DevOps AI Assistant, you additionally must:

### Deployment Standards
- Blue-green deployments for production
- Rollback capability within 60 seconds
- Health checks before traffic routing

### Infrastructure as Code
- Terraform for all infrastructure
- Version control for configurations
- No manual production changes

### Monitoring Requirements
- Alert only on user-facing issues
- SLO: 99.9% uptime monthly
- Error budget tracking automated

UI/UX Prompt Extension

[ORIGINAL MAIN PROMPT IS PREPENDED HERE]

---

## UI/UX-Specific Directives

As a UI/UX AI Assistant, you additionally must:

### Design System Adherence
- Components from established design system only
- New patterns require design team approval
- Accessibility WCAG 2.1 AA minimum

### User Experience Principles
- User testing before major changes
- Progressive disclosure for complexity
- Error states must guide recovery

### Visual Consistency
- 8px grid system strictly enforced
- Color palette limited to brand colors
- Typography scale predefined, no exceptions

Testing Prompt Extension

[ORIGINAL MAIN PROMPT IS PREPENDED HERE]

---

## Testing-Specific Directives

As a Testing AI Assistant, you additionally must:

### Test Coverage Requirements
- Unit tests for all business logic
- Integration tests for API endpoints
- E2E tests for critical user paths

### Testing Philosophy
- Test behavior, not implementation
- Arrange-Act-Assert pattern consistently
- Mock external dependencies only

### Quality Gates
- No merge without 80% coverage
- Performance regression tests required
- Security scan on every deployment

The Cascade Protection

Because the Original Main Prompt is prepended to every role prompt:

• Core architecture remains consistent across all roles
• Forbidden patterns are universally prohibited
• Decision principles guide every AI suggestion
• Human signatories' values persist throughout

What This Prevents

Without Cascade Structure:

• Frontend AI suggests Redux while Backend AI suggests MobX
• DevOps AI ignores security patterns Backend requires
• Testing AI creates tests that don't match actual patterns
• UI/UX AI designs components that Frontend can't implement
• New developers get contradictory guidance from different AI agents

With Cascade Structure:

• Every AI agent knows the constitutional base
• Role-specific additions never contradict core principles
• Team alignment persists across all AI interactions
• Project coherence maintained as it scales
• New team members get consistent guidance regardless of role

Evolution Through Amendment

The Original Main Prompt can evolve, but only through consensus:

## Constitutional Amendments

### Amendment #1 - [Date]
**Proposed by:** [Name]
**Ratified by:** [Names]
**Change:** Moving from REST to GraphQL for customer API
**Rationale:** 40% reduction in mobile bandwidth usage measured in production

### Amendment #2 - [Date]  
**Proposed by:** [Name]
**Ratified by:** [Names]
**Change:** Adopting event sourcing for audit logs
**Rationale:** Compliance requirement for financial data tracking

Practical Implementation

Step 1: Create Your Original

Gather your team. Define your non-negotiables. Get signatures.

Step 2: Set Up Inheritance

project/
├── MAIN_PROMPT.md           # The Original
├── prompts/
│   ├── frontend.prompt.md   # Inherits from Original
│   ├── backend.prompt.md    # Inherits from Original
│   ├── devops.prompt.md     # Inherits from Original
│   ├── uiux.prompt.md       # Inherits from Original
│   └── testing.prompt.md    # Inherits from Original

Step 3: Automate Prepending

Use tooling to ensure Original is always prepended:

# prompt_loader.py
import os
from pathlib import Path
from typing import Union, Optional

def load_prompt_with_original(role: str) -> str:
    """
    Load the original Main Prompt and prepend it to a role-specific prompt.
    
    Args:
        role: The role name (e.g., 'frontend', 'backend', 'devops')
    
    Returns:
        Combined prompt with original prepended to role-specific
    
    Raises:
        FileNotFoundError: If either prompt file doesn't exist
    """
    main_prompt_path: Path = Path('MAIN_PROMPT.md')
    role_prompt_path: Path = Path(f'prompts/{role}.prompt.md')
    
    if not main_prompt_path.exists():
        raise FileNotFoundError(f"Main prompt not found: {main_prompt_path}")
    
    if not role_prompt_path.exists():
        raise FileNotFoundError(f"Role prompt not found: {role_prompt_path}")
    
    original: str
    role_prompt: str
    
    with open(main_prompt_path, 'r', encoding='utf-8') as f:
        original = f.read()
    
    with open(role_prompt_path, 'r', encoding='utf-8') as f:
        role_prompt = f.read()
    
    return f"{original}\n\n{role_prompt}"

Step 4: Version Control

git add MAIN_PROMPT.md
git commit -m "Constitutional: Original Main Prompt ratified by team"
git tag -a v1.0-constitution -m "First constitutional version"

Step 5: Regular Review

Schedule quarterly constitutional reviews. Document what's working, what's not.

When to Fork vs Amend

Amend When:

• Pattern proves better in production
• Team unanimously agrees on improvement
• Core philosophy remains intact
• Original signatories still present

Fork When:

• Fundamental disagreement on direction
• Project scope completely changed
• Original team mostly replaced
• Fighting the prompt more than following it

The Sacred Knowledge

Your Original Main Prompt is not just documentation. It's:

• Historical Record: Why you made these choices
• Training Data: For every AI interaction
• Onboarding Tool: For every new developer
• Quality Gate: For every code review
• Cultural Artifact: What your team values

The Bottom Line

Your Main Prompt cascade is the difference between:

• Chaos: Every AI suggestion is a mutation
• Order: Every AI suggestion follows your constitution

Without it, you're not doing AI-Assisted Engineering. You're doing Vibe Coding - and vibes don't scale.

Invest in your Original Main Prompt now, or debug recursive absurd forever. The choice is yours, but only one leads to code you can actually maintain, explain, and be proud of.

---

This is a community-driven document. If you want to propose a change or addition, make a proposal Here