Claude can write code, explain architecture, generate tests, review pull requests, and draft documentation. But the quality of those outputs depends heavily on how you structure the work.

The common mistake is one-shot prompting: giving Claude one broad instruction, such as “build a scalable authentication system,” and expecting production-ready output. That approach usually produces generic code because Claude has to infer the stack, constraints, architecture, error handling strategy, and success criteria from a vague request.

A better approach is workflow-based prompting. Instead of asking Claude to solve the whole task in one pass, break the work into stages: define the problem, design the architecture, generate implementation, review the output, test failure cases, and refine the result. This mirrors how senior engineers already work, and it turns Claude from a code generator into a guided engineering collaborator.

This article explains how to replace one-shot prompts with structured Claude workflows for architecture planning, implementation, debugging, pull request review, documentation, testing, and automation. For a broader system-level view, see LogRocket’s guide to AI-assisted development governance.

What is one-shot prompting?

One-shot prompting is the practice of giving an AI tool a single broad instruction and expecting a complete, accurate, production-ready result. In software development, it looks like this:

Build a scalable authentication system in Node.js.

That prompt may produce something that looks useful, but it is doing too much at once. It does not define the framework, persistence layer, authentication model, session strategy, security constraints, testing expectations, deployment environment, or integration boundaries.

The result is usually the most statistically common answer, not the right answer for your codebase.

What one-shot prompting gets wrong

One-shot prompting fails because it hides the actual engineering work. The model has to guess at the missing pieces:

• Which framework and project conventions to follow
• Whether to use JWTs, sessions, OAuth, or a hybrid model
• Where validation should happen
• How errors should be returned
• How refresh tokens should be stored and revoked
• What should be unit tested, integration tested, or manually reviewed
• What security risks matter in this specific system

The output may look complete, but it often breaks down when you try to integrate it into a real application.

Common failure modes include:

One-shot prompting feels productive because it is fast. But fast, shallow output can create technical debt faster than writing the code yourself.

One-shot prompting vs. workflow-based prompting

The fix is not a longer one-shot prompt. The fix is a different mental model.

Treat Claude like a collaborator moving through a workflow, not like a function that should return an entire feature from one argument. Anthropic’s prompt engineering guidance emphasizes giving Claude context, defining the task clearly, and iterating on outputs. The same principle applies to engineering work: before asking Claude to build, define what “good” means.

Workflow-based prompting is especially useful with Claude because it gives the model room to reason through structure, tradeoffs, and constraints before it writes code.

The structured Claude workflow

A reliable Claude workflow usually follows this pattern:

1. Define the role and engineering context
2. State the task clearly
3. List requirements and constraints
4. Ask for a plan before code
5. Generate implementation in small sections
6. Review the output against explicit criteria
7. Ask for fixes, tests, and documentation

Here is a reusable prompt structure:

You are a senior [role].
Context:
[Project stack, existing architecture, constraints, and relevant files]
Task:
[Specific engineering task]
Requirements:

[Functional requirement]
[Security requirement]
[Performance requirement]
[Testing requirement]

Constraints:

[Framework/library/version constraints]
[Architecture constraints]
[What not to change]

Return:

Proposed architecture
Implementation plan
Files to create or modify
Code
Tests
Risks and tradeoffs

This prompt does three important things. It defines the model’s role, gives the model the information it needs to make better decisions, and forces the output into a reviewable structure.

Workflow 1: Use Claude for architecture planning before code

Claude is strongest when you ask it to reason about structure before implementation. For larger tasks, start with architecture, not code.

For example, instead of asking:

Build a payment webhook service.

Use a structured prompt:

You are a senior backend engineer.
Task:
Design a Java Spring Boot service that processes payment webhooks.
Requirements:

Idempotency support
Retry handling
Event logging
Redis caching
REST endpoint
Unit and integration tests

Constraints:

Use PostgreSQL for durable event storage
Use Redis only for idempotency locks and caching
Do not expose JPA entities directly from controllers
Include security considerations for webhook signatures

Return:

Folder structure
Architecture overview
Data model
API contract
Error handling strategy
Testing plan
Implementation risks

This produces a better first output because Claude has to separate architecture from implementation. You can review the structure before accepting any code.

A reasonable Spring Boot webhook service might start with this structure:

