Conditional rules by path that apply automatically based on the files being discussed
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.
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 | vPath matcher: "auth/**" -> auth-rules.mdPath matcher: "*.go" -> go-rules.md | vRules injected into system prompt(only the relevant ones)
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
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
Path Rules uses lazy loading based on conversation hints:
1
Context detection
ChatCLI analyzes recent messages and tool calls to identify which files are in context (read, edited, mentioned).
2
Pattern matching
Detected paths are compared against the paths patterns of each rule file.
3
Selective injection
Only rules that match files in context are injected into the system prompt.
4
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.
---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
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
