How Claude Code Turns Ambiguity into Engineering Work

Claude Code is most useful when a request involves more than producing a plausible snippet. This chapter follows the feature-development workflow in the repository to ask a narrower question: how can an agent move from an underspecified request to a change that someone has chosen, reviewed, and verified? The answer is a sequence of gates. Questions, repository exploration, design comparison, approval, review, and verification each remove a different kind of uncertainty.

Questions before architecture

A short request often hides several decisions. “Add authentication” does not say which providers matter, where user state belongs, what should happen to existing sessions, or how failures should be handled. If Claude Code begins editing immediately, it may convert those omissions into assumptions. The feature-dev plugin treats that as a workflow problem rather than a prompt-writing problem. Its first phase is discovery: clarify what needs to be built, what problem is being solved, and what constraints apply.

The next phase explores the codebase. The plugin launches two or three specialized code-explorer agents in parallel, each looking at a different aspect such as similar features, architecture, or user experience. The main process then reads the important files those agents identify. This is more than a speed trick. Parallel exploration creates several independent views of the existing system before a design is selected, while the follow-up reading keeps the final understanding attached to the actual repository rather than to an agent’s summary alone.

A generic prompt can ask for a clean implementation, but it cannot supply repository-specific facts that have not been inspected. Existing code may already have an authentication abstraction, a session lifecycle, a middleware convention, or a test pattern that changes the best design. Exploration also exposes negative information: a seemingly similar feature may depend on assumptions that do not hold in the new case. The value of codebase exploration is therefore not that it produces more files. It reduces the chance that a locally reasonable change will violate a larger system boundary.

After exploration, the plugin has a dedicated clarifying-questions phase. It asks about edge cases, error handling, integration points, backward compatibility, and performance needs, then waits for answers before architecture design. That pause is a control point. It makes an unresolved requirement visible while the cost of changing direction is still low. A question asked after implementation is often a bug report; the same question asked before implementation can be a design input.

Architecture is then treated as a choice among approaches rather than as a single answer that appears automatically. The feature-dev README describes three perspectives: minimal changes that maximize reuse, clean architecture that emphasizes maintainability and separation, and a pragmatic balance between speed and quality. The command asks the user to choose after presenting trade-offs and a recommendation. The point is not that one of these approaches is always correct. It is that the system makes the trade-off explicit and keeps the decision with the person who owns the project’s constraints.

Those approaches also expose different kinds of reversibility. A minimal change may be easy to review and quick to merge, but it can preserve coupling that makes later changes expensive. A clean separation may reduce future coupling, but it can enlarge the immediate diff and introduce more interfaces that need testing. A pragmatic design can fit the current repository while leaving some debt in place. The workflow does not remove this judgment; it packages the alternatives so the user can decide which cost is acceptable. That is a more honest role for an agent than presenting one architecture as inevitable.

sequenceDiagram participant U as User participant C as Claude Code participant X as Exploration agents participant A as Architecture choice participant R as Review agents participant V as Verifier U->>C: Request a feature C->>C: Discovery C->>X: Explore the codebase X-->>C: Findings and key files C->>U: Ask clarifying questions U-->>C: Provide constraints C->>A: Compare approaches A-->>U: Recommendation and trade-offs U->>C: Approve an approach C->>C: Implement the change C->>R: Review the result R-->>C: High-confidence findings C->>V: Verify the setup or change V-->>U: Verification results

The sequence shows why the workflow is not simply a longer instruction to “be careful.” Each transition has a different purpose. Discovery establishes the problem. Exploration supplies context. Clarification resolves missing intent. Architecture makes alternatives and ownership visible. Approval authorizes implementation. Review looks for problems in what was built. Verification checks whether the resulting project or code meets a concrete technical condition. Removing one transition changes what kind of uncertainty can remain hidden.

The transitions are not guaranteed to be one-way or perfectly clean. Exploration can uncover a constraint that sends the request back to clarification. A user can reject every proposed architecture because the feature is not yet defined well enough. Review can expose a defect that requires implementation to reopen, and verification can reveal that the chosen design does not fit the project’s actual setup. A staged workflow is valuable partly because it gives those reversals a visible place to occur. Without named stages, an agent may continue forward while silently carrying an unresolved contradiction.

The implementation phase comes only after explicit approval. The command says to read the relevant files, follow the selected architecture, use existing conventions, and implement the feature. That gate is particularly important for agentic systems because the cost of a wrong assumption is not limited to a bad paragraph. It may be a broad refactor, a new dependency, a changed permission, or a partially completed migration. Waiting for approval does not make the design correct, but it prevents the system from quietly treating its recommendation as the user’s decision.

The workflow also has a quality-review phase and a final summary. Reviewers focus on different concerns such as simplicity, correctness, and project conventions. The separate perspectives are useful because a change can be functionally correct and still violate a local rule, or be elegant and still contain a serious logic error. The final summary records what was built, the key decisions, modified files, and suggested next steps. That summary is not a substitute for tests, but it makes the change legible to the person who must maintain it.

Review and verification are different kinds of confidence

