5 Underhyped Claude Code Tips That Actually Ship Code

The Claude Code hype machine is in full swing. Twitter/ X threads showing agents autonomously building entire applications. YouTube demos of “look ma, no hands” coding sessions. Conference talks about agentic futures.

Here’s the problem: most of those flashy ideas don’t ship code.

The developers actually getting value from Claude Code aren’t using exotic techniques. They’re obsessing over context quality. They’re treating their documentation like infrastructure. They’re making their codebases machine-readable.

These tips aren’t sexy. They don’t make good demos. But they’re what separates “Claude keeps hallucinating my API” from “Claude just implemented that feature in one shot”.

1. Talk Instead of Type

People think they type fast. They don’t. More importantly, typing makes you lazy.

Watch yourself the next time you prompt Claude. You abbreviate. You skip context. You under-specify because keystrokes feel expensive.

Instead of “refactor the user authentication flow to use JWT tokens with a 15-minute expiry, refresh token rotation, and make sure to handle the edge case where a user has multiple active sessions across devices,” you type “fix auth to use jwt”.

Then you wonder why Claude’s implementation misses requirements.

The physics of speech: When you talk, verbosity is free. You naturally include more detail, more edge cases, more context. You think out loud. You catch yourself saying “oh, and also..”. in ways that never happen when typing.

I use Wispr Flow for this. Talk through what you want, let the transcription capture the full thought instead of the compressed version you would’ve typed.

The difference is stark:

Input Method	Prompt
Typed	”add dark mode toggle”
Spoken	”I need a dark mode toggle in the settings page. It should persist to localStorage so it remembers the user’s preference. On first visit, check if they have prefers-color-scheme set to dark and respect that. The toggle should be in the top right of the settings panel, use a sun and moon icon, and the transition between modes should be smooth, maybe 200ms. Oh, and make sure it doesn’t flash the wrong theme on page load”.

Input Method

Prompt

Typed

”add dark mode toggle”

Spoken

”I need a dark mode toggle in the settings page. It should persist to localStorage so it remembers the user’s preference. On first visit, check if they have prefers-color-scheme set to dark and respect that. The toggle should be in the top right of the settings panel, use a sun and moon icon, and the transition between modes should be smooth, maybe 200ms. Oh, and make sure it doesn’t flash the wrong theme on page load”.

Same request. Wildly different implementation quality.

The meta-insight: Your prompt quality is rate-limited by your input method. Remove the rate limit.

2. ASCII Mockups/ Mermaid diagrams Before Code

This one sounds dumb. It works anyway.

Before writing any code for a new feature, have Claude make UI mockups, flowcharts, system diagrams, tables. All in ASCII/ mermaid/ with just pen & paper.

┌─────────────────────────────────────────────────────┐
│  Settings                                      [X]  │
├─────────────────────────────────────────────────────┤
│                                                     │
│  Theme                                              │
│  ┌─────────────────────────────────────────────┐    │
│  │ ○ Light    ● Dark    ○ System               │    │
│  └─────────────────────────────────────────────┘    │
│                                                     │
│  Notifications                                      │
│  ┌─────────────────────────────────────────────┐    │
│  │ [✓] Email notifications                     │    │
│  │ [✓] Push notifications                      │    │
│  │ [ ] SMS alerts                              │    │
│  └─────────────────────────────────────────────┘    │
│                                                     │
│                              [Cancel]  [Save]       │
└─────────────────────────────────────────────────────┘

Or for data flow:

User Request
     │
     ▼
┌──────────┐    ┌─────────┐    ┌─────────┐
│  Auth    │───▶│ Validate│───▶│ Process │
│Middleware│    │  Input  │    │ Request │
└──────────┘    └─────────┘    └─────────┘
     │              │              │
     ▼              ▼              ▼
  401 Error     400 Error     Response/Error

Why this works: It forces both of you to think through the system design before anyone’s written a line of code.

Bad ideas die early when they’re just text boxes. You catch the “wait, what about X?” moments before you’ve got 500 lines to untangle. Edge cases surface when you’re drawing arrows, not when you’re debugging.

Once the ASCII version is solid, implementation is way easier because the hard thinking already happened.

