Develop with AI assistants

Use AI coding assistants like Claude Code, Cursor, or GitHub Copilot to build Putnami applications faster. When you initialize a workspace, Putnami generates a .claude/CLAUDE.md file that teaches AI assistants your project's framework patterns, CLI commands, and file conventions.

What you get

When you run putnami init, a .claude/CLAUDE.md file is created at the workspace root. This file contains:

• 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 AI reads this file automatically and can respond correctly to simple prompts without you explaining the framework.

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 file 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 AI uses the patterns from .claude/CLAUDE.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 the AI context

Edit .claude/CLAUDE.md to add project-specific context. The AI reads this file on every session, so keep it concise.

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