OpenAgentsControl/.opencode/context/core/context-system/standards/codebase-references.md

Codebase References

Purpose: Link context files to actual code implementation

Last Updated: 2026-01-27

---

Core Principle

ALL context files SHOULD include 📂 Codebase References section linking to relevant code. Use sections that apply to your context type (not all files need all sections).

Why: Agents need to find actual implementation, not just read about it.

---

Section Types (Use What's Relevant)

Business Domain Context

**Business Logic**: (MOST IMPORTANT for business domains)
- `src/orders/rules/validation-rules.ts` - Order validation business rules

**Implementation**:
- `src/orders/order-processor.ts` - Main order processing logic

**Models/Types**:
- `src/orders/models/order.model.ts` - Order data model

**Tests**:
- `src/orders/__tests__/processor.test.ts` - Order processing tests

**Configuration**:
- `config/orders.config.ts` - Order processing config

Technical/Code Context

**Implementation**: (MOST IMPORTANT for technical contexts)
- `src/auth/jwt-handler.ts` - JWT authentication implementation

**Examples**:
- `src/auth/examples/jwt-example.ts` - Working JWT example

**Types**:
- `src/auth/types/jwt-payload.ts` - JWT payload types

**Tests**:
- `src/auth/__tests__/jwt.test.ts` - JWT tests

Standards/Quality Context

**Validation/Enforcement**: (MOST IMPORTANT for standards)
- `scripts/validate-code-quality.ts` - Code quality validator
- `eslint.config.js` - ESLint rules

**Examples**:
- `examples/good-code.ts` - Good code example
- `examples/bad-code.ts` - Anti-pattern example

**Tests**:
- `tests/code-quality.test.ts` - Quality validation tests

Operational Context

**Scripts/Tools**: (MOST IMPORTANT for operations)
- `scripts/deploy.sh` - Deployment script
- `scripts/monitor.ts` - Monitoring setup

**Configuration**:
- `config/deployment.config.ts` - Deployment configuration
- `.github/workflows/deploy.yml` - CI/CD workflow

---

Rules

1. Use project-relative paths (src/..., not /Users/...)
2. Use forward slashes (/)
3. Include file extension (.ts, .js, .sh)
4. Brief description (3-10 words) for each file
5. Verify files exist (warn if not found)
6. Use relevant sections only (not all files need all sections)

---

Examples

Business Context:

## 📂 Codebase References

**Business Logic**:
- `src/payments/rules/validation-rules.ts` - Card validation rules
- `src/payments/rules/fraud-detection.ts` - Fraud detection logic

**Implementation**:
- `src/payments/payment-processor.ts` - Main payment processing

**Tests**:
- `src/payments/__tests__/processor.test.ts` - Payment tests

Technical Context:

## 📂 Codebase References

**Implementation**:
- `src/auth/jwt-handler.ts` - JWT authentication

**Examples**:
- `examples/jwt-auth.ts` - Working example

**Tests**:
- `src/auth/__tests__/jwt.test.ts` - JWT tests

---

Validation

• Has "📂 Codebase References" section?
• Most important section for context type included?
• Paths are project-relative?
• Paths include extensions?
• Each path has 3-10 word description?

---

Related

• frontmatter.md - Frontmatter format
• templates.md - File templates
• structure.md - File organization
• templates/ - File templates with codebase references