payment-webhook-service/
├── pom.xml
└── src/
    ├── main/
    │   ├── java/com/payments/webhook/
    │   │   ├── WebhookServiceApplication.java
    │   │   ├── config/
    │   │   │   ├── RedisConfig.java
    │   │   │   └── WebhookProperties.java
    │   │   ├── controller/
    │   │   │   └── WebhookController.java
    │   │   ├── dto/
    │   │   │   ├── ErrorResponse.java
    │   │   │   ├── WebhookRequest.java
    │   │   │   └── WebhookResponse.java
    │   │   ├── exception/
    │   │   ├── model/
    │   │   │   └── WebhookEvent.java
    │   │   ├── repository/
    │   │   │   └── WebhookEventRepository.java
    │   │   ├── service/
    │   │   │   ├── EventLogService.java
    │   │   │   ├── IdempotencyService.java
    │   │   │   ├── PaymentEventHandler.java
    │   │   │   └── WebhookProcessorService.java
    │   │   └── util/
    │   │       └── SignatureUtil.java
    │   └── resources/
    │       ├── application.yml
    │       └── db/migration/
    │           └── V1__create_webhook_events.sql
    └── test/

At this stage, the goal is not to accept the generated application. The goal is to create a draft architecture that you can interrogate.

Ask Claude to explain its design decisions

After Claude proposes the structure, ask it to defend the design:

Review this architecture before writing code.
Explain:

Why each layer exists
Which components should be interfaces
Which responsibilities belong in each service
Where idempotency should be enforced
Which parts are risky in production
What should be tested first

This moves the conversation from “generate code” to “justify the system.” That is a much better place to start.

Workflow 2: Generate implementation in small, reviewable pieces

Once the architecture is clear, generate implementation one piece at a time. Do not ask Claude to build the controller, service, repository, DTOs, exceptions, migrations, and tests in one response.

Use staged prompts:

Implement only the webhook processing service.
Include:

Idempotency lookup
Event persistence
Retryable processing
Failure logging
Recovery behavior

Do not implement:

Controller code
Redis configuration
Database migration
Unit tests

Return:

Code
Assumptions
Risks
Tests to write next

The code below is intentionally substantial. It is the kind of output Claude may generate when it has clear requirements. The point is not that you should paste this directly into production. The point is that a structured prompt produces code with enough shape to review: you can inspect the service boundaries, retry strategy, idempotency flow, and failure states.

package com.payments.webhook.service;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.payments.webhook.dto.WebhookRequest;
import com.payments.webhook.dto.WebhookResponse;
import com.payments.webhook.exception.WebhookProcessingException;
import com.payments.webhook.model.WebhookEvent;
import com.payments.webhook.model.WebhookEvent.ProcessingStatus;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.retry.annotation.Backoff;
import org.springframework.retry.annotation.Recover;
import org.springframework.retry.annotation.Retryable;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import java.util.Optional;
@Service
@RequiredArgsConstructor
@Slf4j
public class WebhookProcessorService {
private final IdempotencyService idempotencyService;
private final EventLogService eventLogService;
private final PaymentEventHandler paymentEventHandler;
private final ObjectMapper objectMapper;
@Transactional
public WebhookResponse ingest(String idempotencyKey, WebhookRequest request) {
Optional<WebhookEvent> existing = eventLogService.findByIdempotencyKey(idempotencyKey);
if (existing.isPresent()) {
log.info("Duplicate webhook received key={}", idempotencyKey);
return WebhookResponse.duplicate(existing.get());
}
if (!idempotencyService.tryAcquire(idempotencyKey)) {
WebhookEvent raceWinner = eventLogService.findByIdempotencyKey(idempotencyKey)
.orElseThrow(() -> new WebhookProcessingException(
"Idempotency conflict on key: " + idempotencyKey));
return WebhookResponse.duplicate(raceWinner);
}
WebhookEvent event = buildEvent(idempotencyKey, request);
event = eventLogService.save(event);
processWithRetry(event.getId(), request);
return WebhookResponse.accepted(event);
}
@Retryable(
retryFor = WebhookProcessingException.class,
maxAttemptsExpression = "#{${webhook.retry.max-attempts:3}}",
backoff = @Backoff(
delayExpression = "#{${webhook.retry.initial-interval-ms:1000}}",
multiplierExpression = "#{${webhook.retry.multiplier:2.0}}",
maxDelayExpression = "#{${webhook.retry.max-interval-ms:30000}}"
)
)
public void processWithRetry(String eventId, WebhookRequest request) {
log.info("Processing webhook eventId={} type={}", eventId, request.getEventType());
eventLogService.markProcessing(eventId);
try {
paymentEventHandler.handle(request);
eventLogService.markCompleted(eventId);
log.info("Webhook processed successfully eventId={}", eventId);
} catch (Exception ex) {
String message = "Processing failed for eventId=%s: %s"
.formatted(eventId, ex.getMessage());
eventLogService.markFailed(eventId, ex.getMessage());
throw new WebhookProcessingException(message, ex);
}
}
@Recover
public void recover(WebhookProcessingException ex, String eventId, WebhookRequest request) {
log.error("Retry attempts exhausted for eventId={}", eventId, ex);
eventLogService.findById(eventId)
.ifPresent(event -> idempotencyService.release(event.getIdempotencyKey()));
}
private WebhookEvent buildEvent(String idempotencyKey, WebhookRequest request) {
String rawPayload;
try {
rawPayload = objectMapper.writeValueAsString(request);
} catch (JsonProcessingException ex) {
log.warn("Failed to serialize webhook payload; using fallback string", ex);
rawPayload = request.toString();
}
return WebhookEvent.builder()
.idempotencyKey(idempotencyKey)
.eventType(request.getEventType())
.paymentId(request.getPaymentId())
.amount(request.getAmount())
.currency(request.getCurrency())
.status(ProcessingStatus.PENDING)
.rawPayload(rawPayload)
.attemptCount(0)
.build();
}
}

