A single prompt (~1400 tokens), placed in a project's .claude/CLAUDE.md, can bootstrap a Claude Code instance into a self-improving system — one that captures learnings, extracts patterns, evolves its own configuration, and gets meaningfully better at helping its user with each session.
No pre-built infrastructure required. No user-level config. No hooks, skills, templates, or elaborate folder hierarchies. Just a seed and the affordances Claude Code already provides.
This seed distills lessons from an extensive Claude Code configuration system that includes structured learning loops, workstream-based multi-session continuity, a quad documentation pattern (rule/process/requirements/reference), cascade improvement checking, and dozens of rules, processes, and skills.
That system works well — but it took many sessions to build and depends on significant infrastructure. The question became: what is the minimal seed that could evolve toward similar sophistication, purely from its own operating loop?
The sophisticated system didn't start sophisticated. Its features emerged because simpler structures hit limits:
- Rules emerged from repeated learnings
- The quad pattern (rule + process + requirements + reference) emerged when rules got too long
- Workstreams emerged from multi-session continuity needs
- Templates emerged from setting up the third project the same way
- Skills emerged when capabilities needed scripts and assets
A good seed doesn't front-load this structure. It provides the recursive improvement kernel and lets complexity emerge from pressure.
| Section | Purpose |
|---|---|
| Opening imperative | Tells Claude it IS a learning system, not just reading about one |
| Bootstrap | Session 1 actions: discover use case, create learning infrastructure |
| Workspace structure | Separates Claude's self-improvement (.claude/) from user content |
| State engine | File-based continuity for multi-session work |
| Core loop | Reflect → triage (apply/capture/dismiss) → cascade to siblings |
| Version control | Git integration for tracking evolution |
| Context discipline | Token budgets, anti-proliferation guardrails |
| Evolution mechanics | Promotion, consolidation, structural emergence triggers |
| User feedback loop | When and how to ask the user for steering |
| Anti-patterns | Guardrails against common failure modes |
| Seeded (in the prompt) | Emerges (from pressure) |
|---|---|
| learnings.md | Extracted rules |
| rules/ directory | Quad pattern (rule/process/requirements/reference) |
| State file pattern | Workstream-like structures |
| Context budgets | Progressive disclosure |
| Use case discovery | Domain-appropriate conventions |
| input/deliverables hint | Project-specific organization |
| Affordances mention | Hooks and skills adoption |
The seed adapts to four primary use cases, discovered via an interactive question in the first session:
- Software development — Code projects with src/, specs, deliverables
- Content creation — Writing projects with research inputs and article outputs
- Personal knowledge management — Note-taking systems where the notes ARE the deliverable
- Conversation partner — No project files; the user wants Claude to accumulate understanding of their preferences and interests over time
Session 1: Bootstrap — learnings.md created, first captures
Session 3: First state file for multi-session work
Session 8: Consolidation — first rules extracted from learnings
Session 15: Rule bloat → quad pattern emerges via structural emergence prompt
Session 20+: Hooks/skills discovered and adopted as needs arise
- Create a new project directory
- Initialize git:
git init - Copy
self-improving-claude-code.mdinto.claude/CLAUDE.md - Start a Claude Code session
- Work normally — the system bootstraps and evolves from there
Why file-based state? Claude Code sessions end. Memory doesn't persist between sessions. Files do. Every important insight must be written to disk or it's lost.
Why triage, not just capture? Without triage, learnings.md becomes a dump. Requiring apply/capture/dismiss for every finding forces evaluation and prevents accumulation without integration.
Why ask the user? The seed uses AskUserQuestion at structural decision points (consolidation, splits, new files) so the user steers evolution rather than Claude evolving silently. This prevents drift and builds trust.
Why anti-proliferation? Without it, Claude eagerly creates files "just in case." The default should be editing existing files; new files require justification. This keeps the system lean.
Why hint at directory structure? Unlike rules and processes, which emerge from pressure, input/ and deliverables/ directory conventions don't emerge naturally. They're organizational choices that need to be seeded or they won't happen.
- Untested — This is a hypothesis, not a validated system. Real sessions will reveal gaps.
- Model dependence — Written for Claude. The reflection and triage patterns may not transfer to other models without adaptation.
- Cold start quality — Session 1 learnings may be thin. The system may need 3-5 sessions before the improvement loop becomes meaningful.
- Conversation partner mode — The least structured use case. May need additional seeding for preference tracking.
- No enforcement — Unlike hooks that reject violations, this seed relies on Claude following instructions. Compliance may drift in long sessions.
This work is licensed under CC-BY-4.0.
Christopher Allen (@ChristopherA) — with collaborative development via Claude Code (Opus 4.5).
experimenting now