Claude isn’t guessing at your mental model. You’ve externalized it in a format it can reference throughout the implementation.

The pattern:

Describe what you want at a high level
Ask Claude to produce ASCII mockups and diagrams
Iterate on the text representation until it matches your intent
Only then say “implement this”

You’ve front-loaded the design feedback loop to where changes cost nothing.

3. Pull Library Docs Local

Web search is a context pollution vector.

When Claude searches for library documentation, it pulls in whatever Google ranks highest.

That means outdated tutorials, wrong version docs, Stack Overflow answers from 2019, and random blog posts that contradict the official docs. Claude then tries to reconcile conflicting information and makes mistakes.

The fix: Pull the relevant docs into a local folder as markdown files with just the parts you actually need.

For a project heavily using Stripe:

docs/
  stripe/
    webhooks.md        # Just the webhook signing and event types you use
    payment-intents.md # The specific flow you implemented
    error-codes.md     # Common errors and how to handle them

Each file is curated. No outdated examples. No conflicting version information. No “here’s how to do it in PHP” noise.

Tools that make this easy:

Gitingest converts any GitHub repo into a single markdown file. Point it at a library’s docs folder and you get clean, copy-pasteable content.
Code2Prompt does something similar for codebases. Useful when you want Claude to understand a library’s source, not just its docs.

There’s also the Context7 MCP plugin that fetches library documentation on demand. It works, but the tradeoff is control. You don’t decide what gets pulled. Context7 makes the relevance call for you, which means you might get more than you need or miss something specific to your use case.

For critical libraries where precision matters, I still prefer local docs. For quick lookups on less central dependencies, Context7 is convenient.

How to build this efficiently: Spin up subagents to do the research. Have one agent pull the latest docs from the official source. Have another agent extract just the sections relevant to your implementation. Have a third agent verify the docs match your installed version.

# In your CLAUDE.md
## Library Documentation
Local docs in /docs/{library}/ - use these instead of web search
- Stripe: /docs/stripe/ (v2025.01, verified)
- Prisma: /docs/prisma/ (v5.x patterns we use)
- NextAuth: /docs/nextauth/ (our custom provider setup)

Why this works: Context is finite. Every token spent on irrelevant information is a token not spent on your actual problem. By curating documentation locally, you’re acting as an editor for Claude’s context window. Clean inputs, clean outputs.

Web search has its place for novel problems. But for libraries you use daily, local curated docs win every time.

4. Tag Your Markdown Files

Here’s a pattern I stole from static site generators: YAML frontmatter with tags. (This is what Skills/ Cursor rules does it too)

If you have a /docs folder, architecture decision records, or scattered markdown files, they’re invisible to Claude unless you manually point to them. And you won’t remember to point to them.

You’ll ask Claude to implement a payment flow, forget that you documented the Stripe integration decision six months ago, and watch it hallucinate a completely different approach.

The fix is simple but powerful: add structured frontmatter to every markdown file.

---
title: Stripe Integration Decision
tags: [payments, stripe, architecture, project:billing]
date: 2025-08-15
status: implemented
---

Then write a small script that lets Claude query by tag:

#!/bin/bash
# scripts/query-docs.sh
# Usage: ./scripts/query-docs.sh "project:billing"

TAG=$1
grep -rl "tags:.*$TAG" docs/ --include="*.md" | head -20

Now add to your CLAUDE.md:

## Documentation
Query project docs by tag: `./scripts/query-docs.sh "tag-name"`
Common tags: payments, auth, architecture, api, database
Project-specific: project:billing, project:onboarding, project:notifications

Why this works: Claude Code doesn’t support semantic search yet. This gets you 80% of the way there with zero infrastructure. Instead of grepping blindly or you manually pointing to files, Claude can ask “what’s tagged project:billing?” and get exactly what it needs.

The tags become a contract between you and the agent. When you document a decision, you’re not just writing for future-you. You’re writing for future-Claude.

Most developers treat CLAUDE.md like a README file. Write it once, forget it exists, wonder why Claude keeps asking the same questions about their project structure.

The mental model shift: CLAUDE.md isn’t documentation for humans. It’s a navigation layer for an agent that’s about to grep around your codebase hoping to find the right file.