This is a useful draft, but it still needs review. In fact, the code contains a subtle production problem: processWithRetry() is called from inside the same class. With Spring AOP, annotations like @Retryable are applied through proxies, so self-invocation can bypass the retry behavior. That is exactly why a review stage matters.

Next, generate the persistence layer separately:

Now implement the event persistence layer.
Include:

WebhookEvent entity
WebhookEventRepository
EventLogService
Flyway migration

Constraints:

Do not expose the entity directly in API responses
Enforce a unique constraint on idempotency_key
Store only sanitized payload fields
Keep status transitions explicit

A generated migration might look like this:

-- V1__create_webhook_events.sql
CREATE TABLE webhook_events (
    id               VARCHAR(36)    NOT NULL,
    idempotency_key  VARCHAR(128)   NOT NULL,
    event_type       VARCHAR(64)    NOT NULL,
    payment_id       VARCHAR(64)    NOT NULL,
    amount           NUMERIC(18,2)  NOT NULL,
    currency         CHAR(3)        NOT NULL,
    status           VARCHAR(32)    NOT NULL DEFAULT 'PENDING',
    raw_payload      TEXT,
    attempt_count    INTEGER        NOT NULL DEFAULT 0,
    last_error       VARCHAR(1024),
    created_at       TIMESTAMPTZ    NOT NULL DEFAULT NOW(),
    updated_at       TIMESTAMPTZ    NOT NULL DEFAULT NOW(),
    processed_at     TIMESTAMPTZ,
CONSTRAINT pk_webhook_events PRIMARY KEY (id),
CONSTRAINT uq_idempotency_key UNIQUE (idempotency_key),
CONSTRAINT chk_status CHECK (status IN (
'PENDING', 'PROCESSING', 'COMPLETED', 'FAILED'
)),
CONSTRAINT chk_amount_positive CHECK (amount > 0)
);
CREATE INDEX idx_event_type_status ON webhook_events (event_type, status);
CREATE INDEX idx_payment_id ON webhook_events (payment_id);
CREATE INDEX idx_created_at ON webhook_events (created_at DESC);
CREATE INDEX idx_status_updated ON webhook_events (status, updated_at)
WHERE status IN ('PENDING', 'FAILED');
CREATE OR REPLACE FUNCTION set_updated_at()
RETURNS TRIGGER AS $$
BEGIN
NEW.updated_at = NOW();
RETURN NEW;
END;
$$ LANGUAGE plpgsql;
CREATE TRIGGER trg_webhook_events_updated_at
BEFORE UPDATE ON webhook_events
FOR EACH ROW EXECUTE FUNCTION set_updated_at();

