Skip to main content

Project Instructions

The ai.instructions section configures the ATMOS.md file that provides persistent, project-specific instructions to the AI assistant.

Experimental

What are Project Instructions?​

Project Instructions are stored in a markdown file (ATMOS.md) in your project root. You create and maintain this file yourself. When enabled, its contents are automatically included with every AI request, providing consistent context across all conversations.

Common things to include:

  • Project Context: Organization name, Atmos version, regions, environments
  • Common Commands: Frequently used Atmos commands for your project
  • Stack Patterns: Naming conventions and YAML structure patterns
  • Infrastructure Patterns: Multi-region setups, component dependencies
  • Component Catalog: Your component organization and structure
  • Team Conventions: Development practices and documentation standards

Configuration​

atmos.yaml

ai:
  instructions:
    enabled: true                        # Enable project instructions (default: false)
    file: "ATMOS.md"                     # Instructions file location (default: ATMOS.md)

Instruction Settings​

instructions.enabled
Enable project instructions (default: false). When enabled, the contents of the instructions file are automatically included with every AI request.
instructions.file
Path to the instructions file, relative to project root or absolute (default: ATMOS.md). The file uses Markdown format. If the file does not exist, instructions are silently skipped.

Creating Your Instructions File​

Create an ATMOS.md file in your project root with any content relevant to your project:

ATMOS.md

# Atmos Project Instructions

## Project Context

**Organization:** acme-corp
**Atmos Version:** 1.89.0
**Primary Regions:** us-east-1, us-west-2
**Environments:** dev, staging, prod

**Stack Naming Pattern:**
```
{org}-{tenant}-{environment}-{region}-{stage}
Example: acme-core-prod-use1-network
```

## Common Commands

```bash
# Describe a component
atmos describe component <component> -s <stack>

# List all stacks
atmos list stacks

# Validate stacks
atmos validate stacks

# Plan a component
atmos terraform plan <component> -s <stack>
```

## Stack Patterns

```yaml
# Common import pattern
import:
  - catalog/stacks/baseline
  - catalog/stacks/network
```

### CIDR Blocks
- dev: 10.0.0.0/16
- staging: 10.1.0.0/16
- prod: 10.2.0.0/16

## Component Dependencies

```
vpc → subnets → security-groups → rds → eks
```

## Team Conventions

- All infrastructure changes require PR review
- Use `atmos validate` before committing
- Tag all resources appropriately
- Document component changes

Instructions vs Context Sharing​

Content
Project Instructions: High-level patterns, conventions, common commands. Context Sharing: Actual stack YAML files and configurations.
Update frequency
Project Instructions: Updated manually by you. Context Sharing: Every request (real-time).
Size
Project Instructions: Small (few KB). Context Sharing: Large (multiple files).
Privacy
Project Instructions: Low risk (you control content). Context Sharing: Higher risk (may contain secrets).
Use case
Project Instructions: Consistent AI behavior across chats. Context Sharing: Deep analysis of specific configs.

Best Practice: Enable both for optimal results:

  • Instructions provide consistent baseline knowledge
  • Context sharing adds real-time specifics when needed

Performance Considerations​

Project instructions add tokens to every AI request:

Small file (1-2 KB)
Negligible impact on performance and cost.
Medium file (5-10 KB)
~500-1000 tokens per request.
Large file (20+ KB)
~2000+ tokens per request. Keep your instructions concise.

Privacy​

The contents of your ATMOS.md file are sent to your AI provider with every request when instructions are enabled. Only include information you are comfortable sharing with your configured AI provider.

Troubleshooting​

Instructions not loading:

# Check if file exists
ls -la ATMOS.md

# Verify configuration
grep -A3 "instructions:" atmos.yaml

AI not using instructions:

  • Verify instructions.enabled: true in atmos.yaml
  • Check that ATMOS.md exists in project root
  • Ensure the file is readable