15 Prompts for Claude Code: From Refactoring to Architecture Design
If you're a developer working with large codebases, you already know the pain: legacy spaghetti, inconsistent naming, fragile tests, and architecture that made sense three years ago but now feels like a house of cards. Claude Code, Anthropic's agentic coding tool released in 2025, changes the game. Unlike simple autocomplete assistants, Claude Code can analyze entire projects, execute terminal commands, edit files, and even run tests — all through natural language prompts.
This article gives you 15 battle-tested prompts for Claude Code, organized into three areas: code review and refactoring, testing and debugging, and architecture and design. Each prompt includes a real usage example so you can copy-paste and adapt immediately.
Code Review and Refactoring Prompts
1. Identify Code Smells in a Module
Task: Scan a specific file or directory for common anti-patterns like long methods, duplicate code, or overcomplicated conditionals.
Prompt:
Analyze the module at src/services/payment.ts for code smells. List each smell with the exact line number, explain why it's problematic, and suggest a concrete refactoring. Group by severity (critical, major, minor).
Example output:
- Critical: Line 142 — method processRefund is 120 lines long; break into 3 smaller functions.
- Major: Lines 45–50 and 78–83 — duplicate validation logic; extract to validateAmount().
- Minor: Line 201 — hardcoded string "USD"; use a constant.
2. Convert a Class to Functional Style
Task: Replace a class-based implementation with pure functions and a simpler data model.
Prompt:
Refactor src/helpers/UserService.ts from class-based to functional style using plain objects and standalone functions. Keep the same public API. Add type annotations. Output the full new file content.
Example: A 50-line UserService class with createUser, updateUser becomes 30 lines of exported arrow functions with shared state passed as parameters.
3. Improve Naming and Comments
Task: Rename unclear variables and replace outdated comments with meaningful ones.
Prompt:
Review src/components/DataGrid.jsx. Rename every ambiguous variable (e.g., `tmp`, `data`, `arr`) to a descriptive name. Update or remove comments that are redundant or wrong. Show a diff of changes.
Example: let tmp = fetchItems(); → let fetchedItems = await fetchItems();
4. Extract a God Class
Task: Split a large class that does too many things into smaller, focused classes.
Prompt:
The class src/services/OrderManager.ts has 800 lines and handles validation, database, email, and PDF generation. Propose a refactoring plan: split into 3–4 classes. For each new class, list its responsibilities, methods, and dependencies. Write the skeleton code for each.
Example output:
- OrderValidator — validates input, no dependencies
- OrderRepository — CRUD operations, depends on DB
- OrderNotifier — sends email, depends on mail service
- OrderExporter — generates PDF, depends on PDF lib
5. Remove Dead Code
Task: Find and delete unused functions, imports, or entire files.
Prompt:
Scan the entire src directory for dead code: unused exports, unreachable branches, functions never called, and imports not used. For each occurrence, show file and line. Suggest removal or explain why it might be kept.
Example: src/utils/legacyParser.ts is not imported anywhere → delete it.
Testing and Debugging Prompts
6. Generate Unit Tests for a Complex Function
Task: Create a comprehensive test suite for a critical business logic function.
Prompt:
Write Jest tests for src/logic/calculateDiscount.ts. Cover: normal cases, edge cases (0, negative, max value), null/undefined inputs, and error paths. Use describe/it blocks. Mock external API calls with jest.mock. Output the full test file.
Example: Tests for calculateDiscount(price, userTier) — gold tier gets 20%, silver gets 10%, expired tier throws error.
7. Debug a Failing Integration Test
Task: Analyze a test failure and suggest the root cause.
Prompt:
Here is the integration test output from tests/api/orders.test.ts:
[ERROR] Expected status 201, got 500. Response body: {"error":"Cannot read property 'id' of undefined"}
Look at src/api/orders.ts and src/models/Order.ts. Find the bug and explain the fix.
Example: The Order model returns null for a nested object, but the API handler doesn't check for null before accessing .id. Fix: add optional chaining.
8. Add TypeScript Types to Untyped Code
Task: Convert a plain JavaScript file to TypeScript with strict types.
Prompt:
Convert src/legacy/mixpanel.ts from JavaScript to TypeScript. Add interfaces for all function parameters and return types. Use strict mode (noImplicitAny). Output the full typed file.
Example: function track(event, props) becomes function track(event: string, props: Record<string, unknown>): void.
9. Performance Profile a Slow Endpoint
Task: Identify bottlenecks in an API endpoint and suggest optimizations.
Prompt:
Profile the GET /api/reports/dashboard endpoint in src/api/reports.ts. The response takes 12 seconds. Use console.time or perf_hooks to measure sections. Suggest caching strategies, query optimizations, or parallelization.
Example: The bottleneck is an N+1 query in the database layer; use Promise.all and batch queries.
10. Lint and Format Entire Codebase
Task: Automatically fix formatting and linting issues across the project.
Prompt:
Run ESLint and Prettier on the entire src directory. Fix all auto-fixable issues. For remaining warnings, list them grouped by rule. Then apply the fixes manually.
Example: ESLint fixes 23 trailing commas, Prettier reformats all files, 2 warnings remain about unused variables.
Architecture and Design Prompts
11. Suggest a Microservices Split
Task: Decompose a monolith into microservices with clear boundaries.
Prompt:
Analyze the monolith in src/ (controllers, services, models, routes). Suggest a microservices decomposition into 3–5 services. For each service: list bounded context, APIs, data store, and communication protocol (REST, gRPC, event bus). Draw the architecture in ASCII.
Example output:
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ User Svc │────▶│ Order Svc │────▶│ Payment Svc │
│ (REST, PG) │ │ (REST, PG) │ │ (gRPC, PG) │
└─────────────┘ └─────────────┘ └─────────────┘
│ │
└──────────────────┬───────────────────┘
▼
┌─────────────┐
│ Kafka Bus │
└─────────────┘
12. Design a New Module from Requirements
Task: Given a feature spec, create the module's API, data model, and key interfaces.
Prompt:
Design a notification module for our SaaS app. Requirements: supports email, SMS, and push; users can set preferences per channel; throttling of 5 emails per minute per user. Output: API endpoints (OpenAPI 3.0 spec), database schema (SQL), and core interfaces in TypeScript.
Example: A POST /api/notifications/send endpoint with validation, a notifications table with channel enum, and a NotifierService interface.
13. Evaluate Trade-offs Between Two Architectures
Task: Compare two design approaches and recommend one with reasoning.
Prompt:
We need to choose between a REST API and a GraphQL API for our dashboard. Compare: learning curve, flexibility, caching, tooling maturity, and team experience (we have 3 frontend devs, 2 backend devs). Recommend one with 3 pros and 2 cons. Use concrete examples from our codebase.
Example output: Recommends REST because team is small and GraphQL's over-fetching is not a bottleneck.
14. Generate API Documentation
Task: Create OpenAPI/Swagger docs from existing route handlers.
Prompt:
Read all route files in src/routes/. Generate an OpenAPI 3.0 YAML spec covering all endpoints, request/response schemas, authentication (Bearer token), and example values. Use proper $ref for reusable components.
Example: A 200-line spec file for 15 endpoints with schemas for User, Order, Error.
15. Audit Security Vulnerabilities
Task: Find common security issues in the codebase.
Prompt:
Audit src/ for OWASP Top 10 vulnerabilities: SQL injection, XSS, CSRF, insecure deserialization, and broken authentication. For each finding: location, severity, and fix (code change). Use npm audit for dependencies.
Example: Line 55 in login.ts uses raw SQL concatenation → switch to parameterized queries.
Conclusion
These 15 prompts cover the most common tasks you'll face when maintaining or evolving a codebase — from cleaning up messy code to designing new features. The key to getting great results with Claude Code is specificity: include file paths, error messages, and clear constraints. Start with the prompts above, then customize them to your project's language, framework, and conventions.
Remember that Claude Code is an assistant, not a replacement for your judgment. Always review the output, run tests, and verify architecture decisions with your team. Used wisely, these prompts can save you hours each week and help you ship cleaner, safer code faster.
Comments