Code Review Best Practices

Example guidelines for Augment Code Review. Use these as inspiration and starting points for your own code review guidelines.

Quick Start

1. Create a .augment folder in your repository root
2. Create a file named code_review_guidelines.yaml inside it
3. Copy and customize rules from the examples below

your-repo/
└── .augment/
    └── code_review_guidelines.yaml

File Format

See code_review_guidelines.example.yaml for a complete working example.

areas:
  area_name:
    description: "Description of this area"
    globs:
      - "**/*.py"           # Files this area applies to
    rules:
      - id: "unique_rule_id"
        description: "What to check for and why it matters"
        severity: "high"    # high, medium, or low

Fields

Field	Required	Description
areas	Yes	Top-level container for all rule areas
area_name	Yes	Unique identifier for each area (e.g., python_security, database)
description	Yes	Human-readable description of the area
globs	Yes	File patterns to match (see Glob Patterns below)
rules	Yes	List of rules for this area
id	Yes	Unique identifier for the rule
description	Yes	What the rule checks and why it matters
severity	Yes	Priority level: "high", "medium", or "low"

Glob Patterns

Pattern	Description	Example Matches
**	Any number of directories	**/test.py matches test.py, src/test.py, src/utils/test.py
*	Any characters in one directory	*.py matches main.py but not src/main.py
?	Single character	test?.py matches test1.py but not test10.py

Example Guidelines

Browse the example-guidelines/ directory for comprehensive rules organized by category:

Languages

File	Description
python.yaml	Security, performance, best practices for Python
typescript.yaml	Type safety, React patterns, async handling
javascript.yaml	Security, performance, common pitfalls
java.yaml	Security, concurrency, best practices
go.yaml	Error handling, concurrency, idioms
rust.yaml	Memory safety, performance, best practices
c-cpp.yaml	Memory safety, undefined behavior, security

Databases

File	Description
sql-general.yaml	SQL injection, query optimization, transactions
postgresql.yaml	PostgreSQL-specific features and performance
mongodb.yaml	NoSQL patterns, indexing, security

Security

File	Description
authentication.yaml	Password handling, sessions, JWT, OAuth
authorization.yaml	Access control, permissions, RBAC
input-validation.yaml	XSS, injection prevention, sanitization
secrets-management.yaml	API keys, credentials, environment variables

Infrastructure

File	Description
docker.yaml	Container security, image optimization
kubernetes.yaml	Pod security, resource management
terraform.yaml	IaC best practices, state management

More Categories

• API Design: rest.yaml, graphql.yaml, grpc.yaml
• Testing: unit-testing.yaml, integration-testing.yaml
• Code Quality: error-handling.yaml, logging.yaml
• Performance: caching.yaml, concurrency.yaml
• Frontend: react.yaml, accessibility.yaml

MCP Integration (External Context)

File	Description
mcp-integration.yaml	Fetch context from Linear, Jira via MCP to verify implementation matches ticket requirements

Note: MCP integration rules require MCP servers to be configured. This is an enterprise-only feature. See here for setup details.

Assembling Your Guidelines

Option 1: Start with the Example File

Copy the complete example and customize it:

mkdir -p .augment
cp code_review_guidelines.example.yaml .augment/code_review_guidelines.yaml
# Edit to match your project's needs

Option 2: Combine Specific Rules

Pick rules from individual example files and combine them:

# .augment/code_review_guidelines.yaml
areas:
  # Copy the python_security area from example-guidelines/languages/python.yaml
  python_security:
    description: "Python security rules"
    globs:
      - "**/*.py"
    rules:
      - id: "avoid-eval-exec"
        description: "Never use eval() or exec() with untrusted input..."
        severity: "high"
      # Add more rules...

  # Copy rules from example-guidelines/security/authentication.yaml
  authentication:
    description: "Authentication security rules"
    globs:
      - "**"
    rules:
      - id: "use-strong-password-hashing"
        description: "Always use bcrypt, argon2, or scrypt..."
        severity: "high"

Option 3: Reference Another Guideline File

You can reference rules from another file by providing its path:

# .augment/code_review_guidelines.yaml

areas:
  custom_rules:
    description: "Project-specific guidelines"
    globs:
      - "**"
    rules:
      - id: "exising_agent_md"
        description: "Read clients/agent.md for general engineering guidelines"
        severity: "medium"

⚠️ Warning: Keep your total guidelines concise. Excessively long guidelines may reduce review quality as the model has more context to process. Focus on the most important rules for your project.

Option 4: Convert Existing Guidelines from agents.md

If you already have coding guidelines in a free-text format (like agents.md or a coding standards document), you can use Augment to convert them to the YAML format.

Example prompt:

Convert the following coding guidelines into Augment Code Review YAML format.

Use this structure for each rule:
- id: unique kebab-case identifier
- description: clear description of what to check and why
- severity: "high" for security/critical bugs, "medium" for best practices, "low" for style

Group related rules into areas with appropriate globs.

Here are my current guidelines:

---
[Provide your agents.md or coding standards document here]
---

Tips

• Be specific: Use targeted globs to avoid applying rules to irrelevant files
• Focus on objective issues: Prioritize bugs, security vulnerabilities, and performance over style
• Keep it maintainable: Start small and add rules as you identify patterns in code reviews
• Use severity wisely: Reserve high for security issues and critical bugs
• Keep guidelines concise: Fewer, high-quality rules are more effective than many vague ones

Resources

• Augment Code Review Documentation

License

This project is licensed under the MIT License.