Your first CLAUDE.md
The instruction file your AI reads on every session. What goes in it, what doesn't.
10 min read · 20 min applyRead
A little understanding.
Then put it to work.
Lessons in AI-assisted building, from the first instruction file to the systems that keep complex work on track.
Your first agent.md (a 'soul file')
Define a specialist. Scope, triggers, authority, tools. One file, one role.
12 min read · 25 min applyRead
Your first Claude Code skill
What a skill is, when to write your own, the bootstrap pattern.
10 min read · 30 min applyRead
The brief format that gets the design you wanted
Five fields that turn fuzzy asks into concrete renders.
8 min read · 15 min applyRead
Asking Claude to write a document
Voice, structure, source-pinning. The difference between a brief and a fight.
10 min read · 20 min applyRead
Asking Claude to make a report
Inputs → research → structured output. The reporting loop in plain language.
10 min read · 20 min applyRead
Building your first simple web page with Claude
Project scaffold, dev server, iterate-by-screenshot. End-to-end.
20 min read · 60 min applyRead
The five phrases that change how Claude responds
Specific language, used at specific moments, that produces outsized improvement.
8 min read · ongoing applyRead
Picking your model — Opus, Sonnet, Haiku
Three models, three jobs. The decision rule that saves $300/month.
12 min read · 20 min applyRead
Your first plan-mode session
When to drop into Plan, how to read its output, when to exit.
12 min read · 30 min applyRead
Reading agent output critically
The trust-but-verify reflex. Spot fabricated results before they ship.
12 min read · ongoing applyRead
Slash commands you'll actually use
The 6 slash commands worth memorizing on day one.
10 min read · 15 min applyRead
Background agents — when, why, never
Long jobs offloaded right; the failure modes nobody warns about.
12 min read · 30 min applyRead
Reading a diff before you accept it
The 4-pass diff review that catches what tests miss.
12 min read · ongoing applyRead
Your first MCP server
The 20-minute setup, the gotchas, when MCP beats writing a tool.
15 min read · 20 min applyRead
Your first custom agent file
Build CIPHER (legal/IP) from scratch in one sitting.
15 min read · 45 min applyRead
Tool permissions and you
Allow vs ask vs deny — the model that prevents 90% of "wait I didn't mean that" moments.
12 min read · 20 min applyRead
When your agent says "done" — turning claims into evidence
The diagnostic that catches every kind of "finished but not really." One prompt, three patterns, one habit.
15 min read · 30 min applyRead
Postmortem discipline — when something breaks anyway
The substitution test for structural causes. Action items that ship. The close-out protocol.
15 min read · 45 min applyRead
Memory architecture — what to remember, what to throw away
MEMORY.md as an index. Four memory types. The single rule that prevents bloat.
12 min read · 20 min applyRead
Hooks — mechanical enforcement vs. promised future discipline
SessionStart, PreToolUse, PostToolUse. Why hooks beat "agents must remember to."
18 min read · 60 min applyRead
Mid-sprint scope changes — the amendment protocol
How to add work to a contract without losing rigor. When a re-sign is required.
10 min read · 15 min applyRead
Cross-agent handoffs — when one agent's done is another agent's begin
Communication protocols, delegation templates, authority boundaries.
14 min read · 30 min applyRead
Vault as operating system — the 13-folder convention
Numbered folders. Single source of truth per concern. Why a markdown vault beats a SaaS stack.
20 min read · 60 min applyRead
Wiki synthesis — turning chat history into queryable knowledge
Karpathy-style ingest. Page format, index pattern, lint cadence.
15 min read · 45 min applyRead
Decision logs — ADRs that ship
Frontmatter, options table, revisit conditions. Future-you reads this.
10 min read · 20 min applyRead
The routing model — one chief of staff, N specialists
Why six is right and fourteen is too many. Authority levels, trigger words, escalation.
14 min read · 30 min applyRead
Sprint contracts in practice
The contract format with three real examples — QC firmware, Parley research, MHG site search.
20 min read · 45 min applyRead
Branch hygiene with agents
When worktrees beat single-branch. The merge etiquette nobody taught you.
18 min read · 40 min applyRead
Cost ceilings + the Sunday-night ritual
The spend dashboard, the kill-switch, the weekly review that prevents bill shock.
16 min read · 30 min applyRead
When to delegate vs do-it-yourself
The 4-question test before you spawn a subagent.
15 min read · 30 min applyRead
Test-first with agents
TDD with an LLM that wants to skip it. The 3 enforcement patterns that work.
18 min read · 45 min applyRead
Plan-mode discipline
Plan mode for senior operators. When to skip Plan, when to triple it, the exit ritual.
16 min read · 30 min applyRead
Code review with agents
The review prompt that catches what humans miss. The escalation rules.
18 min read · 40 min applyRead
Postmortem-on-rails — the template
The 7-section postmortem template + how to make agents write it for you.
20 min read · 45 min applyRead
Decision logs in practice
Why decision logs beat status meetings. Format, cadence, retrieval pattern.
16 min read · 30 min applyRead
What public disclosure does to your patent rights
Pitch without an NDA, publish a write-up, prompt a consumer LLM — each can be a disclosure. The grace period, the foreign-filing trap, and what to check before anything goes public.
12 min read · 60 min applyRead
AGPL vs Apache: the license decision that ships or sinks your product
Permissive vs strong-copyleft, the AGPL SaaS loophole, and why a single library can turn your whole codebase open. The license check that belongs in your workflow.
9 min read · 15 min applyRead
Picking a computer-vision wedge: start with a fixed playfield
The hardest version of a CV problem is an open field; the easiest is fixed geometry you can pin with homography. How to choose the narrow, solvable entry point — then generalize.
11 min read · 20 min applyRead
Decompression channels
A parallel technical project that restores focus to the main work instead of competing for it. How to tell if yours qualifies.
12 min read · 30 min applyRead
Skill-transfer adjacency
Picking a topic close enough to compound with the main work, far enough to feel like rest.
10 min read · 25 min applyRead
The "won't become a product" rule
Declare in writing, before starting, that the arm will not become a product. The declaration is what makes it survive.
10 min read · 20 min applyRead
When NOT to start an arm
Three conditions under which a second project is a distraction, not an arm. Honest about when I would have said no.
10 min read · 15 min applyRead
Scope rails for a research arm
Naming what you commit to NOT building, in writing, before starting. The Parley scope-rails block as the worked example.
10 min read · 30 min applyRead
Monthly cadence as a discipline lever
Why monthly beats weekly and quarterly for a side project. The forcing function logic.
10 min read · 20 min applyRead
Kaggle as a publishing loop
Using a public platform as the forcing function instead of a private repo. Why public is the discipline lever.
10 min read · 15 min applyRead
Kill criteria for the parallel arm
The advance commitments that make starting the arm psychologically safe. The three triggers that put it on ice.
10 min read · 15 min applyRead
Retrofit — applying structure to a project that's already a mess
Where to start when there's no CLAUDE.md, no contracts, no postmortems, and the deadline was yesterday.
25 min read · several hours applyRead
Real ROI from agent hierarchies
When 6 agents are right, when 1 is enough, when more agents make you slower. With numbers.
20 min read · 60 min auditRead
Tracking token spend and identifying waste
Cache health ratios. Tokens per shipped artifact. Idle days vs. uncommitted-output days.
20 min read · 30 min applyRead
Accountability — contracts + postmortems + gates as one system
How the three disciplines compound. Where each catches the others' failures.
18 min read · 45 min applyRead
Scope creep prevention
The amendment protocol at scale. Refusing 'while we're in there' work. Without becoming an obstacle.
12 min read · 30 min applyRead
Multi-venture portfolio operations
Cross-venture routing, shared agents, isolation rules. Running 3+ ventures from one operator.
25 min read · 60 min applyRead
Cloud training discipline — postmortem-driven SOPs
Pod lifecycle decoupling. Exit-path audits. Watchdog cadences. Don't lose a 14-hour run.
20 min read · 90 min applyRead
Hidden cost of agent context drift (and how to detect it)
The signs that your session is gradually losing accuracy. Restart hygiene that compounds.
15 min read · 30 min applyRead
Building your first custom MCP server
When to build vs use existing. The protocol in plain language. The failure modes that cost teams two weeks each.
20 min read · 2 hours applyRead
Multi-agent orchestration patterns
Beyond chief-of-staff routing: parallel-spawn, gather-then-merge, race-then-cancel. When each fires and when each breaks.
18 min read · 60 min applyRead
Production debugging playbook
When an agent misbehaves in prod: the diagnostic ladder. Five rungs from "claim says done but isn't" through context drift, tool failures, schema mismatches, upstream model regressions.
20 min read · 60 min applyRead
Custom agent definition files (build AXIOM + CIPHER)
The 5-section agent file pattern. Two case studies from the TruPath team.
30 min read · 90 min applyRead
AR research sprints when hardware isn't shipped
How to ship Phase-0 R&D against unreleased hardware (Maverick AI).
20 min read · 60 min applyRead
Production incident response with agents
The on-call playbook: paging, evidence collection, triage ladder, and postmortem-on-rails.
20 min read · 60 min applyRead
Compliance + audit trail for AI work
The audit-trail format regulators (and your future self) will thank you for.
20 min read · 45 min applyRead
Programmatic cost ceiling enforcement
Hooks + statusline + a kill-switch script. The whole stack.
20 min read · 90 min applyRead
SBA loan packet drafting with agents
The 12-document SBA 7(a) packet, agent-assisted, with rework rate measured.
25 min read · 90 min applyRead
ASR ground-truth pipelines
Building an ASR eval set from scratch when there's no public benchmark.
25 min read · 2 hours applyRead
Reproduce the as-built model before you correct it
Two models that disagree tell you almost nothing until you can regenerate the one you are auditing. Reproduction converts ambiguous divergence into a named mechanism, and it finds defects before the correction work even starts.
12 min read · 30 min applyRead
The simulator-label trap
Two models agreed on every trajectory to a hundredth of a foot and still flipped 48.3 percent of scored outcomes. Simulated states degrade gracefully; simulated labels fail all at once, right where the outcomes get interesting.
10 min read · 25 min applyRead
Run the sensitivity tornado before you measure anything
Friction swung our prediction 14.9 inches of a roughly 15-inch budget, three times the runner-up, and mass was noise. A one-afternoon sensitivity sweep turned the measurement wishlist into a spending plan.
10 min read · 40 min applyRead
Uncertainty budgets tell you which stage to distrust
The audit put ±2 inches of uncertainty on our flight prediction and ±15 on everything after contact. The failure lived in one stage, and a per-stage budget is what kept us from throwing away the stage that worked.
10 min read · 20 min applyRead
Research isn't done until the handoff brief is written
The QC physics audit produced runnable models, a dozen figures, and a stack of CSVs. The artifact that mattered three weeks later was none of them — it was a short brief written for the engineers who have to act on the findings.
10 min read · 25 min applyRead
Your domain intuition imports the wrong physics
We assumed spin mattered the way it matters on a golf ball. Priced in the same units, the borrowed mechanism was worth 3 inches and the real one 23, a 7× miss in which mechanism matters, caught in one afternoon before it spent our measurement budget.
10 min read · 20 min applyRead