🎯 Learning Objectives
By the end of this issue, you will master:
- Semantic code search using natural language instead of
grep/find
- Understanding how Claude Code combines
Glob + Grep + Read for in-depth exploration
- Practical application of Plan Mode in code auditing
📖 Core Concepts Explained
6.1 Traditional Search vs. Semantic Search
| Dimension |
Traditional Method |
Claude Code |
| Search Filename |
find . -name "*.tsx" |
Glob(**/*.tsx) |
| Search Content |
grep -r "TODO" src/ |
Grep("TODO" in src/**) |
| Understand Context |
❌ Only returns line numbers |
✅ Explains code intent |
| Cross-file Association |
❌ Requires manual linking |
✅ Automatically traces call chains |
| Architecture Understanding |
❌ Requires manual abstraction |
✅ Generates architecture diagrams |
6.2 Three-Step Exploration Method
Step 1: Overview Step 2: Locate Step 3: Deep Dive
┌────────────┐ ┌────────────┐ ┌────────────┐
│ "What is the │──────►│ "Where is the │──────►│ "How are │
│ overall │ │ payment │ │ Stripe │
│ architecture?"│ │ module?" │ │ callbacks │
│ │ │ │ │ handled?" │
│ Tools: │ │ Tools: │ │ Tools: │
│ Glob + Read │ │ Grep + Glob │ │ Read (Multiple files)│
└────────────┘ └────────────┘ └────────────┘
💻 Simulate Claude TUI Interaction
Scenario 1: Overview — Quickly Grasp the Project's Big Picture
$ cd ~/company-monorepo
$ claude --permission-mode plan
╭─ 🔒 Plan Mode ──────────────────────────────────────╮
│ Safe exploration — no files will be modified │
╰──────────────────────────────────────────────────────╯
> Give me a complete architectural overview of this project
╭─ Claude ─────────────────────────────────────────────╮
│ │
│ 🔍 Tool: Glob (**/package.json) │
│ → Found 8 packages (monorepo) │
│ │
│ 🔍 Tool: Read (package.json) │
│ → Workspace root: Turborepo + pnpm │
│ │
│ 🔍 Tool: Glob (apps/**/src/index.*) │
│ → 3 applications found │
│ │
│ 🔍 Tool: Read (apps/web/package.json) │
│ 🔍 Tool: Read (apps/api/package.json) │
│ 🔍 Tool: Read (apps/admin/package.json) │
│ 🔍 Tool: Glob (packages/*) │
│ │
│ ## 🏗️ Project Architecture │
│ │
│ **Type**: Turborepo Monorepo (pnpm workspaces) │
│ │
│ **Application Layer (apps/)** │
│ ├── `web/` → Next.js 14 Frontend (App Router) │
│ ├── `api/` → Express + Prisma REST API │
│ └── `admin/` → Astro SSR Admin Backend │
│ │
│ **Shared Layer (packages/)** │
│ ├── `ui/` → React Component Library (Radix + Tailwind)│
│ ├── `db/` → Prisma schema + Generated Client │
│ ├── `config/` → ESLint / TS Shared Configuration │
│ └── `utils/` → Common Utility Functions │
│ │
│ **Tech Stack** │
│ • Frontend: React 19 + Next.js 14 + Tailwind CSS │
│ • Backend: Express + Prisma + PostgreSQL │
│ • Build: Turborepo + pnpm │
│ • Deployment: Vercel (web) + Railway (api) │
│ │
╰──────────────────────────────────────────────────────╯
Scenario 2: Locate — Find the Entry Point for a Specific Feature
> Where is the user registration logic? Which files are involved?
╭─ Claude ─────────────────────────────────────────────╮
│ │
│ 🔍 Tool: Grep ("register" across apps/api/src/**) │
│ → 7 matches in 4 files │
│ │
│ 🔍 Tool: Grep ("signup" across apps/web/src/**) │
│ → 5 matches in 3 files │
│ │
│ 🔍 Tool: Read (apps/api/src/routes/auth.ts) │
│ 🔍 Tool: Read (apps/api/src/services/user.ts) │
│ 🔍 Tool: Read (apps/web/src/app/signup/page.tsx) │
│ │
│ ## User Registration Call Chain │
│ │
│ ``` │
│ Frontend Backend │
│ ───── ───── │
│ signup/page.tsx │
│ └── useSignup() hook │
│ └── POST /api/auth/register │
│ └── routes/auth.ts:L45 │
│ └── UserService.create() │
│ ├── Password bcrypt encryption │
│ ├── Prisma user.create() │
│ ├── Sends verification email │
│ └── Returns JWT token │
│ ``` │
│ │
│ **Key File List**: │
│ 1. `apps/web/src/app/signup/page.tsx` — Registration Form│
│ 2. `apps/web/src/hooks/useSignup.ts` — Frontend Hook │
│ 3. `apps/api/src/routes/auth.ts:L45` — Route Handler │
│ 4. `apps/api/src/services/user.ts` — Business Logic │
│ 5. `packages/db/prisma/schema.prisma` — User Model │
│ │
╰──────────────────────────────────────────────────────╯
Scenario 3: Deep Dive — Trace Specific Implementation Details
> What algorithm is used for password encryption? What are the salt rounds?
How are verification emails sent?
╭─ Claude ─────────────────────────────────────────────╮
│ │
│ 🔍 Tool: Grep ("bcrypt" across apps/api/**) │
│ 🔍 Tool: Read (apps/api/src/services/user.ts) │
│ 🔍 Tool: Grep ("sendEmail\|mailer\|smtp" │
│ across apps/api/**) │
│ 🔍 Tool: Read (apps/api/src/lib/email.ts) │
│ 🔍 Tool: Read (apps/api/.env.example) │
│ │
│ ## Password Encryption │
│ • Algorithm: **bcrypt** (via `bcryptjs` package) │
│ • Salt rounds: **12** (defined in user.ts:L8) │
│ • Code: `await bcrypt.hash(password, 12)` │
│ │
│ ## Email Sending │
│ • Service: **Resend** (Not SMTP, uses API calls) │
│ • Encapsulated in: `apps/api/src/lib/email.ts` │
│ • Template: Uses React Email (`@react-email/components`)│
│ • Environment Variable: `RESEND_API_KEY` (see .env.example)│
│ │
│ ⚠️ Note: salt rounds=12 is suitable for production environments,│
│ but may lead to slow speeds in unit tests; it is recommended to reduce it to 4 in test environments.│
│ │
╰──────────────────────────────────────────────────────╯
💻 Code Demo: Efficient Prompts for Exploration
# Overview Level
claude -p "Give me an architectural overview of this project, including the tech stack and directory structure"
claude -p "What are the main data models in this project? Draw a text-based ER diagram"
# Location Level
claude -p "Which file is responsible for handling user login?"
claude -p "Which files call the Stripe API?"
claude -p "Find all places marked with TODO or FIXME"
# Deep Dive Level
claude -p "Explain the rate limiting algorithm in src/middleware/rateLimit.ts"
claude -p "Trace the entire payment process starting from when the checkout button is clicked"
# Code Auditing
claude -p "Check for SQL injection risks under src/api/"
claude -p "Review the security of the authentication module and list all potential vulnerabilities"
🔧 Tools Involved
| Tool |
Exploration Phase |
Typical Usage |
Glob |
Overview |
Glob(**/*.ts) Discover project structure |
Read |
Deep Dive |
Read(package.json) Read specific files |
Grep |
Locate |
Grep("stripe" in src/**) Full-text search |
Bash |
Auxiliary |
Bash(wc -l src/**/*.ts) Count lines of code |
WebFetch |
External Reference |
Fetch third-party library documentation for analysis |
📝 Key Takeaways from this Issue
- Exploring codebases with natural language is more efficient than
grep because Claude can understand semantics
- Follow the three-layer exploration method: Overview → Locate → Deep Dive
- Plan Mode is suitable for safe exploration of unfamiliar codebases (zero risk)
- Claude automatically combines multiple search tools to trace cross-file call chains
- Print Mode (
-p) can quickly output analysis results to the terminal
🔗 References