DEV Community: Tony

If AI Can Write the Code, Where Do Software Developers Create Value?

Tony — Fri, 30 Oct 2026 03:16:51 +0000

I started writing code in 2009. Over the years, I've spent entire days solving problems, reading documentation, trying different approaches, and debugging until I finally understood what went wrong. Some systems took months to build and years to mature.

Now, with AI coding agents, I can describe a requirement and get hundreds of lines of code back in minutes. Work that once took several days can sometimes reach a working first version in an afternoon. AI can also read a codebase, write tests, explain errors, and propose changes across multiple files.

This has changed what it feels like to be a software developer. Skills that once took years to develop can now be applied with considerable assistance from AI. I suspect this is part of why some developers feel unsettled. When a large part of your professional work can suddenly be done much faster, where does that leave your value?

I want to approach this question from the economics of the software industry, using a familiar concept from business strategy: the value chain.

One thing worth remembering is that even before AI, writing code was only one stage of building and selling software. We spend years getting better at that stage, so it's understandable that we sometimes see the entire product through the work we do ourselves.

1. How Does a Software Product Create Value?

Imagine you're building inventory and sales management software for small retailers.

Before writing anything, you need to understand the problems these businesses face. Maybe they manage inventory in spreadsheets, struggle to track which products are still in stock, or have trouble reconciling orders across multiple sales channels.

You study how they operate, identify which problems matter most, decide what the software needs to do, and design a solution. Only then do you start coding.

And when the code is written, there is still plenty of work left.

The software needs testing, deployment, maintenance, and data protection. You need to find customers, help them get started, handle support requests, and improve the product based on how people actually use it.

If you can't find customers, the product might never generate revenue. If users can't figure out how it works, even a feature-rich application can be abandoned. If the system constantly breaks, customers may leave despite the quality of its original implementation.

Coding is an important link in a much longer chain.

Figure 1. The software value chain, from market research and design through development, distribution, operations, and customer retention. Coding is highlighted to show where it fits in the overall process.

In Michael Porter's Value Chain framework, a business is understood through a set of connected activities, from creating a product and getting it to customers to providing service afterward. Competitive advantage comes from how a company organizes these activities, manages costs, and creates value that customers are willing to pay for.

Applied to software, this helps separate three concepts that are often confused.

Use value is the practical benefit the software provides. Good inventory management software might reduce losses, save employees time, and help a retailer make better purchasing decisions.

Economic value created concerns the benefits a solution produces relative to the resources required to deliver it. A piece of software might generate benefits far greater than its development cost.

Value captured by the business is the portion of those benefits the company can turn into revenue and profit, accounting for costs, competition, and market conditions.

These concepts are closely related, but they aren't interchangeable.

An engineer might build an extremely sophisticated system that demonstrates exceptional technical skill. Yet if it doesn't solve an important problem or reach the right customers, the economic return may be small.

Meanwhile, a simple application with only a handful of features can become a successful business if it solves the right problem, is easy to use, and has an effective way to reach customers.

There are certainly products where deep technical capability is the main source of differentiation. Databases, infrastructure systems, security software, and applications with demanding reliability requirements are obvious examples.

There is no universal formula for calculating what percentage of a software product's value comes from coding.

What matters is recognizing that technical difficulty and the ability to capture economic value are separate things to evaluate.

2. Three Software Business Models, Three Ways to Create and Capture Value

The software industry has many business models. I'll focus on three familiar ones: software outsourcing, software products, and Software as a Service (SaaS).

All three require software development capabilities. But their revenue models, cost structures, and profit drivers differ considerably.

Figure 2. The value chains of software outsourcing, software products, and SaaS. Different activities matter more for creating and capturing value in each model.

Software Outsourcing: Selling Delivery Capability

In outsourcing, the customer usually already has a business need or a project they want delivered. A software company provides the people, expertise, and processes required to build the solution under a contract.

Suppose a company takes on an $80,000 project to build an internal management system over six months.

It needs to plan staffing, engineering costs, project management, testing, support, and potential risks.

Coding may account for most of the direct engineering hours. But the company's profit also depends on winning the contract, negotiating a reasonable price, estimating the work accurately, controlling scope, allocating people effectively, and maintaining quality.

A company can have excellent developers and still lose money if it consistently underestimates projects, fails to control changing requirements, or spends too much time fixing defects.

In this model, programming expertise is an important production resource. The ability to organize that resource and deliver contracts effectively determines how much revenue the company can turn into profit.

Software Product: Selling Software You Own

In the software product model, a company researches, builds, owns, and commercializes its own software.

Consider a company developing accounting software for small businesses. It needs to understand customer needs, build the right features, choose a pricing model, distribute the software, and provide support.

Once the product is ready, the company can sell the same software to many customers without rebuilding it from scratch for every buyer.

This is one of the important economic advantages of software products.

The initial development cost may be high, but the cost of delivering another copy is often relatively low compared with physical goods. Operating, supporting, updating, and distributing the software still costs money, of course.

Here, intellectual property ownership, product-market fit, brand, and distribution become especially important.

You might own the source code for an excellent application, but that doesn't guarantee people will buy it. Customers still need to discover the product, trust it, and have a reason to choose it over available alternatives.

SaaS: Selling Value Continuously

SaaS shares many characteristics with the software product model, but its business depends more heavily on delivering an ongoing service, usually through subscriptions.

Imagine a task management SaaS priced at $8 per month.

With 1,000 paying customers, that produces $8,000 in monthly recurring revenue before adjustments.

But maintaining that revenue requires reliable infrastructure, customer support, ongoing product improvements, and enough value to convince users to keep paying.

If customers use the product for a month and then leave, the company may struggle even with a healthy number of new signups.

If customers stay for years, the initial acquisition cost can be spread across a longer relationship, potentially improving the economics of the business.

This is why SaaS companies pay close attention to metrics such as Customer Acquisition Cost (CAC), churn rate, Customer Lifetime Value (LTV), gross margin, and Net Revenue Retention (NRR).

For SaaS, shipping the first working version is only the beginning of a much longer business process.

Looking across all three models, coding capabilities are used in different ways. Yet revenue and profit depend on the entire chain of activities.

That distinction matters when we consider how AI affects different software businesses.

3. How Does AI Change the Value Curve?

Another useful model for understanding the value chain is the Smile Curve, which illustrates how value added may be distributed across different activities in an industry.

In its typical form, activities near the beginning of the chain, such as research, design, and technology ownership, can generate substantial value. Activities near the end, including branding, distribution, and customer service, can also be valuable. Meanwhile, standardized production activities in the middle may face stronger price competition.

