Knowledge Base Builder
Build a structured knowledge base for your domain with notation registries, application databases, design principles, and anti-patterns.
Your project's tribal knowledge lives in Slack threads, meeting notes, and one person's head. When they leave or you onboard someone new, months of context walks out the door or takes weeks to transfer.
Who it's for: teams documenting domain knowledge before it's lost, researchers building reference databases for their field, engineering teams codifying design principles and anti-patterns, organizations creating onboarding knowledge bases, anyone who wants Claude to have persistent context about their domain
Example
"Build a knowledge base for our ML infrastructure" → Structured KB with terminology registry, design principles (validated and rejected), anti-pattern catalog with examples, and application database — Claude can reference it for consistent, domain-aware assistance
New here? 3-minute setup guide → | Already set up? Copy the template below.
# Knowledge Base
## Notation Registry
Track terminology, symbols, and naming conventions:
| Term/Symbol | Meaning | First Introduced | Anti-Pattern |
|-------------|---------|------------------|--------------|
| [term] | [definition] | [where] | [what NOT to do] |
### Example (Software Project):
| Term | Meaning | Introduced | Anti-Pattern |
|------|---------|------------|--------------|
| `User` | Authenticated account holder | models/user.ts | Don't conflate with `Visitor` (unauthenticated) |
| `Order` | A completed purchase | models/order.ts | Don't use for shopping carts (use `Cart`) |
| `userId` | Primary key reference | Throughout | Never use `user_id` (consistency) |
### Example (Academic):
| Symbol | Meaning | Introduced | Anti-Pattern |
|--------|---------|------------|--------------|
| β | Regression coefficient | Lecture 1 | Don't use `b` (reserved for intercept) |
| X | Treatment indicator | Lecture 2 | Don't use `T` (reserved for time) |
## Applications Database
Track real-world examples, use cases, or implementations:
| Application | Source | Dataset/Context | Tools Used | Notes |
|------------|--------|-----------------|------------|-------|
| [name] | [paper/project] | [data] | [tools] | [notes] |
### Example:
| Application | Source | Context | Tools | Notes |
|-------------|--------|---------|-------|-------|
| User Auth | Auth0 docs | OAuth 2.0 | JWT, bcrypt | Reference implementation |
| Payment Flow | Stripe guide | E-commerce | Stripe API | Follow their patterns |
## Design Principles
Track validated design approaches:
| Principle | Evidence/Rationale | Applied Where |
|-----------|-------------------|---------------|
| [principle] | [why it works] | [where used] |
### Example:
| Principle | Evidence | Applied |
|-----------|----------|---------|
| Single Responsibility | Easier testing, clearer code | All components |
| Fail Fast | Catch errors early | Validation layer |
| Convention over Configuration | Less boilerplate | Routing, naming |
## Anti-Patterns
Document what NOT to do:
| Anti-Pattern | Why It's Bad | Better Alternative |
|--------------|--------------|-------------------|
| [pattern] | [problems] | [solution] |
### Example:
| Anti-Pattern | Why Bad | Alternative |
|--------------|---------|-------------|
| God Component | Unmaintainable | Split by responsibility |
| Magic Numbers | Unclear intent | Named constants |
| Deep Nesting | Hard to follow | Early returns, extraction |
## Project State
Track current status and decisions:
| Aspect | Current State | Last Updated |
|--------|---------------|--------------|
| [aspect] | [state] | [date] |
### Example:
| Aspect | State | Updated |
|--------|-------|---------|
| Auth System | Auth0 integrated | 2024-01-15 |
| Database | PostgreSQL 15 | 2024-01-10 |
| Frontend Framework | Next.js 14 | 2024-01-08 |
## Common Pitfalls
Project-specific issues to watch for:
1. **[Pitfall]**: [Description and how to avoid]
2. **[Pitfall]**: [Description and how to avoid]
### Example:
1. **Session Timeout**: Our sessions expire after 30 min. Don't cache user state beyond this.
2. **Timezone Handling**: All dates stored UTC. Always convert for display.
3. **API Rate Limits**: Stripe limits to 100 req/sec. Batch operations.
What This Does
This playbook helps you build a structured knowledge base for your project or domain. It includes registries for notation/terminology, databases of examples/applications, validated design principles, and documented anti-patterns. Claude can then reference this knowledge base for consistent, informed assistance.
Prerequisites
- Claude Code installed and configured
- A domain or project you want to document
Step-by-Step Setup
Step 1: Create knowledge base file
touch KNOWLEDGE_BASE.md
Step 2: Start with notation registry
Document your most important terminology:
# Knowledge Base
## Notation Registry
| Term | Meaning | Context | Anti-Pattern |
|------|---------|---------|--------------|
| `User` | Authenticated account | models/ | Not same as Visitor |
| `Product` | Purchasable item | catalog/ | Not a cart item |
| `Order` | Completed purchase | orders/ | Not a pending cart |
Step 3: Add as you learn
Update the knowledge base when you:
- Introduce new terminology
- Make design decisions
- Discover anti-patterns
- Validate principles
Step 4: Reference from CLAUDE.md
Add to your CLAUDE.md:
## Knowledge Base
Read KNOWLEDGE_BASE.md before any task involving domain concepts.
Use terminology consistently with the notation registry.
Avoid documented anti-patterns.
Example Usage
User:
"Create a new data model for handling subscriptions"
Claude (referencing knowledge base):
Before creating the subscription model, I've reviewed our knowledge base:
Terminology alignment:
- Will use
Subscription(notPlanorMembership— different meanings in our registry)- User reference uses
userId(notuser_id— per convention)Anti-patterns to avoid:
- Won't couple subscription status with auth (listed as anti-pattern)
- Won't store derived data (principle: compute don't store)
Here's the proposed model:
interface Subscription { id: string; userId: string; // References User model plan: PlanType; // Defined in types status: SubscriptionStatus; startedAt: Date; // UTC per our convention renewsAt: Date; // UTC }
User:
"Add 'PlanType' to the knowledge base"
Claude:
Added to Notation Registry:
Term Meaning Context Anti-Pattern PlanTypeSubscription tier enum subscriptions/ Don't use 'Plan' alone (ambiguous with future pricing plans)
Tips
- Start small: Begin with 5-10 entries. Add more as you encounter them.
- Update proactively: When you make a decision, document it immediately.
- Review periodically: Some entries become outdated. Clean up quarterly.
- Make it specific: "Use consistent naming" is useless. "Use camelCase for JS, snake_case for DB" is useful.
Troubleshooting
Problem: Claude doesn't reference the knowledge base
Solution: Add explicit instruction: "Check the knowledge base before starting any task."
Problem: Knowledge base is too large
Solution: Split into sections (core/advanced) or by domain area. Only load relevant sections.
Problem: Entries conflict
Solution: Review conflicts are valuable — they surface inconsistencies in your actual design. Resolve the conflict, then update the entry.