Prompt Cookbook

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.

---

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"
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"
Find who to ask	"Who owns internal/api?"
See what's volatile	"Show me hotspots in the codebase"

---

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?"

---

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?"

---

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?"

---

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?

"Is this code still used?"

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

Find dead code in internal/utils

What calls the deprecated ValidateV1 function?

"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"

---

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

• Quick Start — Install and configure CKB
• MCP Integration — Connect to Claude Code/Desktop
• User Guide — All CLI commands
• Configuration — Customize CKB behavior