Path-Specific Rules

Path-Specific Rules is a ChatCLI conditional rules system that automatically applies instructions based on the file paths being discussed or edited in the conversation. Instead of loading all rules all the time, the system detects which files are in context and injects only the relevant rules.

Path Rules complement the bootstrap system (RULES.md). While RULES.md defines global rules, Path Rules defines rules specific to parts of the codebase.

Concept

The idea is simple: different parts of the codebase have different conventions. Go code follows different rules than HTML templates. Tests have different patterns than production code. Path Rules lets you define all of this granularly.

Conversation mentions auth/handler.go
      |
      v
Path matcher: "auth/**" -> auth-rules.md
Path matcher: "*.go"    -> go-rules.md
      |
      v
Rules injected into system prompt
(only the relevant ones)

File Structure

Rules are placed in the .chatcli/rules/ directory (workspace) or ~/.chatcli/rules/ (global):

.chatcli/rules/
|-- go-rules.md          # Rules for Go files
|-- test-rules.md        # Rules for test files
|-- api-rules.md         # Rules for the API module
|-- migration-rules.md   # Rules for database migrations
+-- security-rules.md    # Rules for security modules

File Format

Each rule file is Markdown with YAML frontmatter containing the paths field:

---
paths:
  - "*.go"
  - "**/*.go"
description: "Rules for Go code"
---
# Go Rules

## Style
- Use `gofmt` as the default formatter
- Variable names in camelCase
- Interfaces with "-er" suffix when they have a single method (Reader, Writer)

## Errors
- Always check returned errors
- Use `fmt.Errorf("context: %w", err)` for wrapping
- Never use `panic()` in production code

## Tests
- Use table-driven tests
- Name subtests descriptively
- Use `t.Helper()` in test helper functions

Precedence

Workspace vs Global
Multiple rules

Rules exist at two levels with workspace taking priority:

Level	Directory	Priority
Workspace	`.chatcli/rules/*.md`	High (overrides global)
Global	`~/.chatcli/rules/*.md`	Low (fallback)

If a rule file with the same name exists at both levels, the workspace version takes precedence.

When a file matches multiple patterns, all matching rules are injected:

File: auth/handler_test.go

Rules applied:
  1. go-rules.md        (match: *.go)
  2. test-rules.md      (match: *_test.go)
  3. api-rules.md       (match: auth/**)

Rules are concatenated in the order rule files are found (alphabetical).

Glob Matching

The paths field uses glob patterns to match file paths:

Pattern	Matches
`*.go`	Go files in the root directory
`*/.go`	Go files in any subdirectory
`*_test.go`	Go test files
`src/**`	All files inside `src/`
`auth/**`	All files inside `auth/`
`*.{ts,tsx}`	TypeScript and TSX files
`migrations/*.sql`	SQL files in `migrations/`
`Dockerfile*`	Dockerfiles (Dockerfile, Dockerfile.prod, etc.)

Use ** for recursive matching in subdirectories. The pattern *.go matches only in the root directory, while **/*.go matches across the entire tree.

Lazy Loading

Path Rules uses lazy loading based on conversation hints:

Context detection

ChatCLI analyzes recent messages and tool calls to identify which files are in context (read, edited, mentioned).

Pattern matching

Detected paths are compared against the paths patterns of each rule file.

Selective injection

Only rules that match files in context are injected into the system prompt.

Dynamic update

Every turn, patterns are re-evaluated. New rules can be injected and irrelevant rules can be removed.

Lazy loading ensures the system prompt doesn’t get overloaded with irrelevant rules. Only rules needed for the files under discussion are loaded, saving tokens.

Rule Examples

Go
Tests
Security
Migrations

.chatcli/rules/go-rules.md:

---
paths:
  - "**/*.go"
description: "Project Go conventions"
---
# Go Rules

- Use `errors.New()` or `fmt.Errorf()` for errors, never raw strings
- Exported functions MUST have a godoc comment
- Use `context.Context` as the first parameter when applicable
- Prefer `sync.Mutex` over channels for simple shared state
- Do not use `init()` except for driver registration

.chatcli/rules/test-rules.md:

---
paths:
  - "**/*_test.go"
  - "**/*.test.ts"
  - "**/*.spec.ts"
description: "Patterns for test files"
---
# Test Rules

- Use table-driven tests in Go
- Name subtests with clear English descriptions
- Avoid excessive mocking -- prefer fakes or simple stubs
- Each test should be independent and idempotent
- Use `t.Parallel()` when the test doesn't depend on global state

.chatcli/rules/security-rules.md:

---
paths:
  - "auth/**"
  - "security/**"
  - "**/middleware/auth*"
description: "Security rules for critical modules"
---
# Security Rules

- NEVER log tokens, passwords, or API keys
- Use `crypto/rand` for token generation, NEVER `math/rand`
- Validate ALL user inputs before processing
- Use prepared statements for SQL queries (injection prevention)
- Implement rate limiting on authentication endpoints
- JWT tokens must have a maximum expiration of 1 hour

.chatcli/rules/migration-rules.md:

---
paths:
  - "migrations/**"
  - "db/migrations/**"
description: "Rules for database migrations"
---
# Migration Rules

- Always include UP and DOWN operations
- Names in format: YYYYMMDDHHMMSS_description.sql
- Avoid ALTER TABLE on large tables without a downtime plan
- Use explicit transactions (BEGIN/COMMIT)
- Do not use DROP COLUMN in production without prior deprecation
- Add indexes on fields used in WHERE and JOIN clauses

Viewing Active Rules

You can check which rules are currently active:

User: Which path rules are active?

Agent: Based on the files in context, the following rules are active:

  Active Path Rules:
    go-rules.md       (match: auth/handler.go, auth/jwt.go)
    security-rules.md (match: auth/handler.go, auth/jwt.go)
    test-rules.md     (match: auth/handler_test.go)

  Total: 3 rules, ~450 tokens

Best Practices

Specific rules

Define precise path patterns. Rules that are too broad (**/*) waste tokens on irrelevant contexts.

Concise rules

Keep each rule file short and focused. Long rules consume more tokens.

Version in Git

Put .chatcli/rules/ in your repository to share with the team.

Combine with RULES.md

Use RULES.md for global rules and Path Rules for rules specific to areas of the codebase.

Home

Getting Started

Core Concepts

Features

Security

Support

Path-Specific Rules

Concept

File Structure

File Format

Precedence

Glob Matching

Lazy Loading

Rule Examples

Viewing Active Rules

Best Practices

Specific rules

Concise rules

Version in Git

Combine with RULES.md

Next Steps

Bootstrap and Memory

Customizable Agents

​Concept

​File Structure

​File Format

​Precedence

​Glob Matching

​Lazy Loading

​Rule Examples

​Viewing Active Rules

​Best Practices

Specific rules

Concise rules

Version in Git

Combine with RULES.md

​Next Steps

Bootstrap and Memory

Customizable Agents

Concept

File Structure

File Format

Precedence

Glob Matching

Lazy Loading

Rule Examples

Viewing Active Rules

Best Practices

Next Steps