The difference matters. Human documentation explains why. Agent navigation explains where and how to find things.

# Project Structure

## Routers
- API routes: src/api/routes/*.ts
- Auth flows: src/auth/ (see src/auth/CLAUDE.md for auth-specific patterns)
- Database models: src/models/ (see src/models/CLAUDE.md for schema conventions)

## Local Conventions
- All API handlers follow: src/api/templates/handler.template.ts
- Error handling pattern: src/utils/errors.ts (use AppError class)
- Test files: Co-located as *.test.ts, not in separate __tests__ folder

## Common Tasks
- Adding a new API endpoint: Start with src/api/routes/example.ts as template
- Database migrations: Run `pnpm db:migrate` then update src/models/schema.ts

Why this works: Instead of Claude spending 30 seconds grepping for “where are the API routes,” it reads the navigation layer and goes directly to the right directory. Every file reference becomes a shortcut that saves context tokens and prevents wrong turns.

The power move is hierarchical CLAUDE.md files. Put one at the project root with high-level navigation, then subdirectory-specific files with local conventions:

project/CLAUDE.md           → Project overview, tech stack, entry points
src/api/CLAUDE.md           → API patterns, middleware conventions
src/components/CLAUDE.md    → Component patterns, prop conventions
src/models/CLAUDE.md        → Database patterns, migration rules

Claude reads all applicable CLAUDE.md files when working in any directory. You’re building infrastructure that compounds across sessions.

Why Claude Ignores Your CLAUDE.md

Here’s something most developers don’t realize: Claude frequently ignores CLAUDE.md contents entirely.

You can investigate this yourself. Put a logging proxy between the Claude Code CLI and the Anthropic API using ANTHROPIC_BASE_URL. You’ll see that Claude Code injects this system reminder alongside your CLAUDE.md contents:

<system-reminder>
IMPORTANT: this context may or may not be relevant to your tasks.
You should not respond to this context unless it is highly relevant to your task.
</system-reminder>

Read that again. Claude is explicitly told that your carefully crafted instructions “may or may not be relevant” and to ignore them unless they’re “highly relevant” to the current task.

The consequence: The more information you have in the file that isn’t universally applicable to the tasks you have Claude working on, the more likely it is that Claude will ignore your instructions entirely.

Why did Anthropic add this?

We can speculate. Most CLAUDE.md files we’ve seen include a bunch of instructions that aren’t broadly applicable. Many users treat the file as a way to add “hotfixes” to behavior they didn’t like by appending lots of random rules.

The Claude Code team likely found that by telling Claude to ignore the bad instructions, the harness actually produced better results overall. The system-level prompt is essentially saying: “The user may have dumped a bunch of irrelevant context in here. Use your judgment”.

The practical implication: Your CLAUDE.md needs to be lean and universally applicable. Don’t use it as a junk drawer for every behavioral tweak you want. Every line should be something Claude needs to know for most tasks.

Do This	Not This
Project structure and navigation	”Don’t use semicolons” (put in linter config)
Tech stack and entry points	”Always say please and thank you”
Critical conventions (error handling, testing)	One-off fixes for specific bugs
Links to subdirectory CLAUDE.md files	Lengthy explanations of business logic

If you need task-specific instructions, put them in subdirectory CLAUDE.md files. Claude reads the relevant ones when working in those directories. This keeps your root CLAUDE.md focused and increases the likelihood that Claude actually follows it.

The Underlying Principle

All of these tips are really about the same thing: context quality.

Context is the entire game. The model is the same for everyone. The tools are the same for everyone. What differs is the context you provide.

Tip	Context Improvement
Voice input	Richer context through natural verbosity
ASCII mockups	Explicit context about design intent
Local docs	Curated context without noise
Tagged markdown	Queryable context that surfaces at the right time
Lean CLAUDE.md	Context that Claude actually reads

The flashy demos get attention because they’re surprising. But surprising doesn’t ship features. Clean context does.

Focus on the fundamentals: communicate in high-fidelity, think before you code, curate what the agent sees, make your docs machine-readable, and keep your instructions lean.

The boring stuff works. Use it.

Building with Claude Code? I’d love to hear what patterns you’ve developed. Reach out on LinkedIn.