I wanted to see what this perspective might suggest about software before and after AI.

Figure 3. A conceptual model of how differentiation and value capture may shift across the software value chain. The curves represent a strategic hypothesis, not measured empirical data.

Before AI, turning requirements into working software generally required substantial specialized labor.

A company building a product needed to hire or contract developers who could write code, design systems, test functionality, and deploy applications.

Programming skills had a degree of scarcity, which gave people with those skills a meaningful advantage.

AI is changing that.

Someone who understands a product and knows how to work effectively with AI can build prototypes faster. Developers can use coding agents to generate initial implementations, add tests, refactor code, and understand unfamiliar codebases.

Repetitive technical work that can be clearly specified is becoming easier to automate. In many situations, the cost of producing a unit of software output may fall.

From an economic perspective, when a capability becomes easier to obtain, competitive advantages based mainly on its scarcity may weaken.

This is especially visible in common features such as CRUD interfaces, basic dashboards, landing pages, admin forms, and relatively standard integrations.

If many competitors can build similar features at a lower cost, customers gain more choices. It becomes harder for a business to justify high prices simply because implementation takes a lot of engineering time.

However, we should distinguish the value of coding activity from competitive advantage based on coding.

AI may increase the total amount of software being produced. Ideas that were previously too expensive to pursue may become viable. Demand for reliable, secure, maintainable software doesn't automatically disappear.

What faces greater pressure is the ability to charge a premium solely for programming tasks that tools and competitors can increasingly perform.

Competitive advantage may therefore shift toward other capabilities.

At the beginning of the chain, these include understanding an industry, identifying the right problems, designing solutions, and making appropriate architectural decisions.

At the other end, they include data, ecosystems, distribution channels, customer relationships, and the ability to deliver business outcomes that users actually care about.

AI also increases the need for verification. When code can be generated faster, companies need effective ways to ensure that systems behave correctly, remain secure, and can be maintained over time.

I think this is a reasonable way to understand the possible shift in value, although the shape of the curve will vary considerably across different types of software.

4. How Much More Productive Has AI Made Developers?

If AI can generate code in seconds, does that mean software development tasks get completed proportionally faster?

Research suggests the answer depends heavily on the task, the developer's experience, the tools involved, and the working environment.

In 2023, a study by Sida Peng and colleagues found that developers using GitHub Copilot completed a JavaScript HTTP server programming task 55.8% faster than developers without it.

That is a significant result, but it was measured on a particular task in an experimental setting.

McKinsey also published research in 2023 showing that generative AI could substantially reduce the time required for certain development activities, including code generation, documentation, and refactoring. The improvements varied according to task complexity and developer experience.

Then, in July 2025, METR published a controlled experiment involving 16 experienced developers working on 246 tasks in open-source projects they already knew well.

The result was surprising: under the conditions of that experiment, developers allowed to use AI took approximately 19% longer to complete their tasks.

Interestingly, those developers still felt that AI had made them faster.

In February 2026, METR published a follow-up. The researchers observed signs that newer tools were improving productivity, but limitations involving participant selection and measurement prevented them from making a reliable estimate of the speedup.

I don't think these findings contradict the experience of watching AI produce code incredibly quickly.

They remind us that generating code is only one part of completing a software development task.

A developer still needs to understand the existing system, evaluate the impact of a change, verify the logic, handle errors, integrate the implementation, and make sure it can be deployed safely.

Google's 2025 DORA report, drawing on a survey of nearly 5,000 technology professionals and qualitative research, makes an important observation: AI tends to amplify an organization's existing capabilities.

Teams with strong engineering practices, platforms, and processes are generally better positioned to make effective use of AI.

In an analysis published in March 2026, DORA also highlighted how time saved during code creation can shift into reviewing, evaluating, and verifying the result.

A change generated quickly but difficult to review, poorly tested, or likely to break production may not improve the efficiency of the development process as a whole.

This is why I think we should measure the time from identifying a need to delivering a stable, valuable solution, rather than measuring code generation speed alone.

Figure 4. AI may reduce code generation time, but overall productivity also depends on verification, integration, deployment, and operations.

5. Why Do Some Developers Feel Unsettled?

Becoming proficient in software engineering takes years of work.

From learning your first programming language to understanding data structures, frameworks, databases, and eventually designing complete systems, the process requires continuous practice and accumulated experience.

When someone spends most of their working life solving coding problems, it's natural for programming to become central to their professional identity.

Every difficult bug fixed, every complex query optimized, and every major system delivered reinforces that sense of competence.

But along the way, I think it's easy to confuse three things.

Difficult Work Does Not Always Have High Economic Value

A difficult algorithm may require considerable expertise to implement. But if it solves a minor problem that few people care about, the economic value created may be limited.

Meanwhile, something as simple as automated payment reminders could save a business significant manual work and improve its ability to collect outstanding payments.

Technical difficulty and business benefit are sometimes connected, but they aren't always proportional.

More Time Spent Does Not Necessarily Mean More Value

A feature might have taken us three days to build in the past.

If AI helps us build the same feature in three hours at the same level of quality, the customer may still receive essentially the same benefit.

The amount of labor has decreased while the practical value remains.

This is one of the ways technology creates productivity gains.

What changes is the production cost and the way businesses can price the work.

In a model that sells engineering hours, this creates direct pressure. In a model that sells products, lower development costs may allow a business to test more ideas or improve margins, depending on competition.

Building Something Does Not Guarantee That the Market Will Pay for It

This is something people with engineering backgrounds, myself included, need to keep reminding ourselves.

We often feel a product is nearly finished when its main features are working reliably.

But from a business perspective, it may still be at a very early stage.

Does anyone actually need it? How are they solving the problem now? Are they willing to pay? How will we reach them? Is the product good enough for them to keep using it?

Writing more code usually won't answer those questions.

AI makes the differences between these three ideas more visible.

As the time and effort required for many programming tasks decrease, we have another reason to reconsider how our work contributes to value across the whole system.

6. How the Value Curve Changes for Outsourcing, Software Products, and SaaS

Figure 5. A conceptual comparison of how competitive advantage may shift across three software business models. These curves are analytical hypotheses and cannot be used to infer each activity's share of profit.

For software outsourcing, AI may allow the same team to complete more work.

But if both the provider and the customer continue to price everything strictly by labor hours, greater productivity can create pricing challenges.

Outsourcing companies need to consider how to turn productivity improvements into profit, higher-value services, or outcome-based contracts when results can be measured appropriately.

