49 lines
2.4 KiB
Markdown
49 lines
2.4 KiB
Markdown
# Explore-notes
|
|
|
|
Distilled, reusable maps of complex subsystems, produced by deep code exploration.
|
|
The goal: stop re-exploring the same subsystem from scratch in every new session.
|
|
|
|
These sit **between** the CLAUDE.md files and the code:
|
|
|
|
- **CLAUDE.md** — high-level orientation, hand-maintained, always-loaded.
|
|
- **explore-notes** — deeper subsystem detail (flows, who-calls-whom, invariants) that is
|
|
too fine-grained for a CLAUDE.md but stable enough to be worth caching. Read on demand.
|
|
- **code** — the only source of truth.
|
|
|
|
## Index
|
|
|
|
| Note | Covers |
|
|
|---|---|
|
|
| [worker-task-pipeline](worker-task-pipeline.md) | `TaskRunner` end-to-end: config resolution, worktree, CLI invocation, streaming, commit |
|
|
| [usage-monitoring](usage-monitoring.md) | OAuth usage endpoint, gate, throttle, per-run token accounting, usage pill/modal |
|
|
| [external-mcp](external-mcp.md) | The `claudedo` MCP tool surface + its two test-enforced conventions |
|
|
| [review-merge](review-merge.md) | Approve=merge-unit, verify gate, `MergeCommit`/revert, diff stack, conflict resolver |
|
|
| [conpty-sessions](conpty-sessions.md) | Interactive/planning/list-handler launch specs + the arg-flattening gotcha |
|
|
|
|
## Rules
|
|
|
|
- **Only stable structure.** Flows, responsibilities, entry points, invariants, relative
|
|
file paths. **No line numbers**, no exhaustive symbol dumps — those rot fastest.
|
|
- **Verify before trusting.** A note is a starting map, not authority. Always confirm
|
|
against current code before acting on it. Each note records the commit it was verified
|
|
against so you can diff for drift.
|
|
- **Not a substitute for CLAUDE.md.** If a fact belongs in orientation, put it there.
|
|
|
|
## Header every note must carry
|
|
|
|
```
|
|
> **Explore-note — verify before trusting.** Distilled map of a subsystem, not authoritative.
|
|
> Last verified against commit `<short-hash>` (<date>).
|
|
> Drift check: `git log --oneline <short-hash>..HEAD -- <paths this note covers>`
|
|
> Stable structure only (no line numbers). See docs/explore-notes/README.md.
|
|
```
|
|
|
|
## Workflow
|
|
|
|
1. **Before** deep-exploring a subsystem, check for a matching note here and read it first;
|
|
explore only to fill gaps or confirm.
|
|
2. **After** a deep explore, distill the durable findings into a new/updated note and bump
|
|
its "verified against" commit line.
|
|
3. If the drift check shows the covered paths changed a lot since the verified commit, treat
|
|
the note as suspect and re-verify the parts you rely on.
|