context-engineering-intro

GitHub

Context engineering is the new vibe coding - it's the way to actually make AI coding assistants work. Claude Code is the best for this so that's what this repo is centered around, but you can apply this strategy with any AI coding assistant!

13,293 stars Python Markdown CodeWiki
Documentation CodeWiki
AI Prompts & Endpoints
CodeWiki Knowledge Base

Repository: coleam00/context-engineering-intro


Stars: 13176

CLAUDE.md

🔄 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.

README.md

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?
- Template Structure
- Step-by-Step Guide
- Writing Effective INITIAL.md Files
- The PRP Workflow
- Using Examples Effectively
- 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

text
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

text
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
- Context Engineering Best Practices

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →