So I built them an AI-driven support platform with Claude Code - a tool I’d been using extensively (almost addictively) since its launch. This project evolved alongside it, rebuilt multiple times as we both got better.

Over the past year, every update to Claude prompted a rethink of what the “best possible buildable solution” was. The biggest change was when Anthropic released the Agent SDK, which changed everything from data structures to UI.

It landed somewhere I couldn’t have even imagined a year ago. After all that rebuilding, here are my five main learnings - patterns that ended up enabling more than just support.

Interactive version with demos →

The Top Learnings

1. Collaboration over automation
This isn’t an “answer-bot”. AI drafts, experts refine, and every refinement teaches the system. The human touch isn’t a fallback - it’s the source of quality that compounds over time.

2. Between RAG and brute force tokens: Context Engineering
Vector search is overkill - and still can’t combine constraints like “beginner + budget + low-light.” Giant context windows are tempting but degrade unpredictably. There’s a middle path: the structured data of a database, with the reasoning of an LLM.

3. Agents adapt when workflows fail
Fixed pipelines break on edge cases. Agents adapt: search again, try different strategies, cross-reference dynamically.

4. UIs should show the AI’s work, not its transcript
Chat is friction - instead, structure its reasoning into interactive UI. Glance and click, not read and type. Chat when needed, not by default.

5. An agent is only as good as its tools
Each tool shapes how the agent reasons about your data. Design them well, and edge cases handle themselves.

1. Collaboration Over Automation

For this client, the human touch was the point

Full automation makes sense in a lot of contexts. But it’s not the only model.

This client valued the human connection. The goal wasn’t to replace experts - it was to make their jobs more pleasant while capturing knowledge that was otherwise disappearing into WhatsApp threads.

So instead of an answer-bot, I built a system where AI drafts and experts refine. Every response goes through someone who knows the domain. The human stays in control.

AI handles the grunt work - finding relevant history, drafting a starting point - so experts can focus on judgment and nuance, informed by the right, targeted supporting information.

Their jobs get more interesting. Customers still get that personal connection. And the learnings compound instead of vanishing.

The Learning Loop

Every response is expert-verified before it goes out.

When experts do make corrections, the system captures what changed and why to highlight it when future agents search for similar situations - drawing on the accumulated wisdom of every past interaction.

Expert knowledge compounds. Repetitive questions get easier. Experts spend their time on genuinely hard problems.

Even if the end goal is full automation, this is a useful first step, with observability on where the system is most fragile. When you’re ready to pull humans out of simple cases, the knowledge is already there.

2. Context Engineering

Not RAG, not brute force send-every-token - the middle path

The system draws on two data sources: a knowledge base of expert-verified Q&As that grows with every interaction, and a full product catalog with specs, price ranges, and compatibility notes.

There’s a spectrum of approaches for making this searchable.

One extreme: full vector infrastructure - embeddings, retrieval, reranking. For a few hundred Q&As and products, it’s overkill and not quite the right optimization. Semantic similarity can’t combine “budget + experience level + use case” into a coherent filter. You end up with complex infrastructure that still can’t express the queries you actually need.

The other extreme: dump everything into a giant context window. Modern context windows make this tempting, but bigger isn’t better - it’s just hoping. Performance degrades in surprising ways: irrelevant information competes with relevant, and the degradation isn’t smooth or predictable.

The middle path is context engineering: curating the smallest set of high-signal tokens that maximize the likelihood of good outcomes. The carefully structured data of a database, combined with the reasoning of an LLM.

But first, the data needs structure.

You wouldn’t hand a colleague a 200-page Word doc of copy-pasted emails and say “figure it out” - you’d organize it, highlight what matters, give them context. LLMs deserve the same setup.

Structuring the Chaos

The first task: turn 500+ email Q&As and product marketing and informational docs into structured data.

I used Claude Code with subagents - specially trained parallel Claude instances that can divide and conquer large tasks - to parse the document in chunks, extracting each Q&A into a consistent schema.

