# CLAUDE.md Convention for Adapter Repos

## Three-Layer Context Model

ENTR uses a three-layer documentation strategy so that Claude Code always has the right context at the right level:

| Layer | Location | Contains | Update Frequency |
|-------|----------|----------|-----------------|
| Package knowledge | `entr-adapter-core` co-located markdown + docstrings | Framework patterns, BaseHandler contract, schemas, deployment conventions, handler checklist | Updates with package versions |
| Core platform knowledge | Entr-Core's `CLAUDE.md` and docs | Full pipeline, event system, how adapters fit the bigger picture | Updates with Core releases |
| Adapter-specific knowledge | Adapter repo's own slim `CLAUDE.md` | Tenant business rules, target system details, handler-specific conventions | Rarely changes |

### Why This Model Works

- **Framework knowledge stays current** via package version bumps — no CLAUDE.md drift across 50+ repos
- **Claude Code reads package docs** when it imports from `entr_adapter_core` — it automatically gets framework context
- **Each adapter's CLAUDE.md is small** enough to maintain without overhead — only tenant-specific knowledge that rarely changes

### Separation Principle

Each layer owns its own knowledge. No layer duplicates another.

## What SHOULD Be in an Adapter CLAUDE.md

- Tenant-specific business rules that affect handler logic
- Target system API quirks or limitations
- Environment variables specific to this adapter
- Reasons for any deployment overrides in `deploy/`
- Handler-specific conventions unique to this adapter
- Known issues or workarounds specific to this tenant's data

## What Should NOT Be in an Adapter CLAUDE.md

| Don't include | Why | Where it lives instead |
|--------------|-----|----------------------|
| BaseHandler contract or method signatures | Package docs cover this | `handlers.md` in the package |
| DocumentPayload / AdapterResponse field descriptions | Package docs cover this | `schemas.md` in the package |
| Override resolution mechanism | Package docs cover this | `defaults.md` in the package |
| Core processing pipeline or event system | Core docs cover this | Entr-Core's CLAUDE.md |
| Generic Python or FastAPI coding standards | Not adapter-specific | Standard conventions |
| Handler checklist or recommended flow | Package docs cover this | `handlers.md` in the package |
| Deployment file documentation | Package docs cover this | `defaults.md` in the package |
| Flight recorder or logging conventions | Package docs cover this | `logging.md` in the package |

## Template

The adapter CLAUDE.md template is at `src/entr_adapter_core/defaults/CLAUDE.md.template`. Copy it to your adapter root and fill in the tenant-specific sections.

The template includes these sections:
- **Business Context** — what the tenant does
- **Handlers** — adapter identifiers and handler descriptions
- **Target Systems** — external integrations
- **Business Rules** — tenant-specific processing logic
- **Configuration** — environment variables
- **Deployment Overrides** — what's in `deploy/` and why
- **Development Notes** — testing procedures, known quirks

## Verification Checklist

After creating your adapter's CLAUDE.md, verify:

- [ ] Does not duplicate framework documentation (handler contract, schemas, override mechanism)
- [ ] Does not duplicate Core documentation (pipeline, events, file services)
- [ ] Every handler is listed with its adapter_identifier
- [ ] Target systems are documented with enough detail for a new developer
- [ ] Business rules that affect handler logic are captured
- [ ] Deployment overrides (if any) are explained
