Knowledge Priming

The Default Behavior Problem

Here is what typically happens when asking AI to generate code without priming:

Request: “Create a UserService that handles authentication”

AI generates 200 lines of code using:

• Express.js (the project uses Fastify)
• JWT stored in localStorage (the project uses httpOnly cookies)
• A utils/auth.js helper (the convention is lib/services/)
• Class-based syntax (the codebase is functional)
• An outdated bcrypt API (the project uses the latest version)

The code works. It is syntactically correct. It might even pass basic tests. But it is completely wrong for the codebase.

Why? Because AI defaults to its training data—a blend of millions of repositories, tutorials, and Stack Overflow answers. It generates the “average” solution from the internet, not the right solution for a specific team.

This is exactly what would happen if I asked a new hire to write code on Day 1 without any onboarding. They would draw on their prior experience—which may or may not match our conventions.

What Knowledge Priming Looks Like

Knowledge Priming is the practice of sharing curated documentation, architectural patterns, and version information with AI before asking it to generate code.

Think of it as the onboarding packet for a new hire:

• “Here is the tech stack and versions”
• “Here is how code is structured”
• “Here are the naming conventions”
• “Here are examples of good code in this codebase”

Anatomy of a Priming Document

A good priming document is not a brain dump. It is a curated, structured guide that gives AI exactly what it needs—no more, no less.

I propose seven sections. Each mirrors what I would walk through when onboarding a human colleague:

## Architecture Overview
This is a microservices-based e-commerce platform.
- API Gateway: Handles routing, auth, rate limiting
- User Service: Authentication, profiles, preferences
- Order Service: Cart, checkout, order history
- Notification Service: Email, SMS, push notifications

Services communicate via async message queues (RabbitMQ).
Each service owns its database (PostgreSQL).
        

## Tech Stack
- **Runtime**: Node.js 20.x (LTS)
- **Framework**: Fastify 4.x (not Express)
- **Database**: PostgreSQL 15 with Prisma ORM 5.x
- **Auth**: JWT with httpOnly cookies (not localStorage)
- **Testing**: Vitest + Testing Library (not Jest)
- **Validation**: Zod schemas (not Joi)
        

## Curated Knowledge

### Official Documentation
| Topic | Source | Why We Trust It |
|-------|--------|-----------------|
| Fastify routing | https://fastify.dev/docs/latest/Guides/Getting-Started | Official, matches our v4.x |
| Prisma relations | https://www.prisma.io/docs/orm/prisma-schema/data-model/relations | Authoritative for schema patterns |

### Blogs and Articles We Follow
| Concept | Source | Why It Shaped Our Thinking |
|---------|--------|---------------------------|
| Error handling patterns | [team-vetted blog URL] | Clearer than official docs, practical examples |
| Testing strategies | [team-vetted blog URL] | Influenced our test architecture |

### Internal References
| Topic | Path | What It Captures |
|-------|------|------------------|
| Error conventions | docs/error-handling.md | Our specific patterns |
| API design decisions | docs/adr/003-api-versioning.md | Decision rationale |
        

src/
├── lib/
│   ├── services/      # Business logic (UserService, OrderService)
│   ├── repositories/  # Database access layer
│   ├── schemas/       # Zod validation schemas
│   └── utils/         # Pure utility functions
├── routes/            # Fastify route handlers
├── middleware/        # Auth, logging, error handling
├── types/             # TypeScript type definitions
└── config/            # Environment-specific config
        

## Naming Conventions
- **Files**: kebab-case (`user-service.ts`, not `UserService.ts`)
- **Functions**: camelCase, verb-first (`createUser`, `validateToken`)
- **Types/Interfaces**: PascalCase with descriptive suffixes (`UserCreateInput`, `AuthResponse`)
- **Constants**: SCREAMING_SNAKE_CASE (`MAX_RETRY_COUNT`)
- **Boolean variables**: is/has/can prefix (`isActive`, `hasPermission`)
        

// lib/services/user-service.ts
import { prisma } from '../db/client'
import { UserCreateInput, UserResponse } from '../types/user'
import { hashPassword } from '../utils/crypto'

export async function createUser(input: UserCreateInput): Promise<UserResponse> {
  const hashedPassword = await hashPassword(input.password)
  
  const user = await prisma.user.create({
    data: {
      ...input,
      password: hashedPassword,
    },
    select: {
      id: true,
      email: true,
      createdAt: true,
      // Never return password
    },
  })
  
  return user
}

## Anti-patterns (Do NOT use)
- Class-based services (use functional approach)
- Express.js patterns (this project uses Fastify)
- Storing JWT in localStorage (use httpOnly cookies)
- Using any type (always define proper types)
- Putting business logic in route handlers (use services)
- Raw SQL queries (use Prisma ORM)
        

