External/context-engineering-intro
1
0
Fork 0
mirror of https://github.com/coleam00/context-engineering-intro.git synced 2025-12-17 09:45:23 +00:00
Code Issues Packages Projects Releases Wiki Activity

Context engineering intro

Browse Source
This commit is contained in:
Cole Medin 2025-07-02 06:54:31 -05:00
parent dc8c843cc5
commit 73d08d2236
11 changed files with 1140 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
.claude/commands/execute-prp.md Normal file
View File

@ -0,0 +1,40 @@
# Execute BASE PRP
Implement a feature using using the PRP file.
## PRP File: $ARGUMENTS
## Execution Process
1. **Load PRP**
- Read the specified PRP file
- Understand all context and requirements
- Follow all instructions in the PRP and extend the research if needed
- Ensure you have all needed context to implement the PRP fully
- Do more web searches and codebase exploration as needed
2. **ULTRATHINK**
- Think hard before you execute the plan. Create a comprehensive plan addressing all requirements.
- Break down complex tasks into smaller, manageable steps using your todos tools.
- Use the TodoWrite tool to create and track your implementation plan.
- Identify implementation patterns from existing code to follow.
3. **Execute the plan**
- Execute the PRP
- Implement all the code
4. **Validate**
- Run each validation command
- Fix any failures
- Re-run until all pass
5. **Complete**
- Ensure all checklist items done
- Run final validation suite
- Report completion status
- Read the PRP again to ensure you have implemented everything
6. **Reference the PRP**
- You can always reference the PRP again if needed
Note: If validation fails, use error patterns in PRP to fix and retry.

69
.claude/commands/generate-prp.md Normal file
View File

@ -0,0 +1,69 @@
# Create PRP
## Feature file: $ARGUMENTS
Generate a complete PRP for general feature implementation with thorough research. Ensure context is passed to the AI agent to enable self-validation and iterative refinement. Read the feature file first to understand what needs to be created, how the examples provided help, and any other considerations.
The AI agent only gets the context you are appending to the PRP and training data. Assuma the AI agent has access to the codebase and the same knowledge cutoff as you, so its important that your research findings are included or referenced in the PRP. The Agent has Websearch capabilities, so pass urls to documentation and examples.
## Research Process
1. **Codebase Analysis**
- Search for similar features/patterns in the codebase
- Identify files to reference in PRP
- Note existing conventions to follow
- Check test patterns for validation approach
2. **External Research**
- Search for similar features/patterns online
- Library documentation (include specific URLs)
- Implementation examples (GitHub/StackOverflow/blogs)
- Best practices and common pitfalls
3. **User Clarification** (if needed)
- Specific patterns to mirror and where to find them?
- Integration requirements and where to find them?
## PRP Generation
Using PRPs/templates/prp_base.md as template:
### Critical Context to Include and pass to the AI agent as part of the PRP
- **Documentation**: URLs with specific sections
- **Code Examples**: Real snippets from codebase
- **Gotchas**: Library quirks, version issues
- **Patterns**: Existing approaches to follow
### Implementation Blueprint
- Start with pseudocode showing approach
- Reference real files for patterns
- Include error handling strategy
- list tasks to be completed to fullfill the PRP in the order they should be completed
### Validation Gates (Must be Executable) eg for python
```bash
# Syntax/Style
ruff check --fix && mypy .
# Unit Tests
uv run pytest tests/ -v
```
*** CRITICAL AFTER YOU ARE DONE RESEARCHING AND EXPLORING THE CODEBASE BEFORE YOU START WRITING THE PRP ***
*** ULTRATHINK ABOUT THE PRP AND PLAN YOUR APPROACH THEN START WRITING THE PRP ***
## Output
Save as: `PRPs/{feature-name}.md`
## Quality Checklist
- [ ] All necessary context included
- [ ] Validation gates are executable by AI
- [ ] References existing patterns
- [ ] Clear implementation path
- [ ] Error handling documented
Score the PRP on a scale of 1-10 (confidence level to succeed in one-pass implementation using claude codes)
Remember: The goal is one-pass implementation success through comprehensive context.

23
.claude/settings.local.json Normal file
View File

