Context Engineering Intro Template

This project is a full-stack application designed to solve the limitation where the Claude Agent SDK does not expose an API to fetch historical messages. The solution involves storing messages in a local SQLite database while using the SDK's session_id to resume context.

Tech Stack

• Frontend: React, TypeScript, Vite, Tailwind, shadcn/ui
• Backend: Python, FastAPI, sse-starlette
• Database: SQLite with aiosqlite
• Agent SDK: claude-agent-sdk

Project Structure

agent-session-manager/
├── backend/
│   ├── app/
│   │   ├── main.py           # FastAPI app entry
│   │   ├── database.py       # SQLite connection + queries
│   │   ├── models.py         # Pydantic models
│   │   ├── routes/
│   │   │   ├── sessions.py   # Session CRUD
│   │   │   └── chat.py       # Chat with SSE streaming
│   │   └── sdk_client.py     # Claude Agent SDK wrapper
│   ├── requirements.txt
│   └── pyproject.toml
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── SessionSidebar.tsx
│   │   │   ├── ChatView.tsx
│   │   │   ├── MessageList.tsx
│   │   │   ├── MessageBlock.tsx
│   │   │   ├── ToolUseCard.tsx
│   │   │   └── NewSessionDialog.tsx
│   │   ├── lib/
│   │   │   ├── api.ts
│   │   │   └── types.ts
│   │   ├── App.tsx
│   │   └── main.tsx
│   ├── package.json
│   ├── vite.config.ts
│   └── tailwind.config.js
└── README.md

To enable parallel development without integration failures, the lead must define explicit contracts between layers (e.g., Database $\rightarrow$ Backend $\rightarrow$ Frontend).

Contract Requirements:

• URLs: Must be exact, including trailing slash conventions (e.g., POST /api/sessions/ vs POST /api/sessions).
• Data Shapes: Use explicit JSON structures, not prose descriptions (e.g., {"session": {...}, "messages": [...]}).
• SSE (Server-Sent Events): Document exact event types and JSON formats.
• Error Responses: Specify status codes and body formats (e.g., 404 or 422 error bodies).
• Storage Semantics: Define how data is stored (e.g., whether streaming chunks are accumulated into one row or stored individually).

Contract Chain Example:

• Database $\rightarrow$ Backend: Function signatures, Pydantic models, data types.
• Backend $\rightarrow$ Frontend: API contracts (URLs, response shapes, SSE format).

To ensure a robust and secure MCP server, adhere to these guidelines:

✅ Best Practices

• Input Validation: Always use Zod schemas to validate tool parameters.
• Resource Management: Implement the cleanup() method in your MCP class to close database connections or other resources.
• Security: Use existing patterns like validateSqlQuery and isWriteOperation for database interactions. Separate read vs write operations based on user permissions.
• Error Handling: Use createErrorResponse for tool errors and formatDatabaseError for database-specific issues.

❌ Anti-Patterns to Avoid

• Skipping Validation: Never skip Zod input validation.
• Ignoring Cleanup: Do not forget to implement cleanup() for stateful components like Durable Objects.
• Hardcoding Permissions: Avoid hardcoding user permissions; use a configurable permission system instead.
• Guessing Config: Do not guess OAuth configurations; always test the full flow locally.

Subagents are specialized AI assistants that operate in separate context windows to perform focused tasks (e.g., security auditing, documentation management).

Creating a Subagent: Create a markdown file in .claude/agents/ with a YAML frontmatter header defining its name, description, and allowed tools.

---
name: security-auditor
description: "Security specialist. Proactively reviews code for vulnerabilities and suggests improvements."
tools: Read, Grep, Glob
---

You are a security auditing specialist...

Best Practices:

• Focused Expertise: Assign one clear specialty per agent.
• Proactive Descriptions: Use the keyword "proactively" in the description to encourage the primary agent to invoke the subagent automatically.
• Tool Limitation: Only grant the tools necessary for the task (e.g., use Read and Grep for review-only agents without Write access).
• One-Shot Context: Remember that subagents receive a single prompt from the primary agent and do not have the full conversation history.

Avoid these common mistakes when developing with PydanticAI:

Agent Development

• Skipping TestModel validation during development.
• Hardcoding API keys (always use environment variables).
• Ignoring async patterns (PydanticAI has specific async/sync requirements).
• Creating overly complex tool chains (keep tools focused and composable).
• Neglecting error handling (implement retries and fallbacks).

Architecture

• Mixing agent types (clearly separate chat, tool, workflow, and structured output patterns).
• Ignoring dependency injection (use proper type-safe dependency management).
• Skipping output validation (always use Pydantic models for structured responses).
• Forgetting tool documentation (ensure all tools have proper descriptions and schemas).

Security & Production

• Exposing sensitive data in outputs or logs.
• Skipping input validation (sanitize and validate all user inputs).
• Ignoring rate limiting (implement throttling for external services).
• Deploying without monitoring/observability.

Hooks allow you to execute deterministic shell commands at specific lifecycle events in Claude Code. This is useful for logging, security validations, or triggering builds automatically.

Available Hook Events

• PreToolUse: Before tool execution (can block operations)
• PostToolUse: After successful tool completion
• UserPromptSubmit: When user submits a prompt
• SubagentStop: When a subagent completes its task
• Stop: When the main agent finishes responding
• SessionStart: At session initialization
• PreCompact: Before context compaction
• Notification: During system notifications

Setup Steps

1. Create your shell script in .claude/hooks/.
2. Make the script executable: chmod +x your-hook.sh.
3. Register the hook in .claude/settings.local.json using a matcher and the command type.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/log-tool-usage.sh"
          }
        ]
      }
    ]
  }
}