Each subagent processed 20-30 emails per chunk. The prompts instructed them to flag malformed data, ambiguity, or potential errors - making human review targeted rather than exhaustive. Each time we resolved an agent’s question, it fed back into the agent’s training to improve the next round, reducing human intervention over time.

LLM Filtering

Once the data was structured, the next challenge: giving the model efficient access to it. My early first (early 2025, pre-agent-SDK) pass at this was simple - feed an LLM all the Q&A summaries and carefully chosen structured data (significantly smaller than full text!), and have it return a list of the most “relevant” Q&As, with instructions on how “relevant” was defined.

The full text of these Q&As was then combined with a summarized product catalog, and bundled to a second LLM call with additional instructions to return the first “draft answer” to the customer question.

3. Workflow → Agent

Iterative, adaptive search instead of a fixed pipeline

V1: The Workflow

Three sequential LLM calls, deterministic path.

That first version was a workflow: a fixed sequence of LLM calls that ran the same way every time. Filter relevant Q&As, generate a response, potential re-generate data based on expert feedback, and extract metadata and organize the information when the expert indicated that the answer was ready.

Workflows are a classic in software processes, and it worked for straightforward questions. But complex queries, multi-part requests, and edge cases all struggled. The workflow couldn’t zoom in, couldn’t refocus, couldn’t try a different approach if the first one missed.

V2: The Agent

When Anthropic released the Agent SDK, I rewrote the whole system. Same data sources, same underlying operations - but now the LLM reasons about what it needs instead of following a fixed path.

The difference was immediate: fewer failed searches, better handling of ambiguous questions, and the ability to cross-reference between Q&As dynamically.

The agent searched Q&As, found a relevant one, then looked up the product specs to verify the recommendation was still current. If it hadn’t found enough matches, it could have tried a keyword search, or broadened the query, or checked the product catalog directly.

The agent also unlocked the product catalog. The workflow dumped a static, summarized product catalog into context - it was noisy to include full specs for every product. The agent searches it on demand, pulling detailed specs only when relevant.

This is the power of agents: the same underlying data, but the system adapts to what each question actually needs. Instead of telling the model to read everything, it can intelligently choose what to read.

Multi-Turn Context

Experts can probe the agent’s reasoning, request alternatives, or add constraints without starting over. The agent remembers what it found and builds from there.

The challenge is surfacing this context and making expert feedback effortless, without making them wade through chat transcripts or type repetitively.

4. Agent + UI

More than chat: structured output becomes interactive interface

The answer isn’t “give experts a chatbot.” Rather, take everything it figured out - the reasoning, the sources it used, the alternatives it considered - and turn it into an interface designed for speed.

Glance and click, not read and type.

The expert sees a draft response they can edit directly. Sources are there if they want to verify. Alternatives are one click away. Feedback goes back to the agent in natural language.

The reasoning that would have been buried in a chat transcript becomes interactive UI elements.

The key is structured output. Instead of returning plain text, the agent returns data the UI can render: confidence levels, source references, alternative products with explanations. Each field becomes a component. The agent’s reasoning becomes the interface.

You can tailor any part of this interface by asking the agent to re-structure the data - for example, for the Q&As the agent found most relevant, it generates custom summaries of why the example is relevant to the current customer question, including caveats on how the situation is different and similar, and how that should affect the expert’s reasoning.

Instead of typing, the “top alternatives” are surfaced as easy-click buttons; when you hover over them, the expert sees a text box explaining why it considered that alternative - rather than an enormous transcript, targeted information and reasoning is exposed in actionable ways.

Once you have structured output and well-designed tools, those same building blocks work for different purposes. The support agent wasn’t the end - it became the foundation.

5. The Power of Tools

The agent is only as good as its tools

Tools aren’t utility functions you bolt on at the end. They’re the API between the agent’s reasoning and your data.

A poorly designed tool leads to hallucination - the agent guesses because it can’t get what it needs. A well-designed tool guides the agent toward grounded, verifiable answers.

