Skip to content
Oka Docs

CLAUDE.md patterns

The simplest way to ensure agents capture intelligence is to tell them to. CLAUDE.md (and equivalent config files for other clients) is the soft enforcement layer — instructions that shape agent behavior without any code changes.

Basic setup

Add this to your project’s CLAUDE.md:

## Institutional Intelligence (Oka)


This project uses Oka Reason for persistent organizational intelligence.


### Before starting work


- Call `context` with the area you're working on (e.g., "auth", "billing")
- Review returned learnings before making decisions
- Check `decisions` to see if the question has already been settled


### While working


- Record significant decisions with `decision` (include rationale + alternatives)
- Record deviations from your plan with `deviation`
- Record observations about code quality, patterns, or friction with `observe`


### Before finishing


- Call `done` with the outcome and quality notes
- Record any insights with `learning`
- Call `feedback` on any learnings from `context` that were useful (or not)

This alone gets ~40-60% compliance. Agents follow CLAUDE.md instructions most of the time, and each compliant session feeds the intelligence layer.

Advanced: area-specific instructions

For projects with distinct areas, add targeted instructions:

## Area-specific Oka usage


### Auth work


Before touching auth code, always run:


- `context("auth middleware")`
- `context("JWT refresh")`
- `decisions(module: "auth")`


We've had three incidents from auth changes that ignored prior learnings.


### Billing work


- `context("stripe webhooks")` — we've discovered multiple silent failure
  modes that consolidation has captured
- Always `observe` any new Stripe behavior you encounter


### CI/CD work


- `context("ci pipeline")` — there are known flaky test patterns
- `deviation` any time you work around a CI issue rather than fixing it

Maximizing signal quality

Use structured tools, not just observe

Bad — low signal:

observe("changed the auth approach")

Good — high signal:

decision(
  decision: "Switched from session cookies to JWT for API auth",
  rationale: "Need stateless auth for horizontal scaling. Sessions
    require sticky sessions or shared session store.",
  alternatives: "Session cookies + Redis, Passport.js sessions",
  confidence: 0.9
)

The structured fields make consolidation dramatically more effective. A decision with rationale and alternatives produces better learnings than an observe with the same information in free text.

Tag consistently

Tags power context queries. Establish a tagging convention:

observe(
  content: "The billing webhook handler has no retry logic",
  tags: ["billing", "webhooks", "reliability"],
  category: "bug"
)

Good tag categories:

  • Service area: auth, billing, payments, onboarding
  • Concern: performance, security, reliability, dx
  • Technology: postgres, redis, stripe, supabase

Record failures explicitly

Failures are the highest-value events. They prevent future agents from repeating dead ends:

deviation(
  content: "gRPC approach abandoned for internal gateway",
  expected: "gRPC per ADR-015",
  actual: "REST with protobuf — Cloudflare Workers don't support gRPC",
  impact: "No streaming; polling required for long-running ops"
)


done(
  task: "Implement gRPC gateway",
  outcome: "failed",
  quality: "Incompatible with our edge runtime. Do not retry."
)