Project Rules File

A project rules file lets you give the agent persistent context about your project — tech stack, conventions, architecture decisions, commands to run. The agent reads it at the start of every session.

Supported Filenames

OpenClacky checks for these files in your project root, in order:

The first file found is used. Only one file is loaded per session.

What to Put in It

Anything the agent needs to know to work effectively in your project:

# My Project

## Tech Stack
- Ruby on Rails 7.2 + PostgreSQL
- Stimulus + Hotwire Turbo (no jQuery, no inline JS)
- Tailwind CSS with custom design tokens

## Commands
- `bin/dev` — start dev server (never use `rails s`)
- `rake test` — run full test suite
- `rails runner 'code'` — run one-off Ruby

## Conventions
- All Stimulus controllers must be TypeScript
- Never use raw Tailwind color classes — use semantic tokens
- Controllers render turbo_stream templates, no respond_to blocks

Good things to include:
- How to start / test / build the project
- Architecture decisions and why
- Patterns to follow (and anti-patterns to avoid)
- Domain model overview
- Any gotchas or non-obvious constraints

Keep it focused. The file is injected into the system prompt — concise and structured works better than a long essay.

How It's Loaded

The file is injected as Layer 3 of the system prompt, after the agent's core instructions but before personality and skills context. It's always in scope for the entire session.

Layer 1: Agent role & responsibilities
Layer 2: Universal behavioral rules
Layer 3: ← Your .clackyrules goes here
Layer 4: Agent personality (SOUL.md)
Layer 5: User profile (USER.md)
Layer 6: Available skills

Multiple Projects in One Workspace

If you have multiple sub-projects, put a single .clackyrules at the workspace root covering all of them:

# My Workspace

Two sub-projects, developed in parallel.

## Project A: api/ — Rails backend
- PostgreSQL, Ruby 3.2
- `cd api && bin/dev` to start

## Project B: web/ — Next.js frontend  
- TypeScript, Tailwind
- `cd web && npm run dev` to start

## Shared conventions
- API versioned at /api/v1
- All dates in ISO 8601

Tips

• Update it as the project evolves — outdated rules are worse than no rules
• Use headers — the agent scans structure, not just reads linearly
• Include commands verbatim — exact command strings are more useful than descriptions