Custom Instructions & Memory

This lesson on Custom Instructions & Memory is hands-on and example-driven. You can configure persistent, vendor-agnostic guidelines for AI coding agents using root and scoped agents.md files. This eliminates repetitive prompt instructions by automatically enforcing coding conventions, directory-level overrides, and exact CLI execution rules across your projects.

What You'll Be Able To Do

• Create a root agents.md file to enforce project-wide conventions such as mandatory type hinting.
• Combine multiple global coding standards, including function naming conventions, within a single markdown configuration.
• Implement hierarchical context overrides in subdirectories while linking back to root guidelines.
• Structure agent instruction files with clear environment specifications and command-line execution prefixes.

Detailed Concept Walkthrough

1. Global Instructions via Root Configuration

A root-level agents.md file provides persistent, automatic context to AI agents without requiring manual prompt repetition.

• Mechanism: The AI coding agent loads the root agents.md file into its active context window at the start of every session, applying all documented rules to newly generated code.
• Under the Hood: Rather than relying on transient conversational memory that degrades across turns, the configuration file acts as a permanent system-level instruction layer.
• Best Practice: Define baseline constraints such as required type hints and docstring standards early in the root file to establish project-wide consistency.

# Global Agent Instructions

## Python Code Standards
- Always use type hints for function arguments and return types.
- Follow PEP 8 formatting conventions across all modules.

Key Takeaway: Root agents.md files eliminate prompt repetition by automatically injecting persistent coding standards into every agent interaction.

2. Accumulating Multiple Global Rules

AI agents can process and respect multiple distinct styling and behavioral constraints when organized cleanly in a single configuration file.

• Mechanism: Multiple rules are defined sequentially under clear Markdown headers, allowing the agent to parse and cross-reference multiple constraints simultaneously.
• Execution Flow: When a generation request is received, the agent reconciles all active constraints before producing output, ensuring no single rule is dropped.
• Syntax Rule: Phrase each rule as a clear, imperative directive (e.g., 'Use camel case when defining functions') to minimize ambiguity during token generation.

# Project Code Style

## Naming Conventions
- Use camelCase when defining functions and methods.
- Use PascalCase for class definitions.
- Always include explicit type hints in function signatures.

Key Takeaway: Layering clear, imperative rules within a single configuration ensures consistent adherence across multiple stylistic dimensions.

3. Hierarchical Context and Scoped Overrides

Subdirectory agents.md files allow localized rule overrides while maintaining parent context through relative links.

• Mechanism: Placing an agents.md file in a subfolder allows you to define localized exceptions that override root configurations for that specific subtree.
• Syntax Rule: Subdirectory instruction files should include a relative Markdown link back to the parent file (e.g., ../agents.md) to retain inherited context.
• Best Practice: Use hierarchical overrides for specialized modules like legacy folders or testing directories that require distinct conventions from the main application.

<!-- legacy_module/agents.md -->
# Legacy Module Instructions
- Inherit root instructions: [Root Config](../agents.md)

## Overrides
- Never use type hints in this directory.
- Maintain snake_case for all legacy utility functions.

Key Takeaway: Scoped agents.md files enable granular rule overrides in subdirectories without losing parent repository context.

4. Structured Commands and Environment Context

Defining runtime environments and required CLI prefixes at the top of instructions prevents broken agent command execution.

• Mechanism: Providing explicit CLI prefixes informs the agent how to run tools inside specific package managers and virtual environments.
• Under the Hood: Without explicit command definitions, agents default to standard system binaries (like global python), causing environment mismatches and migration failures.
• Best Practice: Place environment specifications and explicit 'correct vs. incorrect' command examples near the top of agents.md for maximum visibility.

# Environment & Tooling
- Python Version: 3.12
- Package Manager: UV

## CLI Execution Rules
- ALWAYS use: `uv run python manage.py <command>`
- NEVER use: `python manage.py` or `./manage.py`

Key Takeaway: Placing explicit CLI prefixes and environment definitions near the top of configuration files prevents invalid command generation.

Topics Covered in Custom Instructions & Memory

1. Implementing Global Instructions (2:49 - 4:15) — Create a root agents.md file to enforce baseline type hints across the project.
2. Defining Multiple Global Rules (4:51 - 6:05) — Add secondary rules like camelCase naming to demonstrate multi-rule agent compliance.
3. Hierarchical Context and Overrides (6:05 - 7:12) — Configure localized subdirectory instruction files that override root rules via relative links.
4. Structured CLI and Environment (7:12 - 9:08) — Structure instruction files with environment versions, package manager prefixes, and command examples.

AI-Assisted Coding Cheat Sheet

• agents.md (Root) — Defines project-wide persistent agent instructions
  • In practice: # Global Instructions

• Always use type hints.

• [Parent Config](../agents.md) — Links subdirectory instructions to parent context

  - Base rules: [Parent](../agents.md)
  

• agents.md (Subdirectory) — Overrides parent rules for local directory

  • In practice: - Never use type hints here.

• ALWAYS use: <command> — Enforces required execution wrapper prefix

  - ALWAYS use: uv run python
  

• NEVER use: <command> — Explicitly prohibits incorrect CLI execution syntax

  - NEVER use: ./manage.py
  

Comparison Table

Common Pitfalls

• Mistake: Placing CLI command prefixes at the bottom of the configuration file. Avoid: Put environment and execution rules near the top of agents.md.
• Mistake: Overriding rules in a subdirectory without linking to the parent file. Avoid: Add a relative Markdown link to parent instructions.
• Mistake: Giving vague command instructions without negative examples. Avoid: Provide explicit correct and prohibited command usage patterns.
• Mistake: Relying entirely on tool-specific configuration formats for team guidelines. Avoid: Use vendor-agnostic agents.md files for maximum portability.

FAQs

• Why should CLI command prefixes like 'uv run' appear early in agents.md? Placing execution rules near the top ensures the agent prioritizes environment constraints, preventing broken commands like direct Django migrations.
• How does an AI agent handle conflicting instructions between root and local files? The subdirectory agents.md takes precedence within its directory tree while inheriting non-conflicting root rules through relative links.
• What is the primary advantage of agents.md over .cursorrules? agents.md is an open, vendor-agnostic Markdown standard that works across multiple AI coding agents and development environments.
• Do I need to rewrite all global rules inside subdirectory agents.md files? No, link to the root file using ../agents.md and only define the specific rules you wish to override.