Notice how this snippet gives reviewers something concrete to inspect. They can ask whether raw_payload should exist at all, whether DUPLICATE belongs in the persisted enum, whether the indexes match expected query patterns, and whether the idempotency key should be normalized before it reaches the database.

The same staged approach works for controllers. Ask Claude for the controller only after the service and persistence responsibilities are clear:

Implement only the Spring Boot controller for webhook ingestion.
Include:

POST /api/v1/webhooks
Idempotency-Key header validation
Webhook signature validation boundary
202 response for accepted events
200 response for duplicate events

Return only controller and DTO code.

Claude may generate code like this:

@PostMapping
public ResponseEntity<WebhookResponse> receive(
        @RequestHeader("Idempotency-Key") String idempotencyKey,
        @RequestHeader("X-Webhook-Signature") String signature,
        @RequestBody byte[] rawBody,
        @Valid @RequestBody WebhookRequest request) {
boolean valid = SignatureUtil.verify(rawBody, signature, properties.getSignature().getSecret());
if (!valid) {
throw new InvalidSignatureException("Webhook signature verification failed");
}
WebhookResponse response = processor.ingest(idempotencyKey, request);
HttpStatus status = response.getStatus() == WebhookEvent.ProcessingStatus.DUPLICATE
? HttpStatus.OK
: HttpStatus.ACCEPTED;
return ResponseEntity.status(status).body(response);
}

This is useful to keep in the article because it shows both the benefit and risk of AI-generated code. The code looks plausible, but Spring cannot reliably bind two @RequestBody parameters from the same request body stream. A stronger design would move raw-body signature verification into a filter or request wrapper, then pass a validated DTO into the controller.

Workflow 3: Build an AI self-review loop

A good Claude workflow includes a review stage before human review. After implementation, ask Claude to audit its own output against specific engineering standards.

Review the generated code against the following criteria:

SOLID principles
Security risks
Performance bottlenecks
Clean architecture boundaries
Testability
Production readiness

For each issue:

Assign severity: Critical, High, Medium, or Low
Explain why it matters
Provide a concrete fix

This prompt often surfaces the exact issues you would otherwise have to find manually. That matters because AI-assisted development often shifts work from writing code to reviewing generated code. LogRocket has covered this pattern in more detail in why AI coding tools shift the real bottleneck to review.

For the webhook example, a useful review may look like this:

After the review, ask Claude to apply the highest-priority architectural fix first:

Apply the critical retry fix only.
Refactor the code so retry behavior lives in a separate Spring bean.
Do not change the controller, DTOs, or database schema.
Return:

New class
Modified service
Explanation of why this fixes Spring AOP self-invocation

That prompt produces a smaller and safer change:

@Service
@RequiredArgsConstructor
@Slf4j
public class WebhookRetryExecutor {
private final EventLogService eventLogService;
private final PaymentEventHandler paymentEventHandler;
private final IdempotencyService idempotencyService;
@Retryable(
retryFor = WebhookProcessingException.class,
maxAttemptsExpression = "#{${webhook.retry.max-attempts:3}}",
backoff = @Backoff(
delayExpression = "#{${webhook.retry.initial-interval-ms:1000}}",
multiplierExpression = "#{${webhook.retry.multiplier:2.0}}",
maxDelayExpression = "#{${webhook.retry.max-interval-ms:30000}}"
)
)
public void processWithRetry(String eventId, WebhookRequest request) {
eventLogService.markProcessing(eventId);
try {
paymentEventHandler.handle(request);
eventLogService.markCompleted(eventId);
} catch (Exception ex) {
eventLogService.markFailed(eventId, ex.getMessage());
throw new WebhookProcessingException(
"Processing failed for eventId=%s".formatted(eventId), ex);
}
}
@Recover
public void recover(WebhookProcessingException ex, String eventId, WebhookRequest request) {
log.error("All retries exhausted eventId={}", eventId, ex);
eventLogService.findById(eventId)
.ifPresent(event -> idempotencyService.release(event.getIdempotencyKey()));
}
}

