Skip to content

CLAUDE.md

Latest commit

 

History

History
64 lines (39 loc) · 5.56 KB

CLAUDE.md

File metadata and controls

64 lines (39 loc) · 5.56 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repo is

A tutorial repository that teaches building, deploying, and extending AI agents on OpenShift using the fips-agents toolkit (a scaffolding CLI plus composable templates — not a framework). It is not application code — it is published documentation plus two completed worked examples.

Five top-level concerns coexist here:

  1. MkDocs tutorial site (docs/, mkdocs.yml) — published to https://fips-agents.github.io/examples/ via .github/workflows/pages.yml on every push to main.
  2. manifests/platform/ — YAML manifests for the Install OpenShift AI guide (NFD, GPU Operator, DSC, ClusterPolicy, HardwareProfile). Students clone the repo and apply these directly instead of manually creating files from inline code blocks.
  3. calculus-agent/ — finished BaseAgent-based agent (the "Module 1–11" worked example). Has its own CLAUDE.md with BaseAgent-specific guidance.
  4. calculus-helper/ — finished FastMCP v3 server providing 8 SymPy-powered calculus tools. Has its own CLAUDE.md with FastMCP-specific guidance.
  5. calculus-coordinator/ — demo of the subagent-as-tool feature shipped in fipsagents 0.22.0 (agent-template PR #173). A tutor-role coordinator that delegates calculus computation to a registered peer agent (calculus_specialist, which in production points at the deployed calculus-agent route). Pins fipsagents>=0.31.0 to match the tutorial baseline — it is a standalone demo, not part of the Module 1–11 sequence.

When working inside calculus-agent/, calculus-helper/, or calculus-coordinator/, that sub-project's CLAUDE.md is authoritative — it covers the agent or MCP server's structure, decorators, deployment, and common mistakes. This top-level file is only for cross-cutting tutorial-repo work.

Local development of the tutorial site

pip install mkdocs-material
mkdocs serve              # preview at http://localhost:8000
mkdocs build --strict     # what CI runs; fails on broken links/refs

The --strict flag is what GitHub Actions uses, so always reproduce CI behavior locally before pushing changes to docs/ or mkdocs.yml.

site/ is the build output and is gitignored — never commit it.

Tutorial structure

mkdocs.yml defines the canonical module ordering. The tutorial has two tiers:

Core modules (0–11) are sequential — each assumes the previous one is complete:

  • Modules 0–9 live in docs/0N-*.md, Modules 10–11 in docs/1N-*.md.
  • Reference pages live in docs/reference/ and are linked from multiple modules.
  • The tutorial pins a specific fipsagents version (currently v0.31.0 — see docs/index.md). Bumping that version requires a coordinated re-test of every module.

Supplementary modules (docs/supplementary/) are standalone add-ons that extend the tutorial with optional platform features. They are independent of each other and can be completed in any order after their listed prerequisites:

  • Agent Memory with MemoryHub — cross-session memory via semantic search (RHOAI 3.x)
  • Models as a Service — subscription-based model governance, API key auth, token quotas (RHOAI 3.4+). Delegates platform setup to the official Red Hat guide, then teaches CRD anatomy and hands-on governance.
  • MCP Gateway — centralized MCP server access with auth and rate limiting via Kuadrant (RHOAI 3.4+, Tech Preview)

Supplementary modules require RHOAI 3.4 unless noted otherwise. They follow a different pattern than core modules: they include their own infrastructure setup rather than relying on Setup Guides.

When fixing issues found by tutorial walk-throughs, file them at fips-agents/examples on GitHub and link the issue from the commit.

Sub-project relationship

calculus-agent/ and calculus-helper/ are scaffolded outputs, not hand-maintained code. They were generated by fips-agents create ... and are periodically re-scaffolded against newer template versions (most recent: 2e37e3c — "Re-scaffold calculus-agent from v0.11.1 template"). When tutorial steps drift from the scaffolded reality, prefer fixing the tutorial text over hand-editing the scaffolded project — otherwise re-scaffolding will silently revert your fix.

calculus-coordinator/ is hand-built for the subagent-as-tool demo. It was bootstrapped by copying calculus-agent/'s scaffold, dropping the mcp_servers: block, and adding a subagents: block pointing at calculus-agent's /v1/chat/completions. Treat it as hand-maintained until subagent-as-tool reaches the tutorial's pinned fipsagents version, at which point it can become a proper scaffolded sub-project. Its CLAUDE.md covers the coordinator role and the delegate_to_agent flow.

Retrospectives

retrospectives/ holds dated post-mortems from tutorial-development sessions (e.g., 2026-04-22_tutorial-completion/). Add a new dated directory rather than editing existing ones.

Repo conventions

  • This is a public repository — never file issues here that reference internal corporate tooling, internal hostnames, or internal tool names. Mention those in conversation only.
  • Commits follow conventional-commit prefixes (docs:, refactor:, fix:). The calculus-agent/calculus-helper sub-projects have their own commit-message conventions inside their CLAUDE.md files.