For software products, lower initial development costs make it easier for more people to enter the market.

This creates opportunities for small teams and independent developers, but also increases the number of competing products.

When common features can be replicated quickly, owning a particular feature may offer less protection against competition.

Understanding the market, building a brand, owning intellectual property, and reaching customers become increasingly important.

For SaaS, AI can help companies build and improve products faster, including features that would previously have been too expensive to implement.

But the business still needs to retain customers, maintain service quality, and operate with a sustainable cost structure.

Costs related to AI models, inference, infrastructure, and agent operations may also change SaaS economics.

I think AI increases both the opportunities and the competitive pressure across all three models.

The ability to develop software faster doesn't guarantee that a company will make more money.

The outcome depends on whether the company can turn that productivity into customer value and competitive advantage.

7. Where Should Developers Go From Here?

I don't think every developer needs to become a founder, product manager, or business specialist.

We still need engineers with deep technical expertise, particularly for complex systems with demanding reliability requirements.

But I do think we should broaden our understanding of the work happening before and after the part we're responsible for.

Here are five areas worth developing.

1. Understand the Problem Before Choosing a Solution

When you receive a development request, spend time understanding what users actually need.

Suppose a customer asks for an order tracking dashboard.

Before choosing a charting library, ask what decisions they need to make using that dashboard.

Perhaps their real problem is identifying delayed deliveries.

In that case, a timely alert system might be more useful than a complex dashboard.

Understanding the underlying problem helps us avoid building things nobody really needs.

2. Go Deeper Into Systems Thinking and Architecture

AI can generate code, but someone still needs to take responsibility for how the components of a system work together.

It's worth developing a solid understanding of data modeling, transactions, concurrency, authorization, security, integrations, scalability, and operations.

For example, AI can generate an API that receives orders from an ecommerce platform relatively quickly.

But what should happen if the same order is submitted twice?

What if payment succeeds but the inventory update fails?

What if a request is retried after a timeout?

These are problems involving data integrity and system design.

Being able to handle them correctly creates substantial value when software is used in real operations.

3. Use AI Within a Verifiable Engineering Workflow

I believe learning to work with AI coding agents should now be part of a developer's professional development.

Beyond knowing how to assign tasks to AI, we need to provide useful context, define acceptance criteria, design tests, review changes, and evaluate results.

One practical habit is to write down the conditions for successful completion before asking AI to implement anything.

For example, when building a payment feature, the acceptance criteria might include:

Each transaction must be recorded only once.
Partial payments must not be marked as fully paid.
Repeated webhooks must not update a balance twice.
Every update must leave a trace that can be reconciled.

AI can then help write the implementation and tests, but the results still need to be verified against those conditions.

This shifts our attention from the amount of code produced to whether the system behaves correctly.

4. Understand the Business Lifecycle of Software

If you work at a software company, try to understand what happens to the product after deployment.

How do customers discover it? Why do they choose it? How much does it cost to serve one customer? Where do users tend to give up? What problems generate support requests?

If you work on SaaS, learn about CAC, churn, retention, and LTV.

If you work in outsourcing, understand how projects are estimated, priced, and managed for profitability.

You don't need to own these responsibilities yourself.

But understanding them can help you make engineering decisions that better support the business.

5. Measure Outcomes, Not Just Technical Output

A developer might complete 20 tickets in a sprint.

That's useful information for tracking work, but it doesn't tell us what those changes accomplished.

We can start connecting engineering work to more concrete results: reducing order processing time, decreasing defects, improving workflow completion rates, lowering operating costs, or improving system response times.

Of course, not every engineering task can be tied directly to revenue.

Reliability, security, maintainability, and developer experience are important outcomes too.

The goal is to understand how our work contributes to the results the product is supposed to achieve.

Figure 6. Five directions for developers to grow beyond coding execution: problem understanding, system architecture, AI engineering, product thinking, and outcome measurement.

8. So, Does Coding Still Matter?

I think it does, and I expect it will continue to matter for a long time.

But the way we apply that skill may change considerably.

Experienced developers have an advantage when working with AI because they understand systems, can evaluate proposed solutions, and can recognize mistakes that less experienced people might miss.

At the same time, AI gives people with domain expertise new opportunities to participate in software development.

Someone who understands accounting, education, business operations, or marketing may now be able to build prototypes, test ideas, and contribute more directly to developing software.

As more people gain the ability to build, those of us with technical backgrounds need to think carefully about what makes our expertise distinctive.

For some, that may mean deep specialization in distributed systems, security, data, or performance optimization.

For others, it may mean combining engineering with industry knowledge, product design, or the ability to lead complex projects.

There isn't one path that works for everyone.

Personally, I still enjoy programming.

Turning an idea into something that actually works has always been satisfying. AI makes that process even more interesting because I can experiment with things I previously didn't have enough time to build.

But the more I work with AI, the more attention I find myself paying to what should be built, why it needs to exist, what constraints must be respected, and how we can tell whether a solution is actually good.

Writing code faster doesn't answer those questions for us.

Looking at the entire value chain, I think AI presents a meaningful opportunity for developers.

We may be able to spend less time on certain implementation tasks and more time understanding problems, designing systems, verifying quality, and delivering results.

Customers ultimately pay for the problems software solves and the value it delivers. The number of lines we write is rarely what matters to them.

Coding remains one of the capabilities that helps create that value.

As AI changes how coding gets done, this seems like a good time to reconsider where our own work fits within the software value chain.

References

The following sources informed the theoretical framework and helped me examine the evidence on AI's impact. The value curves in this article are my own conceptual illustrations, not empirical measurements from these studies.

Michael E. Porter, The Value Chain, Harvard Business School, Institute for Strategy and Competitiveness.
Sida Peng et al. (2023), The Impact of AI on Developer Productivity: Evidence from GitHub Copilot.
McKinsey (2023), Unleashing Developer Productivity with Generative AI.
METR (2025), Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity.
METR (2026), We are Changing our Developer Productivity Experiment Design.
Google DORA (2025), State of AI-assisted Software Development.
Google DORA (2026), Balancing AI Tensions: Moving from AI Adoption to Effective SDLC Use.

What Actually Belongs in CLAUDE.md?

Tony — Wed, 28 Oct 2026 14:00:00 +0000

I’m Tony. I build and run web products, and I use Claude Code as my main development tool every day. A common problem with coding agents starts when an instruction file grows every time the agent makes a mistake. You add an architecture rule, then a testing reminder, then a preference about formatting, and eventually CLAUDE.md contains permanent policies mixed with notes from tasks nobody remembers.

