Skip to content

Update CLAUDE.md with comprehensive context engineering documentation #49

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
LORDBurnItUp wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update CLAUDE.md with comprehensive context engineering documentation #49

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
281 changes: 232 additions & 49 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,59 +1,242 @@
### 🔄 Project Awareness & Context
- **Always read `PLANNING.md`** at the start of a new conversation to understand the project's architecture, goals, style, and constraints.
- **Check `TASK.md`** before starting a new task. If the task isn’t listed, add it with a brief description and today's date.
- **Use consistent naming conventions, file structure, and architecture patterns** as described in `PLANNING.md`.
- **Use venv_linux** (the virtual environment) whenever executing Python commands, including for unit tests.

### 🧱 Code Structure & Modularity
- **Never create a file longer than 500 lines of code.** If a file approaches this limit, refactor by splitting it into modules or helper files.
- **Organize code into clearly separated modules**, grouped by feature or responsibility.
For agents this looks like:
- `agent.py` - Main agent definition and execution logic
- `tools.py` - Tool functions used by the agent
- `prompts.py` - System prompts
- **Use clear, consistent imports** (prefer relative imports within packages).
- **Use clear, consistent imports** (prefer relative imports within packages).
- **Use python_dotenv and load_env()** for environment variables.

### 🧪 Testing & Reliability
- **Always create Pytest unit tests for new features** (functions, classes, routes, etc).
- **After updating any logic**, check whether existing unit tests need to be updated. If so, do it.
- **Tests should live in a `/tests` folder** mirroring the main app structure.
- Include at least:
- 1 test for expected use
- 1 edge case
- 1 failure case

### ✅ Task Completion
- **Mark completed tasks in `TASK.md`** immediately after finishing them.
- Add new sub-tasks or TODOs discovered during development to `TASK.md` under a “Discovered During Work” section.

### 📎 Style & Conventions
- **Use Python** as the primary language.
- **Follow PEP8**, use type hints, and format with `black`.
- **Use `pydantic` for data validation**.
- Use `FastAPI` for APIs and `SQLAlchemy` or `SQLModel` for ORM if applicable.
- Write **docstrings for every function** using the Google style:
# 🎯 Context Engineering Template - Global Rules for AI Assistants

This repository is a comprehensive template for **Context Engineering** - the discipline of engineering context for AI coding assistants. This CLAUDE.md file provides global instructions that AI assistants should follow when working in this repository.

## 📋 Repository Structure

This is a **template repository** with multiple use cases demonstrating context engineering patterns:

```
context-engineering-intro/
├── .claude/
│ └── commands/ # Slash commands for workflows
│ ├── generate-prp.md # Generate Product Requirements Prompts
│ └── execute-prp.md # Execute PRPs to implement features
├── PRPs/ # Product Requirements Prompts
│ ├── templates/
│ │ └── prp_base.md # Base PRP template
│ └── EXAMPLE_*.md # Example PRPs
├── examples/ # Code examples (add your own)
├── use-cases/ # Specialized use case templates
│ ├── pydantic-ai/ # Building PydanticAI agents
│ ├── agent-factory-with-subagents/ # Multi-agent factory system
│ ├── mcp-server/ # Building MCP servers
│ ├── template-generator/ # Template generation
│ └── ai-coding-workflows-foundation/ # AI workflow foundation
├── claude-code-full-guide/ # Complete Claude Code documentation
├── CLAUDE.md # This file - global rules
├── INITIAL.md # Template for feature requests
├── INITIAL_EXAMPLE.md # Example feature request
└── README.md # Getting started guide
```

## 🎯 Primary Workflow: PRP Pattern

This repository implements the **PRP (Product Requirements Prompt) workflow** for systematic feature implementation:

### Step 1: Create Feature Request (INITIAL.md)
Define what you want to build with:
- **FEATURE**: Detailed description of functionality
- **EXAMPLES**: Reference code patterns and existing files
- **DOCUMENTATION**: Links to relevant docs, APIs, libraries
- **OTHER CONSIDERATIONS**: Gotchas, requirements, edge cases

### Step 2: Generate PRP
```bash
/generate-prp INITIAL.md
```
This command:
1. Researches the codebase for similar patterns
2. Searches for relevant documentation
3. Creates a comprehensive implementation blueprint in `PRPs/`
4. Includes validation gates and test requirements

### Step 3: Execute PRP
```bash
/execute-prp PRPs/your-feature-name.md
```
This command:
1. Reads all context from the PRP
2. Creates detailed implementation plan (use TodoWrite tool)
3. Implements each step with validation
4. Runs tests and fixes issues
5. Ensures all success criteria are met

## 🔄 Working with Use Cases

Each use case in `use-cases/` has its own specialized context:

- **When working in `use-cases/pydantic-ai/`**: Follow the PydanticAI-specific rules in that directory's CLAUDE.md
- **When working in `use-cases/agent-factory-with-subagents/`**: Follow the agent factory orchestration workflow
- **When working in `use-cases/mcp-server/`**: Follow MCP server development patterns
- **When at repository root**: Follow the general rules below

## 🧱 Code Structure & Modularity

- **Never create a file longer than 500 lines of code.** Refactor by splitting into modules when approaching this limit.
- **Organize code into clearly separated modules**, grouped by feature or responsibility:
- For **AI agents**: `agent.py`, `tools.py`, `prompts.py`, `models.py`, `dependencies.py`
- For **APIs**: `routes/`, `services/`, `models/`, `schemas/`
- For **libraries**: Logical module separation by feature
- **Use clear, consistent imports** (prefer relative imports within packages)
- **Use python-dotenv and load_dotenv()** for environment variables - never hardcode secrets
- **Create .env.example files** showing required environment variables

## 🧪 Testing & Reliability

- **Always create comprehensive tests** for new features using pytest
- **Tests should mirror the main structure** in a `/tests` folder
- **Include at least**:
- 1 test for expected/happy path
- 1 edge case test
- 1 failure/error case test
- **For AI agents**: Use TestModel/FunctionModel for testing without API calls
- **Run tests before marking tasks complete**

## ✅ Task Management with TodoWrite

- **Use TodoWrite tool proactively** for multi-step tasks to track progress
- **Create specific, actionable items** with clear completion criteria
- **Mark tasks completed immediately** after finishing them
- **Keep exactly ONE task in_progress** at any time
- **Include both forms** for each task:
- `content`: Imperative form ("Run tests", "Build feature")
- `activeForm`: Present continuous ("Running tests", "Building feature")

## 📎 Style & Conventions

### Python (Primary Language)
- **Follow PEP8** with type hints throughout
- **Use `pydantic` for data validation** and settings management
- **Use `black` for formatting** (or ruff format)
- **Write docstrings for every function** using Google style:
```python
def example():
def example(param1: str) -> dict:
"""
Brief summary.
Brief summary of what function does.

Args:
param1 (type): Description.
param1: Description of parameter.

Returns:
type: Description.
Description of return value.
"""
```

### 📚 Documentation & Explainability
- **Update `README.md`** when new features are added, dependencies change, or setup steps are modified.
- **Comment non-obvious code** and ensure everything is understandable to a mid-level developer.
- When writing complex logic, **add an inline `# Reason:` comment** explaining the why, not just the what.
### Security Best Practices
- **Never hardcode API keys or secrets**
- **Always use .env files** with python-dotenv
- **Validate all external inputs** using Pydantic models
- **Implement proper error handling** without exposing sensitive information

## 📚 Documentation & Explainability

- **Update README.md** when features are added or setup steps change
- **Comment non-obvious code** for mid-level developer understanding
- **Add inline `# Reason:` comments** for complex logic explaining the "why"
- **Create comprehensive PRPs** with all necessary context for one-pass implementation
- **Include validation gates** in PRPs (executable commands that must pass)

## 🧠 AI Assistant Behavior Rules

### Context Engineering Principles
- **Always use the PRP workflow** for complex features (3+ steps)
- **Research extensively** before generating PRPs:
- Search codebase for similar patterns
- Find relevant documentation online
- Identify integration points and gotchas
- **Include ALL necessary context** in PRPs:
- Documentation URLs with specific sections
- Code examples from the codebase
- Library quirks and version-specific issues
- Existing patterns to follow

### General Behavior
- **Never assume missing context** - ask clarifying questions
- **Never hallucinate libraries or functions** - only use verified packages
- **Always confirm file paths exist** before referencing them
- **Never delete or overwrite code** unless explicitly instructed
- **Avoid over-engineering**:
- Don't add unrequested features
- Don't create abstractions for one-time operations
- Don't add error handling for impossible scenarios
- Keep solutions simple and focused
- **Use specialized tools over bash** when available (Read, Edit, Write, Glob, Grep)
- **Use the Explore agent** for codebase exploration rather than direct searches

### Proactive Tool Usage
- **Use TodoWrite** for multi-step tasks to track progress
- **Use Task tool with Explore agent** for codebase questions
- **Use WebSearch** for researching documentation and best practices
- **Use parallel tool calls** when operations are independent

## 🎨 Context Engineering Best Practices

### When Creating PRPs
1. **Be explicit and comprehensive** - don't assume the AI knows preferences
2. **Provide many examples** - show what to do AND what not to do
3. **Include validation gates** - executable tests that must pass
4. **Reference documentation** - specific URLs and sections
5. **Document gotchas** - library quirks, common pitfalls, version issues

### When Executing PRPs
1. **Read the entire PRP first** - understand all context and requirements
2. **Create detailed plan with TodoWrite** - break down into manageable steps
3. **Follow patterns from examples** - don't invent new approaches
4. **Run validation gates** - iterate until all tests pass
5. **Verify success criteria** - ensure all requirements met

## 🔍 Slash Commands Reference

Custom commands available in `.claude/commands/`:

- **`/generate-prp INITIAL.md`** - Generate comprehensive Product Requirements Prompt
- **`/execute-prp PRPs/feature.md`** - Execute PRP to implement feature
- Use case-specific commands may be available in `use-cases/*/. claude/commands/`

## 🚨 Important Anti-Patterns to Avoid

### NEVER:
- ❌ Skip the PRP workflow for complex features
- ❌ Hardcode API keys, secrets, or sensitive data
- ❌ Create files without reading similar existing files first
- ❌ Skip testing phases or mark tasks complete with failing tests
- ❌ Ignore validation gates in PRPs
- ❌ Over-engineer with unnecessary abstractions
- ❌ Add backwards-compatibility hacks for unused code
- ❌ Create PLANNING.md or TASK.md files (use TodoWrite tool instead)
- ❌ Commit to implementing before understanding requirements

### ALWAYS:
- ✅ Use environment variables via python-dotenv
- ✅ Create comprehensive tests for new features
- ✅ Follow existing code patterns and conventions
- ✅ Document implementation decisions
- ✅ Validate against requirements before marking complete
- ✅ Use TodoWrite for task tracking on multi-step features
- ✅ Ask clarifying questions when requirements are unclear

## 📖 Learning Resources

- **README.md** - Quick start guide and overview
- **claude-code-full-guide/README.md** - Complete Claude Code documentation
- **PRPs/templates/prp_base.md** - Template for creating PRPs
- **PRPs/EXAMPLE_*.md** - Example PRPs showing best practices
- **use-cases/** - Specialized templates for different use cases

## 🎓 Using This Template

This repository serves as both:
1. **A template** - Fork or copy for your own projects
2. **A learning resource** - Study the patterns and workflows
3. **A use case library** - Explore specialized implementations

When starting a new project:
1. Copy relevant files (CLAUDE.md, INITIAL.md, .claude/commands/)
2. Customize for your tech stack and conventions
3. Add your own examples to the `examples/` directory
4. Create PRPs for your features using the workflow

---

### 🧠 AI Behavior Rules
- **Never assume missing context. Ask questions if uncertain.**
- **Never hallucinate libraries or functions** – only use known, verified Python packages.
- **Always confirm file paths and module names** exist before referencing them in code or tests.
- **Never delete or overwrite existing code** unless explicitly instructed to or if part of a task from `TASK.md`.
**Remember**: Context Engineering is about providing AI assistants with **all the information they need** to implement features correctly on the first try. The more context you provide upfront, the better the results.