Skip to content
BSWEN
Blog

How Short Prompts Beat Step-by-Step Instructions in Claude Code

Cowrie
Cowrie
Dev @ Bswen

Problem

I was writing 500-line CLAUDE.md files. Every time I encountered a scenario, I’d add another procedure:

My bloated CLAUDE.md
## TypeScript Error Handling
When you encounter a TypeScript error:
1. First, read the error message carefully
2. Check if the type definition exists in the project
3. If not, search for @types package
4. Create the type definition if needed
5. Verify the import statement is correct
6. Check tsconfig.json for path aliases
7. Look for circular dependencies
... (continues for 30 more steps)


## Code Review Procedure
Review this code and:
- Check for security issues (OWASP top 10)
- Look for performance problems (N+1 queries, etc.)
- Verify error handling is comprehensive
- Check naming conventions match style guide
- Ensure all functions have JSDoc comments
- Validate input sanitization
... (continues for 20 more items)

Then I discovered something that stopped me cold. Boris Cherny, the creator of Claude Code, uses a CLAUDE.md that’s barely 100 lines. And his prompts?

Fix.


Grill me on these changes.


Knowing everything you know now, scrap this and implement the elegant solution.

His entire philosophy fits in two words: “Don’t babysit.”

What Happened?

I had assumed more detail = better results. If I carefully specified every step, the AI would follow them perfectly. Right?

The Reddit thread I found showed the opposite. Boris doesn’t micromanage. He gives the model a goal and lets it figure out the path. His motto is explicit: focus on managing context windows, not procedures.

Here’s what I learned from comparing approaches:

Approach Comparison
MY APPROACH (500 lines):
┌─────────────────────────────────────┐
│ CLAUDE.md                           │
│ ─────────────────────────────────── │
│ ├── TypeScript procedures (40 lines)│
│ ├── Code review checklist (35 lines)│
│ ├── Git workflow (25 lines)         │
│ ├── Error handling (30 lines)       │
│ ├── Testing rules (28 lines)        │
│ └── ... (342 more lines)            │
└─────────────────────────────────────┘
        ↓
    AI constrained by my steps
        ↓
    Results: HIT OR MISS




BORIS'S APPROACH (~100 lines):
┌─────────────────────────────────────┐
│ CLAUDE.md                           │
│ ─────────────────────────────────── │
│ ├── Project context (key files)     │
│ ├── Coding preferences (concise)    │
│ └── Essential constraints only      │
└─────────────────────────────────────┘
        ↓
    AI reasons through the problem
        ↓
    Results: CONSISTENTLY GOOD

The irony: Boris built Claude Code itself using this minimal approach. My bloated files were producing worse results.

Why Step-by-Step Fails

I had to understand why my detailed procedures weren’t working.

The Constraint Problem

When I write step-by-step instructions, I’m constraining the model’s reasoning. I’m saying “follow this exact path.” But what if there’s a better path?

Constraint Visualization
DETAILED INSTRUCTIONS:
User intent ──→ Step 1 ──→ Step 2 ──→ Step 3 ──→ Step 4 ──→ Result
                   │
                   └── Model can't explore alternative paths


SHORT PROMPTS:
User intent ──→ Model explores ──→ Model reasons ──→ Result
                   │
                   └── Multiple possible paths considered

The model has seen billions of code patterns. It knows how to debug. It knows how to fix errors. When I force it through my 30-step procedure, I’m preventing it from using its knowledge.

The Knowledge I Don’t Have

My procedures reflect what I know. But the model often knows better approaches than I do.

Example: My Wrong Assumption
I assumed TypeScript errors need:
1. Check type definition
2. Search for @types
3. Create definition
...


But the model might see:
- The error is from a version mismatch
- The real fix is updating a dependency
- My 30 steps would waste time on the wrong problem

By giving a short prompt (“Fix this TypeScript error”), the model can diagnose and solve using its training—which includes patterns I’ve never seen.

Context vs Instructions

The Reddit discussion emphasized this distinction: context management matters more than instruction length.

What does this mean in practice?

