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).

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)

• "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