@ -0,0 +1,23 @@
{
"permissions": {
"allow": [
"Bash(grep:*)",
"Bash(ls:*)",
"Bash(source:*)",
"Bash(find:*)",
"Bash(mv:*)",
"Bash(mkdir:*)",
"Bash(tree:*)",
"Bash(ruff:*)",
"Bash(touch:*)",
"Bash(cat:*)",
"Bash(ruff check:*)",
"Bash(pytest:*)",
"Bash(python:*)",
"Bash(python -m pytest:*)",
"Bash(python3 -m pytest:*)",
"WebFetch(domain:docs.anthropic.com)"
],
"deny": []
}
}

5
.gitignore vendored Normal file
View File

@ -0,0 +1,5 @@
venv
venv_linux
__pycache__
.ruff_cache
.pytest_cache

59
CLAUDE.md Normal file
View File

@ -0,0 +1,59 @@
### 🔄 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:
```python
def example():
"""
Brief summary.
Args:
param1 (type): Description.
Returns:
type: Description.
"""
```
### 📚 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.
### 🧠 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`.

15
INITIAL.md Normal file
View File

@ -0,0 +1,15 @@
## FEATURE:
[Insert your feature here]
## EXAMPLES:
[Provide and explain examples that you have in the `examples/` folder]
## DOCUMENTATION:
[List out any documentation (web pages, sources for an MCP server like Crawl4AI RAG, etc.) that will need to be referenced during development]
## OTHER CONSIDERATIONS:
[Any other considerations or specific requirements - great place to include gotchas that you see AI coding assistants miss with your projects a lot]

26
INITIAL_EXAMPLE.md Normal file
View File

@ -0,0 +1,26 @@
## FEATURE:
- Pydantic AI agent that has another Pydantic AI agent as a tool.
- Research Agent for the primary agent and then an email draft Agent for the subagent.
- CLI to interact with the agent.
- Gmail for the email draft agent, Brave API for the research agent.
## EXAMPLES:
In the `examples/` folder, there is a README for you to read to understand what the example is all about and also how to structure your own README when you create documentation for the above feature.
- `examples/cli.py` - use this as a template to create the CLI
- `examples/agent/` - read through all of the files here to understand best practices for creating Pydantic AI agents that support different providers and LLMs, handling agent dependencies, and adding tools to the agent.
Don't copy any of these examples directly, it is for a different project entirely. But use this as inspiration and for best practices.
## DOCUMENTATION:
Pydantic AI documentation: https://ai.pydantic.dev/
## OTHER CONSIDERATIONS:
- Include a .env.example, README with instructions for setup including how to configure Gmail and Brave.
- Include the project structure in the README.
- Virtual environment has already been set up with the necessary dependencies.
- Use python_dotenv and load_env() for environment variables

395
PRPs/EXAMPLE_multi_agent_prp.md Normal file
View File