Priming as Infrastructure, Not Habit

The most powerful approach, I believe, is treating priming as infrastructure rather than habit.

Instead of manually pasting context at the start of each session (a habit that fades), store the priming document in the repository where it applies automatically:

# Cursor
.cursor/
├── rules                    # Always-on project context (auto-loaded)
└── commands/
└── priming.md          # Referenceable with @priming

# GitHub Copilot
.github/
└── copilot-instructions.md  # Workspace-level instructions

# Claude Projects
Upload priming doc to Project Knowledge
      

Why infrastructure beats copy-paste:

• Version controlled: Changes are auditable and reviewable
• Applies automatically: No manual copy-paste each session
• Team-wide consistency: Everyone gets the same context
• PR-reviewable changes: Governance built into existing workflows

This transforms priming from a “personal productivity hack” into “team infrastructure.” The difference between a habit that fades and a practice that persists.

Just as onboarding materials for new hires are maintained as organizational assets—not improvised each time—priming documents should be treated as first-class artifacts.

Common Pitfalls

In my own experimentation, I have observed several failure modes:

Keeping Priming Documents Current

Documentation rots. Every team has a graveyard of outdated wikis and stale READMEs. How to prevent a priming doc from joining them?

Treat it as code, not docs:

• Store in repo: docs/ai-priming.md
• Changes require PR review (like any code change)
• Tech lead owns quarterly review (aligned with dependency updates)

Reference, do not duplicate:

• For auth decisions: “See ADR-007”
• For API contracts: “See OpenAPI spec in /api/schema.yaml“
• For deployment patterns: “See ops runbook”

Update triggers:

A stale priming doc is worse than none—it teaches AI outdated patterns. But a priming doc that lives in the repo, reviewed like code, stays current by design.

A Real-World Example

Here is a condensed priming document from a project I worked on:

# Acme API - Priming Context

## Quick Overview
B2B SaaS API for inventory management. Multi-tenant, event-driven.

## Stack
- Node.js 20, Fastify 4, TypeScript 5
- PostgreSQL 15 + Prisma 5 (multi-tenant via tenantId)
- Auth: Clerk (external), JWT validation middleware
- Queue: BullMQ + Redis for async jobs
- Testing: Vitest

## Trusted Sources
### Docs
- Fastify: https://fastify.dev/docs/latest
- Prisma multi-tenancy: https://www.prisma.io/docs/orm/prisma-client/queries/multi-tenancy

### Blogs We Follow
- BullMQ patterns: [team-vetted blog on queue handling]

### Internal
- ADRs: docs/adr/ (architecture decisions)
- Error handling: docs/error-conventions.md

## Structure
src/
├── modules/           # Feature modules (users/, products/, orders/)
│   └── [module]/
│       ├── service.ts    # Business logic
│       ├── routes.ts     # HTTP handlers
│       ├── schema.ts     # Zod schemas
│       └── types.ts      # TypeScript types
├── shared/            # Cross-cutting (db, auth, queue)
└── config/            # Env config

## Patterns
- Functional services (no classes)
- All queries include `where: { tenantId }` (multi-tenant)
- Validation at route level with Zod
- Errors thrown as `AppError` with status codes

## Anti-patterns
- No classes for services
- No raw SQL (use Prisma)
- No business logic in routes
- No hardcoded tenantId

## Example Service
[Include one short example from the codebase]
      

Notice: It is under 50 lines. That is the target. Focused, specific, actionable.

Trade-offs and Limitations

This approach is not without costs:

• Upfront effort: Creating and maintaining priming documents requires time
• Diminishing returns: For very simple tasks, the overhead may not be justified
• Stale context risk: Outdated priming docs can be worse than none
• Not a guarantee: Even with good priming, AI will sometimes produce wrong output

I hypothesize that the payoff is greatest for non-trivial work—especially work that spans multiple sessions or involves team coordination. For a quick utility function, manual correction may be faster than maintaining context infrastructure.

Conclusion

Knowledge Priming is, in essence, manual RAG: filling the AI's context window with high-value, project-specific information before asking for code generation. The hypothesis is straightforward—explicit context should override generic defaults, resulting in output that fits the codebase rather than “the average of the internet.”

My current thinking is that the key shift is treating context as infrastructure (versioned files in the repo) rather than habit (copy-pasting at session start). Infrastructure persists; habits fade.

This is the foundation for everything else. Design-first conversations are more productive when AI already understands the architecture. Custom commands work better when AI knows the conventions. The investment in priming compounds.