Project Rules

Define project-specific instructions in .codebuddy/rules.md. CodeBuddy loads them at workspace open, watches for changes, injects them into the Developer Agent’s system prompt in every conversation.

Supports dynamic values via {{js: EXPRESSION}} fragments (e.g. Current branch: {{js: host.gitBranch()}}) — see Sandboxed Scripts for the host bindings you can call.

Example .codebuddy/rules.md

# Project rules

## Code style

- TypeScript strict mode
- Prefer `const` over `let`
- Named exports, not default exports
- 100-char line max

## Testing

- Write tests for every new function
- Vitest for unit tests
- ≥ 80% coverage on new code

## Dependencies

- Use pnpm
- Prefer well-maintained packages (> 1000 weekly downloads)
- Pin dep versions

## Architecture

- Repository pattern for data access
- Zod for all input validation
- Keep controllers thin — business logic in services

Discovery order

ProjectRulesService checks 4 locations, first one found wins:

Priority	Path	Purpose
1	.codebuddy/rules.md	Primary location
2	.codebuddy/rules/index.md	Alternative for complex rule sets
3	.codebuddyrules	Root-level single file
4	CODEBUDDY.md	Convention-based

Token budget

Rules go into the system prompt → they consume context window.

• Default budget: 2000 tokens (~8000 chars)
• Configurable: codebuddy.rules.maxTokens
• Truncation: if rules exceed the budget, truncated with a warning

How rules flow

Each new conversation:

1. ProjectRulesService reads the rules file.
2. {{js:}} fragments expanded via the QuickJS pipeline (workspace context, git branch, glob results, etc.).
3. Rules appended to the system prompt under a ## Project rules section.
4. Agent follows them for code generation, tool selection, and decisions.
5. Custom rules from the rules.customRules setting (an array) are merged in.

Changes to the file are detected automatically — no editor restart.

Monorepo support

Rules at different levels:

my-monorepo/
  .codebuddy/rules.md          ← whole-repo default
  packages/
    frontend/
      .codebuddy/rules.md      ← frontend overrides
    backend/
      .codebuddy/rules.md      ← backend overrides

The closest file to the active file wins.

Settings

Setting	Default	Purpose
codebuddy.rules.enabled	true	Enable rules loading
codebuddy.rules.maxTokens	2000	Token budget
codebuddy.rules.showIndicator	true	Show rules status in the UI
rules.customRules	[]	Extra rules (array) appended to the system prompt, merged with file rules

Writing tips

• Be specific. “Use Zod for validation” > “Validate inputs”.
• Include examples for nuanced conventions.
• Keep concise — every rule costs context tokens.
• Categorize (Code Style / Testing / Architecture) for scannability.
• Update as the project evolves — stale rules mislead the agent.

Related

• Skills — for capability-based conventions rather than free-form rules
• Context system — where rules fit in the per-turn context budget