@ -0,0 +1,395 @@
name: "Multi-Agent System: Research Agent with Email Draft Sub-Agent"
description: |
## Purpose
Build a Pydantic AI multi-agent system where a primary Research Agent uses Brave Search API and has an Email Draft Agent (using Gmail API) as a tool. This demonstrates agent-as-tool pattern with external API integrations.
## Core Principles
1. **Context is King**: Include ALL necessary documentation, examples, and caveats
2. **Validation Loops**: Provide executable tests/lints the AI can run and fix
3. **Information Dense**: Use keywords and patterns from the codebase
4. **Progressive Success**: Start simple, validate, then enhance
---
## Goal
Create a production-ready multi-agent system where users can research topics via CLI, and the Research Agent can delegate email drafting tasks to an Email Draft Agent. The system should support multiple LLM providers and handle API authentication securely.
## Why
- **Business value**: Automates research and email drafting workflows
- **Integration**: Demonstrates advanced Pydantic AI multi-agent patterns
- **Problems solved**: Reduces manual work for research-based email communications
## What
A CLI-based application where:
- Users input research queries
- Research Agent searches using Brave API
- Research Agent can invoke Email Draft Agent to create Gmail drafts
- Results stream back to the user in real-time
### Success Criteria
- [ ] Research Agent successfully searches via Brave API
- [ ] Email Agent creates Gmail drafts with proper authentication
- [ ] Research Agent can invoke Email Agent as a tool
- [ ] CLI provides streaming responses with tool visibility
- [ ] All tests pass and code meets quality standards
## All Needed Context
### Documentation & References
```yaml
# MUST READ - Include these in your context window
- url: https://ai.pydantic.dev/agents/
why: Core agent creation patterns
- url: https://ai.pydantic.dev/multi-agent-applications/
why: Multi-agent system patterns, especially agent-as-tool
- url: https://developers.google.com/gmail/api/guides/sending
why: Gmail API authentication and draft creation
- url: https://api-dashboard.search.brave.com/app/documentation
why: Brave Search API REST endpoints
- file: examples/agent/agent.py
why: Pattern for agent creation, tool registration, dependencies
- file: examples/agent/providers.py
why: Multi-provider LLM configuration pattern
- file: examples/cli.py
why: CLI structure with streaming responses and tool visibility
- url: https://github.com/googleworkspace/python-samples/blob/main/gmail/snippet/send%20mail/create_draft.py
why: Official Gmail draft creation example
```
### Current Codebase tree
```bash
.
├── examples/
│ ├── agent/
│ │ ├── agent.py
│ │ ├── providers.py
│ │ └── ...
│ └── cli.py
├── PRPs/
│ └── templates/
│ └── prp_base.md
├── INITIAL.md
├── CLAUDE.md
└── requirements.txt
```
### Desired Codebase tree with files to be added
```bash
.
├── agents/
│ ├── __init__.py # Package init
│ ├── research_agent.py # Primary agent with Brave Search
│ ├── email_agent.py # Sub-agent with Gmail capabilities
│ ├── providers.py # LLM provider configuration
│ └── models.py # Pydantic models for data validation
├── tools/
│ ├── __init__.py # Package init
│ ├── brave_search.py # Brave Search API integration
│ └── gmail_tool.py # Gmail API integration
├── config/
│ ├── __init__.py # Package init
│ └── settings.py # Environment and config management
├── tests/
│ ├── __init__.py # Package init
│ ├── test_research_agent.py # Research agent tests
│ ├── test_email_agent.py # Email agent tests
│ ├── test_brave_search.py # Brave search tool tests
│ ├── test_gmail_tool.py # Gmail tool tests
│ └── test_cli.py # CLI tests
├── cli.py # CLI interface
├── .env.example # Environment variables template
├── requirements.txt # Updated dependencies
├── README.md # Comprehensive documentation
└── credentials/.gitkeep # Directory for Gmail credentials
```
### Known Gotchas & Library Quirks
```python
# CRITICAL: Pydantic AI requires async throughout - no sync functions in async context
# CRITICAL: Gmail API requires OAuth2 flow on first run - credentials.json needed
# CRITICAL: Brave API has rate limits - 2000 req/month on free tier
# CRITICAL: Agent-as-tool pattern requires passing ctx.usage for token tracking
# CRITICAL: Gmail drafts need base64 encoding with proper MIME formatting
# CRITICAL: Always use absolute imports for cleaner code
# CRITICAL: Store sensitive credentials in .env, never commit them
```
## Implementation Blueprint
### Data models and structure
```python
# models.py - Core data structures
from pydantic import BaseModel, Field
from typing import List, Optional
from datetime import datetime
class ResearchQuery(BaseModel):
query: str = Field(..., description="Research topic to investigate")
max_results: int = Field(10, ge=1, le=50)
include_summary: bool = Field(True)
class BraveSearchResult(BaseModel):
title: str
url: str
description: str
score: float = Field(0.0, ge=0.0, le=1.0)
class EmailDraft(BaseModel):
to: List[str] = Field(..., min_items=1)
subject: str = Field(..., min_length=1)
body: str = Field(..., min_length=1)
cc: Optional[List[str]] = None
bcc: Optional[List[str]] = None
class ResearchEmailRequest(BaseModel):
research_query: str
email_context: str = Field(..., description="Context for email generation")
recipient_email: str
```
### List of tasks to be completed
```yaml
Task 1: Setup Configuration and Environment
CREATE config/settings.py:
- PATTERN: Use pydantic-settings like examples use os.getenv
- Load environment variables with defaults
- Validate required API keys present
CREATE .env.example:
- Include all required environment variables with descriptions
- Follow pattern from examples/README.md
Task 2: Implement Brave Search Tool
CREATE tools/brave_search.py:
- PATTERN: Async functions like examples/agent/tools.py
- Simple REST client using httpx (already in requirements)
- Handle rate limits and errors gracefully
- Return structured BraveSearchResult models
Task 3: Implement Gmail Tool
CREATE tools/gmail_tool.py:
- PATTERN: Follow OAuth2 flow from Gmail quickstart
- Store token.json in credentials/ directory
- Create draft with proper MIME encoding
- Handle authentication refresh automatically
Task 4: Create Email Draft Agent
CREATE agents/email_agent.py:
- PATTERN: Follow examples/agent/agent.py structure
- Use Agent with deps_type pattern
- Register gmail_tool as @agent.tool
- Return EmailDraft model
Task 5: Create Research Agent
CREATE agents/research_agent.py:
- PATTERN: Multi-agent pattern from Pydantic AI docs
- Register brave_search as tool
- Register email_agent.run() as tool
- Use RunContext for dependency injection
Task 6: Implement CLI Interface
CREATE cli.py:
- PATTERN: Follow examples/cli.py streaming pattern
- Color-coded output with tool visibility
- Handle async properly with asyncio.run()
- Session management for conversation context
Task 7: Add Comprehensive Tests
CREATE tests/:
- PATTERN: Mirror examples test structure
- Mock external API calls
- Test happy path, edge cases, errors
- Ensure 80%+ coverage
Task 8: Create Documentation
CREATE README.md:
- PATTERN: Follow examples/README.md structure
- Include setup, installation, usage
- API key configuration steps
- Architecture diagram
```
### Per task pseudocode
```python
# Task 2: Brave Search Tool
async def search_brave(query: str, api_key: str, count: int = 10) -> List[BraveSearchResult]:
# PATTERN: Use httpx like examples use aiohttp
async with httpx.AsyncClient() as client:
headers = {"X-Subscription-Token": api_key}
params = {"q": query, "count": count}
# GOTCHA: Brave API returns 401 if API key invalid
response = await client.get(
"https://api.search.brave.com/res/v1/web/search",
headers=headers,
params=params,
timeout=30.0 # CRITICAL: Set timeout to avoid hanging
)
# PATTERN: Structured error handling
if response.status_code != 200:
raise BraveAPIError(f"API returned {response.status_code}")
# Parse and validate with Pydantic
data = response.json()
return [BraveSearchResult(**result) for result in data.get("web", {}).get("results", [])]
# Task 5: Research Agent with Email Agent as Tool
@research_agent.tool
async def create_email_draft(
ctx: RunContext[AgentDependencies],
recipient: str,
subject: str,
context: str
) -> str:
"""Create email draft based on research context."""
# CRITICAL: Pass usage for token tracking
result = await email_agent.run(
f"Create an email to {recipient} about: {context}",
deps=EmailAgentDeps(subject=subject),
usage=ctx.usage # PATTERN from multi-agent docs
)
return f"Draft created with ID: {result.data}"
```
### Integration Points
```yaml
ENVIRONMENT:
- add to: .env
- vars: |
# LLM Configuration
LLM_PROVIDER=openai
LLM_API_KEY=sk-...
LLM_MODEL=gpt-4
# Brave Search
BRAVE_API_KEY=BSA...
# Gmail (path to credentials.json)
GMAIL_CREDENTIALS_PATH=./credentials/credentials.json
CONFIG:
- Gmail OAuth: First run opens browser for authorization
- Token storage: ./credentials/token.json (auto-created)
DEPENDENCIES:
- Update requirements.txt with:
- google-api-python-client
- google-auth-httplib2
- google-auth-oauthlib
```
## Validation Loop
### Level 1: Syntax & Style
```bash
# Run these FIRST - fix any errors before proceeding
ruff check . --fix # Auto-fix style issues
mypy . # Type checking
# Expected: No errors. If errors, READ and fix.
```
### Level 2: Unit Tests
```python
# test_research_agent.py
async def test_research_with_brave():
"""Test research agent searches correctly"""
agent = create_research_agent()
result = await agent.run("AI safety research")
assert result.data
assert len(result.data) > 0
async def test_research_creates_email():
"""Test research agent can invoke email agent"""
agent = create_research_agent()
result = await agent.run(
"Research AI safety and draft email to john@example.com"
)
assert "draft_id" in result.data
# test_email_agent.py
def test_gmail_authentication(monkeypatch):
"""Test Gmail OAuth flow handling"""
monkeypatch.setenv("GMAIL_CREDENTIALS_PATH", "test_creds.json")
tool = GmailTool()
assert tool.service is not None
async def test_create_draft():
"""Test draft creation with proper encoding"""
agent = create_email_agent()
result = await agent.run(
"Create email to test@example.com about AI research"
)
assert result.data.get("draft_id")
```
```bash
# Run tests iteratively until passing:
pytest tests/ -v --cov=agents --cov=tools --cov-report=term-missing
# If failing: Debug specific test, fix code, re-run
```
### Level 3: Integration Test
```bash
# Test CLI interaction
python cli.py
# Expected interaction:
# You: Research latest AI safety developments
# 🤖 Assistant: [Streams research results]
# 🛠 Tools Used:
# 1. brave_search (query='AI safety developments', limit=10)
#
# You: Create an email draft about this to john@example.com
# 🤖 Assistant: [Creates draft]
# 🛠 Tools Used:
# 1. create_email_draft (recipient='john@example.com', ...)
# Check Gmail drafts folder for created draft
```
## Final Validation Checklist
- [ ] All tests pass: `pytest tests/ -v`
- [ ] No linting errors: `ruff check .`
- [ ] No type errors: `mypy .`
- [ ] Gmail OAuth flow works (browser opens, token saved)
- [ ] Brave Search returns results
- [ ] Research Agent invokes Email Agent successfully
- [ ] CLI streams responses with tool visibility
- [ ] Error cases handled gracefully
- [ ] README includes clear setup instructions
- [ ] .env.example has all required variables
---
## Anti-Patterns to Avoid
- ❌ Don't hardcode API keys - use environment variables
- ❌ Don't use sync functions in async agent context
- ❌ Don't skip OAuth flow setup for Gmail
- ❌ Don't ignore rate limits for APIs
- ❌ Don't forget to pass ctx.usage in multi-agent calls
- ❌ Don't commit credentials.json or token.json files
## Confidence Score: 9/10
High confidence due to:
- Clear examples to follow from the codebase
- Well-documented external APIs
- Established patterns for multi-agent systems
- Comprehensive validation gates
Minor uncertainty on Gmail OAuth first-time setup UX, but documentation provides clear guidance.

212
PRPs/templates/prp_base.md Normal file
View File

@ -0,0 +1,212 @@
name: "Base PRP Template v2 - Context-Rich with Validation Loops"
description: |
## Purpose
Template optimized for AI agents to implement features with sufficient context and self-validation capabilities to achieve working code through iterative refinement.
## Core Principles
1. **Context is King**: Include ALL necessary documentation, examples, and caveats
2. **Validation Loops**: Provide executable tests/lints the AI can run and fix
3. **Information Dense**: Use keywords and patterns from the codebase
4. **Progressive Success**: Start simple, validate, then enhance
5. **Global rules**: Be sure to follow all rules in CLAUDE.md
---
## Goal
[What needs to be built - be specific about the end state and desires]
## Why
- [Business value and user impact]
- [Integration with existing features]
- [Problems this solves and for whom]
## What
[User-visible behavior and technical requirements]
### Success Criteria
- [ ] [Specific measurable outcomes]
## All Needed Context
### Documentation & References (list all context needed to implement the feature)
```yaml
# MUST READ - Include these in your context window
- url: [Official API docs URL]
why: [Specific sections/methods you'll need]
- file: [path/to/example.py]
why: [Pattern to follow, gotchas to avoid]
- doc: [Library documentation URL]
section: [Specific section about common pitfalls]
critical: [Key insight that prevents common errors]
- docfile: [PRPs/ai_docs/file.md]
why: [docs that the user has pasted in to the project]
```
### Current Codebase tree (run `tree` in the root of the project) to get an overview of the codebase
```bash
```
### Desired Codebase tree with files to be added and responsibility of file
```bash
```
### Known Gotchas of our codebase & Library Quirks
```python
# CRITICAL: [Library name] requires [specific setup]
# Example: FastAPI requires async functions for endpoints
# Example: This ORM doesn't support batch inserts over 1000 records
# Example: We use pydantic v2 and
```
## Implementation Blueprint
### Data models and structure
Create the core data models, we ensure type safety and consistency.
```python
Examples:
- orm models
- pydantic models
- pydantic schemas
- pydantic validators
```
### list of tasks to be completed to fullfill the PRP in the order they should be completed
```yaml
Task 1:
MODIFY src/existing_module.py:
- FIND pattern: "class OldImplementation"
- INJECT after line containing "def __init__"
- PRESERVE existing method signatures
CREATE src/new_feature.py:
- MIRROR pattern from: src/similar_feature.py
- MODIFY class name and core logic
- KEEP error handling pattern identical
...(...)
Task N:
...
```
### Per task pseudocode as needed added to each task
```python
# Task 1
# Pseudocode with CRITICAL details dont write entire code
async def new_feature(param: str) -> Result:
# PATTERN: Always validate input first (see src/validators.py)
validated = validate_input(param) # raises ValidationError
# GOTCHA: This library requires connection pooling
async with get_connection() as conn: # see src/db/pool.py
# PATTERN: Use existing retry decorator
@retry(attempts=3, backoff=exponential)
async def _inner():
# CRITICAL: API returns 429 if >10 req/sec
await rate_limiter.acquire()
return await external_api.call(validated)
result = await _inner()
# PATTERN: Standardized response format
return format_response(result) # see src/utils/responses.py
```
### Integration Points
```yaml
DATABASE:
- migration: "Add column 'feature_enabled' to users table"
- index: "CREATE INDEX idx_feature_lookup ON users(feature_id)"
CONFIG:
- add to: config/settings.py
- pattern: "FEATURE_TIMEOUT = int(os.getenv('FEATURE_TIMEOUT', '30'))"
ROUTES:
- add to: src/api/routes.py
- pattern: "router.include_router(feature_router, prefix='/feature')"
```
## Validation Loop
### Level 1: Syntax & Style
```bash
# Run these FIRST - fix any errors before proceeding
ruff check src/new_feature.py --fix # Auto-fix what's possible
mypy src/new_feature.py # Type checking
# Expected: No errors. If errors, READ the error and fix.
```
### Level 2: Unit Tests each new feature/file/function use existing test patterns
```python
# CREATE test_new_feature.py with these test cases:
def test_happy_path():
"""Basic functionality works"""
result = new_feature("valid_input")
assert result.status == "success"
def test_validation_error():
"""Invalid input raises ValidationError"""
with pytest.raises(ValidationError):
new_feature("")
def test_external_api_timeout():
"""Handles timeouts gracefully"""
with mock.patch('external_api.call', side_effect=TimeoutError):
result = new_feature("valid")
assert result.status == "error"
assert "timeout" in result.message
```
```bash
# Run and iterate until passing:
uv run pytest test_new_feature.py -v
# If failing: Read error, understand root cause, fix code, re-run (never mock to pass)
```
### Level 3: Integration Test
```bash
# Start the service
uv run python -m src.main --dev
# Test the endpoint
curl -X POST http://localhost:8000/feature \
-H "Content-Type: application/json" \
-d '{"param": "test_value"}'
# Expected: {"status": "success", "data": {...}}
# If error: Check logs at logs/app.log for stack trace
```
## Final validation Checklist
- [ ] All tests pass: `uv run pytest tests/ -v`
- [ ] No linting errors: `uv run ruff check src/`
- [ ] No type errors: `uv run mypy src/`
- [ ] Manual test successful: [specific curl/command]
- [ ] Error cases handled gracefully
- [ ] Logs are informative but not verbose
- [ ] Documentation updated if needed
---
## Anti-Patterns to Avoid
- ❌ Don't create new patterns when existing ones work
- ❌ Don't skip validation because "it should work"
- ❌ Don't ignore failing tests - fix them
- ❌ Don't use sync functions in async context
- ❌ Don't hardcode values that should be config
- ❌ Don't catch all exceptions - be specific