Then the processor depends on the retry executor instead of invoking its own annotated method:

@Service
@RequiredArgsConstructor
@Slf4j
public class WebhookProcessorService {
private final IdempotencyService idempotencyService;
private final EventLogService eventLogService;
private final WebhookRetryExecutor retryExecutor;
private final ObjectMapper objectMapper;
@Transactional
public WebhookResponse ingest(String idempotencyKey, WebhookRequest request) {
Optional<WebhookEvent> existing = eventLogService.findByIdempotencyKey(idempotencyKey);
if (existing.isPresent()) {
return WebhookResponse.duplicate(existing.get());
}
if (!idempotencyService.tryAcquire(idempotencyKey)) {
return eventLogService.findByIdempotencyKey(idempotencyKey)
.map(WebhookResponse::duplicate)
.orElseThrow(() -> new WebhookProcessingException(
"Idempotency conflict: " + idempotencyKey));
}
WebhookEvent event = eventLogService.save(buildEvent(idempotencyKey, request));
retryExecutor.processWithRetry(event.getId(), request);
return WebhookResponse.accepted(event);
}
private WebhookEvent buildEvent(String idempotencyKey, WebhookRequest request) {
String rawPayload;
try {
rawPayload = objectMapper.writeValueAsString(request);
} catch (JsonProcessingException ex) {
rawPayload = request.toString();
}
return WebhookEvent.builder()
.idempotencyKey(idempotencyKey)
.eventType(request.getEventType())
.paymentId(request.getPaymentId())
.amount(request.getAmount())
.currency(request.getCurrency())
.status(ProcessingStatus.PENDING)
.rawPayload(rawPayload)
.attemptCount(0)
.build();
}
}

This is the workflow loop in action: generate code, review it, isolate one issue, apply one fix, and review again.

Use a severity table to make the review actionable

Ask Claude to format review findings as a table. Tables are easier to scan and easier to convert into PR tasks.

Return the review as a table with these columns:

Severity
File or component
Issue
Why it matters
Recommended fix
Should block merge? yes/no

This turns a vague AI review into an engineering checklist.

Workflow 4: Use Claude for structured debugging

Debugging is one of the highest-value use cases for Claude, but only if you provide the right context.

Do not prompt it like this:

Fix this error.

Use a structured debugging prompt:

You are a senior backend engineer debugging a production issue.
Error:
[paste error message]
Stack trace:
[paste stack trace]
Relevant code:
[paste code snippet]
Runtime context:

Framework:
Version:
Environment:
Recent changes:
Expected behavior:
Actual behavior:

Explain:

Most likely root cause
Evidence for that diagnosis
Minimal fix
Safer production fix
Long-term refactor
Test cases that would prevent recurrence

For the webhook example, the debugging target might be the self-invocation problem from the generated service:

@Transactional
public WebhookResponse ingest(String idempotencyKey, WebhookRequest request) {
    WebhookEvent event = eventLogService.save(buildEvent(idempotencyKey, request));
    processWithRetry(event.getId(), request);
    return WebhookResponse.accepted(event);
}
@Retryable(retryFor = WebhookProcessingException.class)
public void processWithRetry(String eventId, WebhookRequest request) {
eventLogService.markProcessing(eventId);
paymentEventHandler.handle(request);
eventLogService.markCompleted(eventId);
}

A good Claude response should not only say “move this to another service.” It should explain the cause, evidence, and prevention:

You can then ask Claude to generate the prevention test. For example, an ArchUnit-style guardrail might look like this:

@AnalyzeClasses(packages = "com.payments.webhook")
class ArchitectureTest {
@ArchTest
static final ArchRule no_circular_dependencies =
slices().matching("com.payments.webhook.(*)..")
.should().beFreeOfCycles();
@ArchTest
static final ArchRule retry_logic_lives_in_retry_executor =
methods()
.that().areAnnotatedWith(Retryable.class)
.should().beDeclaredInClassesThat()
.haveSimpleNameEndingWith("RetryExecutor")
.because("retry boundaries should be explicit and invoked through Spring proxies");
}

This is where structured prompting becomes more valuable than quick patching. Claude is not just fixing one error; it is helping you convert a bug into a reusable guardrail.

For more on validating AI-generated code instead of accepting it at face value, see LogRocket’s guide to fixing AI-generated code.