The problem isn't simply that the file is long. It's that different instructions have different lifetimes, scopes, and purposes, yet we ask the agent to treat them as one document. In this article, I'll show you how I separate project rules, reusable procedures, and temporary task instructions. You'll leave with a minimal Claude Code configuration, a reusable Skill, a task brief template, and a way to test whether the arrangement actually works.

This is the second article in Making Coding Agents Reliable, a series about building, verifying, and maintaining software with coding agents. The article on trusting code you didn't write in this series focuses on verification. Here, we'll focus on the configuration that guides the agent before it starts making changes.

More instructions do not automatically produce better behavior

Consider a TypeScript monorepo with an administrative web application, a multi-tenant API, and two shared packages. The team uses pnpm, enforces tenant isolation in the API, and maintains reusable components separately from application code. These constraints matter, but they don't all need to appear in every instruction the agent reads.

A developer might start with three useful lines in CLAUDE.md and keep adding more whenever an output looks wrong. An unsuccessful component change produces a rule about UI reuse. An incomplete API test produces another testing reminder. Eventually, the file contains instructions that overlap or contradict each other.

For example:

- Always create a separate component for new features.
- Reuse existing components whenever possible.
- Never modify shared components without approval.
- Keep component implementations as small as possible.
- Follow the approach used in the previous reporting task.

These statements don't establish a consistent decision process. The first two can conflict, while the final instruction refers to a task that may no longer be relevant. Adding more language doesn't resolve which instruction should control the next change.

Claude Code's official guidance recommends specific, verifiable instructions and removing outdated or conflicting rules. Conflicting instructions can produce unpredictable choices. I treat this as a maintenance problem rather than something to solve by writing increasingly forceful prompts.

The useful distinction is between information Claude needs for the project, procedures it needs for certain kinds of work, and requirements that apply only to the current task.

Give CLAUDE.md a clear responsibility

I use CLAUDE.md for durable information about the repository and its development expectations. It should help Claude understand where code belongs, which boundaries matter, and what evidence the team expects before calling a change complete. It doesn't need to reproduce the architecture documentation or describe every possible workflow.

Here's the fictional repository we'll use:

.
├── CLAUDE.md
├── apps/
│   ├── admin/
│   └── api/
├── packages/
│   ├── ui/
│   └── shared/
├── .claude/
│   ├── rules/
│   └── skills/
└── docs/
    └── architecture.md

A minimal root CLAUDE.md could look like this:

# Project Instructions

## Repository

TypeScript monorepo managed with pnpm.

- apps/admin: administrative web application
- apps/api: multi-tenant backend API
- packages/ui: reusable UI components
- packages/shared: shared types and utilities

## Boundaries

- Keep application logic inside its application.
- Shared packages must not import application code.
- Check affected consumers before changing public contracts.
- Preserve existing behavior outside the requested scope.

## Workflow

Before editing:
- Identify affected packages.
- Read the relevant implementation and tests.
- Identify assumptions that affect the change.

Before reporting completion:
- Run relevant available checks.
- Report executed commands and their results.
- State which checks were not run.
- Summarize changed behavior and remaining risks.

## Verification

API tests: pnpm -F api test

## References

Architecture: docs/architecture.md

The template establishes useful boundaries without prescribing every implementation step. It also gives the agent a concrete verification command and a reporting contract. The example assumes the API package is named api in its package.json and defines a test script.

Claude Code supports several instruction locations:

Location	Responsibility
`~/.claude/CLAUDE.md`	Personal instructions across projects
`./CLAUDE.md`	Shared project instructions
`./.claude/CLAUDE.md`	Alternative shared project location
`./CLAUDE.local.md`	Personal instructions for one project
Managed policy file	Organization-managed instructions

Commit shared project instructions so changes can be reviewed. Keep CLAUDE.local.md out of Git by adding it to .gitignore. When Claude Code launches, it loads applicable instruction files in the working directory and its parents, while instructions in subdirectories load when Claude accesses files there.

These files accumulate in context rather than overriding one another. That means a personal preference and a project rule can both appear, even when they disagree. Avoid using multiple files to express competing versions of the same requirement.

Keep area-specific rules out of the root

Tenant isolation is essential for our API, but it doesn't need to accompany every frontend task. Claude Code supports path-scoped instruction files in .claude/rules/. A file with paths frontmatter loads when Claude reads or edits a matching file.

Create .claude/rules/api.md:

---
paths:
  - "apps/api/**/*.ts"
---

# API Rules

- Resolve the authenticated tenant before
  accessing tenant-owned data.
- Scope tenant-owned queries to that tenant.
- Validate authorization before accepting
  a tenant identifier from request input.
- Add tests for authorized and denied access.
- Test cross-tenant access boundaries.

For UI conventions, create a separate file with paths such as packages/ui/**/*.ts and packages/ui/**/*.tsx. Rules without paths frontmatter load at launch, so adding a file to .claude/rules/ doesn't automatically make it conditional. The distinction matters when you want a rule to apply only within a particular part of a monorepo.

Another option is placing CLAUDE.md directly under apps/api/. That keeps instructions near the code they govern. I would choose either approach based on how the team maintains instructions, rather than duplicating the same policies in both.

References are not the same as imports

Claude Code supports @path/to/file imports inside instruction files. Relative paths resolve from the importing file, and imports support up to four nested levels. This helps split documents into manageable files, but importing content doesn't reduce how much context gets loaded.

For a lengthy architecture document, I prefer a reference:

Architecture: docs/architecture.md

Read the relevant sections before changing
module boundaries or public API contracts.

That gives Claude a location to consult without importing the complete document into the initial instruction context. Official guidance also recommends keeping individual instruction files under roughly 200 lines. I treat that as a useful review threshold, not a reason to split one overloaded file into several files that all load together.

Move procedures into Skills

Project rules tell the agent what must remain true. A Skill tells it how to perform a particular kind of work. I use Skills for repeatable activities with recognizable inputs, defined steps, and an output that someone else can inspect.

Suppose the team regularly asks Claude to review API changes before merging. A useful review covers backward compatibility, authentication, tenant isolation, database changes, tests, and API documentation. Putting that entire procedure in the root CLAUDE.md would make Claude carry review instructions even when implementing a button.

A project Skill belongs at:

.claude/
└── skills/
    └── api-review/
        └── SKILL.md

A Skill is centered on SKILL.md, with optional metadata in YAML frontmatter. Claude can use it when relevant or when you invoke it with /api-review. Its description remains available for selection, while its full instructions load when invoked.

Here's a focused example:

---
name: api-review
description: Review API changes before merge, including compatibility, authorization, tenant isolation, migrations, tests, and documentation.
---

# API Review

Review the requested API changes.
Do not modify code, approve, merge, or deploy.

## Input

- Identify the Git base ref for comparison.
- If the base ref is missing, request it.
- Do not select a base ref without confirmation.

## Procedure

1. Identify changed API files and related packages.
2. Read relevant implementation and tests.
3. Check request and response compatibility.
4. Check authentication and authorization.
5. Trace tenant context through data access.
6. Review affected database schema changes.
7. Check relevant tests and documentation.
8. Report evidence and verification gaps.

## Output

For each finding, provide:
- Location
- Issue
- Evidence
- Potential impact
- Recommended action

Also report:
- Areas checked
- Tests executed and their results
- Checks not performed
- Unresolved assumptions

## Boundaries

- Do not change source files.
- Do not approve or merge changes.
- Do not claim a finding without evidence.

This Skill describes a review process rather than encoding the tenant isolation policy itself. The permanent requirement to isolate tenants belongs in the API rules. The Skill defines how to inspect a change against that requirement and report the evidence.

The description deserves particular attention because Claude uses it to decide whether the Skill is relevant. A description such as "Helps with code quality" says very little about when to activate it. "Review API changes before merge" establishes a clearer task boundary.

You can keep additional reference documents or scripts beside SKILL.md when the workflow grows. ${CLAUDE_SKILL_DIR} identifies the Skill directory for referencing those resources. Claude Code recommends keeping the main SKILL.md under 500 lines and moving larger reference material into separate files.

Skills also support disable-model-invocation: true when only the user should invoke them. That is useful for workflows with side effects, such as deployment. The API review example doesn't need that setting, but it still needs appropriate permissions if the workflow uses tools.

There is an important boundary here: neither CLAUDE.md nor a Skill is an enforcement mechanism. They provide instructions, not guarantees. If a team must prevent an action, Claude Code provides hooks and permissions.deny for enforcement. The article on permissions and MCP tool control in this series covers that distinction in more detail.

Keep temporary instructions close to the task

A temporary requirement shouldn't become permanent project policy merely because the agent needs to follow it carefully. Consider a task to add transaction export for administrators. It may require a date filter, pagination, CSV output, and a specific response contract.

Those requirements belong in the task brief, not in the root instructions. They describe one deliverable rather than how the repository should operate for every feature.

I use a small task-brief.md template:

# Task

## Objective

Describe the behavior to implement.

## Scope

- Allowed applications and packages:
- Files or interfaces to inspect:
- Explicit exclusions:

## Requirements

- Required behavior:
- Input and output contracts:
- Authorization requirements:
- Edge cases:

## Verification

- Tests to add or update:
- Commands to run:
- Expected observable results:

## Delivery

- Summarize implementation.
- Report executed checks.
- Identify unverified behavior.
- Do not expand scope without approval.

You can give Claude this brief directly as part of the task. If requirements change, update that task's instructions rather than continually editing CLAUDE.md. This keeps the shared configuration independent of a particular feature's progress.

The distinction becomes especially useful across multiple development sessions. Claude Code re-reads the project-root CLAUDE.md from disk during compaction, while instructions provided only in conversation can be lost. Durable repository conventions therefore need an appropriate file, while temporary work needs a task artifact that can be supplied again.

Design instructions around observable behavior

A useful instruction changes something you can inspect. "Be careful about security" doesn't establish what the agent should check. "Test cross-tenant requests using data owned by two organizations" describes a concrete verification action.

Here are examples of replacing broad preferences with testable expectations:

Vague instruction	Observable instruction
Write clean code	Follow existing module boundaries
Be careful with API security	Check authentication, authorization, and tenant scoping
Test thoroughly	Run `pnpm -F api test` and report the result
Avoid breaking changes	Identify affected API consumers before modifying response contracts
Give a good summary	List changed files, executed checks, and unverified behavior

I also avoid instructions that require the agent to claim certainty it cannot establish. Running an API test suite is useful evidence, but it doesn't prove every endpoint is secure. A review report should separate confirmed findings, unverified assumptions, and checks that weren't executed.

For our fictional API, imagine a new endpoint:

GET /reports/export

A successful response isn't enough to demonstrate correct authorization. The implementation must resolve the authenticated organization and keep its data isolated from other organizations. Tests should include an authorized request, an unauthorized request, and an attempted cross-tenant access.

This is where instruction placement and verification meet. The API rule names the invariant, the task brief defines the endpoint's behavior, and the review Skill guides the assessment. Production authorization must still be implemented and enforced by the application.

Test the setup using representative tasks

I wouldn't judge an instruction setup by asking Claude to explain the contents of CLAUDE.md. The useful evidence is what it does when working on a representative change. That includes the files it inspects, the decisions it makes, the code it changes, and the checks it runs.

For a fair comparison, prepare two documented configurations and use the same repository state and task briefs. Configuration A can use an overloaded root instruction file. Configuration B can use the minimal root file, scoped API rules, and the review Skill.

Define the evaluation criteria before running either setup:

Task	Expected evidence
Update a UI component	No API-specific review procedure for a UI-only change
Add an API export endpoint	Tenant-scoped data access and cross-tenant tests
Change an API response field	Identification of affected consumers
Review an API diff	Findings supported by file and code evidence
Complete an API change	Actual test results and explicit verification gaps

Run the tasks in separate sessions with equivalent starting conditions. Record whether the expected behaviors occurred and whether unrelated changes appeared. Don't treat a polished final explanation as evidence of correct implementation.

For the tenant isolation case, create test fixtures for organizations A and B. Authenticate as an account belonging to A and attempt to retrieve B's data through the relevant endpoint. The expected result is that the account cannot access B's records, regardless of how request parameters are constructed.

Claude Code provides /context to inspect loaded context and /memory to open memory files. Use /context while testing the scoped rules to check which instructions are available. You can use /init to generate an initial CLAUDE.md, but review its contents against your actual repository before adopting it.

For the Skill, test both positive and negative activation cases. Ask Claude to review an API diff and check whether it uses the workflow. Then ask it to explain a TypeScript type or modify an unrelated UI component and check that it doesn't invoke API review unnecessarily.

Separate activation from execution when investigating failures. If Claude doesn't select the review Skill automatically, invoke /api-review directly and evaluate the resulting procedure. If the procedure still misses required checks, the problem is no longer just Skill selection.

A comparison only becomes useful when you preserve the task, the expected results, and the actual artifacts. I wouldn't claim that a shorter configuration improves reliability by a particular percentage without controlled evidence. The immediate objective is to discover whether the instructions produce the behavior your project needs.

Maintain the configuration like code

Agent instructions deserve the same review discipline as application configuration. When the team moves a package, changes a test command, or modifies an architecture boundary, the corresponding instructions may become incorrect. A perfectly followed outdated rule can still produce the wrong implementation.

Consider moving tenant-owned data access into a different package. The original apps/api/**/*.ts glob may no longer cover the code that needs isolation rules. Someone reviewing that architectural change should also review the scoped instruction files and their tests.

I would assign clear ownership and include these checks in configuration reviews:

Does the instruction still describe the repository?
Does it belong at this scope?
Does another file express a conflicting requirement?
Can the expected behavior be observed?
Does a representative test cover the requirement?
Can the instruction be removed without losing necessary guidance?

I would also avoid adding sensitive credentials or tokens to committed instruction files. Shared configuration should describe where approved credentials come from, not contain their values. Review Skills and supporting scripts before sharing them with the team.

When an instruction repeatedly fails, investigate whether Claude received it, whether it is specific enough, and whether competing instructions exist. Fix the relevant cause rather than adding a second version of the rule. If the requirement demands a hard restriction, move that control into the appropriate enforcement mechanism.

A small starter you can adapt

The complete starter for this example has four essential artifacts:

claude-project-starter/
├── CLAUDE.md
├── skills/
│   └── api-review/
│       └── SKILL.md
├── task-brief.md
└── instruction-placement-checklist.md

Copy CLAUDE.md to your project root and skills/api-review/ into .claude/skills/. Keep task-brief.md as a template for individual tasks. Add .claude/rules/ with scoped files when your repository needs area-specific policies.

The final checklist is the decision process I use when deciding where to place a new instruction:

# Instruction Placement Checklist

1. Is this a durable repository-wide rule?
   -> Project CLAUDE.md

2. Does it apply only to specific code paths?
   -> .claude/rules/ with paths

3. Is it a repeatable, multi-step procedure?
   -> .claude/skills/<name>/SKILL.md

4. Is it specific to one deliverable?
   -> Task brief

5. Is it lengthy reference material?
   -> Documentation, read when needed

6. Is it a personal working preference?
   -> Personal CLAUDE.md or CLAUDE.local.md

7. Must the action be technically blocked?
   -> Hooks or permissions.deny

Before adding the instruction:
- Check for an existing equivalent rule.
- Remove conflicting or obsolete wording.
- Define an observable verification criterion.
- Identify who maintains it.

The goal is not to create the smallest possible collection of instruction files. It's to give every instruction a clear responsibility, scope, and way to verify its effect. A useful CLAUDE.md remains understandable because it contains project knowledge, not every procedure and reminder the team has ever written.

The next article, on context and memory in this series, examines another part of the same problem: what the agent needs to retain, what it can retrieve, and what should remain in the repository. For now, take one instruction from your existing CLAUDE.md and apply the checklist. Decide whether it describes the project, a procedure, or a temporary task, then test the behavior it is supposed to produce.

What's one instruction you added to CLAUDE.md that probably doesn't belong there anymore?

Can You Trust Code You Didn't Write?

Tony — Sat, 24 Oct 2026 23:34:34 +0000

I'm Tony. I build and run web products, and Claude Code is my main development tool. A coding agent finishes implementing a feature, reports that everything is complete, and presents a summary of the changes. The code looks reasonable, the tests appear green, and you have another task waiting. But what exactly did the agent prove?

Generating working code and verifying correct behavior are different engineering activities. I use a verification workflow that starts with observable acceptance criteria, checks the implementation at several levels, and records evidence before accepting a change. I'll walk through it using a TypeScript application with an admin interface and a multi-tenant API, including an authorization bug that ordinary tests can miss. You'll leave with a reusable verification checklist and a completed example showing what an acceptable evidence trail looks like.

A completed task is not a verified change

A coding agent can produce a convincing implementation without establishing that it solves the original problem. It might modify the right files, follow the existing patterns, and run the available tests successfully. None of those results automatically establishes that the requested behavior works. They answer narrower questions.

Consider four statements an agent might make:

Statement	What it actually establishes
"Implementation complete"	The agent produced code it considers finished.
"TypeScript compilation passed"	The compiler found no errors covered by that check.
"All tests passed"	The executed tests passed under their configured conditions.
"The requested behavior works"	Requires evidence that the implementation satisfies the acceptance criteria.

The difference matters because tests only exercise the scenarios someone anticipated. A passing authorization test might establish that a resource owner can access a document, while saying nothing about another authorized member or an unrelated tenant. A successful browser interaction might show text appearing in an editor without proving that the correct value was saved. Even a valid download can contain files with incorrect permissions.

I think of this as a verification gap. The agent's final message belongs on one side; evidence that supports the product requirements belongs on the other. My responsibility is to close that gap, not merely decide whether the generated code looks plausible.

The same distinction applies to human-written code, but agents change the amount of implementation a developer can produce without personally tracing every decision. That makes a disciplined acceptance process more important.

Start with an observable acceptance contract

Before implementation, I want a short contract describing what the system must do and how we will know it works. This is not a complete specification or an elaborate test plan. It is a set of observable behaviors that can be checked independently of the agent's explanation.

Imagine a pnpm TypeScript monorepo with the following structure:

apps/
  admin/              # React admin application
  api/                # Multi-tenant API
packages/
  ui/                 # Shared UI components
  shared/             # Shared contracts and utilities

Suppose the API serves multiple customer organizations. A resource can be associated with several groups, and users receive access through group membership. The requested change is to correct a permission check that incorrectly rejects some authorized users.

Here is the acceptance contract I would give the agent:

Task:
Correct group-based access to shared resources.

Expected behavior:
1. A member of any group attached to a resource
   can access that resource within the same tenant.
2. A user outside all attached groups is denied.
3. A user from another tenant is denied, even when
   group identifiers overlap.
4. Existing resource-owner access remains unchanged.

Evidence required:
- Focused authorization tests for all four cases.
- A regression test where the authorized user
  belongs to the second attached group.
- Confirmation that the regression test fails
  without the fix and passes with it.
- A summary of changed files and remaining risks.

Constraints:
- Preserve tenant isolation.
- Do not change unrelated authorization behavior.
- Do not modify tests merely to make them pass.

This contract specifies results rather than implementation details. I have not instructed the agent to use a particular SQL query, ORM method, or function structure. It can choose an approach that fits the existing code, but it cannot redefine successful completion as "the code compiles."

