Five things I learned building a Claude Code plugin. Each one is a decision file the plugin captured while I was building it. Link in comments. (When I say "I wrote" below, I mean Claude wrote most of it while I supervised and said "no, not like that." Claude Code builds Claude Code plugins now - fun times.) 1. Markdown files are the truth. Everything else is a cache. Decisions are .md files in .claude/decisions/, plus a auto-generated list at claude/rules/decisions.md that loads at session start. A SQLite search index sits alongside and rebuilds from markdown on demand. Humans and agents both read markdown natively. No parsing layer in between. Karpathy's LLM knowledge bases post took this mainstream. The decision file here predates it, and Claude Code's memory uses the same principle. Not a trend - just what works. 2. No external libraries - just Python's standard library Just what comes with Python. No pip install anything. Took more work - custom YAML parser, FTS5 queries by hand. (Python stdlib got TOML but still no YAML!) - but the plugin can never break someone's Python environment. 3. A tiny bash layer so hooks stay fast Claude Code runs your plugin on every tool use. Python takes ~100ms to start up, so 50 tool calls adds 5 seconds of lag per session. A bash script catches events that don't need Python. Latency stays under 10ms. The first version ran Python on everything - my own plugin annoyed me. 4. A strict order for when policies fire The plugin runs a handful of policies on every hook - detecting decisions, injecting context, nudging. They fire independently but their outputs merge. Without a firing order, weird bugs emerge. A nudge fires before its context. A validation runs after the file is already written. Now there's a fixed order: block, lifecycle, context, nudges. Even if a policy says "reject", the result gets forced to "allow" - nudge-don't-block locked in at the architecture level. A policy can misfire, but none can stop Claude. 5. Skill, hooks, CLI - each does one job Claude Code plugins have three places for logic: a skill (markdown that tells Claude how to behave), hooks (code that runs on events), and a CLI. My first version stuffed everything into the skill. 200 lines of templates, validation, search logic - trying to be an entire program written in English. Now each layer has one job. The skill says what to do - about 60 lines, nothing more. Hooks enforce correctness. The CLI does the computation. The real reason this matters: LLM work costs tokens and is probabilistic. Local code is free and deterministic. Move what you can down to the CLI. --- Would love to hear from others building Claude Code plugins - or thinking about it. What's working, what's stuck. #ClaudeCode #PluginDevelopment #Python #OpenSource #DevTools
Exactly right! You don’t need organized complexity anymore.
Code Decisions - open source Claude Code plugin that captures decisions from conversation and auto-surfaces them when files get touched. Repo: https://github.com/zimalabs/code-decisions Decision files: https://github.com/zimalabs/code-decisions/tree/main/.claude/decisions