Rules & Guidelines

Overview

Auggie automatically loads custom rules and guidelines from several file locations to provide context-aware assistance. These files help Auggie understand your project’s conventions, coding standards, and preferences.

The Auggie CLI uses the same rules system as the VSCode and JetBrains IDE extensions. For more information on IDE specific features like user guidelines, see Rules & Guidelines for Agent and Chat.

Looking for specialized domain knowledge? Check out Skills - a standardized way to provide framework-specific guidance, tool usage patterns, and workflow procedures following the agentskills.io specification.

Supported Rules Files

Auggie loads rules from these locations:

Custom rules (via the --rule flag): a file or directory
Workspace rules folder: <workspace_root>/.augment/rules/ - Recursively searches .md and .mdc files
User rules folder: ~/.augment/rules/ - Recursively searches .md and .mdc files for user-wide rules
AGENTS.md or CLAUDE.md: Loaded from the current directory and every parent directory. In each directory, Auggie loads AGENTS.md if it exists and otherwise CLAUDE.md
Workspace guidelines: <workspace_root>/.augment-guidelines

Run /rules in interactive mode to see which rules are loaded and their types. Use --no-rules to turn off rule discovery.

System prompt files

Two more files change the system prompt itself:

File	Effect
`.augment/APPEND_SYSTEM.md` or `~/.augment/APPEND_SYSTEM.md`	Appended to Auggie’s default system prompt
`.augment/SYSTEM.md` or `~/.augment/SYSTEM.md`	Replaces Auggie’s default system prompt

The project file is used when it exists; otherwise the user file is used. Rules and AGENTS.md files are still added when you use SYSTEM.md.

SYSTEM.md replaces the built-in instructions Auggie relies on to use its tools well. Prefer APPEND_SYSTEM.md or rules unless you need full control.

User Rules vs Workspace Rules

Rules can be defined at two levels:

Scope	Location	Availability
User	`~/.augment/rules/`	Available in all workspaces
Workspace	`<workspace_root>/.augment/rules/`	Available in current workspace only

User rules are stored in your home directory and apply to all projects. Use these for personal preferences, coding style guidelines, or conventions you want to follow across all your work. User rules are always treated as always_apply type and are automatically included in every prompt regardless of any frontmatter configuration. Workspace rules are stored in the project repository and apply only to that specific project. Use these for project-specific guidelines that should be shared with your team via version control.

Rules File Format

Rules files should be written in Markdown format with natural language instructions. Here’s the recommended structure:

# Project Guidelines

## Code Style
- Use TypeScript for all new JavaScript files
- Follow the existing naming conventions in the codebase
- Add JSDoc comments for all public functions and classes

## Architecture
- Follow the MVC pattern established in the codebase
- Place business logic in service classes
- Keep controllers thin and focused on request/response handling

## Testing
- Write unit tests for all new functions
- Maintain test coverage above 80%
- Use Jest for testing framework

## Dependencies
- Prefer built-in Node.js modules when possible
- Use npm for package management
- Pin exact versions in package.json for production dependencies

Frontmatter Configuration for Rules

Rules files in the <workspace_root>/.augment/rules/ (workspace) directory support frontmatter to configure their behavior. Use YAML frontmatter at the beginning of your rule file to specify how the rule should be applied:

User rules in ~/.augment/rules/ are always treated as always_apply and do not support other frontmatter types. Frontmatter configuration only affects workspace rules.

Frontmatter Field	Purpose	Options	Default
`type`	Controls when the rule is applied	`always_apply`, `agent_requested`, `manual`	`always_apply`
`description`	Brief description of the rule’s purpose (required for `agent_requested` type)	Any text	None

Rule Types:

always_apply: Rule contents are automatically included in every user prompt
agent_requested: Rule is automatically detected and attached based on the description field when relevant
manual: Rule is attached only when you reference it in a message as $rule-name

Manual rules

To attach a manual rule, type $ followed by the rule name in your message. Interactive mode suggests manual rules as you type. For a rule in a subfolder, include the folder, for example $frontend/react. If the name has spaces, quote it: $"my rule".

Review this change and apply $security-review

User rules in ~/.augment/rules/ are always treated as always_apply regardless of frontmatter.

Terminology mapping (CLI ↔ IDE extensions):

CLI (frontmatter `type`)	IDE display name	Behavior
`always_apply`	Always	Included in every prompt
`agent_requested`	Auto	Attached automatically when the agent decides the rule is relevant (based on `description`)
`manual`	Manual	Attached on demand: `$rule-name` in the CLI, @ mention in the IDE

