The Context System: A Complete Guide

What Is Context?

Context is your project's coding standards and patterns stored as markdown files. It tells agents:

How you write code (naming conventions, architecture)
What libraries you use (React, Next.js, Tailwind, etc.)
Your security requirements
Your design system
Your project-specific patterns

Think of it as a style guide for AI agents.

Why Context Matters

Without Context

You: "Create a React component"
Agent: Creates component in its own style
Result: Doesn't match your project

With Context

You: "Create a React component"
Agent: Loads your React pattern from context
Agent: Creates component matching your style
Result: Perfectly matches your project

How Context Works

The Flow

Your Request
    ↓
Agent receives request
    ↓
ContextScout discovers relevant context files
    ↓
Agent loads context files
    ↓
Agent follows patterns from context
    ↓
Code matches your standards automatically

Example: Creating a React Component

Step 1: You ask for a component

"Create a user profile component"

Step 2: ContextScout discovers

core/standards/code-quality.md (modular patterns)
ui/web/react-patterns.md (React conventions)
project-intelligence/technical-domain.md (YOUR patterns)

Step 3: Agent loads context

# From project-intelligence/technical-domain.md

## React Component Pattern

All components should:
- Use TypeScript with strict mode
- Export named component
- Include JSDoc comments
- Use React.FC type

export const UserProfile: React.FC<Props> = ({ user }) => {
  return <div>{user.name}</div>;
};

Step 4: Agent creates component

/**
 * UserProfile - Displays user information
 */
export const UserProfile: React.FC<UserProfileProps> = ({ user }) => {
  return (
    <div className="user-profile">
      <h2>{user.name}</h2>
      <p>{user.email}</p>
    </div>
  );
};

Result: Component matches your patterns automatically!

Context Directory Structure

.opencode/context/
├── core/                           # Universal standards
│   ├── standards/
│   │   ├── code-quality.md        # Modular, functional patterns
│   │   ├── security-patterns.md   # Security best practices
│   │   ├── test-coverage.md       # Testing standards
│   │   └── documentation.md       # Documentation patterns
│   ├── workflows/
│   │   ├── design-iteration.md    # 4-stage UI design
│   │   ├── task-delegation.md     # Task delegation patterns
│   │   ├── external-libraries.md  # Library integration
│   │   └── code-review.md         # Code review process
│   └── task-management/
│       └── standards/
│           └── task-schema.md     # Task JSON schema
│
├── ui/                             # Design & UX
│   └── web/
│       ├── ui-styling-standards.md    # Tailwind + Flowbite
│       ├── animation-patterns.md      # Micro-interactions
│       ├── react-patterns.md          # React conventions
│       └── design-systems.md          # Design system principles
│
├── development/                    # Language-specific
│   ├── backend-navigation.md
│   ├── ui-navigation.md
│   └── [language-specific patterns]
│
└── project-intelligence/            # YOUR custom patterns
    ├── technical-domain.md          # Tech stack & code patterns
    ├── business-domain.md           # Business context
    └── navigation.md                # Quick overview

What's Included in Core Context

1. Code Quality Standards (`core/standards/code-quality.md`)

Teaches agents:

Modular design principles
Functional programming patterns
Pure functions and immutability
Composition over inheritance
Naming conventions

Example:

// ✅ Pure function (from context)
const add = (a, b) => a + b;

// ❌ Impure (agents avoid this)
let total = 0;
const addToTotal = (value) => { total += value; };

2. Security Patterns (`core/standards/security-patterns.md`)

Teaches agents:

Input validation
Authentication checks
Authorization patterns
Secure error handling
Logging best practices

3. Design Iteration (`core/workflows/design-iteration.md`)

Teaches agents:

4-stage UI design workflow
Layout → Theme → Animation → Implementation
Approval gates at each stage
Design versioning strategy

4. External Libraries (`core/workflows/external-libraries.md`)

Teaches agents:

How to integrate external libraries
Common patterns for popular libraries
Configuration best practices
Dependency management

5. UI Styling Standards (`ui/web/ui-styling-standards.md`)

Teaches agents:

Tailwind CSS conventions
Flowbite component usage
Color palette standards
Responsive design patterns

6. React Patterns (`ui/web/react-patterns.md`)

Teaches agents:

Modern React hooks
Component composition
State management patterns
Performance optimization

Adding Your Own Patterns

Step 1: Edit Your Project Context

# Recommended: Use the interactive wizard
/add-context

# Or edit directly (local project install):
nano .opencode/context/project-intelligence/technical-domain.md

# Global install:
# nano ~/.config/opencode/context/project-intelligence/technical-domain.md

Step 2: Add Your Patterns

# Your Project Patterns

## API Endpoint Pattern

All API endpoints should follow this pattern:

```typescript
export async function POST(request: Request) {
  try {
    // 1. Parse and validate input
    const body = await request.json();
    if (!body.email) {
      return Response.json({ error: 'Email required' }, { status: 400 });
    }

    // 2. Check authentication
    const user = await auth.verify(request);
    if (!user) {
      return Response.json({ error: 'Unauthorized' }, { status: 401 });
    }

    // 3. Process request
    const result = await processRequest(body);

    // 4. Return response
    return Response.json({ success: true, data: result });
  } catch (error) {
    console.error('POST error:', error);
    return Response.json({ error: error.message }, { status: 500 });
  }
}

React Component Pattern

All React components should:

Use TypeScript with strict mode
Export named component
Include JSDoc comments
Use React.FC type
Include prop validation

interface UserCardProps {
  userId: string;
  onSelect?: (id: string) => void;
}

/**
 * UserCard - Displays user information in a card
 * @param props - Component props
 */
export const UserCard: React.FC<UserCardProps> = ({ 
  userId, 
  onSelect 
}) => {
  const [user, setUser] = React.useState(null);

  React.useEffect(() => {
    fetchUser(userId).then(setUser);
  }, [userId]);

  return (
    <div className="user-card">
      <h3>{user?.name}</h3>
      <button onClick={() => onSelect?.(userId)}>
        Select
      </button>
    </div>
  );
};

Database Query Pattern

All database queries should:

Use parameterized queries
Include error handling
Log important operations
Return typed results

export async function getUserById(id: string) {
  try {
    const user = await db
      .select()
      .from(users)
      .where(eq(users.id, id))
      .limit(1);
    
    if (!user.length) {
      throw new Error('User not found');
    }

    return user[0];
  } catch (error) {
    console.error('getUserById error:', error);
    throw error;
  }
}

Security Checklist

All endpoints must:

Naming Conventions

Files: lowercase-with-dashes.ts
Functions: verbPhrases (getUser, validateEmail)
Constants: UPPER_CASE
Types: PascalCase
Variables: camelCase
Predicates: isValid, hasPermission, canAccess

Folder Structure

src/
├── components/          # React components
│   ├── common/         # Reusable components
│   ├── features/       # Feature-specific components
│   └── layouts/        # Layout components
├── lib/                # Utilities and helpers
├── api/                # API routes
├── types/              # TypeScript types
├── styles/             # Global styles
└── hooks/              # Custom React hooks


### Step 3: Agents Use Your Patterns

When you ask an agent to create code, it will:
1. Load your project context
2. Follow your patterns
3. Create code matching your style

---

## Real-World Examples

### Example 1: Adding a Component Pattern

**Your project context**:
```markdown
## Button Component Pattern

All buttons should:
- Use Tailwind classes
- Include loading state
- Support disabled state
- Include accessibility attributes

export const Button: React.FC<ButtonProps> = ({
  children,
  isLoading,
  disabled,
  ...props
}) => (
  <button
    disabled={disabled || isLoading}
    className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600 disabled:opacity-50"
    aria-busy={isLoading}
    {...props}
  >
    {isLoading ? 'Loading...' : children}
  </button>
);

