Develop with AI assistants

Use AI coding assistants like Claude Code, Codex, Cursor, or GitHub Copilot to build Putnami applications faster. When you initialize a workspace, Putnami generates shared AI context under .AI/ plus thin assistant entrypoints (CLAUDE.md and AGENT.md) that teach tools your project's framework patterns, CLI commands, and file conventions.

What you get

When you run putnami init, Putnami creates these files at the workspace root:

  • CLAUDE.md / AGENT.md — lightweight entrypoints for Claude and Codex
  • .AI/context.md — generated framework and workspace context
  • .AI/constraints.md — durable project-specific rules shared across assistants

Together these files provide:

  • CLI commands — the AI knows to use putnami (not npm/yarn/bun)
  • Project structure — file-based routing conventions, where to put pages, loaders, actions, endpoints
  • Code patterns — builder APIs (page(), loader(), action(), endpoint()), schema types, UI components
  • Recipes — step-by-step instructions for adding database, authentication, configuration

The assistant reads the entrypoint file for its tool, then loads .AI/constraints.md first and .AI/context.md second.

Polyglot workspaces

If you add extensions after the initial setup, regenerate the AI context to include patterns for all installed languages:

putnami extensions install @putnami/go
putnami context generate

The regenerated shared context includes sections for every installed extension (TypeScript, Go, Python).

Orient in a project with agent context

When an assistant (Claude, Codex, or any MCP-aware tool) needs to understand a single project — where its composition roots are, which contracts and capabilities it exposes, which source is worth reading first, and how it is tested — Putnami can hand it those framework-owned facts directly instead of making it enumerate the repository.

putnami context pack

putnami context pack --project <project-id>

context pack aggregates one project's facts by reference into <project>/.gen/agent-context.json: identity and dependency graph, composition roots (application main, describe entrypoint), capability/contract/infra/migration references (path + digest), representative source ranges (never file content), a tests section (conformance packs or a machine-readable absence reason), adjacent docs, and a config-schema reference. Omit --project to pack every selected project.

The artifact is ephemeral: it lives under .gen/ (gitignored, never committed) because it embeds content digests and the workspace revision and would churn on every commit. Regenerate it on demand — do not check it in.

putnami context pack --check

putnami context pack --check

--check is a freshness gate: it verifies the on-disk artifact matches what the aggregator would produce now and exits 2 on drift (for example after you change a referenced source or a manifest) without rewriting anything. Use it in a pre-flight or CI step to catch a stale context.

The agent_context MCP tool

The Putnami MCP server exposes a read-only agent_context tool. An agent calls it to get a single project's identity, composition roots, contracts, representative sources, and tests in one structured response — including on-disk freshness — instead of listing directories and reading files one by one. It complements describe_project: describe_project answers "what commands/tasks/dependencies does this project have", while agent_context answers "how is this project composed and where should I read first".

These same tools are advertised to assistants in the generated .AI/context.md, so an agent that has loaded your workspace context already knows they exist.

Say what you want built, once

Framework facts tell an assistant how your project is composed; they never say what a change is for. That is what a spec holds — intended outcomes, non-goals, and the sentences your team agreed to — in one small, strictly validated file per feature. See Write a feature spec.

Prompt recipes

Here are prompts that work well with AI assistants in a Putnami project. The assistant uses the patterns from .AI/context.md to generate correct code.

Web applications (typescript-web)

Pages and routing:

  • "Add a page at /dashboard that shows a welcome message"
  • "Add a page at /users/[id] that displays user details"
  • "Add a layout for the /admin section with a sidebar navigation"

Data loading:

  • "Add a loader to the dashboard page that fetches stats from /api/stats"
  • "Add a loader to /users/[id] that fetches user data by ID"

Forms and actions:

  • "Add a form on /settings that lets users update their name and email"
  • "Add a contact form at /contact with name, email, and message fields"

API endpoints:

  • "Add a /api/users REST API with GET (list) and POST (create) endpoints"
  • "Add a GET /api/users/[id] endpoint with UUID validation"
  • "Add pagination with page and limit query params to GET /api/tasks"

API services (typescript-server)

  • "Add CRUD endpoints for a tasks resource with UUID ids"
  • "Add request validation to the POST /api/tasks endpoint — require name (string) and priority (int)"
  • "Add a GET /api/health endpoint that returns the server version"
  • "Add an endpoint that accepts file uploads"

Database and persistence

  • "Connect to PostgreSQL and create a users table with id, name, and email"
  • "Add a tasks table with id, title, done status, and created date"
  • "Create a repository for the users table with find-by-email support"

Authentication

  • "Add OAuth2 authentication and protect the /dashboard route"
  • "Add session-based auth with a login page"

Go services (go-server)

  • "Add a /health endpoint that returns JSON"
  • "Add CRUD handlers for a tasks resource"
  • "Add request logging middleware"

Python services (python-server)

python-server is experimental and explicit opt-in. It is not a default path and has no Go or TypeScript parity promise; first run putnami deps add @putnami/python, then create it with putnami projects create <name> --template python-server.

  • "Add a /tasks endpoint with GET and POST methods"
  • "Add a Pydantic model for task validation"

Customizing shared AI rules

Edit .AI/constraints.md to add project-specific context. Keep .AI/context.md generated and disposable; putnami context generate will rewrite it.

Good things to add:

  • Business rules — "Tasks belong to projects. A user can only see tasks in their projects."
  • Naming conventions — "Use camelCase for TypeScript, snake_case for database columns."
  • Architecture decisions — "This app uses a modular architecture. Each module has its own api/, web/, and data/ directories."
  • External dependencies — "We use Stripe for payments. The API key is in the STRIPE_API_KEY env var."

Tips for effective prompting

  1. Be specific about resource names — "Add a users endpoint" works better than "add an endpoint"
  2. Mention validation requirements — "name is required, email must be valid" helps the AI use the right schema types
  3. Reference sample projects — For complex patterns, point the AI to typescript/samples/13-fullstack-app or other samples
  4. Start simple, iterate — "Add a page at /dashboard" then "Add a loader that fetches user stats" works better than one giant prompt
  5. Use putnami serve to verify — After changes, run the app and check the result