Wrong Focus
# This is instruction-heavy but context-poor
When debugging:
1. Read error
2. Check logs
3. Search StackOverflow
4. ... (steps continue)


# The model doesn't know:
# - What files are relevant
# - What the codebase structure is
# - What recent changes were made
Right Focus
# This is context-heavy but instruction-light
Project structure:
- src/api/ contains REST endpoints
- src/db/ contains database models
- Recent change: added user authentication


Fix this error: [paste error]

The second approach gives the model what it needs: knowledge about the problem space. The model already knows how to debug.

How Short Prompts Work

I tested the short-prompt approach on real problems.

Test 1: Bug Fix

My old approach:

I'm getting a TypeScript error. Please:
1. Read the error message carefully
2. Identify which file has the problem
3. Check if types are installed
4. If not installed, install them
5. Verify the import is correct
6. If still failing, check tsconfig paths
7. Report back at each step

Short-prompt approach:

Fix. [paste error]

Result: Both approaches eventually solved the problem. But the short prompt was faster and didn’t constrain the model to my mental model of debugging.

Test 2: Code Review

My old approach:

Review this code for:
- Security issues
- Performance problems
- Error handling gaps
- Style violations
- Missing tests
- Hardcoded values
- Potential null references
... (15 more items)

Boris’s approach (from the thread):

Grill me on these changes. Don't make a PR until I pass your test.

The difference? My checklist made the model tick boxes. Boris’s prompt made the model think critically and challenge him—which is what you actually want from a code review.

Test 3: Refactoring

My old approach:

Refactor this module:
1. Identify all dependencies
2. Check which ones are actually used
3. Remove unused imports
4. Split into smaller functions
5. Add error handling
... (20 more steps)

Boris’s approach (from the thread):

Knowing everything you know now, scrap this and implement the elegant solution.

This prompt trusts the model’s judgment. It signals “I want better architecture” without constraining how to get there.

The Art of Short Prompts

Short doesn’t mean vague. Short prompts work because they’re high-trust, high-clarity goals.

Good Short Prompts

Fix.                                          # Clear goal, trust model


Grill me on these changes.                    # Clear goal, specific behavior


Refactor for readability.                     # Clear goal, no constraints


Implement the feature from this spec: [spec]  # Clear context, trust model

Bad Short Prompts

Do it.                                        # No goal, no context


Fix this.                                     # Goal clear, but what's "this"?


Make it better.                               # Vague goal, no criteria


Help.                                         # Nothing actionable

The pattern: Good short prompts have a clear goal. Bad short prompts have no goal or no context.

When Short Fails

Short prompts fail when you actually need constraints:

# This needs constraints
Deploy to production.


# Better
Deploy to production, but:
- Run tests first
- Create backup
- Use blue-green deployment

But notice: even with constraints, this is shorter than a 30-step deployment procedure. The model knows how to deploy. It just needs the constraints that are specific to your setup.

The “Don’t Babysit” Principle

Boris’s philosophy is worth expanding on. “Don’t babysit” means:

BABYSITTING (What I was doing):
┌────────────────────────────────────────┐
│ "Check error message"                   │
│         ↓                               │
│ "Now check types"                       │
│         ↓                               │
│ "Now install if missing"                │
│         ↓                               │
│ "Now verify import"                     │
│         ↓                               │
│ Model follows, doesn't think            │
└────────────────────────────────────────┘