You ask:

"Create a submit button for the login form"

Agent creates:

export const SubmitButton: React.FC<SubmitButtonProps> = ({
  isLoading,
  disabled,
}) => (
  <Button
    type="submit"
    isLoading={isLoading}
    disabled={disabled}
  >
    Sign In
  </Button>
);

✅ Automatically follows your button pattern!

Example 2: Adding an API Pattern

Your project context:

## API Response Pattern

All API responses should:
- Return { success, data, error }
- Include proper status codes
- Log all requests
- Validate input

export async function POST(request: Request) {
  try {
    const body = await request.json();
    
    // Validate
    if (!body.email) {
      return Response.json(
        { success: false, error: 'Email required' },
        { status: 400 }
      );
    }

    // Process
    const result = await process(body);

    // Return
    return Response.json({ success: true, data: result });
  } catch (error) {
    return Response.json(
      { success: false, error: error.message },
      { status: 500 }
    );
  }
}

You ask:

"Create an API endpoint to create a new user"

Agent creates:

export async function POST(request: Request) {
  try {
    const body = await request.json();
    
    // Validate
    if (!body.email || !body.password) {
      return Response.json(
        { success: false, error: 'Email and password required' },
        { status: 400 }
      );
    }

    // Process
    const user = await createUser(body);

    // Return
    return Response.json({ success: true, data: user });
  } catch (error) {
    return Response.json(
      { success: false, error: error.message },
      { status: 500 }
    );
  }
}

✅ Automatically follows your API pattern!

Example 3: Adding a Security Pattern

Your project context:

## Security Requirements

All endpoints must:
- Verify user authentication
- Check user permissions
- Validate all inputs
- Use parameterized queries
- Log security events

Example:
```typescript
export async function POST(request: Request) {
  // 1. Verify authentication
  const user = await auth.verify(request);
  if (!user) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 });
  }

  // 2. Check permissions
  if (!user.isAdmin) {
    return Response.json({ error: 'Forbidden' }, { status: 403 });
  }

  // 3. Validate input
  const body = await request.json();
  if (!validateInput(body)) {
    return Response.json({ error: 'Invalid input' }, { status: 400 });
  }

  // 4. Log security event
  console.log(`Admin action by ${user.id}: create-user`);

  // 5. Process
  const result = await process(body);
  return Response.json({ success: true, data: result });
}


**You ask**:

"Create an admin endpoint to delete a user"


**Agent creates**:
```typescript
export async function DELETE(request: Request) {
  // 1. Verify authentication
  const user = await auth.verify(request);
  if (!user) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 });
  }

  // 2. Check permissions
  if (!user.isAdmin) {
    return Response.json({ error: 'Forbidden' }, { status: 403 });
  }

  // 3. Validate input
  const { userId } = await request.json();
  if (!userId) {
    return Response.json({ error: 'User ID required' }, { status: 400 });
  }

  // 4. Log security event
  console.log(`Admin action by ${user.id}: delete-user ${userId}`);

  // 5. Process
  await deleteUser(userId);
  return Response.json({ success: true });
}

✅ Automatically includes all security checks!

Context Best Practices

1. Keep It Organized

# Your Project Patterns

## Components
[Component patterns]

## API Endpoints
[API patterns]

## Database
[Database patterns]

## Security
[Security requirements]

## Naming
[Naming conventions]

## Folder Structure
[Folder structure]

2. Include Real Examples

## Good ✅
export const Button: React.FC<Props> = ({ ... }) => {
  // Real example from your project
};

## Bad ❌
export const Button = (props) => {
  // Generic example
};

3. Be Specific

## Good ✅
All API endpoints must:
- Validate input with Zod
- Return { success, data, error }
- Log with console.error for errors
- Use 400 for validation, 401 for auth, 500 for server