Every tool in this system was shaped by real usage. What worked, what broke, what edge cases emerged. Most have been rewritten multiple times.

Search as Zoom Controls

The tools aren’t just utilities - they’re designed as zoom controls. Broad sweeps to find candidates, targeted lookups to verify, the judgment to know which to use when.

submit_answer: Forcing Structure

The output tool is just as important as the search tools. Instead of letting the agent return free-form text, submit_answer requires a specific structure: the customer-facing response, the internal reasoning, confidence level, sources used, and alternatives considered.

This is what enables Section 4’s UI. Without structured output, you can’t build interactive elements.

Tools Recombine

Once you have good tools, you can recombine them.

The same Q&A search, product lookup, and pattern analysis tools that power the support agent also power a second agent - this one focused on strategic brand intelligence rather than customer support.

And here’s where the compounding pays off. The Q&A knowledge base isn’t a static dump of historical emails anymore - it’s a living knowledge base that grows with every customer interaction.

Every question answered, every expert refinement, every edge case resolved becomes searchable institutional knowledge. A research agent tapping into that knowledge base isn’t just searching old data; it’s drawing on the accumulated wisdom of months or years of customer conversations.

The research agent can audit ad copy against actual product specs - reading a Google Sheet of headlines, checking each claim against the product catalog, flagging inconsistencies. It can analyze a quarter of customer questions to find emerging trends, then write up findings in a shared doc. It can research how competitors position similar products, grounded in knowledge of what actually differentiates yours.

Two agents, same core tools, completely different purposes. Build tools well and they become infrastructure, not one-off solutions.

Camera gear used as example domain. The real system is in a different industry.

Interactive version with demos →

Have you ever wanted to panic-Google your own brain? Please tell me it’s not just me.

After a year of asking AI to remind me what we’d talked about, I realized I wanted something more rigorous than chat logs.

I have tried journaling before: apps, morning pages, sporadic notebooks, random bursts of adherence across too many mediums. The problem wasn’t just consistency. It was that the good stuff didn’t resurface. Context got lost, with motivation close behind it.

I wasn’t looking for “perfect memory.” Rather, I wanted journaling to compound: a facilitated habit that builds an index of my own context, pulls in history when it matters, and lets me choose a useful lens in the moment - so when Future Me goes, “...what was I thinking?”, there’s something real to resurface.

I wanted a well-read thinking partner and a filing system with low friction and high returns - an interactive place where thoughts become structured, decisions stay traceable, old clarity connects to new dilemmas, and usefulness and insight grows over time. So I used the same toolkit I do for engineering and started building one!

Turning the toolkit inward

Over the past year, I’ve been leveraging AI to make data science systems more powerful and rigorous. This repo was an experiment in taking the same toolkit and pointing it at my own thoughts.

What it enables:

• Capture thoughts quickly (often by dictation)

• Ingest and organize historical snippets (old journals, notes, half-finished thoughts) into a consistent, searchable structure

• Structure new reflection into repeatable, low friction habits (daily + weekly)

• Resurface what I’ve already worked through when I’m stuck

• Connect old context to new decisions

• Learn patterns over time, constantly adapting and improving.

How it works

Commands as habits

Low-friction, consistent entry points to start a reflection session without negotiating with a blank page.

• Lower activation energy. A single, familiar trigger to begin (especially when I’m tired or overwhelmed).

• Routing into structure. Whatever happens next lands in the right weekly/day/decision place automatically, instead of becoming another stray note.

• Continuous personalization. As you teach the system you preferences, it adapts and remembers

• Mix-and-match. You can interact with the system however you want—quick guided check-ins, long freeform rambles, or focused deep dives—and it all still lands in the same structure (so summaries/indexes/search keep working).

Files + structure over chat logs

Chat is great for thinking in the moment. But generic chats didn’t have the storage format for the targeted task that I wanted journaling to serve.

This system makes the output land as durable artifacts inside an intentional structure: predictable folders + lightweight templates (weekly journals, decision threads, dashboards, self‑map). That structure is what enables everything downstream—summaries, indexes, and the search agent—because the system has a map of where things live.

