Rules System

What Are Rules?

Rules are markdown files in ~/.claude/rules/ that provide Claude with contextual instructions. Unlike the main CLAUDE.md system prompt which is always loaded, rules are injected based on the type of work Claude is doing. They define standards for document formatting, file organization, and metadata.

Rules are shipped with Cognova and applied automatically. You can customize them or add your own.

Built-in Rules

markdown.md -- Formatting Conventions

Defines how Claude should write and format vault documents.

Headers: Use hierarchically -- # for document title (one per file), ## for major sections, ### for subsections.

Lists:

• - for unordered lists
• 1. for ordered/sequential steps
• - [ ] for action items within notes

Links: Wiki-style [[note-name]] for internal references between vault documents, standard markdown [text](url) for external links.

Code: Always use fenced code blocks with language identifiers.

Emphasis: **bold** for important terms, *italic* for emphasis or titles.

note-organization.md -- File and Folder Structure

Defines how vault documents should be named and organized.

File naming: Lowercase with hyphens -- project-ideas.md, not Project Ideas.md. Dated content uses the format meeting-notes-2024-01.md.

Folder structure: Documents follow the PARA method:

vault/
  inbox/       -- Uncategorized captures
  projects/    -- Active projects
  areas/       -- Ongoing responsibilities
  resources/   -- Reference material
  archive/     -- Completed or inactive

Before creating a note: Claude checks if a related note already exists, places it in the appropriate folder, adds frontmatter, and links to related notes.

When to split: A note should be split when it exceeds roughly 500 lines, covers multiple distinct topics, or contains sections that could be referenced independently.

frontmatter.md -- Metadata Standards

Defines the YAML frontmatter required on all vault documents.

Default frontmatter (applied automatically by the document sync system):

---
tags: []
shared: false
---

All fields:

Visibility modes:

1. Hidden (default) -- shared: false, requires authentication
2. Private -- shared: true, shareType: 'private', accessible via direct link only
3. Public -- shared: true, shareType: 'public', fully public and indexed

Tag conventions: Lowercase, hyphenated, limit 3-5 per document, prefer specific over generic (nuxt over programming).

How Rules Are Applied

Rules in ~/.claude/rules/ are available to Claude Code as contextual instructions. Claude Code loads them based on filename conventions and the current working context. The rules supplement the main CLAUDE.md system prompt with domain-specific guidance.

Adding Custom Rules

Create a new markdown file in ~/.claude/rules/:

# My Custom Rule

## When to Apply

Describe when this rule should be followed.

## Standards

- Specific instruction one
- Specific instruction two

Naming convention: Use descriptive, lowercase-hyphenated filenames -- api-design.md, code-review.md, commit-messages.md.

Example: Code Style Rule

# TypeScript Style

## Formatting
- No semicolons
- Single quotes for strings
- 2-space indentation

## Imports
- Group: built-in, external, internal, relative
- Use type imports: `import type { Foo } from './types'`

## Error Handling
- Always use typed errors
- Never catch and ignore silently

Example: Documentation Rule

# API Documentation

## When Documenting Endpoints
- Include method, path, and description
- Show request body with TypeScript types
- Show response format with example
- Note required authentication

Customizing Built-in Rules

The built-in rules are installed to ~/.claude/rules/ during setup. You can edit them directly:

# Edit the formatting rules
nano ~/.claude/rules/markdown.md

# Add a new rule
nano ~/.claude/rules/my-convention.md

Changes take effect on the next Claude session -- no restart required.