NOT BABYSITTING (Boris's approach):
┌────────────────────────────────────────┐
│ "Fix this error"                       │
│         ↓                               │
│ Model diagnoses, decides, acts          │
│         ↓                               │
│ Model uses its training                 │
│         ↓                               │
│ Model explores better solutions         │
└────────────────────────────────────────┘

The model is trained on billions of examples of debugging, refactoring, and reviewing code. It knows the steps. When I specify them, I’m not helping—I’m getting in the way.

What to Focus on Instead

If not procedures, then what? Context.

Context-Rich CLAUDE.md
# Project: E-commerce API


## Key Files
- `src/api/routes/` - REST endpoints
- `src/db/models/` - Database models
- `src/middleware/` - Auth, validation, logging


## Architecture
- PostgreSQL + Redis caching
- JWT authentication
- Rate limiting per endpoint


## Conventions
- Use repository pattern for data access
- All endpoints return `ApiResponse<T>`
- Tests in `__tests__/` mirror `src/` structure

This tells the model what it needs to know: the project structure, the patterns, the conventions. The model already knows how to code.

Practical Examples

Let me show some before/after transformations:

Example 1: Feature Request

BEFORE: My Over-Specified Prompt
Implement user search feature:
1. Create a new endpoint GET /users/search
2. Add query parameters: q (required), limit (optional, default 20)
3. Validate q is at least 2 characters
4. Search in users table using ILIKE
5. Return results in ApiResponse format
6. Add rate limiting (10 requests per minute)
7. Write tests in __tests__/api/users.test.ts
8. Update API documentation
... (10 more steps)
AFTER: Short Prompt with Context
Add user search. Follow existing patterns.


Reference: GET /products/search for similar implementation.

Result: The model followed existing patterns without me specifying them. It found the similar endpoint and replicated the structure. My 18 steps became 2 lines.

Example 2: Bug Investigation

BEFORE: Over-Specified Debugging
I'm seeing a weird error. Please:
1. Check the server logs in /var/log/app.log
2. Look for any stack traces
3. If found, identify the file and line number
4. Check if it's a database connection issue
5. If so, verify DATABASE_URL environment variable
... (15 more steps)
AFTER: Short Prompt
Getting intermittent 500 errors on /api/checkout.
Logs: [paste relevant logs]

Result: The model identified a race condition I hadn’t considered. My debugging procedure would have missed it because I was looking for connection issues.

Example 3: Code Cleanup

BEFORE: Detailed Checklist
Clean up the authentication module:
- Remove unused imports
- Split functions > 50 lines
- Add JSDoc to all public functions
- Check for hardcoded values
- Replace any with proper types
- Remove console.log statements
... (20 more items)
AFTER: Short Prompt
Refactor auth/ for clarity and maintainability.
Follow project conventions.

Result: The model did all those things and more—including some I hadn’t thought of, like extracting common validation logic into a shared utility.

Common Mistakes

I made these mistakes when transitioning to short prompts:

Mistake 1: Being too vague

# Too vague
Fix it.


# Better
Fix the authentication error on login.

Mistake 2: Forgetting context

# No context
Add caching.


# With context
Add caching to the user lookup endpoint.
Current bottleneck: database queries on /api/users/:id.

Mistake 3: Removing all guidance

Short prompts still need constraints for your specific situation:

# No guidance for specific context
Deploy.


# With context-specific constraints
Deploy to staging. Must pass tests first.
Production uses blue-green, staging doesn't.

Mistake 4: Not iterating

The beauty of short prompts is they enable conversation. If the first attempt isn’t right:

Fix.
[Model fixes wrong thing]
No, the other error. The one about the missing type.
[Model fixes correct thing]

This back-and-forth is faster than writing a perfect 30-step procedure upfront.

When to Use Detailed Instructions

Short prompts aren’t always the answer. Use detailed instructions when:

  1. Safety-critical operations: Database migrations, production deployments
  2. Unusual requirements: Non-standard patterns the model wouldn’t guess
  3. Specific formatting: When output must match exact structure
  4. New team members: When the model needs to learn your specific conventions

But even then, the detailed version should be in your CLAUDE.md as context, not in every prompt.

Summary

In this post, I explained why short, direct prompts outperform step-by-step instructions in Claude Code. The key insight is that the model has extensive training in coding patterns—constraining it with detailed procedures prevents it from using that knowledge.

Boris Cherny’s “don’t babysit” philosophy means: give clear goals, provide rich context, and let the model reason. My 500-line CLAUDE.md became unnecessary once I trusted the model to figure out the steps.

The real leverage comes from managing what the model knows (context files, project structure, conventions) rather than how it thinks (step-by-step procedures).

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: