What IT Is

Teaching Technical Teams to Adopt AI Responsibly

October 31, 2026Scott S NelsonLeave a comment

TL;DR: IT and software engineering teams don’t adopt GenAI just because they have access to it. They adopt it once they learn where it fits, which engineering habits still apply, which ones quietly break, and why using AI isn’t a threat to their livelihood. Adopting it responsibly means spending tokens deliberately instead of maxing them out, testing probabilistic output differently than deterministic code, keeping rules that must always hold out of the model’s hands, shipping only code the team understands well enough to maintain, and configuring the tool’s instruction files and hooks on purpose. AI tools easily help engineers produce more code. But how much of that code actually ships and how much of it really shouldn’t? More importantly, what do you do when you know the difference and are ready to move up to the next level of agentic productivity?

Engineers Get the Tools First and the Training Last

IT and engineering teams are usually the first in an organization to get GenAI. They get coding assistants, API keys, and an unqualified expectation to triple their previous output with no ill side effects. (For those who were part of an enterprise Agile “transformation,” this may sound familiar… and not all corporate cultures have evolved since, despite a few gigabytes of files “capturing” lessons learned from the retrospectives.)

The tools have certainly arrived. About 90% of technology professionals now use AI at work, and over 80% believe it has increased their productivity, yet about 30% of developers still report little to no trust in AI-generated code (from the 2025 DORA findings cited in Balancing AI tensions: Moving from AI adoption to effective SDLC use). Wide use combined with low trust means teams use the tools without knowing how far to rely on them.

Engineers learn prompting quickly, wire up an API call in an afternoon, and have a demo by Friday (or lunch, depending on ambition, skill, and risk tolerance). What they don’t pick up from the “Quick Start” guides and YouTube promos is the judgment underneath: what the model should own, how to test something that doesn’t return the same answer twice, and how to tell a real improvement from a lucky run. Those gaps don’t show up in the demo. They show up in production, in the token bill, or in a post-production incident audit.

DORA’s 2025 research describes AI’s primary role as an amplifier that magnifies an organization’s existing strengths and weaknesses, with the greatest returns coming from improving the underlying organizational system rather than from the tools alone (see DORA | State of AI-assisted Software Development 2025…and yes, I know that “2025” is considered dated, but rigorously reported data still lags behind Age of AI evolution rates). A team with weak testing discipline gets weak testing at higher speed.

The training Anthropic provides for its Claude Certified Architect – Professional (CCAR-P) certification (similar public reference: Four role-based certifications for the people who put Claude to work for customers) frames the missing skills as four “AI Fluency competencies”: Delegation, Description, Discernment, and Diligence (similar public reference: AI Fluency: Framework & Foundations).

Delegation means deciding “not just whether Claude can do it, but whether Claude should own it” (CCAR-P training, Module 1, Claude Platform & Solution Design, “Delegation: deciding what Claude is trusted to own”).
Description means telling the model precisely what you want: the scope of the task, the format of the output, and the constraints that bound it (CCAR-P training, Module 1, Claude Platform & Solution Design, “Description: the 4D competency applied to prompt design”).
Discernment means judging model output “rather than accepting it at face value” (CCAR-P training, Module 2, Enterprise Integration & Production, “Discernment: judging the output”).
Diligence means taking responsibility for verifying and vouching for AI output, including whether the author can explain what shipped (CCAR-P training, Module 5, Team Enablement and Operational Productivity, “Improving developer workflows with AI tooling”).

None of them is a prompting skill, and none of them shows up in the typical enablement session.

One team I worked with began merging story code three times faster after receiving their Claude licenses, yet actual delivered velocity stayed flat. The problem was that “LGTM” (looks good to me, if you’re a non-dev reading this) results did look good by the old standards. Variables and functions had clear names, the code was well-organized and easily read, and unit tests passed with flying colors. But seven times out of ten the results were bounced back by QA for missing some of the acceptance criteria, and two of the three that passed QA were sent back by product because of a problem that would have been recognized by a developer not feeling pressured to triple their output or caught by a QA tester who hadn’t had their workload suddenly quadrupled (don’t forget, the failed code had to be re-tested).

I coached the team in using /plan mode. Planning is a feature that Claude introduced in February of 2025. While Claude has evolved beyond the need to pre-plan its work, the human prompters have not. Plan mode forces the developer to think through what they are asking the coding agent to do. That, coupled with the /grill-me skill, slowed down the time from the start of implementing a story to the creation of a pull request, but tripled the number of stories that passed QA and product review the first time through, resulting in a true doubling of team velocity.

More Code Isn’t More Software

The tools work, and the evidence on that is strong. A study of more than 500,000 GitHub developers found that autocomplete, interactive coding agents, and autonomous coding agents raised commits by 30%, 180%, and 240% respectively, as cumulative effects of adopting each generation (from the Abstract of Writing Code vs. Shipping Code: Productivity Effects Across Generations of AI Coding Tools).

The gains shrink sharply on the way to production. That same 240% increase in commits “falls to 80% for the number of projects, and to 30% for actual releases” (Abstract). Interactive agents such as Claude Code raised lines of code by 958% and pull requests by 86%, but releases by only 20% (Section 1, Introduction). After adopting interactive agents, developers added 7.0 times as many lines of code but deleted 12.2 times as many, created 79% more branches, and saw the share of new repositories abandoned after their first month climb from 60% to 69% between 2021 and 2026 (Section 6.2, Mechanisms Underlying Attenuation). The paper describes the binding constraint as “shifting from writing code to reviewing, integrating, and distributing it” (Section 8, Conclusion).

DORA sees the same trade-off from the team’s side. It found that higher AI adoption is associated with increases in both delivery throughput and delivery instability, and it describes a “verification tax,” where time saved writing code gets spent auditing it. It also flags a gap between prototype and production: AI speeds up prototyping, but integrating the result into production can cancel out those gains (see Balancing AI tensions).

The NBER paper adds a detail that matters for training. The growing gains from interactive agents were “driven primarily by improvements in the frontier models that power them, rather than by within-developer learning over time” (Writing Code vs. Shipping Code, Section 5.4, Results: Dynamic Treatment Effects). Engineers don’t need much training to write more code with these tools; the models handle that. Training has to target the review, integration, testing, and design decisions that decide whether the extra code ships.

Good Engineering Instincts, Wrong Kind of System

Most of the costly mistakes in GenAI adoption come from experienced engineers applying sound instincts to a system that behaves differently from the ones they were trained on. Simplify the design. Cut integrations. Trust what passes in testing. Those habits work for deterministic code. With a probabilistic model, they can quietly backfire.

One scenario from Anthropic’s architect certification training shows the problem clearly. A team had a rule that any claim over £5,000 goes to a senior adjuster, enforced by a SQL check. The architect proposed letting the model extract the amount and route the claim instead, which meant one less integration and a cleaner design. Three months later, an audit found 41 misrouted claims. The amounts had been written in sentences like “damages estimated around five thousand pounds,” and the model read them as estimates rather than threshold triggers (CCAR-P training, Module 1, Claude Platform & Solution Design, “A scoping call, transcribed”).

Every engineer knows the urge to remove a dependency. What this team hadn’t been taught is that a deterministic rule, one that has to be right every time, doesn’t belong in a system that’s right most of the time. Nobody wrote test cases for the routing either, because it was treated as something the model would just handle. The SQL check would have been tested as a matter of course.

The same mistake shows up in how teams configure their coding assistants. Anthropic’s Claude Code documentation is explicit that Claude treats CLAUDE.md files “as context, not enforced configuration,” and that blocking an action takes a hook (see How Claude remembers your project). Allowing or blocking specific tool calls belongs in the permissions and hooks in settings.json (see Explore the .claude directory). Writing “never deploy to production without approval” into a Markdown file is a reminder. The deployment platform still has to require the approval. Teams that haven’t been trained on that distinction treat a policy written in prose as if it were an enforced control.

Reaching for the Agent Because It Sounds Like Progress

Engineers like flexible designs, and agents feel like the most flexible option available. Another Anthropic training scenario is a 90-day retrospective from a team that picked an agent for exactly that reason. One team member said they’d added so many guardrail tools by month two that they’d “basically rewritten the workflow inside the agent loop, minus the logging.” When they finally mined the traces, the real paths through the system “fell into only four shapes. Four.” Their conclusion was that a router and four chains would have “saved ourselves six months” (CCAR-P training, Module 1, “When the team wanted flexibility and got non-determinism”).

That’s six months of engineering time spent because nobody on the team had been trained to tell a task that feels open-ended from one that actually needs an agent. The training puts the test plainly: if the steps could have been written in code, a workflow would have done the job (similar public reference: Building effective agents).

“Use the Best Model” Feels Like Diligence

When engineers don’t know how to choose a model tier, they choose the safest-sounding one. In one Anthropic training scenario, a team ran every call on Opus. Ninety days after launch, monthly cost was running at seven times the original forecast, and median latency was 2.3 seconds against an 800-millisecond target, with no change in customer satisfaction (CCAR-P training, Module 1, “When defaulting to Opus everywhere produced a 7× cost overrun”).

Once the team built an eval set, it moved classification to Haiku and summarization to Sonnet, and kept Opus only for the final response. Monthly cost dropped 71%, and median latency fell to 940 milliseconds (CCAR-P training, Module 1, “90 days after launch”). The training’s verdict: “The absence of a deliberate choice is not neutral.”

Defaulting to the top tier is one form of a broader habit sometimes called “token maxxing”: the most capable model, the largest context, extended thinking switched on everywhere, and retries until something sticks, as if spending more were the same as being careful. It feels responsible, and it isn’t. Every token spent on a step that didn’t need it is budget that a step which did need it no longer has, and the bill gives no hint of which was which until someone measures.

