From a43de6c71faac38df876bcf020cd33f63c3087e5 Mon Sep 17 00:00:00 2001 From: Fabio Martino Date: Tue, 8 Jul 2025 22:41:26 +0200 Subject: [PATCH 1/2] updated readme --- CLAUDE.md | 11 ++-- INITIAL.md | 6 +-- INITIAL_EXAMPLE.md | 26 +++++----- README.md | 124 +++++++++++++++++++++++++++++++-------------- 4 files changed, 107 insertions(+), 60 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index f0423f5470..72d2d65108 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,7 +2,7 @@ - **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. +- **Activate `venv_linux`**, the designated virtual environment, before executing any Python commands, including 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. @@ -11,14 +11,13 @@ - `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 clear, consistent imports**, preferring 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. +- **Place all tests in a `/tests` folder**, mirroring the main app’s directory structure. - Include at least: - 1 test for expected use - 1 edge case @@ -26,7 +25,7 @@ ### βœ… 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. +- Log any newly discovered sub-tasks or TODOs in `TASK.md`, under a β€œDiscovered During Work” section. ### πŸ“Ž Style & Conventions - **Use Python** as the primary language. @@ -54,6 +53,6 @@ ### 🧠 AI Behavior Rules - **Never assume missing context. Ask questions if uncertain.** -- **Never hallucinate libraries or functions** – only use known, verified Python packages. +- **Never hallucinate libraries or functions** β€” always rely on 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`. \ No newline at end of file diff --git a/INITIAL.md b/INITIAL.md index 80e88f55be..63b7b947af 100644 --- a/INITIAL.md +++ b/INITIAL.md @@ -4,12 +4,12 @@ ## EXAMPLES: -[Provide and explain examples that you have in the `examples/` folder] +[Provide and explain the examples located 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] +[List any relevant documentation (web pages, MCP server sources like Crawl4AI RAG, etc.) that should 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] +[Any other considerations or specific requirements β€” this is a great place to highlight common pitfalls that AI coding assistants tend to miss in your projects] diff --git a/INITIAL_EXAMPLE.md b/INITIAL_EXAMPLE.md index c7fca83647..695b9eed50 100644 --- a/INITIAL_EXAMPLE.md +++ b/INITIAL_EXAMPLE.md @@ -1,26 +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. +- Create a Pydantic-based AI agent that uses another Pydantic agent as a tool. +- The primary agent is a Research Agent; the sub-agent is responsible for drafting emails. +- Provide a CLI interface to interact with the agents. +- Use Gmail integration for the email draft agent, and the 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. +The `examples/` folder includes a `README.md` that explains the context of the provided examples and offers a template for structuring your own documentation. -- `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. +- `examples/cli.py` – use this as a reference for implementing the CLI. +- `examples/agent/` – review all files in this directory to understand best practices for building Pydantic AI agents that support multiple providers and LLMs, manage agent dependencies, and register tools. -Don't copy any of these examples directly, it is for a different project entirely. But use this as inspiration and for best practices. +Note: These examples belong to a different project. Do not reuse them directly, but use them as inspiration and to guide best practices. ## DOCUMENTATION: -Pydantic AI documentation: https://ai.pydantic.dev/ +- [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 +- Provide a `.env.example` file and a `README.md` with setup instructions, including configuration for Gmail and Brave. +- Document the project structure in the `README.md`. +- The virtual environment has already been configured with the necessary dependencies. +- Use the `python-dotenv` library and `load_env()` to manage environment variables. diff --git a/README.md b/README.md index d1843daca8..bb5fcad133 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ -# Context Engineering Template +# Context Engineering Starter 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. +A comprehensive template for getting started with Context Engineering - the discipline of engineering context for AI coding assistants so they have all the necessary information to complete tasks from start to finish. -> **Context Engineering is 10x better than prompt engineering and 100x better than vibe coding.** +> **Context Engineering outperforms prompt engineering by an order of magnitude – and offers far more structure and reliability than informal 'vibe coding'. This template is optimized for use with the CLAUDE Code.** ## πŸš€ Quick Start @@ -15,17 +15,17 @@ cd Context-Engineering-Intro # Edit CLAUDE.md to add your project-specific guidelines # 3. Add examples (highly recommended) -# Place relevant code examples in the examples/ folder +# 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: +# 5. Generate a comprehensive PRP (Product Requirements Prompt – a detailed implementation blueprint for AI assistants) +# In Claude Code (Anthropic's coding assistant), run: /generate-prp INITIAL.md # 6. Execute the PRP to implement your feature -# In Claude Code, run: +# In Claude Code (Anthropic's coding assistant), run: /execute-prp PRPs/your-feature-name.md ``` @@ -38,19 +38,23 @@ cd Context-Engineering-Intro - [The PRP Workflow](#the-prp-workflow) - [Using Examples Effectively](#using-examples-effectively) - [Best Practices](#best-practices) +- [Common Pitfalls](#common-pitfalls) +- [Resources](#resources) ## What is Context Engineering? Context Engineering represents a paradigm shift from traditional prompt engineering: -### Prompt Engineering vs Context 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 @@ -59,30 +63,30 @@ Context Engineering represents a paradigm shift from traditional prompt engineer 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 +3. **Enables Complex Features**: AI can handle multi-step implementations effectively when given 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 +β”‚ β”‚ β”œβ”€β”€ 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 +β”‚ β”‚ └── 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 +β”œβ”€β”€ examples/ # Your code examples (critical!) +β”œβ”€β”€ CLAUDE.md # Project-wide rules for the AI assistant +β”œβ”€β”€ INITIAL.md # Initial feature request definition +β”œβ”€β”€ INITIAL_EXAMPLE.md # Example INITIAL.md +└── README.md # Context Engineering starter guide (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. ;) +Additional templates and support for RAG-based architectures (Retrieval-Augmented Generation) will be included in a future update. ## Step-by-Step Guide @@ -110,7 +114,7 @@ Edit `INITIAL.md` to describe what you want to build: [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] +[Include links to relevant documentation, APIs, or internal resources such as your MCP (Model Control Protocol) server] ## OTHER CONSIDERATIONS: [Mention any gotchas, specific requirements, or things AI assistants commonly miss] @@ -127,9 +131,22 @@ PRPs (Product Requirements Prompts) are comprehensive implementation blueprints - Error handling patterns - Test requirements -They are similar to PRDs (Product Requirements Documents) but are crafted more specifically to instruct an AI coding assistant. +They are similar to PRDs (Product Requirements Documents), but PRPs are tailored specifically for AI coding assistants and include strict context and validation logic. + +Here's a quick comparison: + +**PRD (Product Requirements Document):** +- Written for human developers +- May include ambiguous goals +- Often high-level and descriptive + +**PRP (Product Requirements Prompt):** +- Written to instruct an AI coding agent +- Requires specificity and validation +- Operational and execution-oriented Run in Claude Code: + ```bash /generate-prp INITIAL.md ``` @@ -138,7 +155,7 @@ Run in Claude Code: - `.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`). +The `$ARGUMENTS` variable in these commands represents the input passed after the slash command name (e.g., `INITIAL.md` or `PRPs/your-feature.md`). This is a placeholder used inside `.claude/commands/*.md` files to reference user-supplied input dynamically. This command will: 1. Read your feature request @@ -155,32 +172,39 @@ Once generated, execute the PRP to implement your feature: ``` The AI coding assistant will: + 1. Read all context from the PRP -2. Create a detailed implementation plan +2. Create a detailed feature implementation plan with step-by-step guidance 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 +For a broader comparison between human-readable and AI-specific requirements, see the [PRD vs PRP comparison](#3-generate-the-prp) in the Generate the PRP section. + ### 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 @@ -190,31 +214,33 @@ The AI coding assistant will: ### 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 +2. **Plan**: Creates a detailed task list using the TodoWrite system (a planning module within Claude Code) 3. **Execute**: Implements each component 4. **Validate**: Runs tests and linting 5. **Iterate**: Fixes any issues found @@ -229,68 +255,90 @@ The `examples/` folder is **critical** for success. AI coding assistants perform ### 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 +β”œβ”€β”€ 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 +- This helps ensure the implementation works correctly on the first execution ### 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 +## Common Pitfalls + +Avoid these frequent mistakes to get the most out of Context Engineering: + +- **Skipping examples**: Without patterns to follow, the AI assistant will produce generic or inconsistent code. +- **Vague FEATURE descriptions**: The more specific your `INITIAL.md`, the better the results. +- **Neglecting CLAUDE.md**: Without rules and structure, implementations may drift from your project's conventions. +- **Forgetting validations**: If tests or linting steps are not included, PRPs may result in incomplete or non-functional implementations. + ## Resources - [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code) -- [Context Engineering Best Practices](https://www.philschmid.de/context-engineering) \ No newline at end of file +- [Context Engineering Best Practices](https://www.philschmid.de/context-engineering) + +--- + +**Start engineering your context today β€” and unlock the full potential of AI-powered development in your team, your product, and your workflow.** From 633ea273838613839b7649ec55e3269440931afa Mon Sep 17 00:00:00 2001 From: Fabio Martino Date: Thu, 10 Jul 2025 12:40:28 +0200 Subject: [PATCH 2/2] docs(readme) Improve and update README.md for clarity and flexibility --- README.md | 334 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 333 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index bb5fcad133..9b9ecd4c58 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,7 @@ cd Context-Engineering-Intro - [What is Context Engineering?](#what-is-context-engineering) - [Template Structure](#template-structure) +- [Integrating into Existing Projects](#integrating-into-existing-projects) - [Step-by-Step Guide](#step-by-step-guide) - [Writing Effective INITIAL.md Files](#writing-effective-initialmd-files) - [The PRP Workflow](#the-prp-workflow) @@ -88,6 +89,337 @@ context-engineering-intro/ Additional templates and support for RAG-based architectures (Retrieval-Augmented Generation) will be included in a future update. +## Integrating into Existing Projects + +The Context Engineering template can be easily integrated into any existing project. Rather than starting from scratch, you can add the Context Engineering infrastructure to your current codebase and start benefiting from structured AI assistance immediately. + +### Integration Steps + +#### 1. Add Context Engineering Infrastructure + +```bash +# Navigate to your existing project root +cd your-existing-project + +# Create the Context Engineering directories +mkdir -p .claude/commands PRPs/templates examples + +# Download the essential files from this repository +curl -O https://raw.githubusercontent.com/your-repository/context-engineering-intro/main/.claude/commands/generate-prp.md +curl -O https://raw.githubusercontent.com/your-repository/context-engineering-intro/main/.claude/commands/execute-prp.md +curl -O https://raw.githubusercontent.com/your-repository/context-engineering-intro/main/.claude/settings.local.json +curl -O https://raw.githubusercontent.com/your-repository/context-engineering-intro/main/PRPs/templates/prp_base.md +curl -O https://raw.githubusercontent.com/your-repository/context-engineering-intro/main/CLAUDE.md +curl -O https://raw.githubusercontent.com/your-repository/context-engineering-intro/main/INITIAL_EXAMPLE.md + +# Move files to correct locations +mv generate-prp.md .claude/commands/ +mv execute-prp.md .claude/commands/ +mv settings.local.json .claude/ +mv prp_base.md PRPs/templates/ +``` + +#### 2. Customize for Your Project + +**Edit `CLAUDE.md`** to match your project's conventions: + +```markdown +# Add your project-specific rules +## Technology Stack +- Framework: [Your framework - React, Django, etc.] +- Language: [Your primary language] +- Testing: [Your testing framework] +- Database: [Your database] + +## Project Structure +- Follow existing module organization in `/src` or `/app` +- Maintain current naming conventions +- Keep existing import patterns + +## Existing Patterns to Follow +- Look at `/src/components/` for component patterns +- Check `/tests/` for testing approaches +- Review `/docs/` for documentation style +``` + +#### 3. Create Examples from Existing Code + +This is the most important step! Extract patterns from your existing codebase: + +```bash +# Create examples directory structure +mkdir -p examples/components examples/utils examples/tests + +# Copy representative examples of your patterns +cp src/components/UserProfile.js examples/components/ +cp src/utils/apiClient.js examples/utils/ +cp tests/components/UserProfile.test.js examples/tests/ +``` + +**Create `examples/README.md`** to explain your patterns: + +```markdown +# Project Examples + +## Components (`/components/`) +- `UserProfile.js` - Shows our standard component structure with hooks +- Follow the prop validation and state management patterns + +## Utils (`/utils/`) +- `apiClient.js` - Our standard API client pattern with error handling +- Use this authentication and retry logic approach + +## Tests (`/tests/`) +- `UserProfile.test.js` - Our testing conventions with mocking +- Follow this structure for all component tests +``` + +#### 4. Create Your First Feature Request + +Create an `INITIAL.md` file for your next feature: + +```markdown +## FEATURE: +Add a new user settings page with profile editing capabilities + +## EXISTING PATTERNS: +- Follow the component structure shown in examples/components/UserProfile.js +- Use the API client pattern from examples/utils/apiClient.js +- Implement tests following examples/tests/UserProfile.test.js + +## INTEGRATION REQUIREMENTS: +- Must integrate with existing Redux store in /src/store +- Should use existing design system components from /src/components/ui +- Follow current routing patterns in /src/App.js + +## EXAMPLES: +- examples/components/ - Component architecture to follow +- examples/utils/ - API integration patterns +- examples/tests/ - Testing approach + +## DOCUMENTATION: +- Internal API docs: [link to your API docs] +- Design system: [link to your design system] +- Current user flow: [link to existing user management] + +## OTHER CONSIDERATIONS: +- Must maintain backward compatibility with existing user data +- Should handle edge cases like incomplete profiles +- Performance: Page should load in under 2 seconds +``` + +#### 5. Start Using Context Engineering + +Now you can use the Context Engineering workflow: + +```bash +# Generate a comprehensive PRP for your feature +/generate-prp INITIAL.md + +# Execute the PRP to implement the feature +/execute-prp PRPs/user-settings-page.md +``` + +### Integration Best Practices + +#### 1. **Inventory Your Existing Patterns** + +Before starting, identify what patterns already exist in your codebase: + +- **Architecture patterns**: How do you structure modules/components? +- **API patterns**: How do you handle HTTP requests, authentication? +- **Testing patterns**: What testing framework and patterns do you use? +- **Error handling**: How do you handle errors consistently? +- **State management**: Redux, Context API, or other patterns? + +#### 2. **Gradual Integration** + +Don't try to convert everything at once: + +- Start with **one new feature** using Context Engineering +- Use it for **refactoring** existing components +- Gradually build up your examples library +- Train your team on the new workflow + +#### 3. **Maintain Consistency** + +- **Update CLAUDE.md** as your project evolves +- **Keep examples current** with your latest patterns +- **Document deviations** from standard patterns +- **Regular reviews** of generated PRPs for quality + +#### 4. **Team Adoption** + +- **Share examples** of successful Context Engineering implementations +- **Document wins** - faster development, fewer bugs +- **Train team members** on writing effective INITIAL.md files +- **Establish review process** for PRPs before execution + +### Example Integration in Different Project Types + +#### React/Next.js Project +```bash +# Focus on component patterns, hooks, and page structure +examples/ +β”œβ”€β”€ components/ +β”‚ β”œβ”€β”€ UserCard.tsx # Standard component pattern +β”‚ └── Modal.tsx # Modal pattern with portal +β”œβ”€β”€ hooks/ +β”‚ └── useApi.ts # Custom hook pattern +β”œβ”€β”€ pages/ +β”‚ └── user/[id].tsx # Next.js page pattern +└── tests/ + └── components/ + └── UserCard.test.tsx +``` + +#### Angular Project +```bash +# Focus on components, services, and modules +examples/ +β”œβ”€β”€ components/ +β”‚ β”œβ”€β”€ user-card/ +β”‚ β”‚ β”œβ”€β”€ user-card.component.ts # Component with lifecycle hooks +β”‚ β”‚ β”œβ”€β”€ user-card.component.html # Template pattern +β”‚ β”‚ └── user-card.component.scss # Styling pattern +β”‚ └── shared/ +β”‚ └── modal.component.ts # Reusable modal component +β”œβ”€β”€ services/ +β”‚ β”œβ”€β”€ user.service.ts # Service with HTTP client +β”‚ └── auth.service.ts # Authentication service +β”œβ”€β”€ guards/ +β”‚ └── auth.guard.ts # Route guard pattern +β”œβ”€β”€ modules/ +β”‚ └── user.module.ts # Feature module pattern +β”œβ”€β”€ pipes/ +β”‚ └── date-format.pipe.ts # Custom pipe pattern +└── tests/ + β”œβ”€β”€ user-card.component.spec.ts # Component testing + └── user.service.spec.ts # Service testing +``` + +#### Angular + Ionic Project +```bash +# Focus on mobile-first components and Ionic patterns +examples/ +β”œβ”€β”€ pages/ +β”‚ β”œβ”€β”€ home/ +β”‚ β”‚ β”œβ”€β”€ home.page.ts # Ionic page component +β”‚ β”‚ β”œβ”€β”€ home.page.html # Ionic template with ion-components +β”‚ β”‚ └── home.page.scss # Mobile-first styling +β”‚ └── user-profile/ +β”‚ β”œβ”€β”€ user-profile.page.ts # Page with ion-nav lifecycle +β”‚ └── user-profile.page.html # Form with ion-input, ion-button +β”œβ”€β”€ components/ +β”‚ β”œβ”€β”€ user-card/ +β”‚ β”‚ β”œβ”€β”€ user-card.component.ts # Reusable component +β”‚ β”‚ └── user-card.component.html # Using ion-card, ion-avatar +β”‚ └── loading/ +β”‚ └── loading.component.ts # Custom loading component +β”œβ”€β”€ services/ +β”‚ β”œβ”€β”€ api.service.ts # HTTP service with capacitor +β”‚ β”œβ”€β”€ storage.service.ts # Ionic storage service +β”‚ └── camera.service.ts # Capacitor camera integration +β”œβ”€β”€ guards/ +β”‚ └── auth.guard.ts # Route guard for mobile +β”œβ”€β”€ capacitor/ +β”‚ └── capacitor.config.ts # Capacitor configuration +└── tests/ + β”œβ”€β”€ home.page.spec.ts # Page testing + └── api.service.spec.ts # Service testing with mocks +``` + +#### NestJS API Project +```bash +# Focus on controllers, services, and modules +examples/ +β”œβ”€β”€ controllers/ +β”‚ β”œβ”€β”€ users.controller.ts # Controller with decorators +β”‚ └── auth.controller.ts # Authentication controller +β”œβ”€β”€ services/ +β”‚ β”œβ”€β”€ users.service.ts # Service with dependency injection +β”‚ β”œβ”€β”€ auth.service.ts # JWT authentication service +β”‚ └── database.service.ts # Database connection service +β”œβ”€β”€ modules/ +β”‚ β”œβ”€β”€ users.module.ts # Feature module +β”‚ β”œβ”€β”€ auth.module.ts # Authentication module +β”‚ └── database.module.ts # Database module +β”œβ”€β”€ entities/ +β”‚ β”œβ”€β”€ user.entity.ts # TypeORM entity +β”‚ └── role.entity.ts # Entity with relations +β”œβ”€β”€ dto/ +β”‚ β”œβ”€β”€ create-user.dto.ts # Data transfer object +β”‚ └── update-user.dto.ts # Update DTO with validation +β”œβ”€β”€ guards/ +β”‚ β”œβ”€β”€ jwt-auth.guard.ts # JWT authentication guard +β”‚ └── roles.guard.ts # Role-based authorization +β”œβ”€β”€ interceptors/ +β”‚ └── logging.interceptor.ts # Request logging interceptor +β”œβ”€β”€ pipes/ +β”‚ └── validation.pipe.ts # Custom validation pipe +β”œβ”€β”€ filters/ +β”‚ └── http-exception.filter.ts # Exception handling +└── tests/ + β”œβ”€β”€ users.controller.spec.ts # Controller testing + β”œβ”€β”€ users.service.spec.ts # Service testing + └── e2e/ + └── users.e2e-spec.ts # End-to-end testing +``` + +#### Django Project +```bash +# Focus on models, views, and templates +examples/ +β”œβ”€β”€ models/ +β”‚ └── user.py # Model pattern with validation +β”œβ”€β”€ views/ +β”‚ └── user_views.py # ViewSet pattern +β”œβ”€β”€ serializers/ +β”‚ └── user_serializer.py # Serializer pattern +└── tests/ + └── test_user_views.py +``` + +#### Express.js API +```bash +# Focus on routes, middleware, and controllers +examples/ +β”œβ”€β”€ routes/ +β”‚ └── users.js # Route pattern +β”œβ”€β”€ middleware/ +β”‚ └── auth.js # Authentication middleware +β”œβ”€β”€ controllers/ +β”‚ └── userController.js # Controller pattern +└── tests/ + └── users.test.js +``` + +### Migration Checklist + +- [ ] Context Engineering directories created +- [ ] Essential files downloaded and placed correctly +- [ ] `CLAUDE.md` customized for your project +- [ ] Examples extracted from existing codebase +- [ ] `examples/README.md` created to explain patterns +- [ ] First `INITIAL.md` written for a new feature +- [ ] Team trained on Context Engineering workflow +- [ ] PRP generation and execution tested +- [ ] Integration documented for future team members + +### Common Integration Challenges + +**Challenge**: "My existing code doesn't follow consistent patterns" +**Solution**: Use Context Engineering to establish patterns going forward. Create examples of the patterns you want to adopt, not necessarily what exists. + +**Challenge**: "Our codebase is too large to create examples for everything" +**Solution**: Focus on the most common patterns (components, API calls, tests). You can always add more examples later. + +**Challenge**: "Team resistance to new tools" +**Solution**: Start small with one feature. Show concrete benefits like faster development and fewer bugs before rolling out team-wide. + +**Challenge**: "Integration with existing CI/CD" +**Solution**: PRPs can include validation steps that integrate with your existing pipeline. Update the PRP templates to match your deployment process. + ## Step-by-Step Guide ### 1. Set Up Global Rules (CLAUDE.md) @@ -341,4 +673,4 @@ Avoid these frequent mistakes to get the most out of Context Engineering: --- -**Start engineering your context today β€” and unlock the full potential of AI-powered development in your team, your product, and your workflow.** +**Start engineering your context today β€” and unlock the full potential of AI-powered development in your team, your product, and your workflow.** \ No newline at end of file