## Bad ❌
All API endpoints should be good

4. Update Regularly

When you change patterns:

Run /add-context --update or edit project-intelligence/technical-domain.md directly
Agents will use new patterns immediately
No need to restart anything

Troubleshooting

Problem: Agent isn't following my patterns

Solution:

Check that project-intelligence/technical-domain.md exists (run /add-context if not)
Verify the pattern is clearly written
Include a real example
Ask agent to "follow project patterns"

Problem: Agent uses old patterns

Solution:

Run /add-context --update or edit project-intelligence/technical-domain.md
Restart the agent
Ask agent to "load latest context"

Problem: Pattern is too complex

Solution:

Break into smaller patterns
Include step-by-step example
Add comments explaining why

Problem: Agent creates code that doesn't match

Solution:

Check if pattern is in project-intelligence/technical-domain.md
Verify pattern is specific enough
Ask agent to "review against project patterns"
Provide feedback to refine pattern

Advanced: Context Hierarchy

Agents load context in this order:

Core Standards (universal patterns)
- core/standards/code-quality.md
- core/standards/security-patterns.md
Workflows (how to do things)
- core/workflows/design-iteration.md
- core/workflows/external-libraries.md
Domain-Specific (language/framework)
- development/[language]/patterns.md
- ui/web/react-patterns.md
Project-Specific (YOUR patterns) ← Most important!
- project-intelligence/technical-domain.md

Project context overrides everything else!

Summary

Context is your secret weapon for AI-assisted development:

✅ Automatic pattern following - No manual configuration ✅ Consistent code - All code matches your style ✅ Team alignment - Everyone follows same patterns ✅ Easy updates - Change patterns once, agents use everywhere ✅ Living documentation - Patterns stay in sync with code

Get started:

Run /add-context to create project intelligence interactively
Or edit .opencode/context/project-intelligence/technical-domain.md directly
Ask agents to create code
Watch them follow your patterns automatically!

Next Steps

Run /add-context to create project intelligence interactively
Review your current coding patterns
Include real examples from your project
Test by asking agents to create code
Refine patterns with /add-context --update

Your agents will become better and better as your context improves!

FilesExpand file tree

CONTEXT_SYSTEM_GUIDE.md

Latest commit

History

CONTEXT_SYSTEM_GUIDE.md

File metadata and controls

The Context System: A Complete Guide

What Is Context?

Why Context Matters

Without Context

With Context

How Context Works

The Flow

Example: Creating a React Component

Context Directory Structure

What's Included in Core Context

1. Code Quality Standards (core/standards/code-quality.md)

2. Security Patterns (core/standards/security-patterns.md)

3. Design Iteration (core/workflows/design-iteration.md)

4. External Libraries (core/workflows/external-libraries.md)

5. UI Styling Standards (ui/web/ui-styling-standards.md)

6. React Patterns (ui/web/react-patterns.md)

Adding Your Own Patterns

Step 1: Edit Your Project Context

Step 2: Add Your Patterns

React Component Pattern

Database Query Pattern

Security Checklist

Naming Conventions

Folder Structure

Example 2: Adding an API Pattern

Example 3: Adding a Security Pattern

Context Best Practices

1. Keep It Organized

2. Include Real Examples

3. Be Specific

4. Update Regularly

Troubleshooting

Problem: Agent isn't following my patterns

Problem: Agent uses old patterns

Problem: Pattern is too complex

Problem: Agent creates code that doesn't match

Advanced: Context Hierarchy

Summary

Next Steps

1. Code Quality Standards (`core/standards/code-quality.md`)

2. Security Patterns (`core/standards/security-patterns.md`)

3. Design Iteration (`core/workflows/design-iteration.md`)

4. External Libraries (`core/workflows/external-libraries.md`)

5. UI Styling Standards (`ui/web/ui-styling-standards.md`)

6. React Patterns (`ui/web/react-patterns.md`)