Workflow 5: Use Claude for pull request review

Claude can help review pull requests, but a single “review this PR” prompt is too broad. It usually returns a mix of useful comments, generic advice, and low-priority style feedback.

A better PR review workflow separates the review into passes:

1. Correctness
2. Performance
3. Security
4. Test coverage
5. Readability and maintainability

Start by exporting the diff:

git diff main > pr_changes.txt

Then prompt Claude one pass at a time:

You are a staff engineer reviewing a pull request.
Review this diff for correctness only.
Focus on:

Broken behavior
Incorrect assumptions
Missing edge cases
Race conditions
API contract changes

Do not comment on style, naming, formatting, or performance unless it causes a correctness issue.
Return:

Blocking issues
Non-blocking issues
Questions for the author
Suggested tests

Then run a security pass:

Review the same diff for security risks.
Focus on:

Input validation
Authentication and authorization
Secret handling
Logging of sensitive data
Unsafe defaults
Dependency or supply-chain risks

Return only actionable findings.

Finally, run a maintainability pass:

Review the same diff for maintainability.
Focus on:

Over-engineering
Unclear abstractions
Duplicated logic
Poor names
Missing comments where intent is not obvious
Places where a future developer may misunderstand the code

This approach produces more useful feedback because each pass has a clear purpose. It also prevents minor style suggestions from distracting from correctness and security issues.

Generate a PR summary

Claude is also useful for PR descriptions. After reviewing the diff, ask:

Generate a pull request summary.
Include:

Problem statement
Implementation approach
Files or modules changed
Testing performed
Risks and rollback plan
Reviewer notes

A good output might look like this:

This PR adds idempotent payment webhook processing.
Changes:

Adds WebhookController for inbound provider events
Adds Redis-backed idempotency lock handling
Persists webhook lifecycle events in PostgreSQL
Adds retry handling for transient processing failures
Adds unit tests for idempotency, signature verification, and event logging

Testing:

Unit tests for duplicate webhook detection
Controller tests for invalid signatures and missing headers
Repository migration verified locally

Risks:

Signature verification depends on raw request body handling
Retry behavior should be verified with an integration test
rawPayload storage should be reviewed for PII before production

This can save time, but it should still be reviewed. PR summaries are communication artifacts, and they shape how reviewers understand the change.

Workflow 6: Use Claude to generate documentation

One-shot documentation prompts usually produce vague, generic explanations:

Write docs for this code.

That prompt does not define the audience, the docs format, or what the reader needs to do next.

Use a documentation workflow instead:

Generate developer documentation for this module.
Audience:
Backend engineers who need to maintain or extend the service.
Include:

What the module does
Architecture overview
Request flow
API contract
Configuration
Error handling
Operational risks
Local development steps
Examples

Then refine by audience:

Rewrite the documentation for an onboarding engineer.
Assume they understand Spring Boot, but they do not know this codebase.
Add:

Glossary
Common failure modes
Where to add a new webhook event type
How to run the tests locally

Generated documentation often describes what code does, but misses why it exists. Add this prompt:

Review the documentation and add design intent.
For each major component, explain:

Why it exists
What decision it protects
What tradeoff it makes
What a future developer should avoid changing casually

That produces documentation that is more useful for maintenance.

Workflow 7: Use Claude for test generation

Claude can generate useful tests, especially for deterministic functions, service methods, and controller behavior. But it often over-mocks or writes tests that assert implementation details instead of user-visible behavior.

Use a staged test workflow:

Generate a test plan before writing tests.
Code under test:
[paste code]
Return:

Happy-path scenarios
Edge cases
Failure modes
Security-related tests
Integration tests
Tests that should not be written because they would be brittle

Then ask for one test class at a time. The example below is long enough to show the value of the workflow: it covers first acquisition, duplicate handling, null Redis responses, release behavior, and lock checks.