Cheapest isn’t automatically right either. The FinOps Foundation’s guidance is to define quality criteria for each task, test candidate models, and choose the least expensive one that meets the bar. It tracks over-provisioning with a “model fit” KPI, the share of requests sent to a more capable model than the task needs, and gives an example where 12,000 of 60,000 requests, or 20%, were over-provisioned (see FinOps for AI Overview). The same guidance measures cost per successful outcome: total cost of all runs divided by the runs that met the quality bar, as in its example of $1,200 / 8,000 = $0.15. A cheap model that needs three tries isn’t cheap.

Engineers already profile code before optimizing it. Model-tier selection is the same discipline, measuring per step and choosing per step, but teams only apply it once someone shows them it’s an engineering decision and not a vendor setting.

Testing Habits That Don’t Transfer

Testing is where untrained teams struggle most, because their testing instincts were built for code that returns the same output every time.

Another Anthropic training scenario (a composite of a common pattern) describes a team that tested a new system prompt on 50 sessions against 50 on the old version. The new prompt scored a 68% task success rate against 62%, so the team shipped it. Two weeks later it had settled at 61%, and “the apparent 6-point gain had disappeared” (CCAR-P training, Module 2, Enterprise Integration & Production, “The 50-session winner that wasn’t”). For comparison, the same training works through a properly sized test in which detecting a 5-point improvement from a 70% baseline “with 80% power and 5% significance requires approximately 1,500 sessions per group” (CCAR-P training, Module 2, “Production readiness builder”).

The same gap shows up in load and failure testing. In one post-launch review, “the long documents in the tail were consuming 80% of the total token spend,” and a 529 error at peak on day three took the whole workflow down because nobody had tested what happens when the call fails (CCAR-P training, Module 2, “The demo cost profile that became the production bill”). Uneven input distributions and fallback paths are standard engineering concerns. Teams new to GenAI tend to set them aside, as if the rules had changed.

Anthropic’s training also gives engineers a familiar way in: set eval thresholds the way you’d set acceptance criteria, based on the business requirement, and “Don’t just choose what your first prototype happens to achieve” (CCAR-P training, Module 2, “Evals as acceptance criteria”; similar public reference: Define success criteria and build evaluations). Framed that way, evals look like something engineers already know how to do.

Feeling Faster Isn’t Being Faster

Teams also misread their own productivity. In METR’s randomized study from early 2025, 16 experienced open-source developers took 19% longer to finish tasks on their own repositories when they were allowed to use AI tools (see Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity).

Things have moved since then. METR’s late-2025 follow-up covered 57 developers, 143 repositories, and more than 800 tasks. It measured an 18% speedup for developers returning from the original study (confidence interval -38% to +9%) and a 4% speedup for new developers (-15% to +9%) (see We are Changing our Developer Productivity Experiment Design). METR treats those figures as a likely lower bound and calls its own data “very weak evidence” for the size of the change. Part of the reason is that 30% to 50% of surveyed developers said they skipped tasks they didn’t want to do without AI. METR also notes that self-reported speedups are unreliable.

Two things follow for adoption. The gains are real and growing, but they’re smaller and less certain than they feel, and the only way to know what a team is actually getting is to measure it. Training should also teach engineers to recognize when doing the work by hand is faster. Knowing when not to use the tool is part of being fluent with it.

Review Is Now the Bottleneck, and It’s Easy to Rubber-Stamp

If writing code is no longer the constraint, review is. The NBER paper notes that the bottleneck should be tighter inside companies than in open source, “where shipping code involves review and approval processes that open-source developers largely avoid,” and it cites enterprise data identifying code review as the binding constraint (Writing Code vs. Shipping Code, Section 8, Conclusion). DORA describes the same tension: authors can generate large changes quickly, and the review burden lands on their colleagues (see Balancing AI tensions).

Under that pressure, review tends to give way. An Anthropic training scenario describes a reviewer facing 400 items a day with only the model’s output and an approve button: “After the first hour I have to just hit approve to keep up with the pace” (CCAR-P training, Module 3, Responsible AI, Safety, and Risk for Architects, “When routing everything to review makes review meaningless”).

The fix is an engineering one: route items by stakes, and give reviewers the inputs and the reason each item was flagged. DORA’s recommendations point the same way. It advises AI-driven checks that reach authors while they’re writing, splitting large AI-generated changes into small batches that are easier to review and test, investing in test automation, and considering context-aware review agents to enforce standards (see Balancing AI tensions). Some of that discipline can be packaged into the tooling itself. The community-built Popquiz skill for Claude Code, created by scoobydrew83, targets what its author calls “comprehension debt”: code that ships without anyone understanding it. Before agent-generated or unfamiliar code merges, it walks the reviewer through an explanation of the change and ends with a written quiz that has to be answered before an approval is allowed. It even fails reviews that approve with rubber-stamp phrasing. It triggers on the phrases reviewers use when they’re in a hurry, such as “LGTM,” “ship it,” and “approve this PR.” It’s a third-party skill, so it should go through the same review as any other shared artifact before the team adopts it. Review that approves everything is not oversight, whoever the reviewer is.

Speed Today, Skills Tomorrow

There’s a quieter cost that training has to cover too. DORA points out that AI can help engineers learn unfamiliar areas quickly, but it can also lead to shallow understanding and skills that erode. Its recommendations include pairing junior engineers with senior mentors to review AI-driven design decisions, and deliberately keeping some complex components manual (see Balancing AI tensions).

This is the part of training that has nothing to do with the tool. An engineer who never had to work through a hard design problem won’t be able to review the model’s attempt at one. The review bottleneck above depends on reviewers whose judgment came from doing the work themselves. It’s also a maintenance problem. Code nobody on the team understands is code nobody else can safely change, debug during an outage, or hand to the next hire. Shipping only what someone can explain is part of adopting AI responsibly, because comprehension skipped today gets paid for later by whoever inherits the code.

Lumpy Adoption Never Becomes a Team Practice

Hand out licenses without a plan and adoption doesn’t spread evenly. A few engineers go all in, most use the tool occasionally, and some don’t use it at all. Anthropic’s architect certification training calls this “lumpy adoption”: a few developers use AI tooling heavily while the rest barely touch it, so the team never realizes the tool’s real gain and the practice never becomes standard (CCAR-P training, Module 5, Team Enablement and Operational Productivity, “Improving developer workflows with AI tooling”).

The unevenness costs more than unused licenses. The heavy users generate the large changes that DORA warns about, and the light users end up reviewing them without the experience to judge them. Estimates drift because half the team works at one pace and half at another. Each heavy user also builds a private setup that nobody else can reproduce. The same training module names a related failure: teams that never get past using Claude as a question-and-answer box, because nobody set up the more valuable workflows. Its summary is blunt: “Providing a team with access is not adoption.”

The remedy the training describes is a rollout that’s planned rather than left to early adopters. In its example, a 200-person engineering org rolling out Claude Code across four departments starts with one champion per department. Each champion gets two weeks to convert a real workflow, such as a code-review assist or a test-generation step, then runs a 45-minute session for a first batch of five peers. By the broad rollout, every department has a working example, a local expert, and a shared CLAUDE.md the champion has already tuned. The training notes that the same rollout done as a single mass email would likely have produced a wave of confused first-time prompts and a quiet return to old habits (CCAR-P training, Module 5, “Configuring Claude tooling and environments for teams”).

Champions are the training plan. They turn one person’s fluency into the team’s baseline, which is the same job done by the shared Markdown files described below.

Hours Saved Aren’t Dollars Saved

The ROI case for GenAI usually multiplies hours saved by salary and calls the result savings. Finance will eventually see through that. If a team finishes maintenance work sooner, the organization gains capacity, but payroll doesn’t change unless spending actually changes. A credible business case keeps capacity that gets reassigned to valuable work separate from spending that’s actually avoided, such as reduced contractor demand, and from direct cost cuts.

That distinction is where many programs fail. As cited by SmartDev, McKinsey’s 2025 survey found that 88% of organizations use AI in at least one function, but only about 39% report measurable profit impact at the enterprise level (see Real Cost of Generative AI: What SMEs Actually Pay). The same article points to McKinsey’s finding that workflow redesign was strongly associated with measurable financial impact, and it notes that ongoing costs often exceed initial development for most enterprise AI initiatives. Licenses and tokens are the visible part of the bill. Integration, workflow redesign, evaluation, governance, support, and training make up the rest.

The FinOps Foundation’s data points to ownership as the difference. In its State of Tokenomics survey, proving value or ROI was the most commonly named challenge, at 43%, and organizations with defined ownership of AI economics were 3.7 times more likely to show value to the CFO (see FinOps for AI Overview). Its practical guidance is to tag experimentation separately from production, map each API key to one team, application, and cost center, and set a functional baseline alongside the cost baseline. Its infrastructure guidance adds that observed costs should be checked against the business case’s original assumptions (see Choosing an AI Approach and Infrastructure Strategy).

The training also isn’t only for engineers. The FinOps Foundation recommends teaching FinOps basics to the people building with AI and AI cost basics to finance, procurement, and leadership (see FinOps for AI Overview). A manager who can’t tell activity from realized benefit will approve the wrong expansion.

The Markdown Files Nobody Told the Team About

Hand a team Claude Code licenses without training and they get a capable assistant, but not much of what makes it work well for a team. Claude Code reads a set of Markdown files that hold project instructions, scoped engineering rules, reusable procedures, specialist subagents, and memory that carries across sessions (see Explore the .claude directory). Each file’s name, location, and frontmatter decide whether Claude sees it, when it sees it, and what it does with it. Nothing about those rules is obvious from the file names.

Untrained teams tend to fall into one of three patterns.

They don’t use the files at all. Claude still works, but it has to infer conventions from the code and the conversation. Every engineer re-explains the build command, the architecture boundaries, and what “done” means, in every session. That’s the prompt-engineering equivalent of tribal knowledge.

Everyone writes their own. One engineer runs /init, commits the result without reviewing it, and moves on. Another keeps a private CLAUDE.local.md with a better test workflow that nobody else knows about. A third copies a skill from a blog post. Each developer’s sessions now behave differently, and the team’s best practices live on one person’s laptop. A workflow isn’t reproducible if it quietly depends on one senior developer’s private files. Anthropic’s architect certification training describes the alternative as a shared team baseline (a project CLAUDE.md, an agreed set of tools, and a permission posture) that every member starts from, instead of personal setups that drift apart (CCAR-P training, Module 5, “Configuring Claude tooling and environments for teams”).

They write them wrong. This one is the most expensive, because the team believes guidance is active when it isn’t, or that guidance is enforced when it’s only advice. The common mistakes are all predictable from how the files load:

Bloated instructions. A 900-line CLAUDE.md uses up context on every session and lowers how closely Claude follows it. Anthropic recommends keeping each CLAUDE.md under 200 lines (see How Claude remembers your project).
Stale instructions. An old test command or a reference to a decommissioned service is worse than no instruction, because it supplies the wrong assumption every time.
Contradictions. Root and nested CLAUDE.md files are concatenated into context rather than overriding each other, and when two instructions conflict, the Claude Code documentation warns that Claude may pick one arbitrarily (see How Claude remembers your project). A billing service file that contradicts the root file doesn’t win; it just adds a coin flip.
Broken path rules. A rule whose path glob matches nothing never activates. A rule whose YAML frontmatter doesn’t parse loads as if it had no paths at all (see How Claude remembers your project), so guidance meant only for Terraform files gets applied to every task.
Skill name collisions. When names match, enterprise skills take precedence over personal ones, and personal skills over project ones (see Extend Claude with skills). A developer’s personal release-review skill silently replaces the team’s version.
Unreviewed memory. Claude’s auto memory is machine-local and isn’t shared across machines or cloud environments (see How Claude remembers your project). It’s one developer’s working notes, not approved policy. If a mistaken correction gets saved, it carries into later sessions until someone finds and removes it.
Policy written in prose. “Never touch production” in a Markdown file is a reminder, not a control.

None of this shows up in a demo. It shows up as inconsistent output between developers, verification claims that weren’t actually checked, and senior engineers wondering why the assistant “keeps forgetting” a rule that was never loaded.

What Deliberate Looks Like

The difference between a weak instruction file and a useful one is easy to see side by side. Here’s a CLAUDE.md that an untrained team typically produces:

# Project Notes

Write clean, high-quality code. Follow best practices.
Be careful with the database.

Run tests with: npm run test:all   (old script, removed in 2024)

Use the payments-v1 service for billing. (decommissioned)

API key for staging: sk-staging-4f9a...

I prefer tabs and verbose explanations.

## Everything about Terraform, Kubernetes, React, the billing
## service, our 2019 architecture review, and the full style guide
...(700 more lines)...

Almost every line has a problem. The vague standards (“clean,” “careful”) can’t be tested. The commands and services are out of date. There’s a secret in a committed file, a personal preference written as a team rule, and enough unrelated material to bury the parts that matter.

Here’s the version a trained team writes:

# Project instructions

## Commands
- Install dependencies: npm ci
- Check types: npm run typecheck
- Run unit tests: npm test
- Run lint checks: npm run lint

## Architecture
- HTTP handlers call application services.
- Application services access persistence through repository interfaces.
- Do not introduce an alternative persistence framework without approval.

## Change verification
- Add or update tests for changed behavior.
- Report the checks executed and their actual results.
- If a check cannot run, state the reason; do not claim it passed.

## Specialized guidance
- Infrastructure conventions are in infra/CLAUDE.md.
- Use the migration-review skill for database migration reviews.

It’s short, every instruction can be checked, and it points to specialized guidance instead of including it. The “Change verification” section deals directly with the Discernment problem from earlier: it tells Claude to report what it actually ran, not to claim success.

Scoped rules show the same contrast. A poorly written one:

---
paths: infra/**/*.tf
  - "**/*"
---
Follow Terraform best practices.

The YAML is malformed, so the rule loads unconditionally. Even if it parsed, **/* matches every file, and “best practices” tells Claude nothing. A well-written one:

---
paths:
  - "infra/**/*.tf"
---

# Infrastructure conventions

- Use the repository's approved module versions.
- Preserve mandatory resource tags.
- Explain any change affecting public network exposure.
- Report validation results and identify checks not executed.

It loads only when Claude touches Terraform files, the infrastructure team owns it, and every line is something a reviewer can verify.

Skills follow the same pattern. A skill described as “helps with databases” either never triggers or triggers on everything. A skill with a precise description, explicit steps, and disable-model-invocation: true runs only when an engineer asks for it:

---
name: migration-review
description: Review a database migration for compatibility and operational risk.
disable-model-invocation: true
---

# Migration review

1. Identify schema changes and affected application versions.
2. Check backward compatibility during rolling deployment.
3. Assess locking, data volume, and runtime risks.
4. Review recovery and rollback assumptions.
5. Identify missing tests and operational checks.
6. Produce findings with evidence and unresolved questions.

Do not execute the migration.

That last line is still guidance, not enforcement. The database permissions are what actually prevent the migration from running.

Hooks are the piece that closes that gap inside the tool itself. A hook is a script configured in settings.json that runs before or after Claude uses a tool (see Explore the .claude directory). Because the hook runs every time, it doesn’t depend on Claude remembering an instruction. Anthropic’s documentation is direct about the distinction: to block an action regardless of what Claude decides, use a PreToolUse hook rather than a line in CLAUDE.md (see How Claude remembers your project).

The responsible split is simple to state and easy to get wrong without training. Put preferences and conventions in Markdown. Put anything that must always or never happen in a hook: blocking edits to lockfiles, generated code, or production configuration; refusing destructive shell commands; running the formatter and the relevant tests after every edit. Hook scripts are code that runs on every developer’s machine, so they belong in version control and go through the same review as everything else. A team that knows when to use a hook stops arguing about whether Claude “followed the rules” and starts proving it.

A Practical Repository Layout

Put together, a team using these files deliberately ends up with a repository that looks something like this (an illustrative layout, not a required structure):

repository/
├── CLAUDE.md
├── AGENTS.md                       # Optional shared multi-tool instructions
├── CLAUDE.local.md                 # Gitignored
├── .gitignore
├── .claude/
│   ├── settings.json               # Shared configuration; not Markdown
│   ├── settings.local.json         # Private configuration
│   ├── rules/
│   │   ├── testing.md
│   │   ├── api-design.md
│   │   └── terraform.md
│   ├── skills/
│   │   ├── migration-review/
│   │   │   ├── SKILL.md
│   │   │   └── reference.md
│   │   └── incident-analysis/
│   │       └── SKILL.md
│   ├── agents/
│   │   └── security-reviewer.md
│   └── output-styles/
│       └── engineering-review.md
├── services/
│   └── billing/
│       └── CLAUDE.md
├── infra/
│   └── CLAUDE.md
└── docs/
    ├── architecture.md
    ├── adr/
    └── runbooks/

The structure shows who owns each piece. The root CLAUDE.md holds what every change needs. Each service and infrastructure team maintains its own nested file and scoped rules. Reusable procedures live in skills, and specialist reviewers are agents with restricted tools. Personal preferences stay in gitignored files, and permissions live in settings.json, where they’re enforced. Ordinary documentation stays in docs/. A runbook doesn’t become a standing instruction just because it’s a Markdown file; Claude reads it when it’s imported, referenced, or encountered during the work.

The payoff comes from how the team manages these files, as much as from the files themselves. Shared instructions, rules, skills, and agents get committed, reviewed through pull requests (with CODEOWNERS where it helps), tested against representative tasks, and rolled back when a change makes things worse. The files also need upkeep, and Claude Code can help with that: running /doctor prompt-audit has Claude check instruction files for instructions written for older models, references to files or commands that no longer exist, and files that contradict each other (see How Claude remembers your project). When an engineer’s private memory captures something useful, it gets promoted into a reviewed rule or skill so the whole team benefits. That’s where cooperation turns into capability. What one engineer figured out about the billing service, or how to review a risky migration, becomes how every developer’s sessions work, including new hires on their first day.

Managed this way, the files support every outcome this post has covered. Quality improves because standards and verification steps are in place at the point of work. Productivity improves because procedures get reused instead of rebuilt from prompts. Cost goes down because scoped rules and on-demand skills keep irrelevant material out of context. And the training investment holds up, because what people learned is written down, versioned, and shared rather than leaving with whoever learned it.

What Engineering Teams Need to Be Trained On

Enablement for IT and engineering teams usually stops at tool features and prompting tips. The NBER findings suggest that’s the part teams need least help with. The cases above point to a different curriculum:

Delegation: deciding which logic stays deterministic, which work the model owns, and where people stay in charge.
Pattern selection: the difference between an augmented call, a workflow, and an agent, and when each one earns its added complexity.
Model and cost decisions: choosing model tiers step by step, backed by evals, measuring cost per successful outcome, modeling costs at production volume with realistic inputs, and recognizing token maxing for what it is.
Testing probabilistic systems: evals as acceptance criteria, experiments big enough to trust, failure-path testing, and checking that generated tests actually exercise the requirements.
Review and integration: review flows sized to the volume AI now generates and given enough context to catch problems, small batches, early feedback, and judgment about which experiments are worth carrying through to release.
Guidance vs. enforcement: knowing what belongs in CLAUDE.md, rules, and skills, and what has to be enforced through hooks, permissions, CI, and deployment gates, including how, when, and why to write a hook.
Skill preservation: mentoring, and deliberately manual work, so reviewers keep the judgment that review depends on.
Selective non-use: recognizing when doing the work by hand is faster and measuring actual results instead of trusting how fast it felt.

Format matters as much as content. Training works best when it’s role-specific and hands-on with representative work, not a generic prompting demo, and when it’s treated as part of the operating model rather than a one-time onboarding event. It also works best when it’s rolled out through champions and small batches rather than a single all-hands switch-on, so fluency spreads deliberately instead of pooling with early adopters. DORA’s advice to measure impact, not output, sets the bar: lines of code accepted is a volume metric, not a result (see Balancing AI tensions). In practice that means a sequence: establish baselines for delivery speed, quality, and cost; pick bounded use cases with clear acceptance criteria; train against real work; build validation and spending controls into the existing workflow; pilot and measure, including verification effort and rework; then scale, revise, or stop each use case based on the results.

Not every engineer needs an architect certification. The ones making these design calls need more than a kickoff session, and the rest of the team needs enough fluency to notice when a “simpler” design is really a riskier one.

Training Is How Adoption Actually Happens

Engineering teams don’t fail at GenAI because they lack talent. They fail when they’re handed new tools and left to apply old habits. The tools already boost output: 240% more commits. Only 30% more releases come out the other end. The difference is in review, integration, testing, and design decisions, which is the same place the 41 misrouted claims, the six months spent on an agent, and the 7× overrun came from. That’s what adopting AI responsibly looks like in practice: spending tokens where they earn their keep, testing probabilistic output for what it is, keeping must-hold rules in deterministic code and hooks, shipping only what the team can explain and maintain, and managing the files that shape the tool’s behavior like any other code. Training aimed there is what turns more code into more shipped software, and it’s the line item that makes the license spend pay back.

If you found this interesting, please share.

Markdown Made Manageable Minus the IDE

September 20, 2026Scott S NelsonLeave a comment

TL;DR: Markdown cuts token costs and stays readable as plain text, but raw syntax isn’t everyone’s idea of a good time. My two favorites cover both sides of the problem, VS Code and its built-in Markdown preview for writing and MDHero for reading, Pandoc keeps Word documents in the mix, and several other free options fill in the gaps.

Why Markdown

Markdown carries structure (headings, lists, links, emphasis) with a handful of punctuation marks instead of the packaging that comes with HTML or a DOCX file. The gap is big enough to show up on the bill: Markdown runs roughly 65 to 90 percent fewer tokens than DOCX for the same content, and that compounds with every round of edits (see Efficient Claude Usage with Microsoft Word Documents for the full rant).

HTML has its own fan club, and the claim that it is the new Markdown holds up in one narrow case: an LLM producing a deliverable a human has to read and navigate. For model input, internal agent loops, and repository documentation, Markdown still wins, at around 80 percent fewer tokens than HTML for equivalent content (see Markup is the New Markdown for the scenario breakdown). That leaves the practical question of which app to use with it.

Developers Already Have an Editor and Everyone Else Needs a Viewer

For developers, and for anyone braving VS Code to get a better look at what their AI is doing, the editor is already installed. VS Code has a built-in Markdown preview that runs side by side with the raw file or as a full-page view (Ctrl+Shift+V for the full page, Ctrl+K then V for side by side, Cmd on a Mac). The file on disk is still plain Markdown, and it sits in the same folder as the code, prompts, and docs it belongs with.

Asking a colleague to install a developer environment just to read a README is a good way to ensure it goes unread. The new Windows Notepad has picked up Markdown “support,” which does some heavy lifting next to a purpose-built reader. MDHero is a free, open source viewer at under 8MB that renders the file cleanly and otherwise gets out of the way (no vault, no sync, no plugin marketplace, no account). When the goal is to read a document, less app is the feature, and it is small enough to hand to a non-technical teammate without a lecture attached.

Documents Bound for Word Can Still Be Worked in Markdown

Plenty of documents start in Word and end in Word, and nobody is about to change that. It doesn’t mean Word has to be the place where the AI-assisted work happens. Pandoc is a free, open source converter that turns a DOCX into Markdown and back again, so the drafting and revising can happen in the cheap format and only the finish happens in the expensive one. Word plugins for Claude improve the ergonomics but leave the same DOCX overhead underneath, so the token bill stays put (see Efficient Claude Usage with Microsoft Word Documents for the full workflow and the numbers behind it).

The short version, in two commands:

pandoc input.docx -o draft.md
pandoc draft.md -o final.docx

Convert the existing document to Markdown, do the thinking and editing there with AI, convert back, and apply styling and branding in Word last. Pointing Pandoc at a styled template with --reference-doc=template.docx on the way back carries fonts and headings into the result. Complex tables, tracked changes, and heavily designed layouts may not survive the round trip cleanly, so keep the original DOCX around for anything exotic.

The Rest of the Free Field

These are the other popular free options, roughly sorted by what they are best at:

Obsidian: A local-first notes app built on a folder of Markdown files, with backlinks, a graph view, and a large plugin ecosystem. Free for personal use. It is a knowledge base first and an editor second, so expect a learning curve.
MarkText: A free, open source editor that renders as you type, with a clean interface and no account. Check the project’s recent activity before standardizing on it, since update cadence has been uneven.
Zettlr: Free, open source, and aimed at academic and long-form writing, with citation support and Pandoc export.
Joplin: Free, open source note-taking in Markdown with sync across desktop and mobile through the storage service of your choice. It also has a good WYSIWYG mode, which makes it the easiest pick here for anyone who would rather never see the syntax.
Notepad++: Markdown is text, so any text editor opens it (syntax highlighting is the only upgrade needed).

Typora, one of the best-known Markdown editors, is left off this list because it is paid, and this list is free only (psst…Claude made me say that…I never heard of it before it edited this post).

I spent years mastering HTML, and found the shift to markdown a bit annoying at first. I’m embracing not as something I personally find better, but as something that people (and now machines) that I would to communicate with have adopted as their preference. The ability to change is not only the sign of a good architecture, it is a requirement for good architects and other creatures.

If you found this interesting, please share.

SaaS Has No Box

September 8, 2026September 9, 2026Scott S NelsonLeave a comment

TL;DR: SaaS doesn’t remove implementation work, it relocates it: from servers and patches to configuration, nested declarations, and complex weaving of separate-but-related features to deliver enterprise capabilities over custom code written against vendor interfaces. Demos can be deceiving, even if not intentionally so. More often it’s the expectation that everything you need is available “out of the box” that makes SaaS look like a magic bullet to enterprise product owners instead of just another tool that takes training and skill to build with and effort to maintain.

When There Is No Box

SaaS can be the perfect architectural choice for an organization to focus on business value instead of unique technology capabilities. You don’t buy SaaS, you lease it, and that distinction is its value proposition. The vendor manages technology refresh cycles as part of the subscription through continuous updates instead of IT trying to keep up on endless patch cycles and observability-driven improvements. Traditional software, whether licensed on-prem or custom built (even “cloud native”), is a distraction for some organizations, and an outright burden for others, especially when the maintenance isn’t budgeted for during the design and build phases. Organizations that make the wrong choice end up in endless cycles of replacing systems through CapEx as a result of under-funded OpEx. These cycles are as disruptive to the users as they are to the support teams, both having to reskill while losing they “muscle memory” built up with the previous system. SaaS is often the solution for these organizations, but not always. Technical debt can written declaratively as well as programmatically, especially when enterprise SaaS is confused with enterprise software.

The gray area between SaaS and software is what it takes to turn a collection of separate-but-related features into an enterprise capability: level of effort, support, and everything a vendor demo skips over. Demos are built for the business buyer with a checkbook, not the developer with a deadline. A single capability, shown on its own, looks like a checkbox. Implementing it by wiring together ten other features, each documented as if the others didn’t exist is a different job entirely, and it’s the job nobody demos.

Bottom line: Nothing is “out of the box” with SaaS. SaaS has no box. It has a tenant, a contract, a configuration console, a few license tiers, an identity integration, and eventually a backlog. No box.

The wrong assumption is that enterprise SaaS is a pre-built application, so implementation is mostly a matter of switching it on (an understandable confusion because some non-enterprise SaaS does work that way). A more accurate model: enterprise SaaS is a product (and, with successful vendors, a collection of acquired, competing, products) sitting on a platform shared by thousands of other customers. The product supplies standard capabilities. The platform supplies features to configure, automate, extend, secure, integrate, monitor (sometimes) and govern them. Both matter, and they’re different implementation problems.

While there’s no box, SaaS still delivers many of the same benefits standard software has always had over custom builds, and a small company running a fairly standardized process can get close to production-ready with limited setup (warning: no organization with an IT staff ever has a limited setup). Those are the things business users are so used to that they forget to count them: security, role management, standard integrations, audit logging, backup and disaster recovery, single sign-on, and standard compliance (support) built in rather than bolted on. A department adds users, roles, approvals, reports, and a few local variations, and configuration becomes real work. An enterprise running the same product across business units, regulations, and integrations turns it into a configurable platform that needs architecture and governance, whether or not anyone wrote a line of code. Again, the confusion is mistaking standard features as “out of the box”. They are parameters necessary to use a well designed platform to protect both the customer and the vendor.

Cloud Has Changed the Meaning of OOTB

“Out of the box” used to mean a shrink-wrapped disk that installed a working application on a server you owned. Cloud didn’t kill the phrase, it’s just no more literal than dialing a phone or pasting text. The concepts are still the same, though sometimes mis-applied because the meaning has been lost in translation.