How it becomes durable and searchable

“Searchable” isn’t a single feature. It’s an outcome of a few pieces working together.

• Commands create predictable structure. When I run /start-day or /end-day, the output lands in a consistent place and format (weekly files, decision files, dashboards), instead of another one-off chat.

• Claude shapes messy input into clean artifacts. Dictation and brain-dumps go in; Claude turns them into something I can actually come back to: headings, bullets, a next step, a short summary.

• Weekly review generates the index layer. /weekly-review creates small summaries/rollups that describe what happened without me re-reading everything.

• Import builds a real archive. If I have old journals or notes, /import-history processes them into organized files (themes, key relationships, a quotes index) so the past isn’t just “stored,” it’s navigable.

• Search is index-first. When I ask “what was I thinking?”, the search agent reads index files and summaries first, then dives into raw entries when useful.

History that surfaces

/import-history is the part that turns this from “a fresh journaling habit” into an actual archive.

You just dump in whatever data you have (text, images, etc), it processes them into a structure that’s easier to navigate later—things like:

• a full-text archive (so nothing is lost)

• a quotes index (useful lines you can actually resurface)

• theme files (recurring topics/patterns)

• relationship files (people as entities, over time)

Import doesn’t just archive the past—it creates the navigation layer (index files + consistent structure) that tells the search agent what exists. When I ask a question later, search reads indexes first, scans summaries to find the right timeframes, and only then dives into raw entries—so it feels like structured recall, not grep.

That’s also why I didn’t build an “embed everything + vector database” setup. Recall is powered by simple human-readable summaries and index files—thin enough to maintain, flexible enough to evolve, strong enough to resurface what matters.

That means I can ask questions that are hard to answer from scattered notebooks, like:

• “Pull the most relevant quotes I’ve written about burnout”

• “What themes keep showing up when I’m making big decisions?”

• “How has my thinking about X changed across the years?”

• “When did I first start circling this decision—and what else was going on around then?”

Frameworks: Lenses for Reflection

The repo ships with a few starting lenses (Stoicism, Atomic Habits, Brené Brown), but the real idea is that you build a reference library over time based on what actually resonates.

When something clicks—a book, an author, a concept—you can run /add-framework and Claude researches, builds, and routes it into the right reference folder (frameworks/, practices/, or personality/). The reference files stay generic (the “lens” itself). My personal application lives separately in private/—especially assessments/, other archive files, and the self-map.

The point is flexibility: I’m not declaring “I’m a Stoic.” I’m asking, “What questions would a Stoic lens ask right now?”

Shareable System, Private Lessons

Journaling is a very private practice! But I also wanted the compounding of something I could share. Here’s how I split the difference:

The system is open source. You can fork it, customize it, and still pull updates. But the content of what you learn stays yours. The public component is shared structure, training, and broad expertise - your personalization stays private (see Privacy Notes for more).

Universal scaffolding, individual learning: Benefit from an evolving architecture, while evolving with your individual patterns, learnings, and preferences.

Dictation for Maximum Ramble Power

On macOS, I set dictation to Press Globe Key Twice (System Settings → Keyboard → Dictation). Then I just talk. There are other great dictation options out there but I find this both sufficient and easy to use.

Typos, garbled transcription, stream-of-consciousness rambling: Claude can still shape it into something coherent. I dictate more than I type now.

What this is (and isn’t)

This is a space for reflection, not therapy.

Writing things down, noticing patterns, and having a thinking partner can be valuable—but it isn’t treatment, and it’s not a replacement for human connection.

If you’re working through something heavy, a good therapist offers things this can’t.

Privacy Notes

The journal lives locally in gitignored Markdown, and the repo adds guardrails to reduce the chance you accidentally publish personal content:

• private/ is gitignored

• a hook blocks any attempt to commit private/ or CLAUDE.md

• another hook scans committed content for likely personal/sensitive text