package com.payments.webhook.service;
import com.payments.webhook.config.WebhookProperties;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.InjectMocks;
import org.mockito.Mock;
import org.mockito.junit.jupiter.MockitoExtension;
import org.springframework.data.redis.core.RedisTemplate;
import org.springframework.data.redis.core.ValueOperations;
import java.time.Duration;
import static org.assertj.core.api.Assertions.assertThat;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.ArgumentMatchers.eq;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.when;
@ExtendWith(MockitoExtension.class)
@DisplayName("IdempotencyService")
class IdempotencyServiceTest {
@Mock RedisTemplate<String, Object> redisTemplate;
@Mock ValueOperations<String, Object> valueOps;
@Mock WebhookProperties properties;
@Mock WebhookProperties.Idempotency idempotencyProps;
@InjectMocks IdempotencyService idempotencyService;
private static final String KEY = "evt_abc123";
private static final String REDIS_KEY = "webhook:idempotency:" + KEY;
@BeforeEach
void setUp() {
when(properties.getIdempotency()).thenReturn(idempotencyProps);
when(idempotencyProps.getTtlSeconds()).thenReturn(86400L);
when(redisTemplate.opsForValue()).thenReturn(valueOps);
}
@Test
@DisplayName("tryAcquire returns true on first call")
void tryAcquire_firstCall_returnsTrue() {
when(valueOps.setIfAbsent(eq(REDIS_KEY), eq("1"), eq(Duration.ofSeconds(86400))))
.thenReturn(true);
assertThat(idempotencyService.tryAcquire(KEY)).isTrue();
verify(valueOps).setIfAbsent(REDIS_KEY, "1", Duration.ofSeconds(86400));
}
@Test
@DisplayName("tryAcquire returns false when key already exists")
void tryAcquire_duplicate_returnsFalse() {
when(valueOps.setIfAbsent(eq(REDIS_KEY), eq("1"), any(Duration.class)))
.thenReturn(false);
assertThat(idempotencyService.tryAcquire(KEY)).isFalse();
}
@Test
@DisplayName("tryAcquire treats null Redis response as false")
void tryAcquire_nullResponse_returnsFalse() {
when(valueOps.setIfAbsent(any(), any(), any(Duration.class))).thenReturn(null);
assertThat(idempotencyService.tryAcquire(KEY)).isFalse();
}
@Test
@DisplayName("release deletes the Redis key")
void release_deletesKey() {
idempotencyService.release(KEY);
verify(redisTemplate).delete(REDIS_KEY);
}
@Test
@DisplayName("isLocked returns true when key exists")
void isLocked_keyExists_returnsTrue() {
when(redisTemplate.hasKey(REDIS_KEY)).thenReturn(true);
assertThat(idempotencyService.isLocked(KEY)).isTrue();
}
@Test
@DisplayName("isLocked returns false when key is absent")
void isLocked_keyAbsent_returnsFalse() {
when(redisTemplate.hasKey(REDIS_KEY)).thenReturn(false);
assertThat(idempotencyService.isLocked(KEY)).isFalse();
}
}

After Claude generates tests, ask it to critique them:

Review the generated tests.
Identify:

False confidence risks
Over-mocking
Missing failure cases
Assertions that are too weak
Tests that duplicate implementation details

This is important because AI-generated tests can look thorough while still missing the behavior that matters. LogRocket’s experiment on replacing a test suite with AI agents shows the same general pattern: AI-generated tests can be useful, but they need careful review around assumptions, selectors, and failure modes.

Good test-generation targets

Claude is usually strongest for:

• Pure functions with clear inputs and outputs
• DTO validation tests
• Controller status-code tests
• Error handling branches
• Utility functions
• Serialization and formatting behavior

Use more caution with:

• Auth flows
• Async race conditions
• Provider-heavy component trees
• Integration tests with complex app wiring
• Tests where over-mocking could hide the real failure

A good rule: let Claude draft tests, but make a human decide what confidence those tests actually provide.

Workflow 8: Use Claude for automation scripts

Claude is useful for small internal automation tasks, but one-shot prompts often produce scripts that work once and then become hard to reuse.

Instead of:

Write a script to automate dependency upgrades.

Use:

Design a reusable automation script.
Task:
Scan a GitHub repository for outdated dependencies and create upgrade pull requests.
Requirements:

Support dry-run mode
Handle npm and Python dependencies
Respect GitHub API rate limits
Avoid duplicate PRs
Add structured logging
Fail safely without modifying files when credentials are missing

Return:

Design overview
CLI arguments
Error handling strategy
Implementation
Example commands
Risks and limitations

