Context Engineering with CodeRadius

Context Engineering is the discipline of systematically building, distributing, and governing the instructions, constraints, and knowledge that AI coding agents use to operate within a specific codebase or organization.

In a team of 5 engineers, context engineering is informal: the senior developer writes a .cursorrules file, shares it in Slack. In an organization of 300 repositories across 20 teams, informal context engineering fails. CodeRadius exists to industrialize it.

What Is AI Coding Context?

When an AI coding agent works in your repository, it operates based on:

1. Global rules — Instructions that always apply in this repository, regardless of the file being edited (.cursorrules, CLAUDE.md, GEMINI.md).
2. Scoped rules — Instructions that activate only for specific file patterns (.cursor/rules/database-migrations.mdc applies only when editing **/migrations/**).
3. Skills — Portable, executable procedures the agent can follow for specific, repeatable tasks.
4. Workflows — Multi-step automation scripts the agent can execute.
5. MCP Servers — Real-time data connections that allow the agent to query live systems as part of its reasoning (e.g., querying CodeRadius itself for blast radius data, or querying Jira for open tickets).

Together, these form the AI context stack for a repository. The richer and more accurate this stack, the lower the probability of AI hallucinations, architectural drift, and misaligned output.

Reaching Each Maturity Level — In Practice

Getting to L1: Awareness

The minimum viable act of context engineering. Create a global rule file for your AI tool of choice and add any content at all. Even a brief description of the service's purpose prevents the agent from guessing.

# .cursorrules (or CLAUDE.md, or GEMINI.mdx)

This is the **payments-service**, responsible for processing card transactions
and refunds using the Stripe API.

- Language: TypeScript (strict mode)
- Framework: NestJS with hexagonal architecture
- Database: PostgreSQL via Prisma ORM
- Never use `any` types
- All async operations must use async/await, not callbacks

This 50-word file, placed in the root of the repository, immediately saves the agent from having to infer the service's purpose and constraints from scratch on every conversation.

Getting to L2: Configuration

Expand the global rule with substantive content: domain-specific constraints, prohibited patterns, architectural boundaries. The key threshold is 200+ characters — enough to encode at least 5–10 meaningful constraints that measurably influence agent behavior.

# .cursorrules

## Architecture
This service follows Clean Architecture. Business logic lives in `src/domain/`.
Infrastructure adapters (Stripe, PostgreSQL) live in `src/infra/`.
Never import from `infra/` directly inside `domain/`.

## API Design
- All endpoints must be versioned (`/api/v1/...`)
- Request/response payloads must be validated with Zod schemas
- Raw `req.body` access is forbidden outside DTO validation layers

## Error Handling
- Never swallow errors silently. All catch blocks must log via the shared Logger.
- Payment failures must emit a `payment.failed` event to the MessageBus.
- Sentry is configured — any unhandled exception will be captured automatically.

## Prohibited Patterns
- Never use `setTimeout` for business logic. Use the scheduled task system.
- Never store credit card data. Stripe tokenization is mandatory.
- Never log PII (email addresses, names, card numbers).

Getting to L3: Skills

Skills transform the agent from a rule-follower into a task-executor. A skill is a structured markdown file that teaches the agent how to perform a specific repeatable task in the context of this codebase.

Skill directory: .agents/skills/<skill-name>/SKILL.md

Example skill: Creating a database migration

---
name: "database-migration"
description: "How to create a new database migration for the payments service"
---

# Database Migration Skill

## When to use this skill
Use this when asked to add a new column, create a new table, or modify an existing
database schema in the payments service.

## Steps

1. **Create the migration file**
   Run: `npm run migration:create -- --name <descriptive-name>`
   This creates a timestamped file in `src/infra/db/migrations/`.

2. **Write the migration**
   - All migrations must be idempotent (use `IF NOT EXISTS`, `IF EXISTS`)
   - Include both `up` and `down` methods
   - Add a comment with the JIRA ticket reference: `-- JIRA: PAY-{number}`

3. **Update the Prisma schema**
   Reflect the migration in `prisma/schema.prisma`. Run:
   `npx prisma generate`

4. **Test the migration**
   Run: `npm run migration:run -- --env test`
   Verify the migration applies and rolls back cleanly.

5. **Update the seed data** (if applicable)
   Update `src/infra/db/seed.ts` to include any new required reference data.

This skill, placed in the repository, is detected by CodeRadius, indexed in the Capabilities Catalog, and becomes discoverable by any Principal Engineer scanning the fleet.

Getting to L4: Orchestration

At L4, the repository runs a coordinated agentic pipeline rather than ad-hoc agent conversations. There are two paths:

Path A: MCP Integration

The repository's MCP configuration connects the AI agent to live data sources during its reasoning process:

{
  "mcpServers": {
    "coderadius": {
      "command": "cr",
      "args": ["mcp", "start"]
    },
    "jira": {
      "command": "npx",
      "args": ["-y", "@jira/mcp-server"],
      "env": { "JIRA_API_TOKEN": "..." }
    }
  }
}

Path B: Subagent Modes

The repository defines specialized subagent modes with role-specific rules and capabilities:

# config/agents.yaml (CrewAI example)
agents:
  - name: architect
    role: Senior Software Architect
    goal: Review all architectural decisions for consistency with domain boundaries
    backstory: An expert in hexagonal architecture and domain-driven design
    
  - name: security-reviewer  
    role: Application Security Specialist
    goal: Identify OWASP violations and data exposure risks in proposed code changes
    backstory: A specialist in payment system security and PCI DSS compliance

Distributing Context at Scale

The Golden Path Pattern

A "Golden Path" is a curated set of AI context files that every new repository in the organization receives by default. It typically includes:

1. A baseline global_rule file encoding organizational-wide coding standards
2. A security scoped rule for any security-sensitive file patterns
3. A reference to the organization's core MCP server (CodeRadius)

The Golden Path is typically distributed through:

Backstage Templates: Every service scaffolded from a Backstage template includes the Golden Path files automatically.

CI Propagation: A scheduled GitHub Actions workflow that checks every repository for the presence of baseline context files and opens a PR to add them if missing.

One-time seeding script: For large-scale initial rollouts, a script that clones every repository and commits the baseline files in a single batch.

The Discovery Loop

In short: once CodeRadius is ingesting your fleet, sort the Capabilities Catalog by Usage ascending, find high-quality skills with usageCount: 1, generalize them, and distribute. Repeating this loop quarterly converts isolated team expertise into organizational leverage.

Supported Config File Formats

The following file formats are automatically detected and indexed by CodeRadius:

Global Rules (always-on instructions)

Scoped Rules (file-pattern-activated)

Skills and Workflows

MCP Configuration

Multi-Agent / Orchestration