To a vendor, OOTB usually means the feature exists in the licensed edition, fits the product’s intended model, and can be enabled or demonstrated without a separate application. That’s an honest intent. It’s also incomplete. The platform including the building blocks is not the same as an organization putting the thing into production next week with its own data, users, policies, integrations, processes, and exceptions.

To a business stakeholder, OOTB often means something closer to done: complete, supported, included in the purchase, ready with minimal effort, sensible about exceptions to processes that “everyone” follows. Fair enough for a consumer app, but it falls apart fast in enterprise SaaS, because “normal” is in the eye of the beholder (or buyer), and the vendor is working from a normal defined by the lowest common denominator across their entire customer base.

To an engineer or an experienced administrator, it means the capability exists, there’s probably a supported configuration path, and there may also be three licensing constraints, a technical prerequisite nobody mentioned, and a limitation that won’t surface until a user asks a perfectly reasonable question in production.

The reason those three points of view keep colliding is simple: a feature demo is a planned, orchestrated, and practiced event to showcase what a product does. An enterprise capability is the business secret sauce baked into solution that relies on twice as many features and sometimes held together by bubblegum and baling wire. One is maybe out of the box. The other never saw a box, and the instructions were in a different language for a different purpose and required a lot of creativity that often goes unrecognized.

Enterprise SaaS is less a finished solution than a pile of Legos with an incomplete picture and no instructions (but sometimes a blog post, which isn’t always going to mention the complexity required or the dozens of failed attempts that came before it). The pieces are good. Plenty fit together well. But the pieces being in the box, metaphorically, since SaaS still doesn’t have one, doesn’t tell you what to build, whether the model survives the next upgrade, or who fixes it when someone changes a foundational rule six months from now.

Take a routing requirement. In a demo: a new request comes in, gets assigned by region, triggers a notification, and that’s it. In production: region comes from more than one system, the request touches multiple accounts, the assigned team depends on product line and contract status, some records are role-restricted, the notification has to respect local hours, and the downstream system is occasionally down. The feature is the same one from the demo. The demo was not OOTB, and neither is the solution the business needs. If you’re lucky, you might get details of how to duplicate the demo. You will not get instructions on how to make the version you actually need. And what seems the hardest for the non-technical folks to understand is that it is much more effort to create the configuration without direction than it is to develop with custom code. The custom code has no multi-tenant constraints.

OOTB is a capability statement. It is not an implementation estimate, an operational guarantee, or a substitute for architecture. And it isn’t available with SaaS (though some enterprising companies build add-ons that are, but they are usually even more constrained than the SaaS itself).

The Simpler the Configuration, the More Complex the Code It Hides

The difference between abstraction and misdirection is that the magician will often tell you he is misdirecting you. To identify abstraction, you need to think like an engineer, not business user.

Abstraction is not a bad thing. The steering wheel of a car is an abstraction from the complex systems necessary to change the orientation of the front wheels, and even developers who can read binary would still rather use method that abstracts the library of components that abstract the bits away from streaming data from one location to another.

But you can make better decisions about how to steer the car or which streaming library to use if you understand that it is an abstraction and actions have deeper consequences.

Configuration and declarative programming are that same kind of abstraction, a steering wheel for the platform instead of a wrench in its engine. An out-of-the-box capability is a feature the platform supplies through exactly that abstraction. It may work as-is for the standard case, but it usually needs configuration, permissions, data setup, licensing, and training before it’s useful, and it may not match the current process exactly.

Configuration means shaping standard behavior through supported settings: roles, page layouts, field validation, reports, routing rules, approval structures, notifications, integration endpoints. Once it affects production behavior, it’s implementation work, full stop, with requirements, design review, test cases, deployment control, documentation, and an owner. Calling it “not development” is technically defensible in the narrowest sense. It’s also how a team ends up with 437 rules, three administrators who understand half of them, and no confident answer for what happens when a customer’s status changes (see Agile is not Ready, Fire, Aim for more on this).

Declarative development, workflow tools, rules engines, visual process designers, formula fields, event triggers, is a platform-provided way to define logic without conventional code. It’s still code. The platform abstracts the syntax away from the person assembling it. It doesn’t abstract away the consequences. A few boxes connected by arrows can represent a substantial amount of execution logic, error handling, and dependency chains the calm canvas never shows, until production has other opinions, usually at an inconvenient hour. Stack enough simple, individually reasonable configurations and the system ends up simple nowhere and complex everywhere at once (see 5 Considerations About Low-Code/No-Code).

That’s the mechanism that makes SaaS scale, not a flaw to engineer away. A platform flexible enough to fit a hospital system, a bank, and a mid-size distributor without three separate codebases has to carry that flexibility as complexity somewhere. The vendor pushes it into configuration and declarative tooling instead of custom code. That doesn’t make the complexity optional, it just changes who manages it and what tools they get to do it with.

Custom development, code within supported extension mechanisms, custom applications on the platform, middleware, integration services, isn’t automatically a failure of SaaS. A five-line extension with source control, automated tests, logging, and a documented owner can be safer than a heroic visual flow nobody wants to touch because the canvas now resembles an airport terminal map. The safer default is buy-before-build: standard components first, AppExchange next, custom code only when nothing else genuinely fits (see Enterprise Salesforce Team Recipe for a longer rant on this aspect). Either way, the distinction that matters isn’t code versus clicks. It’s whether the result can be understood, tested, secured, upgraded, and supported by whoever inherits it. Microsoft’s own guidance on low-code governance is telling here: it talks about guiding “both professional and citizen developers who build custom applications for business needs” (see What Is Low-Code Governance and Why Is It Necessary?). A low-code solution is still a custom application, and it needs roles, controls, and oversight regardless of how few characters got typed to build it.

“Can Be Done” != “Is Supported”

This is worth repeating more than once: almost anything is technically possible with enough extensions, workarounds, APIs, and questionable judgment. Whether it’s supported is a different question entirely (insert Jeff Goldblum Jurassic Park meme here).

Vendor-supported means the mechanism is documented, stood behind, and preserved through normal releases. Whether your own teams can support it comes down to whether they can diagnose it, test it, change it, and hand it off. And it only stays sustainable if the whole thing remains economically and operationally reasonable as the platform, the process, and the team keep changing around it. A demo answering yes to “can it be done” tells you nothing about the other three.

Undocumented API behavior, browser automation standing in for a real integration, a customization that quietly modifies vendor-delivered files, a workflow built on a feature the vendor has already announced it’s retiring, a marketplace add-on with one maintainer and an optimistic roadmap: all technically working. A documented, versioned extension point is a different commitment than any of that.

The cost and risk of “custom” depends less on the label and more on the stability of what it’s built on. A stable foundation has published APIs with deprecation notices, documented extension points, sandboxes, deployment and rollback mechanisms, and a realistic talent pool that can maintain it. An unstable one has undocumented internals, screen scraping, direct database access outside vendor guidance, fragile third-party dependencies, and configuration too tangled to inventory. A small customization on a documented extension point can have a modest lifecycle cost. A small customization on undocumented behavior can turn into a recurring upgrade project. The line count, or the number of boxes in a flow, tells you less than the stability of the surface it’s built on.

Standard declarative features aren’t automatically exempt from this either. Salesforce ended support for Workflow Rules and Process Builder after December 31, 2025. Existing automation can keep running. Salesforce’s own documentation puts the distinction plainly: “Your active Workflow Rules and Process Builder processes continue to run as they do today,” followed immediately by the limitation that “customer support is not available, and bugs will not be fixed” (from Workflow Rules and Process Builder End of Support). Salesforce’s own stated reasoning for the consolidation was that spreading automation across multiple tools “hampers both maintenance and innovation” (see Go with the Flow: What’s Happening with Workflow Rules and Process Builder?), which is a reasonable product decision. It doesn’t change who pays for inventorying, testing, migrating, and retraining on what got built on the old feature. “We didn’t write code” was never a lifecycle strategy.

Which is where architects earn their keep, not by vetoing low-code or routing every request through a custom-dev project, but by distinguishing product configuration from business-critical custom behavior, spotting dependency and lifecycle risk before it’s load-bearing, and asking what happens when the vendor retires the thing three years from now. The job isn’t making the solution more complicated. It’s making the complexity visible early enough that the organization can choose where to carry it.

The Ocean View Capability

Every enterprise SaaS platform has Ocean View capabilities. They look excellent from the balcony. The demo is clean, the data is cooperative, the presenter knows the route, and the integration has already been arranged. The value is obvious.

Shiny things can be dazzling, but don’t mistake them for a trick. A ninety-second demo has to compress a hard problem into something presentable, and that compression is what quietly removes the cases that would make the problem visible.

Then implementation starts, and someone asks about identity federation, field-level security, migration errors, audit history, a regional exception, an approval delegation, an API failure, and the department that’s been running its actual process out of a shared mailbox since 2014. The ocean’s still there. It’s just farther from the lobby than the brochure implied.

Vendor blogs are good for learning what a feature is intended to do. They’re written to explain a capability, not to catalog every limitation, so they lean on clean prepared data, follow the happy path, and rarely dwell on edition-specific licensing, exception handling, or recovery scenarios. A vendor blog can show that a feature exists. It rarely proves the feature fits your operating model.

Demos are orchestrated on purpose, not deceptively, just deliberately: prepared dataset, existing roles and permissions, the expected route through the workflow, integrations already wired, no duplicate records, no outages, no data-quality problems, no last-minute policy exception. Call it theater, not fraud. It’s designed to explain a capability quickly, not reproduce a customer’s production environment. The mistake is mistaking a successful demo for a fit assessment.

