Skip to content

Prompt Cookbook

Jump to bottom
Lisa edited this page Dec 18, 2025 · 14 revisions

CKB Prompt Cookbook

Real prompts for real problems. Copy, paste, and adapt these to your codebase.

New to CKB or MCP? This page shows you what to ask your AI assistant when CKB is connected. These prompts work with Claude Code, Claude Desktop, or any MCP-compatible tool.

Table of Contents

Getting Started

Core Recipes

Workflow Sequences

Reference

Why This Matters

Without CKB, your AI assistant is guessing. It searches for text patterns, reads random files, and hopes for the best. With CKB, it has actual code intelligence—it knows what calls what, who owns what, and what's risky to change.

You don't need to be an expert to use these prompts. If you're new to a codebase (or new to coding), CKB helps you ask the right questions and get structured answers instead of walls of text.

Quick Reference

I want to... Start with this prompt
Find where something is defined "Search for symbols named X"
Understand how code flows "Trace how X is reached from entrypoints"
Debug an error "Trace how X is called and show recent changes nearby"
Know if a change is safe "What's the impact of changing X?"
Review a PR intelligently "Summarize the diff and highlight risks"
Learn a new module "Explain the internal/X module"
Understand a file's purpose "Explain what this file does and its role"
Find dead code "Is X still used? Should I keep or remove it?"
Find who to ask "Who owns internal/api?"
See what's volatile "Show me hotspots in the codebase"
Generate a cleanup plan "Audit this repo and produce a prioritized improvement report"

Find the Symbol

When to use

  • You know a function/type name but not where it lives
  • You want to find all variations (Handler, handleRequest, etc.)
  • You're searching for something you saw in logs or errors

Prompts

Basic search:

Search for symbols named "authenticate"

Filtered search:

Find all functions containing "user" in the internal/api module

Type-specific:

Show me all interfaces in this codebase

What to expect

Found 3 symbols matching "authenticate":

1. UserService.Authenticate (method)
   Location: internal/auth/service.go:45
   Signature: func (s *UserService) Authenticate(ctx context.Context, creds Credentials) (*User, error)

2. AuthenticateMiddleware (function)
   Location: internal/api/middleware.go:23
   Signature: func AuthenticateMiddleware(next http.Handler) http.Handler

3. Authenticator (interface)
   Location: internal/auth/types.go:12
   Signature: type Authenticator interface { ... }

If results aren't helpful

Problem Try this instead
Too many results Add a scope: "Search for authenticate in internal/auth"
Wrong kind of symbol Filter by kind: "Find functions named authenticate"
Nothing found Try partial name: "Search for auth"
Misspelled? CKB does fuzzy matching, but check spelling

Follow-up prompts

  • "Explain the UserService.Authenticate symbol"
  • "Who calls UserService.Authenticate?"
  • "What's the impact of changing this?"

Trace Request Flow from Entrypoints

When to use

  • You're debugging and need to understand how a request reaches some code
  • You want to see the full call chain from API/CLI to a function
  • You're new and want to understand how the system processes requests

Prompts

Trace from all entrypoints:

How is the ProcessPayment function reached? Show me the call paths from API endpoints.

Trace specific entrypoint types:

Trace how UserService.Create is called from CLI commands

List entrypoints first:

What are the main entrypoints in this codebase? Show me API endpoints and CLI commands.

What to expect

ProcessPayment is reached via 2 paths:

Path 1: API → ProcessPayment (confidence: 0.95)
  POST /api/v1/checkout
  → CheckoutHandler.Handle (internal/api/checkout.go:34)
  → OrderService.Complete (internal/orders/service.go:89)
  → PaymentService.ProcessPayment (internal/payments/service.go:45)

Path 2: Job → ProcessPayment (confidence: 0.89)
  RetryFailedPayments (cron job)
  → PaymentService.RetryPending (internal/payments/service.go:112)
  → PaymentService.ProcessPayment (internal/payments/service.go:45)

Entrypoint types: api, job

If results aren't helpful