296
README.md Normal file
View File

@ -0,0 +1,296 @@
# Context Engineering Template
A comprehensive template for getting started with Context Engineering - the discipline of engineering context for AI coding assistants so they have the information necessary to get the job done end to end.
> **Context Engineering is 10x better than prompt engineering and 100x better than vibe coding.**
## 🚀 Quick Start
```bash
# 1. Clone this template
git clone https://github.com/coleam00/Context-Engineering-Intro.git
cd Context-Engineering-Intro
# 2. Set up your project rules (optional - template provided)
# Edit CLAUDE.md to add your project-specific guidelines
# 3. Add examples (highly recommended)
# Place relevant code examples in the examples/ folder
# 4. Create your initial feature request
# Edit INITIAL.md with your feature requirements
# 5. Generate a comprehensive PRP (Product Requirements Prompt)
# In Claude Code, run:
/generate-prp INITIAL.md
# 6. Execute the PRP to implement your feature
# In Claude Code, run:
/execute-prp PRPs/your-feature-name.md
```
## 📚 Table of Contents
- [What is Context Engineering?](#what-is-context-engineering)
- [Template Structure](#template-structure)
- [Step-by-Step Guide](#step-by-step-guide)
- [Writing Effective INITIAL.md Files](#writing-effective-initialmd-files)
- [The PRP Workflow](#the-prp-workflow)
- [Using Examples Effectively](#using-examples-effectively)
- [Best Practices](#best-practices)
## What is Context Engineering?
Context Engineering represents a paradigm shift from traditional prompt engineering:
### Prompt Engineering vs Context Engineering
**Prompt Engineering:**
- Focuses on clever wording and specific phrasing
- Limited to how you phrase a task
- Like giving someone a sticky note
**Context Engineering:**
- A complete system for providing comprehensive context
- Includes documentation, examples, rules, patterns, and validation
- Like writing a full screenplay with all the details
### Why Context Engineering Matters
1. **Reduces AI Failures**: Most agent failures aren't model failures - they're context failures
2. **Ensures Consistency**: AI follows your project patterns and conventions
3. **Enables Complex Features**: AI can handle multi-step implementations with proper context
4. **Self-Correcting**: Validation loops allow AI to fix its own mistakes
## Template Structure
```
context-engineering-intro/
├── .claude/
│ ├── commands/
│ │ ├── generate-prp.md # Generates comprehensive PRPs
│ │ └── execute-prp.md # Executes PRPs to implement features
│ └── settings.local.json # Claude Code permissions
├── PRPs/
│ ├── templates/
│ │ └── prp_base.md # Base template for PRPs
│ └── EXAMPLE_multi_agent_prp.md # Example of a complete PRP
├── examples/ # Your code examples (critical!)
├── CLAUDE.md # Global rules for AI assistant
├── INITIAL.md # Template for feature requests
├── INITIAL_EXAMPLE.md # Example feature request
└── README.md # This file
```
This template doesn't focus on RAG and tools with context engineering because I have a LOT more in store for that soon. ;)
## Step-by-Step Guide
### 1. Set Up Global Rules (CLAUDE.md)
The `CLAUDE.md` file contains project-wide rules that the AI assistant will follow in every conversation. The template includes:
- **Project awareness**: Reading planning docs, checking tasks
- **Code structure**: File size limits, module organization
- **Testing requirements**: Unit test patterns, coverage expectations
- **Style conventions**: Language preferences, formatting rules
- **Documentation standards**: Docstring formats, commenting practices
**You can use the provided template as-is or customize it for your project.**
### 2. Create Your Initial Feature Request
Edit `INITIAL.md` to describe what you want to build:
```markdown
## FEATURE:
[Describe what you want to build - be specific about functionality and requirements]
## EXAMPLES:
[List any example files in the examples/ folder and explain how they should be used]
## DOCUMENTATION:
[Include links to relevant documentation, APIs, or MCP server resources]
## OTHER CONSIDERATIONS:
[Mention any gotchas, specific requirements, or things AI assistants commonly miss]
```
**See `INITIAL_EXAMPLE.md` for a complete example.**
### 3. Generate the PRP
PRPs (Product Requirements Prompts) are comprehensive implementation blueprints that include:
- Complete context and documentation
- Implementation steps with validation
- Error handling patterns
- Test requirements
They are similar to PRDs (Product Requirements Documents) but are crafted more specifically to instruct an AI coding assistant.
Run in Claude Code:
```bash
/generate-prp INITIAL.md
```
**Note:** The slash commands are custom commands defined in `.claude/commands/`. You can view their implementation:
- `.claude/commands/generate-prp.md` - See how it researches and creates PRPs
- `.claude/commands/execute-prp.md` - See how it implements features from PRPs
The `$ARGUMENTS` variable in these commands receives whatever you pass after the command name (e.g., `INITIAL.md` or `PRPs/your-feature.md`).
This command will:
1. Read your feature request
2. Research the codebase for patterns
3. Search for relevant documentation
4. Create a comprehensive PRP in `PRPs/your-feature-name.md`
### 4. Execute the PRP
Once generated, execute the PRP to implement your feature:
```bash
/execute-prp PRPs/your-feature-name.md
```
The AI coding assistant will:
1. Read all context from the PRP
2. Create a detailed implementation plan
3. Execute each step with validation
4. Run tests and fix any issues
5. Ensure all success criteria are met
## Writing Effective INITIAL.md Files
### Key Sections Explained
**FEATURE**: Be specific and comprehensive
- ❌ "Build a web scraper"
- ✅ "Build an async web scraper using BeautifulSoup that extracts product data from e-commerce sites, handles rate limiting, and stores results in PostgreSQL"
**EXAMPLES**: Leverage the examples/ folder
- Place relevant code patterns in `examples/`
- Reference specific files and patterns to follow
- Explain what aspects should be mimicked
**DOCUMENTATION**: Include all relevant resources
- API documentation URLs
- Library guides
- MCP server documentation
- Database schemas
**OTHER CONSIDERATIONS**: Capture important details
- Authentication requirements
- Rate limits or quotas
- Common pitfalls
- Performance requirements
## The PRP Workflow
### How /generate-prp Works
The command follows this process:
1. **Research Phase**
- Analyzes your codebase for patterns
- Searches for similar implementations
- Identifies conventions to follow
2. **Documentation Gathering**
- Fetches relevant API docs
- Includes library documentation
- Adds gotchas and quirks
3. **Blueprint Creation**
- Creates step-by-step implementation plan
- Includes validation gates
- Adds test requirements
4. **Quality Check**
- Scores confidence level (1-10)
- Ensures all context is included
### How /execute-prp Works
1. **Load Context**: Reads the entire PRP
2. **Plan**: Creates detailed task list using TodoWrite
3. **Execute**: Implements each component
4. **Validate**: Runs tests and linting
5. **Iterate**: Fixes any issues found
6. **Complete**: Ensures all requirements met
See `PRPs/EXAMPLE_multi_agent_prp.md` for a complete example of what gets generated.
## Using Examples Effectively
The `examples/` folder is **critical** for success. AI coding assistants perform much better when they can see patterns to follow.
### What to Include in Examples
1. **Code Structure Patterns**
- How you organize modules
- Import conventions
- Class/function patterns
2. **Testing Patterns**
- Test file structure
- Mocking approaches
- Assertion styles
3. **Integration Patterns**
- API client implementations
- Database connections
- Authentication flows
4. **CLI Patterns**
- Argument parsing
- Output formatting
- Error handling
### Example Structure
```
examples/
├── README.md # Explains what each example demonstrates
├── cli.py # CLI implementation pattern
├── agent/ # Agent architecture patterns
│ ├── agent.py # Agent creation pattern
│ ├── tools.py # Tool implementation pattern
│ └── providers.py # Multi-provider pattern
└── tests/ # Testing patterns
├── test_agent.py # Unit test patterns
└── conftest.py # Pytest configuration
```
## Best Practices
### 1. Be Explicit in INITIAL.md
- Don't assume the AI knows your preferences
- Include specific requirements and constraints
- Reference examples liberally
### 2. Provide Comprehensive Examples
- More examples = better implementations
- Show both what to do AND what not to do
- Include error handling patterns
### 3. Use Validation Gates
- PRPs include test commands that must pass
- AI will iterate until all validations succeed
- This ensures working code on first try
### 4. Leverage Documentation
- Include official API docs
- Add MCP server resources
- Reference specific documentation sections
### 5. Customize CLAUDE.md
- Add your conventions
- Include project-specific rules
- Define coding standards
## Resources
- [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)
- [Context Engineering Best Practices](https://www.philschmid.de/context-engineering)

0
examples/.gitkeep Normal file
View File