The edge cases carry much of the value. Testing an owner and an unauthorized stranger is insufficient when access depends on several relationships. The important case is a user who belongs to a valid group that the previous implementation failed to consider.

For a bug fix, I also provide the reproduction command, relevant stack trace when one exists, and steps needed to reproduce the behavior. I state whether the failure is intermittent. These details reduce guesswork and give the agent a concrete starting point.

The principle is simple: define success before evaluating the implementation. Otherwise, the agent's solution can influence what everyone considers an acceptable test.

Ask the agent to implement, not declare victory

I separate implementation instructions from acceptance decisions. The agent can inspect the repository, propose a solution, edit code, and execute tests. It can also identify missing cases and explain technical tradeoffs. But I do not treat its final assessment as independent evidence.

For changes with unclear scope, I start Claude Code in plan mode:

claude --permission-mode plan

Plan mode lets Claude read the project and propose an approach without editing files until approval. I use that boundary to examine assumptions, identify impacted modules, and check whether the proposed tests cover the acceptance contract. The plan is useful because it exposes decisions before implementation makes those decisions harder to notice.

For the authorization example, I might use this prompt:

Inspect the shared-resource authorization flow.

Identify:
- How resources are associated with groups.
- Where tenant isolation is enforced.
- Which tests cover users with multiple group paths.
- Why membership in the second attached group fails.

Propose the smallest safe change and the tests
needed to verify it. Do not edit files yet.

After reviewing the proposal, I authorize implementation and ask for a report containing the actual commands and outcomes. I also ask the agent to identify missed edge cases. This makes the agent useful as an implementation partner without making it the final authority on correctness.

An instruction in CLAUDE.md can require the agent to include test evidence in its response. That is a useful working convention, not an enforcement mechanism. The presence of a well-formatted report does not prove that the underlying evidence is valid.

If the change moves in the wrong direction, Claude Code's /rewind can restore the conversation and code to a checkpoint. That helps manage the implementation process, but it does not replace version control or acceptance testing.

Verify at different levels

Verification works better when each check has a specific responsibility. Compilation, automated tests, browser interactions, and human review observe different properties of the system. Running more checks is not automatically better; choosing checks that cover different failure modes is what matters.

Static checks: Is the change structurally valid?

I start with the checks already defined by the repository. For a TypeScript project, these typically include type checking, linting, and build validation. They reveal broken imports, incompatible types, invalid code patterns, and some integration mistakes.

For example:

pnpm -F api exec tsc --noEmit

This command only makes sense when the workspace and TypeScript configuration support it. A successful result tells me that the relevant TypeScript checks passed. It does not establish that group membership is evaluated correctly or that the API returns the expected authorization decisions.

I record which command ran, its exit status, and whether the check covers the changed code. "Static checks passed" is less informative than the exact command and result.

Focused tests: Does the behavior match the contract?

Consider this incorrect permission check:

const group = await db.resourceGroup.findFirst({
  where: {
    resourceId,
  },
});

const allowed = group
  ? await isGroupMember(userId, group.groupId)
  : false;

The implementation checks membership against the first group returned by the database. If a resource belongs to groups A and B, a user belonging only to B can be denied access. The code compiles, and a test using a member of A might pass.

The correction should ask whether there is at least one qualifying membership, not whether the user belongs to one arbitrarily selected group. One possible approach is a relational query that keeps the tenant condition within the authorization predicate:

const allowed = await db.resourceGroup.count({
  where: {
    resourceId,
    resource: {
      tenantId,
    },
    group: {
      tenantId,
      memberships: {
        some: {
          userId,
        },
      },
    },
  },
}) > 0;

The exact query depends on the application's data model and ORM schema. Its essential property is that it evaluates all eligible relationships while preserving tenant boundaries. The surrounding authorization flow must still validate the user's tenant context and any additional access rules.

The regression test is more valuable than a generic "authorized user succeeds" test:

it("allows a member of the second attached group", async () => {
  const resource = await createResource({
    tenantId: tenantA.id,
    groupIds: [groupA.id, groupB.id],
  });

  const user = await createUser({
    tenantId: tenantA.id,
    groupIds: [groupB.id],
  });

  const response = await requestResource({
    resourceId: resource.id,
    asUser: user,
  });

  expect(response.status).toBe(200);
});

Here, createResource, createUser, and requestResource represent application-specific test helpers. A real implementation should use the repository's existing fixtures and request utilities, with deterministic setup that makes the relevant group ordering explicit.

Regression proof: Does the test detect the original bug?

A passing test is useful. A test that fails against the broken implementation and passes against the correction provides stronger evidence that it detects the intended defect.

One way to perform this check in a controlled working tree is:

git stash push src/auth/permissions.ts
npm test -- permissions
git stash pop

This sequence assumes the working-tree state, stash contents, and test command have been inspected first. The stash must actually restore the known broken implementation for the test to mean anything. It can also stash other uncommitted edits in the named file, so I would use a clean, isolated working tree rather than run it casually against active work.

Notice another operational detail: combining the test and restore operations with ; allows the restore attempt to run even if the test fails. With three separate commands, I must explicitly execute the restoration after the expected failure and inspect the resulting working-tree state.

The evidence I want is specific: the regression test fails for the expected authorization reason without the fix, then passes with the correction restored. A failure caused by missing fixtures, invalid imports, or environment setup is not proof that the regression test detects the original bug.

The repository might use pnpm instead:

pnpm -F api test -- permissions

I use the command that matches the actual project rather than changing package managers simply to match an example.

Browser checks: Does the user see the correct result?

API tests do not establish that the browser handles state correctly. A common case is automation entering text into a rich-text editor built with DraftJS-style or React-managed state. The text becomes visible, but the application saves a default value because the submitted content lives in parent component state.

A screenshot of the editor would look correct while the saved record would be wrong. The appropriate fix is to update the value through the component's supported onChange mechanism, then save and read back the persisted content. The verification target is the reopened or fetched record, not merely the visible text before submission.

For the authorization example, a browser check can establish that an authorized member can open the shared resource and an unauthorized member receives the intended denial. That user-facing result complements the API tests without replacing them.

I cover browser automation patterns in more detail in the article on browser testing with Playwright in this series.

Human review: Does the behavior make sense?

Automated checks can establish consistency with written expectations. They cannot decide whether those expectations fully reflect the product's intended policy. A developer still needs to evaluate whether the change introduces unintended access, violates an architectural boundary, or relies on an assumption the tests never challenge.