Problem Try this instead
No paths found The symbol might be internal—try "Show me what calls X directly"
Too many paths Filter by type: "Trace from API endpoints only"
Paths seem incomplete Check if SCIP index is fresh: "Run ckb doctor"
Want more detail "Show me the call graph for X with depth 3"

Follow-up prompts

  • "Explain the CheckoutHandler file"
  • "What else does OrderService.Complete call?"
  • "Is POST /api/v1/checkout a risky endpoint?"

Bug Investigation

When to use

  • You're debugging an error and need to find the root cause
  • You see a stack trace and want to understand the flow
  • Something broke and you need to find what changed recently
  • You want to trace back from a symptom to its source

Prompts

Trace the error path:

I'm seeing an error in FooHandler. Trace how it's reached from entrypoints and show me the call chain.

Find recent changes:

What changed recently near ProcessPayment? Show me hotspots and recent commits in that area.

Understand dependencies:

UserService.Authenticate is failing. What does it depend on? What could cause it to fail?

Combine tracing with context:

This error happens in OrderService.Complete. Show me:
1. How it's reached from the API
2. What it calls downstream
3. Recent changes to this code

What to expect

Bug Investigation: FooHandler error

Call Path (from entrypoint):
  POST /api/v1/foo
  → FooHandler.Handle (internal/api/foo.go:23)
  → FooService.Process (internal/foo/service.go:45)
  → Database.Query (internal/storage/db.go:89)  ← error originates here

Dependencies of Database.Query:
  - ConnectionPool (internal/storage/pool.go)
  - QueryBuilder (internal/storage/query.go)
  - Logger (internal/logging/logger.go)

Recent Activity (last 7 days):
  ⚠️ internal/storage/db.go - 3 commits, 2 authors
     - abc123: "Optimize query timeout" (2 days ago)
     - def456: "Add connection retry" (5 days ago)

Hotspot Status: INCREASING (was stable, now volatile)

Suggested Investigation:
  - Check commit abc123 "Optimize query timeout" - most recent change
  - Review ConnectionPool for connection issues

If results aren't helpful

Problem Try this instead
Can't find the symbol "Search for symbols containing 'Foo'" first
Path seems wrong Check if you're looking at the right function (overloads?)
No recent changes Expand time window: "Show changes in last 30 days"
Need more context "Explain the Database.Query symbol and its callers"

Follow-up prompts

  • "Show me the diff for commit abc123"
  • "What tests cover Database.Query?"
  • "Who owns internal/storage? I need to ask them about this."

Understand a File or Path

When to use

  • You landed on a file and don't know what it's for
  • You want quick orientation before reading code
  • You're trying to understand why a path exists
  • You need to classify: is this core, legacy, glue code, or tests?

Prompts

File explanation:

Explain what internal/query/engine.go does and what I should read next.

Path role:

Why does internal/legacy/handler.go exist? Is it core, glue, legacy, or test-only?

Quick orientation:

Give me a quick overview of internal/api/middleware.go - key functions, what it imports, what uses it.

What to expect

File: internal/query/engine.go

Role: core (main query processing logic)

Purpose: Central query engine that coordinates all CKB operations.
This is the main entry point for query processing.

Key Symbols (top 5):
  - Engine (struct) - Main query engine type
  - Engine.Search - Symbol search implementation
  - Engine.GetReferences - Find all usages
  - Engine.AnalyzeImpact - Change impact analysis
  - NewEngine - Constructor

Imports:
  ← internal/backends (SCIP, LSP, Git adapters)
  ← internal/cache (query caching)
  ← internal/compression (response optimization)

Used By:
  → internal/api (HTTP handlers)
  → internal/mcp (MCP tool handlers)
  → internal/cli (CLI commands)

Local Hotspots:
  Engine.Search - modified 3 times in 30 days

Read Next:
  - internal/backends/orchestrator.go (how backends are coordinated)
  - internal/query/types.go (query/response types)

If results aren't helpful

Problem Try this instead
Too high-level "Show me the signatures of key functions in this file"
File not found Check the path, or "Search for files named engine.go"
Want more detail "Explain the Engine.Search function specifically"
Need context "What module does this file belong to?"