A strong automation output should explain not only what the script does, but how it behaves when something goes wrong.

For example, Claude might return usage instructions before the full script:

pip install requests packaging toml
Dry run first. No branches or PRs are created.
GITHUB_TOKEN=ghp_xxx GITHUB_REPO=acme/backend 

python dep_upgrader.py --dry-run
Real run. Python dependencies only, limited to five PRs.
python dep_upgrader.py 

--token ghp_xxx 

--repo acme/backend 

--ecosystem python 

--limit 5 

--label "dependencies,automated"

Then it should explain the design decisions:

Then ask Claude to review the script:

Review this script as if it will run in CI.
Focus on:

Secret handling
Idempotency
Rate limits
Error handling
Rollback behavior
Observability

Automation is where structured prompting matters most. A fragile one-off script can create more operational risk than the manual task it replaced.

Prompt templates for Claude workflows

Here are reusable prompt templates for common engineering workflows.

Architecture prompt

You are a senior software architect.
Design a solution for:
[task]
Context:
[stack, existing architecture, constraints]
Return:

Architecture overview
Data flow
Components and responsibilities
Interfaces
Risks and tradeoffs
Testing strategy
What you need to know before implementation

Implementation prompt

Implement only this stage:
[scope]
Use:
[stack, libraries, versions]
Constraints:

[constraint]
[constraint]

Do not:

[out-of-scope item]
[out-of-scope item]

Return:

Files changed
Code
Notes on assumptions
Tests to add next

Review prompt

Review this generated code.
Focus on:

Correctness
Security
Performance
Maintainability
Architecture boundaries
Tests

Return a severity-ranked table with concrete fixes.

Debugging prompt

Debug this issue.
Error:
[paste error]
Relevant code:
[paste code]
Context:
[paste runtime details]
Return:

Root cause
Evidence
Minimal fix
Safer production fix
Long-term prevention
Tests

Documentation prompt

Generate developer documentation for this module.
Audience:
[audience]
Include:

Purpose
Architecture
Setup
API contract
Examples
Failure modes
Maintenance notes

Test prompt

Create a test plan for this code before writing tests.
Return:

Behaviors to test
Edge cases
Failure modes
Mocks required
Tests that would be brittle
Recommended test order

Best practices for prompting Claude

The best Claude prompts are not just longer. They are more constrained, easier to evaluate, and easier to iterate on.

Use these rules:

• Give Claude the role it should play
• Define the task in one or two sentences
• Provide relevant code, logs, and constraints
• Ask for a plan before code
• Generate one part of the system at a time
• Ask Claude to state assumptions
• Ask for tradeoffs, risks, and alternatives
• Review output against explicit criteria
• Ask for tests before accepting code
• Keep reusable prompts in your repository or team docs

This is also where tools like Claude Code become more useful. LogRocket’s guide to leveling up Claude Code covers practical patterns like hooks, commands, and worktrees that can make Claude workflows more repeatable.

When not to use Claude

Claude is useful, but it should not replace engineering judgment.

Avoid relying on Claude alone for:

• Security-sensitive changes
• Authentication and authorization logic
• Payment flows
• Data migrations
• Compliance-sensitive code
• Infrastructure changes
• Large refactors without tests
• Business logic with ambiguous requirements

In these cases, Claude can still help with planning, review, and test generation. But a human should own the final architecture, risk assessment, and merge decision.

Conclusion

Better Claude output does not come from one perfect prompt. It comes from a better workflow.

One-shot prompting asks Claude to guess the task, architecture, constraints, tests, and tradeoffs all at once. Workflow-based prompting separates those steps so each output can be reviewed, improved, and tested before moving forward.

The practical shift is simple:

• Use Claude to plan before it codes
• Generate implementation in small sections
• Make Claude review its own output
• Debug with context, not vague error messages
• Review PRs in focused passes
• Generate tests from a test plan
• Document intent, not just behavior
• Keep human judgment in the loop

AI-assisted development is not about typing less. You have to turn engineering judgment into repeatable prompts, review steps, and guardrails. Claude becomes much more useful when you stop treating it like a one-shot code generator and start using it as part of a structured development workflow.

The post Stop trying to one-shot: How to prompt Claude better appeared first on LogRocket Blog.