For authorization code, I examine query scoping, user identity, tenant ownership, and any caching that might retain stale permissions. I also look for inconsistent behavior between endpoints using the same permission model. Those concerns are part of engineering review, not defects a green test suite automatically rules out.

Review the diff against the original intent

After executing the checks, I return to the original acceptance contract and inspect the actual diff. The question is not simply whether I understand the implementation. I want to know whether every change serves the requested behavior.

For the authorization fix, the intended scope is narrow: correct membership evaluation and add meaningful coverage. A change that also modifies authentication middleware, restructures tenant resolution, or removes failing assertions deserves separate justification. Scope expansion increases the number of assumptions I need to verify.

My diff review focuses on five questions:

Which behavior changed? Identify the precise condition that produces a different result.
Which files changed, and why? Look for unrelated formatting, generated files, or dependency updates.
Which assumptions did the implementation introduce? Check group ordering, nullable relationships, tenant context, and error handling.
Which failure paths remain untested? Consider cross-tenant requests, absent memberships, deleted groups, and resource ownership.
Did the tests become weaker? Look for removed assertions, permissive mocks, skipped cases, or fixtures changed to avoid failures.

Another useful example is generating a downloadable ZIP package. The download can succeed, contain the correct files, use the expected version, and pass a secrets check. Yet its setup script might lose the executable bit because the ZIP library does not preserve Unix file modes.

After extraction, this result is wrong:

-rw-r--r-- scripts/setup.sh

Running the script directly produces:

./scripts/setup.sh: Permission denied

For a package where scripts are expected to run directly on Unix, a packaging rule can assign mode 0755 to files beginning with #! and 0644 to ordinary files. Verification should then inspect the extracted archive, not just the source directory.

The expected extracted permission is:

-rwxr-xr-x scripts/setup.sh

This example demonstrates why a passing pipeline can still miss an important delivery requirement. The implementation artifact must be checked in the form and environment where someone actually uses it.

Give every result an evidence trail

I prefer a compact verification report over a long transcript of everything the agent attempted. The report should let another developer understand the requested behavior, identify the executed checks, reproduce important results, and see what remains uncertain. It should also distinguish the agent's statements from recorded observations.

The following is a completed example for our fictional authorization fix. The paths and outcomes illustrate what a report should contain; they are not claims that these commands were executed against a real repository.

agent-change-verification.md

# Agent Change Verification

## Task
Correct group-based access to shared resources.

## Acceptance criteria
- [x] Member of any attached group is allowed.
- [x] Nonmember is denied.
- [x] User from another tenant is denied.
- [x] Existing owner access remains unchanged.

## Files changed
- src/auth/permissions.ts
  Replaced first-group lookup with membership query.
- src/auth/permissions.test.ts
  Added second-group and tenant-isolation cases.

## Checks executed

| Check | Result | Evidence |
|---|---|---|
| TypeScript check | PASS | typecheck.log |
| API permission tests | PASS | permissions-test.log |
| Regression without fix | EXPECTED FAIL | regression-red.log |
| Regression with fix | PASS | regression-green.log |
| Focused diff review | PASS | review-notes.md |

## Expected vs observed
Expected:
A user in group B can access a resource shared
with groups A and B within the same tenant.

Observed:
The API returns 200 for the group B member.
The regression test fails with the original
first-group logic and passes with the fix.

## Unverified scenarios
- Concurrent group membership changes.
- Cache invalidation after permission updates.
- Browser-level permission error presentation.

## Known limitations
- Tests use a local test database.
- Production data distribution was not reproduced.
- No performance evaluation of the new query.

## Human review decision
APPROVED FOR REVIEW, NOT DEPLOYMENT.

Reason:
Acceptance tests pass and regression behavior
is demonstrated. Query execution characteristics
and cache behavior require separate review.

The report does not need to claim absolute confidence. Its value comes from making the evidence inspectable and showing where the evidence stops. In a real repository, the referenced logs and review notes should exist, correspond to the tested revision, and be accessible to the reviewer.

I find it useful to rank evidence by what it establishes:

The agent says the task is complete.
A command executes without error.
Relevant tests pass.
A regression test fails without the fix and passes with it.
The resulting behavior is read back from the system where the user actually encounters it.

This is an ordering of evidence strength, not a replacement for evaluating test quality or requirement coverage. A read-back confirms a particular observed result; it does not establish that every untested condition is safe.

For write operations, I like tools that return both verified and evidence. The first indicates whether post-action verification succeeded. The second explains what the system returned when the tool read the result back.

For example:

{
  "operation": "deleteResource",
  "verified": true,
  "evidence": {
    "method": "GET",
    "path": "/resources/example-id",
    "status": 404
  }
}

In this example, the write tool deleted a resource and then performed a separate read. A successful delete request alone would not provide equivalent evidence. The observed 404 supports the claim that the resource is no longer retrievable at that endpoint, assuming the read uses the appropriate identity and tenant context.

For pull requests, I can use gh pr create to connect a Claude Code session with a PR and reopen that session using claude --from-pr <number>. The PR then becomes a practical place to review the diff, attach test evidence, and ask Claude to flag risks. The review decision still belongs to the people responsible for accepting the change.

Know when the workflow is insufficient

A verification checklist helps make acceptance consistent, but it cannot compensate for missing requirements or an environment that fails to represent production behavior. Authorization, billing, data migration, destructive operations, and sensitive-data handling deserve closer attention because incorrect behavior can have consequences beyond a single feature.

Weak test coverage also changes how much confidence I assign to a passing suite. If the application has no realistic integration environment, no tenant-isolation fixtures, or no way to inspect persisted changes, the verification report should say so. The correct response is to identify the missing evidence, not lower the acceptance criteria until everything appears green.

I also separate new failures from existing failures. If an unrelated test was already failing, I do not edit it, skip it, or change its expectations just to produce a green result. I document the failure in the PR, explain why it appears unrelated, and leave the decision visible to reviewers.

Some decisions remain fundamentally human. Whether two groups should share access to a sensitive resource is a product and security policy question before it is a query implementation question. An agent can implement the stated rule and test that implementation, but the team must decide whether the rule is correct.

The workflow I use is therefore not "make the agent pass every check." It is to define observable expectations, collect independent evidence, review the change against its intent, and explicitly record what has not been established. That process makes code written by an agent easier to understand, verify, and maintain.

This is the foundation of Making Coding Agents Reliable, a six-article series about practical workflows for working with AI coding agents. The next article covers CLAUDE.md and Skills, including how to make project instructions useful without confusing instructions with enforcement.

What's the one check you never skip before accepting an AI-generated change?