Follow-up prompts

  • "Show me how Engine.Search is called"
  • "What's the impact of changing Engine?"
  • "Who owns this file?"

Blast Radius / Impact Analysis

When to use

  • Before refactoring a function
  • Before changing a public API
  • When reviewing someone else's changes
  • When deciding if a change needs more testing

Prompts

Basic impact:

What's the impact of changing UserService.Authenticate?

With risk assessment:

Analyze the blast radius if I modify the Response struct. Is this a risky change?

Scope to tests:

What tests would be affected if I change the Database.Query method?

What to expect

Impact Analysis: UserService.Authenticate

Risk Score: HIGH (0.82)

Visibility: public (exported, used across modules)

Direct Callers (12):
  - AuthenticateMiddleware (internal/api/middleware.go:45)
  - LoginHandler.Handle (internal/api/auth.go:23)
  - RefreshTokenHandler.Handle (internal/api/auth.go:89)
  ... and 9 more

Affected Modules (4):
  - internal/api (8 callers)
  - internal/admin (2 callers)
  - internal/jobs (1 caller)
  - tests (15 references)

Breaking Change Risk:
  ⚠️ Signature change would break 12 callers
  ⚠️ Return type change affects error handling in 8 places

Suggested Drilldowns:
  - "Show callers in internal/api"
  - "What tests cover UserService.Authenticate?"

If results aren't helpful

Problem Try this instead
Risk seems too high/low "Explain why UserService.Authenticate has high risk"
Missing callers Index might be stale—regenerate SCIP index
Want transitive impact "Show impact with depth 3" (follows callers of callers)
Need owner info "Who owns the code that calls UserService.Authenticate?"

Follow-up prompts

  • "Show me all 12 direct callers"
  • "Which of these callers are in production code vs tests?"
  • "What's the safest way to change this without breaking callers?"

Summarize PR Diff by Risk

When to use

  • Reviewing a pull request
  • Understanding what changed in a commit range
  • Checking if recent changes are risky before deploying
  • Catching up on what happened while you were away

Prompts

For a PR:

Summarize PR #123 and highlight any risky changes

For a commit range:

What changed between main and feature/new-auth? Summarize by risk level.

For recent changes:

Summarize changes in the last 7 days. What's most likely to cause problems?

For a specific commit:

Explain commit abc123 and its potential impact

What to expect

PR #123 Summary: "Add rate limiting to API"

Files Changed: 8
Lines: +245 / -32

Risk Assessment: MEDIUM

High Risk Changes:
  ⚠️ internal/api/middleware.go
     - Modified request handling path
     - Affects all API endpoints
     - 3 functions changed: RateLimiter, CheckLimit, ResetBucket

  ⚠️ internal/api/config.go
     - New configuration options
     - Defaults may affect existing deployments

Medium Risk Changes:
  ⚡ internal/api/errors.go
     - New error type: RateLimitExceeded
     - Added to error handling chain

Low Risk Changes:
  ✓ internal/api/middleware_test.go (tests)
  ✓ docs/rate-limiting.md (documentation)

Suggested Reviewers: @api-team, @security-team
Suggested Tests: Run API integration tests, load tests

Hotspot Warning:
  internal/api/middleware.go has been modified 8 times in 30 days
  (trend: increasing)

If results aren't helpful

Problem Try this instead
PR not found Make sure you're in the right repo, or use commit range instead
Risk seems wrong "Explain why middleware.go is high risk"
Want more detail on a file "Explain the changes to internal/api/middleware.go"
Need ownership info "Who should review changes to internal/api?"

Follow-up prompts

  • "Show me the impact of the RateLimiter changes"
  • "What tests cover the modified code?"
  • "Are there any architectural decisions related to rate limiting?"

Dead Code Cleanup

When to use

  • You suspect something isn't used anymore
  • You're cleaning up after a migration
  • You want to remove deprecated code safely
  • You're doing a codebase cleanup sprint

Prompts

Check if something is used:

Is the LegacyAuthenticator still used? Should I keep it or remove it?

Get a verdict:

Justify whether I should keep or remove the ValidateV1 function.

Find unused code in a module:

Are there any unused exports in internal/utils?

Check deprecated code:

What still calls the deprecated ProcessV1 function? Can I remove it?

What to expect

Symbol: LegacyAuthenticator

Verdict: REMOVE (confidence: 0.92)

Reasoning:
  - No direct callers found in production code
  - Only referenced in 2 test files (test-only usage)
  - Marked @deprecated in documentation
  - Last modified 8 months ago
  - Superseded by: Authenticator (new implementation)

References Found:
  - internal/auth/legacy_test.go:23 (test)
  - internal/auth/legacy_test.go:45 (test)

Safe to Remove:
  ✓ No production callers
  ✓ Tests can be removed with it
  ⚠️ Check if external packages depend on it (not indexed)

Suggested Actions:
  1. Remove LegacyAuthenticator and its tests
  2. Search for string references: "LegacyAuthenticator" in configs
  3. Check CHANGELOG for migration notes

If results aren't helpful

Problem Try this instead
Says "keep" but you think it's dead "Show me ALL references to LegacyAuthenticator, including tests"
Uncertain verdict "Explain why LegacyAuthenticator might still be needed"
External dependencies CKB only indexes your repo—check external consumers manually
Want to see the code "Show me the LegacyAuthenticator symbol details"

Follow-up prompts

  • "What replaced LegacyAuthenticator?"
  • "Show me the file where LegacyAuthenticator is defined"
  • "Are there any ADRs about deprecating the legacy auth?"

Onboarding to an Unfamiliar Module

When to use

  • You're new to the codebase
  • You need to work in a module you've never touched
  • You're reviewing code in an area you don't know
  • You want the "lay of the land" before diving in

Prompts

Module overview:

Explain the internal/payments module. What does it do and what are the key types?

Architecture first:

Show me the architecture of this codebase. What are the main modules and how do they connect?

Key concepts:

What are the main domain concepts in this codebase?

File orientation:

Explain internal/payments/service.go. What's this file for?

Find the important stuff:

What are the most important symbols in the internal/auth module?

What to expect

Module: internal/payments

Responsibility: Payment processing and transaction management

Key Types:
  - PaymentService (main service, 12 methods)
  - Transaction (domain model)
  - PaymentProvider (interface for Stripe/PayPal)
  - PaymentResult (return type for operations)

Key Functions:
  - ProcessPayment - Main entry point for payments
  - RefundTransaction - Handle refunds
  - ValidateCard - Card validation logic

Dependencies:
  → internal/users (gets user info)
  → internal/orders (updates order status)
  ← internal/api (called by handlers)
  ← internal/jobs (called by retry jobs)

Owner: @payments-team
Recent Activity: 5 commits in last 30 days (stable)

Entry Points:
  - POST /api/v1/payments (ProcessPayment)
  - POST /api/v1/refunds (RefundTransaction)
  - RetryFailedPayments job (ProcessPayment)

If results aren't helpful

Problem Try this instead
Too high-level "Show me the key symbols in internal/payments with their signatures"
Module not found "What modules exist in this codebase?"
Want relationships "What does internal/payments depend on? What depends on it?"
Need examples "Show me how PaymentService.ProcessPayment is called"

Follow-up prompts

  • "Trace how ProcessPayment is reached from the API"
  • "What tests exist for the payments module?"
  • "Who has been working on payments recently?"

Codebase Improvement Audit

When to use

  • You want a quick, evidence-based cleanup plan (dead folders, duplicated code, dependency bloat, TODO debt)
  • You're preparing for a cleanup sprint or tech-debt week
  • You suspect the repo contains legacy copies, build artifacts, or unused packages

Prompts

Safe default (recommended):

Audit this repository and produce a prioritized codebase improvement report.

Constraints:
- Do not modify files.
- Do not propose refactors unless you can cite specific evidence (paths/symbols/usages).

Output format:
1. Top 10 findings sorted by impact × confidence
2. For each: evidence (file paths, counts/sizes, symbols), why it matters, and a safe next action
3. Confidence: High / Medium / Low
4. Include a verification step before any destructive action (delete/move)

