feat: modernize AI Engineering curriculum with SDD methodology and context engineering

docs/3-AI-Engineering/3.1.2-ai-agents.md

@@ -35,6 +35,7 @@ These are the things that the agent can use to interact with the real world or g
 * **Windsurf**: Like GitHub Copilot but with agentic interaction capabilities. Has its own IDE.
 * **GitHub Copilot**: Most features need a paid account. Lives in your IDE or on GitHub. Can read everything in your workspace. You can use commands with /, extensions with @ or refer to sources with #.
 * **Anthropic's Claude**: Has agentic capabilities through its Claude Artifacts feature, additionally Claude Desktop brings MCP servers into the mix for agentic interaction.
+* **Claude Code**: Command-line AI agent with strong context management features including /context command for monitoring context utilization and structured workflows. Particularly effective for managing context rot through intentional compaction.
 * **AutoGPT**: An open-source autonomous agent that can use GPT models to accomplish tasks.
 
 ## Best Practices for Working with AI Agents

docs/3-AI-Engineering/3.3.2-agentic-ide.md

@@ -39,6 +39,7 @@ Popular Examples:
 - [Windsurf Cascade](https://windsurf.com/)
 - [Zed](https://www.zed.dev/)
 - [Cursor](https://www.cursor.com/)
+- [Claude Code](https://claude.ai/code) - Command-line AI agent from Anthropic featuring robust context management, /context monitoring, structured workflows through slash commands, and integration with development tools
 
 As of the time of writing each of these are all very close in feature sets though some excel in different areas. All currently support a free tier though as you start exploring agentic development you will likely run into the limits of the free tier.
 
@@ -159,26 +160,165 @@ prompt: |
 
 Workflows can be triggered through command palettes or custom keybindings, making complex AI-assisted patterns accessible to the entire team. This approach moves beyond one-off prompts to create reusable, maintainable AI interaction patterns that grow with your codebase.
 
-## Exercise 1 - VSCode Vibing
+## Exercise 1 - Structured MCP Server Development with SDD
 
-Let's give agentic development a spin In this exercise we are going to put into practice what we have learned and build an MCP server with AI. AI writing tools to interface with AI whoa.
+This exercise applies the SDD (Spec-Driven Development) methodology you learned in [3.3.1 AI Development for Software Engineers](3.3.1-agentic-best-practices.md) to build an MCP server with AI assistance. Rather than exploratory "vibing," you'll follow a structured four-stage workflow: Generate Specification → Task Breakdown → Execute with Management → Validate Implementation.
+
+This structured approach helps you manage complexity, track progress, prevent context rot, and create verifiable proof of functionality at each stage.
+
+**Note:** While this exercise uses VSCode as the primary environment, you may also use Claude Code or other AI assistants. If using Claude Code, leverage the `/context` command to monitor context utilization throughout the exercise.
+
+### Context Management Tips
+
+Before diving into the exercise, keep these context management practices in mind:
+
+- **Monitor Context Utilization**: Use `/context` (in Claude Code) or similar features in your AI assistant to track context window usage
+- **Trigger Compaction at 60%**: When context utilization exceeds 60%, trigger intentional compaction by summarizing completed work and starting fresh
+- **Progressive Disclosure**: Load MCP documentation on-demand rather than front-loading everything. Reference the [MCP Full Text](https://modelcontextprotocol.io/llms-full.txt) and [Python MCP SDK](https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/refs/heads/main/README.md) as needed during development
+- **Avoid Context Rot**: The 40%+ utilization "dumb zone" causes performance degradation. Stay aware of this threshold and compact proactively
+
+For detailed coverage of these concepts, see [3.1.4 AI Best Practices](3.1.4-ai-best-practices.md#understanding-context-windows).
+
+### Proof Artifacts
+
+While proof artifacts are optional for this exercise, creating them is excellent practice for real-world development:
+
+- **What They Are**: Evidence demonstrating your implementation works (screenshots, CLI output, test results, configuration examples)
+- **Why They Matter**: Provide verification checkpoints, enable troubleshooting, and support validation against your original spec
+- **What to Collect**: Screenshots of your MCP server running, CLI output from MCP Inspector tests, configuration files showing client registration, examples of successful tool invocations
+
+These artifacts become invaluable when debugging issues or demonstrating functionality to stakeholders.
 
 ### Steps
 
-1. Install VSCode and if you have access to Copilot paid plans log into that account (Check with your org or use an education account)
-2. Seed the AI with the [MCP Full Text](https://modelcontextprotocol.io/llms-full.txt) and [Python MCP SDK](https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/refs/heads/main/README.md) and brainstorm a spec
-3. Convert the spec into a product requirements document
-4. Iterate on the PRD committing frequently and practicing best agentic practices. It is a good idea to start with the smallest running MCP server then add functionality. Make sure you are testing frequently.
-5. You can test your MCP server with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector)
-6. Register your MCP server with some MCP client (Claude Desktop, Windsurf, VSCode etc.) and try it out!
+Follow these four SDD stages to build your MCP server:
+
+#### Stage 1: Generate Specification (SDD Stage 1)
+
+1. **Set Up Environment**: Install VSCode and if you have access to Copilot paid plans, log into that account (check with your org or use an education account). Alternatively, you can use Claude Code if preferred.
+
+2. **Brainstorm Your Spec**: Using the [MCP Full Text](https://modelcontextprotocol.io/llms-full.txt) and [Python MCP SDK](https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/refs/heads/main/README.md) as reference, work with your AI assistant to create a comprehensive specification. Focus on:
+   - What problem your MCP server will solve
+   - What tools/resources it will expose
+   - How clients will interact with it
+   - Success criteria and constraints
+
+3. **Ask Clarifying Questions**: Before finalizing the spec, ensure you understand:
+   - MCP protocol requirements and standards
+   - Python SDK patterns and best practices
+   - Testing approaches (MCP Inspector usage)
+   - Client registration requirements
+
+4. **Create Developer-Ready Specification**: Convert your brainstormed ideas into a clear, actionable specification that includes:
+   - Feature requirements
+   - Technical architecture
+   - API/tool definitions
+   - Testing strategy
+   - Success criteria
+
+**Checkpoint**: You should have a written specification document before proceeding to Stage 2.
+
+#### Stage 2: Task Breakdown (SDD Stage 2)
+
+5. **Break Down Into Parent Tasks**: Divide your spec into parent tasks representing demoable units. For example:
+   - Parent Task 1: Create minimal MCP server scaffold that responds to protocol handshake
+   - Parent Task 2: Implement first tool/resource with basic functionality
+   - Parent Task 3: Add error handling and validation
+   - Parent Task 4: Implement remaining tools/resources
+
+6. **Identify Relevant Files**: For each parent task, identify which files you'll need to create or modify (server implementation, configuration, tests, etc.)
+
+7. **Create Sub-Tasks with Proof Artifacts**: Break each parent task into actionable sub-tasks. Define what proof artifacts will demonstrate completion:
+   - Example: "Create server.py with protocol initialization" → Proof: CLI output showing successful server startup
+   - Example: "Implement calculator tool" → Proof: MCP Inspector output showing tool invocation and result
+
+**Checkpoint**: You should have a structured task list with proof artifacts defined before implementing.
+
+#### Stage 3: Execute with Management (SDD Stage 3)
+
+8. **Implement Incrementally**: Work through tasks one at a time following this pattern:
+   - Start with the smallest running MCP server, then add functionality incrementally
+   - Test frequently using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector)
+   - Commit after completing each parent task with clear commit messages
+   - Collect proof artifacts as you go (screenshots, CLI output, test results)
+
+9. **Monitor Context and Compact**: Throughout implementation:
+   - Check context utilization regularly (aim to stay below 60%)
+   - When approaching 60%, trigger intentional compaction: summarize completed work, document remaining tasks, start fresh conversation
+   - Use progressive disclosure: load documentation snippets only when needed
+
+10. **Practice Verification Checkpoints**: After each parent task:
+    - Run tests to verify functionality
+    - Review proof artifacts to confirm requirements met
+    - Commit changes before moving to next task
+
+**Checkpoint**: You should have a working, tested MCP server with commits showing incremental progress.
+
+#### Stage 4: Validate Implementation (SDD Stage 4)
+
+11. **Test Against Original Spec**: Review your completed MCP server against the specification from Stage 1:
+    - Does it solve the problem you defined?
+    - Does it implement all required tools/resources?
+    - Does it meet success criteria?
+
+12. **Register and Integration Test**: Register your MCP server with an MCP client (Claude Desktop, Windsurf, VSCode, etc.) and perform end-to-end testing:
+    - Verify client recognizes your server
+    - Test all tools/resources through the client interface
+    - Validate error handling and edge cases
+
+13. **Review Proof Artifacts**: If you collected proof artifacts, review them to ensure they demonstrate all required functionality
+
+14. **Document Learnings**: Note what worked well, what challenges you encountered, and what you'd do differently next time
+
+**Checkpoint**: You should have a fully functional, validated MCP server registered with a client and demonstrating all specified capabilities.
+
+## Exercise 2 - Structured MCP Server Development with Windsurf IDE
+
+Now let's experience another agentic IDE while applying the same SDD methodology. Windsurf was an early mover in the agentic IDE space and in many ways has shaped the experience that is being mirrored in competitors. Go [here to download Windsurf](https://windsurf.com/).
+
+This exercise applies the identical SDD workflow from Exercise 1 but in a different development environment. This helps you understand how the structured approach transcends specific tools.
+
+**Note:** As with Exercise 1, you may use Claude Code or other AI assistants instead of Windsurf if preferred. Monitor context utilization using available tools (e.g., `/context` in Claude Code).
+
+### Steps
+
+Follow the same four-stage SDD workflow from Exercise 1:
+
+#### Stage 1: Generate Specification
+
+1. **Set Up Windsurf**: Install Windsurf IDE and configure your preferred AI assistant
+2. **Brainstorm Your Spec**: Use the [MCP Full Text](https://modelcontextprotocol.io/llms-full.txt) and [Python MCP SDK](https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/refs/heads/main/README.md) to create your specification
+3. **Ask Clarifying Questions**: Ensure you understand requirements, patterns, and testing approaches
+4. **Create Developer-Ready Specification**: Document features, architecture, APIs, testing strategy, and success criteria
+
+#### Stage 2: Task Breakdown
+
+5. **Break Down Into Parent Tasks**: Divide your spec into demoable units with clear deliverables
+6. **Identify Relevant Files**: Map tasks to specific files you'll create or modify
+7. **Create Sub-Tasks with Proof Artifacts**: Define actionable sub-tasks and specify what evidence demonstrates completion
+
+#### Stage 3: Execute with Management
+
+8. **Implement Incrementally**: Build one task at a time, test frequently with [MCP Inspector](https://github.com/modelcontextprotocol/inspector), commit after each parent task
+9. **Monitor Context and Compact**: Track context utilization, compact at 60%+, use progressive disclosure
+10. **Practice Verification Checkpoints**: Test, review proof artifacts, commit before proceeding
 
-## Exercise 2 - Windsurf
+#### Stage 4: Validate Implementation
 
-Now let's experience another agentic IDE. Windsurf was an early mover in the agentic IDE space and in many ways has shaped the experience that is being mirrored in competitors. Go [here to download Windsurf](https://windsurf.com/).
+11. **Test Against Original Spec**: Verify your MCP server meets all specification requirements
+12. **Register and Integration Test**: Register with an MCP client and perform end-to-end testing
+13. **Review Proof Artifacts**: Ensure all evidence demonstrates required functionality
+14. **Document Learnings**: Compare your experience with Exercise 1—what worked better in Windsurf? What was more challenging?
 
-Repeat the same exercise you did with VSCode but this time in Windsurf. Leverage the best practices you have learned and anything you learned along the way last time.
+**Key Reflection**: As you work through this exercise, note how the SDD methodology remains consistent even as the development environment changes. The structured approach you learned in [3.3.1 AI Development for Software Engineers](3.3.1-agentic-best-practices.md) applies universally across tools.
 
 ## Deliverables
 
-- What worked well in the exercise?
-- Which Agentic IDE did you like the most?
+- What worked well when applying the SDD workflow to MCP server development?
+- How did following the four-stage methodology (Generate Spec → Task Breakdown → Execute → Validate) compare to exploratory development?
+- Did you experience context rot during the exercise? How did you manage it?
+- What proof artifacts did you collect, and how did they help verify your implementation?
+- Which Agentic IDE did you prefer, and why?
+- How did monitoring context utilization affect your development process?
+- What challenges did you encounter when breaking down your spec into tasks with proof artifacts?
+- What would you do differently if you were to repeat this exercise?

docs/README.md

@@ -370,7 +370,7 @@ docs/3-AI-Engineering/3.1.3-ai-tools.md:
         - AI Tools
 docs/3-AI-Engineering/3.1.4-ai-best-practices.md:
   category: AI Engineering
-  estReadingMinutes: 10
+  estReadingMinutes: 30
 docs/3-AI-Engineering/3.2-mcp.md:
   category: AI Engineering
   estReadingMinutes: 12
@@ -386,7 +386,7 @@ docs/3-AI-Engineering/3.3-best-practices.md:
   estReadingMinutes: 5
 docs/3-AI-Engineering/3.3.1-agentic-best-practices.md:
   category: AI Engineering
-  estReadingMinutes: 30
+  estReadingMinutes: 40
 docs/3-AI-Engineering/3.3.2-agentic-ide.md:
   category: AI Engineering
   estReadingMinutes: 20