Using Claude Code also means the text you work with is sent to Anthropic’s servers for processing. Data retention and model-improvement use depends on your Claude account privacy settings. See the project README for more information.

What I don’t know yet

Will this stick? It’s week one. Ask me in six months.

Is this useful for anyone else? I open-sourced it to find out.

Am I over-engineering my feelings? Possibly. But other emotional strategies I’ve tried include suppressing, forgetting, and avoiding. Sooo, hard to do worse, tbh.

Try it

Repo: github.com/Wrendered/journaling-with-claude

Fork it, open Claude Code in the repo, run /onboarding.

But “Is the AI accurate?” is the wrong question. A more useful one is: “Have I built a system that produces trustworthy outputs from fallible components?”

Tl;dr

• Reliability isn’t a model property - it’s a system property built around fallible components. Just like it always has been.

• Treat repetition as a signal: encode it - starting with small misses, then graduating into workflows and tools.

• You’ll never get 100% adherence, so where you encode matters: target the right instruction for the right time with minimal distraction.

• Use a layered toolkit (CLAUDE.md, skills, agents, hooks, tools) so your training sticks.

“Infallibly correct” has never been the bar for humans or software. Data centers assume hardware will fail; engineering teams assume people will ship bugs and occasionally nuke production. Reliability comes from designing systems around fallible parts. Treating AI the same way - something that is both powerful and failure-prone, and that deserves a real investment in tooling and training - has completely changed how I work.

Over the last year of pushing Claude Code to its limits, I’ve hit every classic failure: confident fabrications, fallbacks that hide real errors, and imaginary databases springing up when connections fail. At the same time, my analysis work has become deeper, faster, more rigorous, and easier for other people to replicate and build on. Not because the AI is magically correct, but because it’s extremely capable at the parts that bottleneck humans: writing and refactoring code, building full-stack glue, and exploring more variations than I could reasonably do by hand.

I’ve stopped hand coding analyses in one-off notebooks, and moved towards building shared AI tooling, pipelines, and reusable workflows to enable higher quality analyses at scale for myself and my team - far more than I’d previously ever dreamed of being “in scope” for a single data scientist.

This is my personal playbook for that shift: how I see the human role changing, how to continuously up-level your work with DRY for AI, and how to architect a practical ecosystem in Claude Code to make rigorous work with fallible models not just possible, but normal.

Note: Claude Code is used as the running example as I’ve found its configurability fits well with my data science work, but the principles can be applied more broadly.

Your Job Has Changed

The ceiling of what an AI coding assistant can do is not set by the model’s raw “IQ,” but by the tools, context, and training you surround it with. Most of the frustrating “out of the box” quirks you’ve hit aren’t permanent traits of AI - they’re missing scaffolding: principles, knowledge of your stack, and access to the systems you rely on.

You wouldn’t hire the smartest engineer you’ve ever met, hand them a laptop on day one, and say: “Here’s an obscure, high-stakes problem in a codebase you’ve never seen. Figure it out.” You’d give them docs, code labs, a clear scope, and start with a small area of ownership, increasing responsibilities over time. Your AI deserves the same grace.

Your goal is to train your AI until it can operate at your task-level altitude - as a peer, not a junior you’re endlessly correcting. When you open a session to start a project, the agent you’re interacting with is your coordinator and collaborator. It should know your task, your principles, and your stack well enough to think at the level you do. Its precious context should be spent on the highest-level problem you’re solving, not constantly re-deriving basic functions.

It reaches that level of abstraction the same way you do: by leaning on an ecosystem. Tools, scripts, agents, and services become its infrastructure and “colleagues,” each with a clear job. Together they behave like a small AI org that extends what one human can realistically cover.

As you design that ecosystem, your scope actually expands rather than shrinks. You end up responsible for more systems, but at an operational level, not an implementation level. You don’t need every API and library call in your head; you do need a solid mental model of how the pieces fit together and when something smells off. The learning here is non-optional - most bad outcomes I see come from skipping that step - and the AI’s job is to carry the mechanical recall and boilerplate so you can focus on the reasoning and design.

That might sound like a daunting amount of training and architecture. It isn’t. The system emerges from a simple discipline: fix each issue once, properly, in a way the system can remember, and let those fixes compound over time. Kieran Klaassen calls this “compounding engineering” - building systems where every bug, review, and decision becomes a permanent lesson rather than a one-off fix. In practice, the main way I do that with AI is DRY for AI: treating repetition as a signal that something should be encoded into the AI’s ecosystem so it becomes shared, reusable behavior, not a constant re-teach.

DRY for AI

It can feel like a victory - even vindication - when you hand-code something faster than your AI pair programmer.

But in a world of increasingly capable AI agents, DIY is technical debt: you’re keeping yourself in the loop on work the model could handle reliably if you gave it the right scaffolding.

Your time is better spent building that tooling than racing it line by line.

DRY - Don’t Repeat Yourself - is foundational to software engineering. Copy-paste code? Refactor into a function. Same logic twice? Abstract into a module. The same principle applies to AI work, just at a different abstraction layer: not just in code, but in how you run analyses, correct mistakes, and coordinate workflows.

• Traditional DRY: Don’t copy-paste code → write a function.

• AI DRY: Don’t repeat corrections, access patterns, or training → encode the principle once.

The classic DRY tradeoff - “will the time I save outweigh the time to automate?” - is radically skewed by AI. The time to build drops toward zero, while the impact multiplies as properly designed tools scale instantly across your and your teammates’ projects.

The diagnostic question: Where am I repeating myself, and what kind of repetition is it?

1. Repeated Corrections

Any prompt I’ve given more than twice goes in this category. Doubly if curse words were involved. This is usually the first, most obvious layer of failures and fixes.

“One paved path or clear failure, do NOT create fallbacks.”

“When you make a PR, use pull_request_template.md, be professional, no emojis.”

The most naive first step you can take is to encode these straight into a CLAUDE.md file. At the end of this I’ll talk through how I refactor many of these into areas that enforce better AI behavior. But the critical starting point is clearly identifying and articulating the incorrect underlying behavior, and what behavior you want to see instead.

2. Repeated Access (You as Human Clipboard)

Every time you copy/paste logs, fetch data Claude can’t reach, or shuttle information between systems, that’s infrastructure waiting to be built. Building that infrastructure might not have been “in your wheelhouse” before, but this is exactly the sort of thing AI coders excel at. Describe what you need, collaborate on the simplest implementation. In many cases it’s as simple as generating a script and adding a sentence like “use ./scripts/fetch_logs.sh to get the last hour of production logs” - first in conversation with Claude, then in your CLAUDE.md or other strategic places.

You are an extraordinarily slow bottleneck that prevents efficient iteration - investments here are well worth it.

3. Repeated Training (You as Tutor)

Sometimes the repetition isn’t a single command - it’s an entire pattern of work you keep hand-holding your AI through.

For example, I used to run 10–20 variations of API-based LLM labeling runs on my datasets to tune prompts and understand edge cases. I (embarrassingly) tracked the experiment variations manually in a Jupyter notebook comment block. It was messy, hard to reference, and duplicated across dozens of projects. At single-human speed and scale, that was tolerable. Once Claude was in the mix, it became obviously wrong: increasingly error-prone, unreliable, and constantly demanding attention from both of us.

Once I treated that whole process as DRY debt, the shape of the work changed. I started by asking Claude to build a small CLI wrapper - one command that handles validation, execution, and logging. It replaced my messy text file with a comprehensive, queryable table and baked in several other checks and steps. Over a few weeks of incremental capability development, what used to be “Wren’s janky logging notebook” became infrastructure that dozens of people now lean on. A heavy, error-prone process that demanded constant attention became code-automated, letting us both focus on higher-level experiment design.

That’s the real shift: AI didn’t just make me faster - it made it worth building the kind of software infrastructure that used to be “out of scope” for a single data scientist. It accelerated and deepened the analyses I could run and made it trivial to share that methodology with other data scientists. The process moved from “in my head and my notebook” to “in shared software + Claude Code infrastructure,” raising capabilities while reducing onboarding overhead.

Together, these three kinds of repetition - corrections, access, and training - tell you what to encode. The toolkit in the next section is about where that encoding should live.

The Toolkit: Where to Encode What

Imperfect Adherence

A strength of AI coding is that most of your “encoding” is language-based and flexible, not rigid code. The flip side is: you will never get 100% adherence.

Rules you put in CLAUDE.md will sometimes be ignored, no matter how many **CRITICAL**s you add. Skills and agents that worked once will fail in slightly different situations.

This makes your job more nuanced than “throw everything you need to know in a file.” You have to be strategic in your context engineering.

After a repeated miss, the first question shouldn’t be “What’s wrong with the model?” but “How did I set it up for failure?”

Were expectations clear? Did I encode this in the right layer, or bury it in a long doc where the instruction is low-salience noise in an already crowded context window?

To get better behavior, you have to be intentional about where things live so your primary coordinator gets the right information at the right time. That’s what the toolkit is for: deciding where each kind of encoding should live so it can actually work.

CLAUDE.md: Orientation Guide

CLAUDE.md is an always-loaded brief on what this repo is, how it behaves, and how you expect Claude to work with it. In practice, it should answer three questions:

What is this project?
Plain language about what the system does and what “good” looks like.

How do we work here?
The scientific mindset you expect, communication styles, whether to fail loudly instead of inventing fallbacks, whether to bias toward a quick internal prototype or production-quality changes - your work style and “culture”

Where is the deeper context?
Pointers to resources (docs, repos, folders, or other toolkit components like agents and skills) that will help across different tasks required to work in this system:
“See ARCHITECTURE.md before proposing structural changes.”
“See analysis-examples/ for templates of our most common analysis patterns.”
“Use the log-debugger agent to investigate job failures.”

That keeps CLAUDE.md lean while giving Claude a durable mental model: what this thing is, how to behave inside it, and where to go for depth - without you re-explaining the basics in every prompt.

Like everything in this toolkit, CLAUDE.md is a living document. Any time you catch yourself repeating the same explanation or correction, ask: “Should this be integrated into the CLAUDE.md instead?” With continuous refinement and refactoring, this becomes not only valuable for Claude, but also a helpful, durable human readable artifact.

Skills: Workflows and Scripts

Skills are your SOPs and formal bundles of behavior. They capture how a job is usually done. Think of them as organized folders of instructions, scripts, and resources that Claude can load into your main context window to perform a recurring job exactly the way you intend.

Because they operate as LLM-based instructions rather than rigid, hard-coded pipelines, Skills are incredibly good at handling branching and ambiguous situations. They can adapt to what they find, ask clarifying questions, recover from unexpected states, and trigger other tools or agents.

Example Skill: eval-runner/

• SKILL.md: how we run labeling/eval experiments (inputs, validation, logging, failure rules)

• scripts/: helpers like eval_runner.py, summarize_runs.py

Inside that Skill, Claude might still decide to run: “Run ./scripts/eval_runner.py to kick off a configured evaluation with logging.” This makes complex tasks consistent and repeatable. The LLM decides when conversationally to use the skill and how to configure the components, while the code (scripts, etc.) is still executed reliably and programmatically.

Skills vs. Agents. Use a skill when the workflow should:

• See your full conversation and current work-in-progress, and

• Run as a structured “mode” of your main collaborators

Use an agent when the work is a separable sub-problem that benefits from a fresh, focused context (deep log-diving, extensive docs research, large search spaces). Think of skills as orchestrated workflows in your main session; agents as specialists you spin up for isolated deep work.

Agents: Delegated Sub-Problems

Agents are specialized sub-contexts with their own system prompts. They do deep work in isolation and return condensed summaries.

Use an agent when:

The task is token-heavy. Digging through 500 lines of logs, exploring a new API’s documentation, analyzing a complex stack trace - this would bloat your main context and push out the conversation history you actually need.

The task is at a lower altitude. Your coordinator should stay at system-level, strategic thinking. Detailed debugging, exhaustive research, or brute-force exploration is a sub-problem you delegate.

You want parallel exploration. Multiple agents can run simultaneously on independent tasks, then you synthesize their findings.

Think of agents as specialists with a job description and a clear ask. For example:

log-analyzer - “Spin up a log-analyzer agent to find out which runs failed, review the logs and tell me the most likely root cause, plus your confidence.”

query-builder - “Use a query-builder agent to debug this query, test how memory efficient it is, and propose improvements.”

docs-researcher - “Create a researcher agent to read this API’s docs and summarize the key endpoints that I will need for our current task.”

They bring you summarized outputs, not a play-by-play of every step.

Anthropic calls this “separation of concerns”: each agent gets its own tools, prompts, and exploration trajectory. The detailed work stays isolated; your coordinator focuses on synthesis and decision-making. You can define reusable agents in your repo, or spin up one-off specialists via prompt (“have a subagent do [task]”).

Hooks: Process Encoded

Hooks are event-driven automation that fire when Claude takes specific actions. You define a trigger and what should happen when it fires.

• Trigger: “Whenever someone runs gh pr create…”

• Action: “…check if the /review command was run; if not, ask them to do it first.”

This isn’t just guardrails - it’s how you encode your team’s process into the system itself. Hooks let you:

• Hard-block - prevent an action entirely.

• Soft-guide - suggest the right path without blocking anything.

• Automate - format, lint, notify, or checkpoint with no extra prompt.

The real power is in soft enforcement. Don’t block PRs that skip review - just make the right path obvious and low-friction. People (and AIs) follow the path of least resistance; hooks let you shape that path.

Use hooks when you find yourself saying:

• “I wish no one would run X without doing Y first.”

• “Every time we do this, we forget to also log / format / notify.”

• “I want this check to happen every time, even if I forget to ask.”

Tools: Executable Actions & Connectors

Tools are the registered, permission‑gated, and discoverable executable actions that actually carry out the work. If Skills are the procedural instructions, Tools are the hands.

This includes:

• Built‑in tools: Edit, Bash, Read, Write, Glob, Grep.

• Custom CLI tools: Local scripts you register yourself.

• MCP Servers: Connectors to external systems like Slack, databases, internal services, or APIs (via the Model Context Protocol).

MCP is the standard way to serve these tools across projects. Claude uses the natural‑language description to decide when a tool is relevant and how to fill its arguments, then runs the underlying code to do the work. It’s conversational at the edges, programmatic in the middle.

In my own work, I most often consume MCPs owned by others (databases, search, Slack) and create Skills for task‑level workflows I care about.

For more detail on how Claude reasons about and uses tools, Anthropic’s Writing Tools for Agents is a great deep dive.

Write less code, do more good science.

This isn’t the end of engineering rigor; it’s the scaling of it.

You aren’t just writing code; you’re encoding reasoning, intent, and judgment. The bottleneck is no longer how many library calls you’ve memorized, but whether you can decompose and formalize your intent clearly enough for an ecosystem of agents to execute.

That’s always been the bedrock of good engineering and science. But this shift opens a critical door. Because the interface to this power is now written language, we can plug the rigorous thinking of other disciplines directly into the development loop. I’ve seen investigators probing edge cases, lawyers stress-testing risk, and Ops teams defining evaluations - not by filing tickets, but by engaging with the system itself.

We need this depth of collaboration to survive the pace of modern development. We are wiring together models and systems faster than traditional development can handle. If we don’t encode our best thinking into shared, intelligible workflows, we end up with fragile, ad-hoc analysis. But when we do, we can powerfully pool, share, and amplify diverse individual rigor into scalable systems.

The old flex was how much you could outperform the AI.

The new flex is how much the AI outperforms because you taught it to operate that way.