The fix is straightforward, if less exciting than watching a polished walkthrough: ask the vendor to run the organization’s actual process with representative data, not the generic version. Require the exception path, not just the happy one. Test the real identity, role, and approval requirements, and find out what happens when an integration or automation fails. Get the licensing tiers, support boundaries, and lifecycle commitments in writing. The best single question in the room is usually, “Show me what happens when it doesn’t work.”

Gregor Hohpe, (the definitive author on architecture, IMO) states the reality experienced architects live in more plainly than almost anyone writing about this, goes further in The Quest for Low-Code. His starting point: there’s no magic in software. Every code-reduction mechanism implies a trade-off, and the evaluation job is naming which one you’re accepting. From there his checklist gets concrete: is what’s left actually low cognitive load, or just low line-count with the complexity relocated into a jumble of custom syntax buried in quotes inside a YAML file? How does the solution evolve, is there version control, can you roll back, does it hold up past the scale of the demo? And what happens on the unhappy path, do the error messages help or just leak the tool’s internals? His three vendor exercises put that last question to the test directly: introduce an error on purpose and read what the message actually tells you, leave the room and have the vendor break the thing and debug it live, or take the keyboard yourself and see how much hand-holding it takes to build something real.

Configure Deliberately, Extend Carefully

SaaS is frequently the right call. It reduces unnecessary ownership, accelerates access to mature capability, and spares an organization from rebuilding commodity software it has no business rebuilding. Standard functionality should be the default. Sometimes the business process should adapt to a proven product model instead of demanding a bespoke replica of every legacy exception it’s accumulated out of habit.

None of that means every use case gets covered for free. The same flexibility that lets the platform serve wildly different businesses is what makes your specific business’s edge cases someone’s implementation problem, not a checkbox someone forgot to include. And custom code isn’t automatically the harder path. A clean extension against a documented interface can take less time and less risk than the half-dozen declarative features it would take to fake the same behavior through configuration. The label on the technique, code or clicks, was never a reliable way to estimate the work.

Watch for the case study that shows someone getting a complex capability working by wiring together three or four platform features. It’s real, but it’s also incomplete: what made it into the write-up is the wiring, not the weeks of trial, error, and platform-specific knowledge that came before it worked cleanly enough to demo. A capability that took a seasoned admin forty hours to get right the third time doesn’t become a ten-minute task because the polished version only takes ten minutes to watch someone build.

And the decision to go with SaaS is not where the architecture ends. A workflow assembled in a visual designer can still affect revenue, customer commitments, regulatory obligations, and a support team’s weekend. An integration configured through a menu can still fail at 2:00 AM. A field renamed without documentation can still turn next year’s migration into archaeology.

Use the standard product where it genuinely fits. Configure it with discipline, and price that discipline honestly: time, effort, and cost scale with how far the requirement sits from the common case, because the common case is what SaaS was built to solve cheaply. The more unique the business need, the more of that cost the organization carries itself, whether it ends up in configuration, declarative automation, or custom code. Treat declarative automation as software, because it is. Extend stable, documented foundations when the requirement earns it, code included. And the next time someone says a capability is available out of the box, ask who it’s actually out of the box for.

In enterprise SaaS, nothing is truly out of the box. The capability exists. What it costs to make that capability yours, in time, effort, and risk, is an architecture decision shaped by how far your need sits from the common case, not a vendor claim and not a line item copied from someone else’s case study.

If you found this interesting, please share.

Lessons Learned, Lessons Lost: Why AI Retrospectives Rule

August 1, 2026Scott S NelsonLeave a comment

TL;DR: The Sprint Retrospective would be the most valuable ceremony in Scrum…if it weren’t also the one with the worst follow-through. AI can run the same ceremony and actually keep the results, because the lesson gets loaded before the next session instead of filed and forgotten. It’s a simple habit to learn, and there are plenty of free examples of how to automate it. It’s a small investment of time and thought that pays real dividends in productivity and confidence.

The Ceremony That Everyone Likes and Nobody Finishes

The 2020 Scrum Guide puts the Sprint Retrospective at the end of the Sprint, timeboxed to three hours for a one-month Sprint (not that many places do one-month Sprints anymore, or allot three hours for improving things). The process is simple: provide a safe space where people can speak their mind about what went well, what didn’t, and how they would change things to be better in the next Sprint. The goal is to capture ways to increase quality and effectiveness while reducing friction and wasted time.

In theory it’s the smartest ceremony of any SDLC. A room full of people who just lived through the same thing, comparing notes while it’s fresh, with permission to say what actually happened.

I was introduced to this ceremony before Agile approaches were common in the enterprise. We ran it after a major release, and I found the process very enlightening. Someone wrote up a summary of the findings and posted it on the company intranet.

This was a long time ago. Years later I remembered that document and got curious about whether anyone had ever gone back to it.

I was the only one who ever looked at it again.

I can’t recall a single piece of wisdom it captured. Not one. What I do remember is the aura of “this makes so much sense” when we discussed the stickies on the wall. And that the same mistakes were repeated across later projects, many with some of the same people in the room who had sat through the meeting where we agreed not to make them again. Sigh.

What Happens to the Findings

Follow the output and the pattern is easy to see.

Some items become real assignments. Someone owns it, someone completes it, and the team is measurably better off. That’s a real win and it’s worth saying so.

The problem is, it is too often a one-off win. The task closes. It’s checked off and moved to Done. Then the same thing comes up three Sprints later. Or the next Sprint.

Because the good stuff that gets surfaced in a retro isn’t something that can be fixed with a story. It’s a lesson. “We committed before we understood the integration.” “We let the staging environment drift.” “We assumed the client would review in three days and they took three weeks.” Those aren’t tickets. They’re rules for how to behave next time, and there is nowhere to put them where people will remember them (yes, there’s an exception, for those who are already ahead of the game with a living PROJECT.md, aka CLAUDE.md, AGENTS.md, or whatever your favorite harness uses).

So they go into a document. Which goes onto an intranet page. Which nobody opens during the next project, because during the next project everyone is busy doing the next project.

The retrospective produces knowledge with no delivery mechanism. Six weeks later a new team, or the same team with two new people, walks into the identical wall and holds an identical meeting about it. We call that continuous improvement. It’s closer to continuous rediscovery.

That failure, organizations not learning from their own experience even after making the capture of lessons a required part of the process, is a big part of why the Best Practices section on this site exists at all.

Run the Same Ceremony, by Hand

Now try it with AI at the end of a working session. At its most basic, this is two prompts.

Review this session. What worked, what didn't, what should change next time?
Give it to me as Start, Stop, Continue.

Start doing this, stop doing that, keep doing this other thing. Read what comes back, edit anything that’s wrong or too vague to act on, then:

Save that to memory and apply it going forward.

That’s the entire ceremony. Under two minutes, no tooling, no setup. (YMMV on the prompt, depending on your type and style of work…BWTM)

Here’s the part that changes everything. It doesn’t file the lesson. It applies it, every time, forever. Next session, and every session after that, those rules are loaded before the first word of work gets done. There is no folder, no onboarding deck, no hoping somebody remembers. The correction is simply in effect.

And it updates. Session ten refines what session three concluded. A rule that turned out to be wrong gets replaced instead of quietly ignored.

Same ceremony. Same format. The difference is entirely in what happens after the meeting ends.

The productivity gain is obvious enough. The part that sneaks up on you is the confidence. After a few weeks you stop bracing for the mistake you already corrected once, because it doesn’t come back.

The Gap Was Never Honesty

The lesson here isn’t that AI is disciplined and people are sloppy. People are perfectly capable of discipline. What people don’t have is a place to put a lesson where it will find them again at the moment they need it.

That’s the gap the retrospective has always had. Not insight. Distribution.

AI closes it almost by accident, because persistent memory is just how the thing works. The lesson arrives in the same channel as the work, automatically. You don’t have to remember to go check.

Which reframes a lot of process failures. Most of the time the problem isn’t that we didn’t learn. It’s that the learning had no route back into the work.

Almost Nobody Does This

Here’s the honest part. Very few people take the time to run a retrospective on their AI sessions, and fewer still do it consistently.

It isn’t hard and it isn’t slow, which is exactly what makes it easy to skip. Two minutes is nothing. Two minutes you never spend is also nothing, and it’s what most people land on by about the third busy week. The ceremony that depends on remembering to hold it is the ceremony that quietly stops happening, which is the same failure mode as the intranet page, just faster.

That’s the argument for automating the capture rather than relying on the habit.

You Don’t Have to Invent This

Run it by hand for a few weeks first, though. You want a feel for what a useful captured lesson looks like before you hand the job to something that writes them without asking, because you’ll be reviewing that output later and you need to be able to spot a bad one. Automated capture drifts. It records the frustrated aside instead of the actual rule, or it generalizes a one-off into a standing instruction. Doing it manually first is how you learn to recognize that when you see it.

And you don’t have to tune that prompt from scratch, or build the automation yourself either. There’s an entire cottage industry of shared instruction sets, skills, and rule files built to automate this loop, and most of them are free and MIT-licensed. Read a few and you’ll find better phrasing than mine sitting right there in someone’s repo.

claude-reflect is the most widely adopted of the ones I found. Hooks watch your prompts for correction patterns like “no, use X” or “actually” and queue them automatically. You then run a command to review the queue and approve what gets written into your persistent instructions. Capture is automatic, application requires your sign-off. It also mines your session history for repeated requests and offers to turn them into reusable commands.

bokan’s self-improvement skill takes a different angle: it fans out parallel agents across your past sessions, ranks friction patterns by how often they recur, and attaches the raw quote where things went sideways. Frequency plus evidence, which makes the finding arguable rather than just asserted.