Focus on: obsolete/duplicate dirs, build artifacts, dependency bloat, TODO clusters, and hotspots.

Scope it (faster + less noise):

Audit only internal/api and internal/query. Ignore build/ and generated artifacts.
Same output format as above.

Dependency hygiene:

Check go.mod (or package.json / pubspec.yaml) for:
- Dependencies that should be dev-only
- Unused packages
- Heavy optional dependencies

Give a proposed change list (no edits) + expected impact + how to verify.

What to expect

CKB Codebase Improvement Report

🚨 High Priority: Obsolete / Duplicate Code
┌─────────────────────────────────────────────────────────────────┐
│ Issue: obsolete/legacy-api/                                     │
│ Evidence: 45MB, contains older sources duplicated in internal/  │
│ Why it matters: Wastes disk, confuses onboarding, risk of       │
│   accidental edits to dead code                                 │
│ Confidence: HIGH                                                │
│                                                                 │
│ Action: Delete obsolete/legacy-api/ (after verification)        │
│ Verification:                                                   │
│   1. rg "obsolete/legacy-api" -n  (expect: no references)       │
│   2. Confirm newer implementation exists in internal/api/       │
└─────────────────────────────────────────────────────────────────┘

⚠️ Medium Priority: Dependency Hygiene
┌─────────────────────────────────────────────────────────────────┐
│ Issue: testify in dependencies instead of test-only             │
│ Evidence: go.mod line 45                                        │
│ Confidence: HIGH                                                │
│                                                                 │
│ Action: Move to require block with // test comment              │
│ Verification: go mod tidy && go test ./...                      │
└─────────────────────────────────────────────────────────────────┘

