CLAUDE.md Template: Angular Material + FastAPI Agents SDK Starter

Overview

The CLAUDE.md template provides a copyable Claude Code instruction block for a stack that combines Angular Material UI with a FastAPI backend and the Agents SDK. This page is a CLAUDE.md template designed to be pasted directly into Claude Code to bootstrap a repeatable workflow.

When to Use This CLAUDE.md Template

• When building AI-driven UI with Angular Material components.
• When your backend is FastAPI and you need to orchestrate agents via the Agents SDK.
• When you want a reproducible CLAUDE.md that documents roles, rules, and deployment guidance for this stack.
• When you need a starter that reduces architecture drift between frontend and backend code paths.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are Claude Code acting as a software-engineering assistant for an Angular Material frontend paired with a FastAPI backend using the Agents SDK. Your task is to provide concrete, stack-specific Claude Code instructions that enable reproducible AI agent orchestration.

Architecture rules:
- Design for a clear frontend-backend boundary: Angular Material UI communicates with FastAPI via REST/WebSocket endpoints; keep business logic server-side.
- Keep the Agents SDK integration as a dedicated service module on the backend and a thin adapter on the frontend.
- Favor stateless API endpoints with in-memory or Redis-backed session state in production.
- Do not bypass authentication for internal agent endpoints.

File structure rules:
- Frontend: /frontend (Angular project) with src/app components/services/models
- Backend: /backend (FastAPI project) with app/main.py, app/routers, app/agents
- Do not create duplicate entry points; keep a single start script per service.

Authentication rules:
- Back-end uses OAuth2 with Password flow or JWT Bearer tokens; attach tokens in Authorization header for all agent calls.
- Front end stores tokens securely (HttpOnly cookies or secure storage) and sends them on requests.

Database rules:
- Do not rely on a persistent database for this starter; use in-memory state or Redis for production-grade sessions.
- Avoid direct SQL in Claude-coded blocks; rely on Pydantic models for validation.

Validation rules:
- Validate all inputs with strict schemas (Pydantic on FastAPI, Angular reactive forms with validators).
- Never forward untrusted data to agent logic.

Security rules:
- Never commit secrets to CLAUDE.md blocks; read from environment variables at runtime.
- Enforce HTTPS; set CORS appropriately for the frontend domain.
- Disable directory listing and ensure safe defaults in container environments.

Testing rules:
- Unit tests for frontend components, backend endpoints, and the agent orchestration layer.
- Integration tests for interactions between the UI, API, and agents.
- Include a simple end-to-end test for a typical agent workflow.

Deployment rules:
- Use Docker Compose to run frontend and backend in development; use Kubernetes manifests for production.
- Set environment variables via a secret management solution; avoid embedding credentials in CLAUDE.md content.

Things Claude must not do:
- Do not call admin endpoints or bypass authentication.
- Do not write or read files outside allowed project directories.
- Do not introduce production secrets or hard-coded credentials.

Recommended Project Structure

frontend/
  angular.json
  package.json
  tsconfig.json
  src/
    app/
      components/
      services/
      models/
    assets/
    styles/
backend/
  app/
    __init__.py
    main.py
    routers/
    agents/
requirements.txt
Dockerfile
docker-compose.yml
README.md

Core Engineering Principles

• Clear separation of concerns between UI (Angular Material) and API/agent orchestration (FastAPI).
• Deterministic agent behavior with explicit input validation and strict typing.
• Idempotent, testable code with comprehensive unit and integration tests.
• Declarative configuration and reproducible builds (Docker, CI).

Code Construction Rules

• Frontend must be in TypeScript with Angular Material components; use RxJS for streams.
• Backend must use FastAPI with Pydantic models; endpoints must be async when IO-bound.
• Agent orchestration must live in a dedicated backend module and expose a stable API.
• All data models must be explicit and validated; avoid any-typing in production code.
• Environment-driven configuration; never hard-code secrets.

Security and Production Rules

• Use HTTPS everywhere; configure CORS to allow only the frontend origin.
• Authenticate all agent calls with JWT/OAuth2; protect admin/agent-control endpoints.
• Audit logs for agent actions; avoid logging sensitive payload data.
• Regularly rotate credentials and store secrets in a secure vault.

Testing Checklist

• Frontend: component unit tests, UI interaction tests with Angular testing utilities.
• Backend: unit tests for Pydantic models, coroutine endpoints; test agent handlers.
• Integration: API + agent flow end-to-end tests; simulate agent prompts and responses.
• Deployment: smoke tests, health checks, and load testing in CI.

Common Mistakes to Avoid

• Mixing UI logic with business rules; keep them separate.
• Ignoring input validation on the backend; trust but verify.
• Hard-coding secrets or credentials in CLAUDE.md blocks.
• Disabling CSRF or overly permissive CORS settings in prod.

FAQ

• Q: Can I adapt this CLAUDE.md template to other stacks?
• A: Yes, modify the code block with stack-appropriate roles and files; keep the structure intact.
• Q: Do I need to run a specific command to apply the CLAUDE.md template?
• A: Paste the CLAUDE.md content into Claude Code and follow the template instructions to generate files.
• Q: Where should agent state be stored?
• A: In production, use a dedicated state store (e.g., Redis); for dev, in-memory is acceptable.
• Q: How is deployment handled?
• A: Use Docker Compose for development and Kubernetes manifests for production as described in the deployment rules.