claude-improve is worth reading even if you never install it, because its README openly credits the six community approaches it was assembled from. One of those, a one-prompt reflection pattern, contributes the single most practical idea in the whole space: write the captured lesson as an enforceable rule. Lead with why, use NEVER and ALWAYS, include a concrete example. Most captured lessons fail because they’re written as vague observations that nothing can act on.

Cursor users have the same pattern in a different wrapper, usually a self_improve.mdc rule paired with a rules file, as described in Stop Babysitting your AI.

Pick one, use it as-is, or read three of them and build the version that fits how you actually work. Standing on someone else’s structure beats staring at a blank file.

What the Evidence Says

One thing to calibrate before you go shopping, because I’d rather say it than have you find out later.

None of these tools has been independently reviewed or benchmarked. What they have is stars, forks, and enthusiastic author write-ups. A thousand stars measures whether an idea sounds good, not whether it works. There’s no head-to-head comparison, so pick on fit rather than on popularity.

The underlying mechanic, though, has real support. The Reflexion paper from NeurIPS 2023 found that agents that write a short natural-language reflection on what went wrong outperform agents that store the raw record of what happened by eight percentage points absolute. Storing the transcript is worth less than storing the conclusion. That is the academic version of Start, Stop, Continue.

Anthropic’s own context management benchmark reports a 39% performance improvement over baseline when memory and context editing are combined, and 84% fewer tokens consumed on a long multi-step task. Vendor-run, so discount it accordingly, but it’s a real evaluation with published numbers.

The mechanism is sound. The specific tooling is a matter of taste.

Prune It, or You’ve Just Rebuilt the Intranet Page

The one part none of this tooling can do for you: every system here accumulates rules, and none of them has a convincing answer for pruning. claude-reflect ships a dedupe command, which tells you the problem is real enough to need a command.

So budget a few minutes every month or so to read what’s piled up and delete what’s gone stale. That’s the intervention the manual practice trained you for. A memory file nobody audits becomes the same dead document, except this one is actively steering your work instead of quietly sitting on an intranet.

Making the Time Before You Save the Time

All of this runs into the oldest problem in efficiency work: you have to spend the time before you get the time. Every initiative that eventually saves hours starts by costing hours you didn’t have when you decided to do it. Automating your retrospectives is no different. The build is small, but it’s still a build, and it competes with the actual work that made you want the efficiency in the first place.

I get it. New habits are hard. I confess that I don’t do this as regularly as I should, and that even though I have some prompts pre-written in UpNote to use that are more involved than the example given in this post, I usually write one off the cuff when I do remember. Maybe if I spent less time writing about techniques and more time automating them…

Which is exactly why the two-prompt version matters. It costs nothing to start, it works on its own, and it buys you the judgment you’ll need before you spend an afternoon wiring up anything fancier. Start there. Automate when the habit is annoying you enough to be worth removing.

An Answer to the Question Everyone Keeps Asking

“What are we doing with the time we save using AI?”

Fair question, and most of the answers are vapor. Here’s one that isn’t.

Spend a slice of it teaching the tool what it just learned. Those two minutes are the highest-leverage part of the whole workflow, because they’re the only part that compounds. Every other minute you save gets saved once. This one gets saved again on every future session.

It shouldn’t take all of it. And it should take less as time goes on, which is the tell that it’s working. Early sessions produce a lot of corrections because there’s a lot the tool doesn’t know about how you work. Later sessions produce a few refinements. Eventually you’re mostly confirming that the rules still hold.

Use the rest to go touch grass.

That’s not a throwaway. The entire argument for this technology is that it gives us capacity back. If we spend all of the reclaimed time on more work, we didn’t gain capacity, we just raised the quota.

Now Tell Me What You’re Actually Doing

This is the part where a post like this usually promises a follow-up with results. I’d rather ask than promise.

If you’re already running some version of this, I want to hear it. Which tool, or which few lines you wrote yourself. What the capture prompt actually says. Whether you review what gets written or let it accumulate. What broke.

If you’re not doing it yet and this pushed you into trying, say so at the start and tell me what happened three weeks in. Including if the answer is that you did it twice and stopped, because that result is more useful than another enthusiastic write-up. The failure modes are what’s missing from every article I read while putting this together.

If enough of it turns out to be interesting, there’s probably a follow-up in it, built mostly out of what readers send rather than what I think. Credited unless you’d rather not be. A comment, an email, a reply on LinkedIn, whatever’s easiest.

The retrospective finally works. Let’s find out whether we actually run it.

If you found this interesting, please share.

Keep Claude from Forgetting You When Moving to a New PC

July 26, 2026July 26, 2026Scott S NelsonLeave a comment

TL;DR: Copying your project folders to a new laptop moves the files and leaves the work behind. Everything Claude Desktop actually remembers, your Cowork sessions, your MCP connector config, your Claude Code settings, lives in a Windows package sandbox that a normal search will never find. Zip that folder with the app closed and your history comes with you. Skip it and you start over with a very clean, very empty sidebar.

New Laptop Day

New laptop day is supposed to be a good day. Copy the projects, sign in, get back to work.

For most non-developers it generally is pretty straightforward, especially if your company manages backups and you use defaults. Sign in, wait for the sync icon to stop spinning, open the same three apps you always open. Whatever you’d customized was mostly customized inside something that follows your account, so it follows your account.

For developers and other power users it has never been that straightforward. There are a million little tweaks accumulated over years for personal preference and productivity, and not one of them is written down anywhere. The PATH entry you added at 11pm to make a build work. The tool installed from a zip file into a folder you invented. The config that lives three levels below AppData because that’s where the installer decided to put it. You don’t have a list. You have a vague sense that something will be missing, and you find out which something at the worst possible moment, usually about four days later.

Thanks to the popularity of Claude, now everyone gets those extra steps. And they’re not that straightforward even for the power users.

Here’s how it goes wrong. You copy the project folders. OneDrive handles the synced ones, a USB drive handles the local-only ones, file counts check out, you spot-check a few documents and nothing’s corrupted. Install Claude Desktop, sign in, open Cowork.

Empty.

The files are all there. The work is not. Every session, every bit of accumulated context, every conversation where you finally got Claude to understand your codebase, none of it came along. Because none of that lives in the project folder. It lives somewhere else entirely, and the app gives you no indication where.

Worth sorting out before you wipe the old machine, which is the point of no return most people hit about an hour after they think they’re done.

Two Kinds of Sessions, Only One of Which Is Your Problem

Some good news first. Cowork sessions now run remotely and are tied to your Claude account rather than your hardware. Sign into a new machine and those sessions are already there, waiting, automagically. Nothing to move, nothing to find. For once, the defaults crowd wins outright.

The catch is that this only holds for sessions created after remote sessions shipped. Anything older is a local artifact sitting on the old hard drive. If you’ve been using Cowork for a while, that’s likely most of your history.

So the question isn’t whether to migrate. It’s whether your sessions predate the cutover.

If none of them do, close the tab and enjoy the new laptop. Although before you go, it’s worth a moment’s honest reflection: if you’ve been at this for a while and have nothing accumulated that’s worth the trouble of moving, that’s telling you something. Not about the migration. About how much of Claude you’re actually using. A tool you’ve spent months teaching your projects, your standards, and your preferences to is a different tool than one you open to write emails. If none of this applies to you, the interesting question isn’t how to migrate. It’s what you’ve been leaving on the table.

For everyone else, keep reading.

Where It Actually Lives

Ask Claude where its own session data lives on Windows and it will tell you %APPDATA%\Claude\local-agent-mode-sessions\. It will tell you this confidently. Community migration tooling references the same path, so it isn’t inventing it from nothing.

It isn’t there.

Nor is it at %LOCALAPPDATA%\Claude\, which is the natural second guess and the next thing you’ll be told to try. You can run a recursive search across your entire user profile for audit.jsonl, the conversation log written inside every Cowork session, and get nothing back at all. That result is disorienting enough that you start to wonder whether the sessions ever existed on disk in the first place.

Whether that documented path was ever correct on Windows, or whether it’s a Mac convention that got generalized, isn’t something I can tell you. What matters is that on a current Windows install it’s a dead end, and it’s the dead end you’ll be pointed at first.

The real reason is architectural. Claude Desktop installs as a packaged Windows app, and packaged apps get their own private storage sandbox. Writes to the conventional locations get quietly redirected somewhere like this:

C:\Users\<username>\AppData\Local\Packages\Claude_<packageid>\LocalCache\Roaming\Claude\

Note the shape of that path. It ends in Roaming\Claude, exactly as documented. It’s just sitting under a package container that no reasonable person would think to check, which is why searching for the documented path fails while the documented path is, in a sense, still accurate.

The package ID is a short string of characters, and there’s no reason to guess at yours. Find it:

Get-ChildItem -Path $env:APPDATA, $env:LOCALAPPDATA, $env:USERPROFILE -Recurse -Filter "*claude*" -ErrorAction SilentlyContinue |
  Where-Object { $_.PSIsContainer } |
  Select-Object FullName |
  Out-File "$env:USERPROFILE\Desktop\claude-folders.txt"

That writes every Claude-related folder on the machine to your desktop. Open the file, look for the one containing local-agent-mode-sessions, and you have your real path. Two notes: run it in PowerShell, not Command Prompt, and expect it to take a minute or two while it walks the profile.

Depending on how and when Claude was installed, your data may genuinely sit in the plain %APPDATA%\Claude\ path. Both are possible. The one holding session subfolders with long UUID-style names is the one that matters. Don’t assume, check.

Claude Will Help You Move, and You Don’t Even Need to Buy It a Pizza Afterwards

Here’s the part that’s mildly funny in hindsight: the way to find all of this is to ask Claude, in Cowork, on the machine you’re migrating away from. It has shell access to the profile it’s running in. Point it at the problem and it will run the searches, read what comes back, and narrow the path down with you.

It will also send you to those two wrong folders on the way there, because the documented path and the actual path aren’t the same thing, and the documented path is what it reaches for first. That’s not a knock. It’s the ordinary pattern of working with these tools, and the fix is the same as always: make it show you the output rather than accept the summary. The searches above came out of exactly that back and forth. Claude proposed, the filesystem disagreed, and the third attempt found it.

Which is the useful lesson here, more than the folder path. The tool is genuinely good at the mechanical part, walking a filesystem, reading a directory listing, writing the PowerShell you’d otherwise be looking up. It is not reliable about where things live, because that’s a fact about your specific install and not something it can know from training. Use it for the legwork. Verify the destination yourself.

What to Copy and What to Leave

Open that Claude folder and you’ll find far more than sessions. Most of it is cache, crash logs, GPU state, and machine-specific scratch that regenerates on its own. Copying it doesn’t help and can actively cause conflicts.

Bring these:

local-agent-mode-sessions is the whole reason you’re here. Your Cowork session history.
claude_desktop_config.json holds your MCP server configuration. Lose it and every connector gets set up again from scratch. This is the one people don’t realize they needed until it’s gone.
claude-code and claude-code-vm carry Claude Code settings and VM data, if you use it.
vm_bundles for Claude Code VM bundles.
ChromeNativeHost for the Claude in Chrome integration.
config.json and cowork-enabled-cli-ops.json for general app and Cowork settings.
git-worktrees.json if you run Claude Code against git worktrees.
pending-uploads if anything is sitting in it.

Leave IndexedDB alone. It stores app state tied to your current signed-in session, and the new machine builds its own. Overwriting it invites problems you’ll spend an evening diagnosing.

Also grab C:\Users\<username>\.claude\ on the old machine. That’s a separate folder outside the sandbox, holding configuration and skills, and it goes to the same place on the new profile.

Zip It on the Old Machine

Rather than dragging ten items across a USB drive and hoping you got them all, package them once. Quit Claude Desktop completely first. Not the window, the app. Right-click the tray icon and choose Exit. Zipping live data files is how you end up with a corrupted history and no idea why.

Then, in PowerShell, substitute your own package ID into the first line and run this:

$Claude = "$env:LOCALAPPDATA\Packages\Claude_<packageid>\LocalCache\Roaming\Claude"

$Items = @(
  "local-agent-mode-sessions",
  "claude-code",
  "claude-code-vm",
  "vm_bundles",
  "ChromeNativeHost",
  "pending-uploads",
  "claude_desktop_config.json",
  "config.json",
  "cowork-enabled-cli-ops.json",
  "git-worktrees.json"
) | ForEach-Object { Join-Path $Claude $_ } | Where-Object { Test-Path $_ }

Compress-Archive -Path $Items -DestinationPath "$env:USERPROFILE\Desktop\claude-migration.zip" -CompressionLevel Optimal

The Where-Object { Test-Path $_ } line quietly skips anything you don’t have, so you can run it as-is whether or not you use Claude Code.

One detail that makes the other end easy: the archive stores paths relative to the items you named, not their full absolute paths. local-agent-mode-sessions\ and config.json land at the root of the zip. The archive is effectively a snapshot of the Claude folder itself, which means unpacking it is a single step with nothing to rearrange.

Then package the profile folder separately, since it lives elsewhere:

Compress-Archive -Path "$env:USERPROFILE\.claude" -DestinationPath "$env:USERPROFILE\Desktop\claude-dotfolder.zip"

Two zips on your desktop. Move them however you like: USB drive, OneDrive, network share.

If Compress-Archive throws a path-length error, that’s the 260-character Windows limit biting, and it’s plausible here given how deep the sandbox path already runs before your session UUIDs even start. Enable long paths in Windows, or fall back to robocopy with the /E switch to stage the folders somewhere shallow like C:\ClaudeMigration\ first, then zip from there.

Unzip It on the New Machine

Install Claude Desktop, sign in, and open Cowork once. This creates the directory structure you’re about to unpack into. Then quit completely again.
Find the package path on this machine. Run the same Get-ChildItem search from earlier. The package ID can differ between installs, so confirm rather than assume.
Unpack straight into the Claude folder. Because the archive is relative to that folder, everything lands where it belongs on its own:

$Target = "$env:LOCALAPPDATA\Packages\Claude_<packageid>\LocalCache\Roaming\Claude"

Expand-Archive -Path "$env:USERPROFILE\Desktop\claude-migration.zip" `
               -DestinationPath $Target -Force

-Force overwrites files that already exist and leaves everything else untouched. The only collisions are the config files the fresh install generated a minute ago, and replacing those with yours is the entire point.

Restore the profile folder:

Expand-Archive -Path "$env:USERPROFILE\Desktop\claude-dotfolder.zip" `
               -DestinationPath "$env:USERPROFILE" -Force

Restart Claude Desktop. Your old sessions should appear in the sidebar.
Reconnect your workspace folders. These are machine-specific paths and won’t follow you. Copy your project files first, then point Cowork at their new locations.
Reinstall plugins that rely on local MCP servers. Cloud-only plugins come across with your account.
Keep the old machine intact until you’ve verified all of it. Open a few migrated sessions, confirm your connectors work, and only then wipe.

The Same-Account Assumption

Everything above assumes one thing that’s easy to overlook: the Windows username is identical on both machines. When it is, every path inside those session files still resolves and the unpack just works.

When it isn’t, you have a problem the zip won’t solve. Sessions store absolute local paths, so C:\Users\OldName\Documents\... follows you onto a machine where no such user exists. The files arrive fine. The references inside them point at nothing.

If your usernames differ, this is the one case that needs an extra stop. Unpack to a scratch folder instead of straight into the target, run a find-and-replace across the JSON and JSONL files inside the extracted sessions to swap the old profile path for the new one, verify a single session opens correctly, and only then copy the corrected folders into place. Apply the same scrutiny if anything else moved, a different drive letter, a relocated Documents folder, OneDrive redirection that was on before and off now. Any of those breaks the same assumption in the same way.

Setting expectations honestly here: migrated sessions may land as readable history rather than fully resumable conversations. You get the record of what was discussed and decided, which is the part that took months to accumulate. Whether Cowork lets you pick up where you left off is a separate question, and one worth testing with a single session before you count on it for all of them.

With AI, Every How-To Has an Unknown Expiration Date

Everything above is a workaround for a design that’s already being replaced. That much is normal. What’s different now is that nobody can tell you when the replacement lands.

Software used to telegraph its changes. Version numbers, release notes, deprecation warnings, a beta period where the community wrote up what moved. A how-to written against version 4 stayed true until version 5, and version 5 announced itself. You could read a three-year-old post, check the version in the header, and know within seconds whether it still applied.

AI tools don’t work that way. They ship continuously, the client updates itself, and the thing you’re actually interacting with changes underneath a version number that may not move at all. Storage locations migrate. Local features become account features. The answer that was correct on Tuesday is wrong on Thursday, and nothing announces it. There’s no header to check.

Which is exactly what’s happening to this article. With sessions running remotely and tied to your account, the machine stops being where the work lives and becomes just a window onto it. Sign in anywhere and your history, your projects, and your scheduled tasks are already present. No folder to find, no zip to move, no package sandbox to go spelunking in. For anyone starting fresh today, this is already unnecessary.

That’s the right direction, and worth saying plainly rather than grumbling about the transition. Local-first storage bought you privacy and offline access at the cost of making your work a hostage to one piece of hardware. Account-first storage trades that the other way. Reasonable people weigh those differently, but nobody has ever been glad their context was trapped on a laptop with a failing battery.

The catch is the seam, and seams are always where the work is. Tools in transition leave a cohort stranded on the old model, holding data in a format the new model doesn’t automatically reach for. That cohort is anyone who adopted early, which is to say the people with the most accumulated context and the most to lose. Migration guides exist for the gap between what a tool used to be and what it’s becoming.

So treat this one, and every AI how-to you find, as perishable goods with no date stamped on the carton. Verify the path before you trust the instructions. If the folder isn’t where the article says it is, the article is probably older than the software. That will be true of this post eventually, and I can’t tell you when. Neither can anyone else. Until then, somebody has to move the boxes.

What This Actually Costs You

A little perspective on why any of us write these things down.

My first how-to post, back in 2002, was about building web services with Apache Axis. Working it out took the better part of two days: documentation that assumed you already knew the answer, examples that didn’t compile, and a long stretch of staring at a stack trace. The post that came out of it took a reader about twenty minutes. Two days of my confusion, compressed into twenty minutes of somebody else’s afternoon.

This one took about an hour of prompting and probing with Claude. It should take you fifteen minutes. Ten, if you run this post through an AI and ask it to strip out all my digressions, which I’d encourage, though I’d like it noted that the digressions are the part I enjoy.

The ratio held. It’s just faster on both ends now.

Fifteen minutes, then, against rebuilding context that took months to accumulate. That’s the entire calculation, and it’s the same calculation behind every unglamorous piece of groundwork in this business. Nobody gets excited about verifying a folder path. Everybody gets excited about the new laptop. The gap between those two feelings is where work disappears.

The broader lesson has nothing to do with Claude. Any tool you’ve spent real time training to your context is holding state somewhere, and “somewhere” is rarely where the marketing implies. Before you decommission a machine, ask what the tools on it know that the files don’t. Then go find out where they keep it.

Then wipe the old laptop. Not before.

If you found this interesting, please share.