📋 Low Priority: TODO Cluster
┌─────────────────────────────────────────────────────────────────┐
│ Evidence: 23 TODOs across 7 files, concentrated in:             │
│   - internal/cache/manager.go (8 TODOs)                         │
│   - internal/query/engine.go (6 TODOs)                          │
│ Confidence: MEDIUM (some may be intentional placeholders)       │
│                                                                 │
│ Action: Triage into 3 categories (fix now, track, won't fix)    │
│ Verification: Link actionable TODOs to issues/tickets           │
└─────────────────────────────────────────────────────────────────┘

Summary: 3 high, 4 medium, 6 low priority findings
Estimated cleanup effort: 2-3 hours for high priority items

If results aren't helpful

Problem Try this instead
Too generic "Only report findings that include file paths + concrete evidence"
Too many findings "Limit to top 10 by impact × confidence"
Confidence feels low "Show raw evidence: references/usages/sizes and why confidence is low"
Suggests risky deletes "Add verification steps and require 'no references found' before delete"

Follow-up prompts

  • "For finding #1: show me all references/usages that prove it's safe to remove."
  • "Turn the top 5 findings into a 2-week cleanup plan with milestones."
  • "Which findings touch hotspots (high churn) and should be scheduled carefully?"
  • "Create GitHub issues for the top 3 findings with acceptance criteria."

Workflow Sequences

These are the recommended tool sequences for common tasks. You can ask for these explicitly or let CKB chain them automatically.

New Codebase Ramp-Up

The sequence:

getStatus → listKeyConcepts → getArchitecture → listEntrypoints → searchSymbols

As a prompt:

I'm new to this codebase. Give me:
1. System status (is everything working?)
2. Key domain concepts
3. Architecture overview (depth 2)
4. Main entrypoints (API, CLI, jobs)
5. Then I'll search for specific symbols

What you'll learn: Overall health, main concepts, module structure, where requests enter the system.

Bug Investigation

The sequence:

searchSymbols → traceUsage → getCallGraph → recentlyRelevant

As a prompt:

I'm debugging an error in FooHandler. Help me:
1. Find the FooHandler symbol
2. Trace how it's reached from entrypoints
3. Show me its call graph (what it calls, what calls it)
4. What changed recently in related code?

What you'll learn: The exact path to the error, dependencies, and recent changes that might be the cause.

Before Making Changes

The sequence:

searchSymbols → explainSymbol → findReferences → analyzeImpact → getHotspots

As a prompt:

I want to change the authenticate() function. Before I touch it:
1. Find and explain the symbol
2. Show me all references (including tests)
3. Analyze the impact—what breaks if I change this?
4. Is this a hotspot? How volatile is this area?

What you'll learn: Full context of what you're changing, who depends on it, risk level, and recent volatility.

Code Review

The sequence:

summarizeDiff → getHotspots → getOwnership → traceUsage

As a prompt:

Review PR #123 for me:
1. Summarize the diff by risk level
2. Does it touch any hotspots?
3. Who should review these changes?
4. What execution paths are affected?

What you'll learn: Risk assessment, volatility warnings, suggested reviewers, and downstream impact.

Dead Code Sanity Check

The sequence:

searchSymbols → justifySymbol → explainFile

As a prompt:

Is LegacyFoo dead code?
1. Find the symbol
2. Justify: keep, investigate, or remove?
3. Explain the file's role—is it all legacy?

What you'll learn: Whether code is safe to remove, with evidence.

Understanding Module Ownership

The sequence:

getArchitecture → getOwnership → getModuleResponsibilities

As a prompt:

I need to understand who owns what:
1. Show me the module structure
2. Who owns internal/api?
3. What is internal/api responsible for?

What you'll learn: Module boundaries, ownership, and responsibilities.

Recording Design Decisions

The sequence:

getDecisions → recordDecision → annotateModule

As a prompt:

We decided to use Redis for caching. Help me:
1. Check if there are existing decisions about caching
2. Record this new decision as an ADR
3. Link it to the affected modules

What you'll learn: Existing context, and you'll create a permanent record.

More Recipes

"Who should I ask about this code?"

Who owns internal/api/handler.go?

Who are the main contributors to the auth module in the last 90 days?

Suggest reviewers for changes to internal/payments

"What's been causing problems?"

Show me hotspots in the codebase—what's been changing a lot?

What files in internal/api have the highest churn?

Are there any increasing hotspots I should be worried about?

"What decisions led to this?"

Are there any architectural decisions about caching?

Why does the payments module use this pattern? Any ADRs?

Show me all accepted architectural decisions

"Help me understand this error"

I'm seeing an error in ProcessPayment. Trace how it's called and show me the relevant code.

The UserService.Authenticate is failing. What does it depend on?

Tips for Better Results

Be specific about scope

❌ "Find handlers"
✅ "Find HTTP handlers in internal/api"

Ask for what you'll do next

❌ "Show me the auth code"
✅ "I need to add a new auth method. Show me the Authenticator interface and its implementations."

Chain prompts for complex tasks

1. "What modules exist in this codebase?"
2. "Explain the internal/auth module"
3. "Show me the key symbols in internal/auth"
4. "How is UserService.Authenticate called?"
5. "What's the impact of adding a parameter to Authenticate?"

Use CKB tools explicitly when needed

"Use getArchitecture to show me the module structure"
"Use traceUsage to find how this is reached"
"Use analyzeImpact to assess this change"

Always require verification before deletes

❌ "Delete all unused code"
✅ "Show me unused code with evidence, and include verification steps before any delete"

Any finding that recommends deletion should include:

  1. Evidence (no references found, no callers, etc.)
  2. A verification command you can run
  3. Confidence level

When CKB Can't Help

CKB is for navigation and comprehension, not code changes. It won't:

  • Write or modify code for you
  • Generate tests
  • Fix bugs
  • Suggest refactorings
  • Enforce style rules

But it will tell you where to make changes, what might break, and who to ask—so you can make informed decisions.

Troubleshooting

"No results found"

  1. Check if CKB is initialized: ckb status
  2. Regenerate index if stale: scip-go --repository-root=.
  3. Try broader search terms

"Results seem incomplete"

  1. Run diagnostics: ckb doctor
  2. Check index freshness in status
  3. The index might not cover all files—check .ckb/config.json

"I don't have CKB tools available"

  1. Make sure CKB MCP server is configured
  2. Check: claude mcp list should show "ckb"
  3. See MCP Integration for setup

Next Steps

Clone this wiki locally