The code-review plugin makes the review gate more explicit. It first decides whether a pull request needs review, gathers relevant CLAUDE.md guidance, and summarizes the change. It then asks multiple agents to inspect the pull request from different perspectives: guideline compliance, obvious bugs, and historical context. Candidate issues receive a confidence score from 0 to 100, and the detailed documentation says that issues below 80 are filtered out by default.

A confidence threshold is a noise-control mechanism, not a truth detector. It tries to avoid flooding a developer with speculative findings, pre-existing problems, pedantic points, or issues that do not affect the change. It does not establish that every reported issue is real, that every unreported issue is absent, or that the review covers every relevant security property. The plugin itself frames the result as a starting point for human review. A high-confidence filter changes which warnings reach the user; it does not change the underlying uncertainty of model-based judgment.

The skip rules are part of that calibration. The plugin is designed to skip closed, draft, trivial, or already-reviewed pull requests, and it focuses on problems introduced by the change rather than every imperfection in the repository. That makes the output more actionable, but it narrows the question being answered. A clean result can mean “no high-confidence issue in the selected change scope,” not “the repository is secure.” The reviewer’s scope, its evidence, and its threshold must travel together whenever its result is interpreted.

The source also illustrates why evidence must stay attached to its exact wording. The detailed code-review documentation describes four review agents: two guideline auditors, one bug detector, and one history analyzer. The top-level plugin catalogue says five parallel Sonnet agents. That discrepancy does not invalidate the workflow’s broader mechanism, but it is a reason not to repeat an exact agent count as if it were stable product law. In an evolving repository, counts and model names can drift while the larger design remains recognizable.

Verification answers a different question from review. Review asks whether a change appears problematic according to selected perspectives. Verification asks whether a concrete setup or implementation condition holds. The Agent SDK development plugin makes this distinction visible. Its /new-sdk-app command gathers requirements one at a time, checks current package versions before installation, creates a starter project and environment files, and then verifies it. TypeScript projects are checked with tsc --noEmit; Python projects receive syntax and import checks. A language-specific verifier agent examines SDK usage, configuration, environment and security, error handling, functionality, and documentation.

The command also requires a fresh look at external documentation and package registries before installation. That requirement is important for a moving SDK: the repository can describe the setup process, but it cannot freeze the latest package version or every current API detail. The plugin’s own verification path therefore has two dependencies. It needs a local check that the generated project is coherent, and it needs current external information to avoid treating a snapshot’s example as the present contract. A workflow that omits either side can produce a project that is internally tidy but externally stale.

That sequence matters because scaffolding can succeed while the resulting application is still unusable. A project directory can contain the right-looking files but import the wrong package, omit an environment variable, use an outdated API pattern, or expose a credential through source control. The plugin therefore recommends .env.example, puts .env in .gitignore, and tells users never to hardcode API keys. Verification is not a final flourish added to a successful creation step. It is a separate boundary where the system tests the artifact it just produced.

There is also a difference between verifying a local condition and deciding whether the work is fit for its environment. A type checker can catch a mismatch in an interface; it cannot decide whether the interface should expose sensitive data. A security review can identify a likely injection path; it cannot by itself approve the application’s threat model. A feature workflow can obtain explicit architectural approval; it cannot remove the need for deployment testing. Each gate is valuable because it narrows one uncertainty, not because it closes every uncertainty at once.

The gates also distribute responsibility rather than eliminating it. The exploration agents are responsible for finding useful context, but the main process must read and interpret that context. The architecture stage can recommend a pragmatic approach, but the user owns the trade-off. Review agents can filter and rank findings, but a maintainer decides whether a finding is valid and what to do with it. The verifier can report a failed type check or missing setup detail, but it cannot decide whether the application is ready for a sensitive workload. Keeping these responsibilities distinct prevents an automated result from silently becoming an authorization decision.

This makes the feature-dev workflow a model of staged agency. Claude Code is allowed to explore before it changes, propose before it implements, and review after it acts. The person remains involved at the points where project intent and trade-offs matter most. The arrangement is not frictionless: questions take time, alternatives can feel excessive for a small fix, and parallel agents consume resources. The plugin itself says it is not intended for trivial changes or urgent hotfixes. Its value appears when the cost of a wrong assumption is higher than the cost of a deliberate pause.

The same reasoning helps decide when to use a workflow at all. A one-line correction may not need architecture alternatives. A feature spanning several modules, requiring a new integration, or carrying backward-compatibility risk benefits more from exploration and explicit choice. The decision should follow consequence and ambiguity, not enthusiasm for automation. Claude Code’s contribution is strongest when its process matches the shape of the problem.

The resulting lesson is practical. Questions are not a failure of intelligence; they are a way to keep missing requirements from becoming hidden implementation state. Exploration is not a delay; it is a way to ground choices in the repository. Review is not proof; it is a filtered source of additional evidence. Verification is not the same as approval; it tests a concrete condition after a choice has been made. Together, these gates turn Claude Code from a system that can act into one that can make its actions easier to inspect and contest. The next issue is how teams extend that process without confusing a new capability with a new authority.

References