Use agent_requested over always_apply if you want to optimize context usage. For these rules, the agent will determine the rule is relevant to your current task, ensuring specialized guidelines are available when needed. Example with frontmatter:

---
type: always_apply
---

# TypeScript Guidelines

- Use strict mode in all TypeScript files
- Define explicit return types for all functions
- Avoid using `any` type unless absolutely necessary

Agent-requested example:

---
type: agent_requested
description: React component development patterns and best practices
---

# React Component Guidelines

- Use functional components with hooks
- Implement proper TypeScript interfaces for props
- Follow the established folder structure in src/components/

Hierarchical Rules

In addition to workspace-level rules, the agent supports hierarchical rules through AGENTS.md and CLAUDE.md files placed in subdirectories. When working on files in a subdirectory, Augment automatically discovers and applies rule files from that directory and all parent directories.

How Hierarchical Rules Work

When the agent reads, edits, or writes a file, Auggie looks for AGENTS.md or CLAUDE.md in the file’s directory
It then walks up the directory tree, checking each parent directory up to the workspace root
Newly discovered files are added to the context for the rest of the session

Example Directory Structure

my-project/
  AGENTS.md                  <- Always included (workspace root)
  src/
    AGENTS.md                <- Included when working in src/ or subdirectories
    frontend/
      AGENTS.md              <- Included when working in src/frontend/
      App.tsx
    backend/
      AGENTS.md              <- Included when working in src/backend/
      server.ts
  tests/
    AGENTS.md                <- Only included when working in tests/

When working on src/frontend/App.tsx:

src/frontend/AGENTS.md is loaded (current directory)
src/AGENTS.md is loaded (parent directory)
AGENTS.md at workspace root is loaded via standard rules
src/backend/AGENTS.md and tests/AGENTS.md are not loaded (different branches)

Use Cases for Hierarchical Rules

Framework-specific guidelines: Place React-specific rules in your frontend directory and Node.js rules in your backend directory
Module-specific conventions: Define API design patterns in your api/ directory
Test-specific rules: Add testing conventions that only apply when writing tests
Team boundaries: Different teams can maintain their own coding standards in their directories

Important Notes

Only AGENTS.md and CLAUDE.md files are discovered hierarchically. If a directory has both, only AGENTS.md is used
Files in .augment/rules/ are only loaded from the workspace root, not from subdirectories
Rules are cached per conversation session to avoid duplicate inclusion
Hierarchical rules are combined with workspace and user rules

Best Practices for Rules Files

Be Specific: Provide clear, actionable guidelines rather than vague suggestions
Use Examples: Include code examples when describing patterns or conventions
Keep Updated: Regularly review and update rules as your project evolves
Be Concise: Focus on the most important guidelines to avoid overwhelming the AI
Test Guidelines: Verify that Auggie follows your rules by testing with sample requests

Command-Line Flag

You can load extra rules when starting Auggie. Pass a file or a directory, and repeat the flag to add more:

auggie --rule /path/to/custom-rules.md --rule /path/to/team-rules/

Rules loaded this way are always applied, in addition to the rules Auggie discovers automatically.

Getting Started

Cosmos

Auggie CLI

Other clients

Admin

Models & Pricing

Troubleshooting

Rules & Guidelines

Overview

Supported Rules Files

System prompt files

User Rules vs Workspace Rules

Rules File Format

Frontmatter Configuration for Rules

Manual rules

Hierarchical Rules

How Hierarchical Rules Work

Example Directory Structure

Use Cases for Hierarchical Rules

Important Notes

Best Practices for Rules Files

Command-Line Flag

See Also

​Overview

​Supported Rules Files

​System prompt files

​User Rules vs Workspace Rules

​Rules File Format

​Frontmatter Configuration for Rules

​Manual rules

​Hierarchical Rules

​How Hierarchical Rules Work

​Example Directory Structure

​Use Cases for Hierarchical Rules

​Important Notes

​Best Practices for Rules Files

​Command-Line Flag

​See Also

Overview

Supported Rules Files

System prompt files

User Rules vs Workspace Rules

Rules File Format

Frontmatter Configuration for Rules

Manual rules

Hierarchical Rules

How Hierarchical Rules Work

Example Directory Structure

Use Cases for Hierarchical Rules

Important Notes

Best Practices for Rules Files

Command-Line Flag

See Also