AGENTS.md File Specification

The AGENTS.md file provides a standardized schema for configuring the behavior of AI agents across various AI code development tools. Through this file, developers can define project-specific instructions, coding standards, and guidelines to direct AI agents to follow consistent requirements when working with codebases.

Definition of AGENTS.md

AGENTS.md is used to configure the behavioral patterns of AI agents in software projects. It is a lightweight Markdown file located in the project root directory, containing a set of instructions for AI code assistants. This standard is currently supported by several mainstream AI code tools.

AGENTS.md can be understood as a README for AI agents — it explicitly tells AI agents how to adapt to a specific project, which coding conventions to follow, and what constraints to abide by.

Benefits of Using AGENTS.md

• Cross-tool Compatibility: Functions across multiple AI code tools without modification
• Version Control: Stored in the code repository alongside project code, enabling version tracking
• Team Consistency: Ensures all team members' AI assistants adhere to unified specifications
• Project Customization: Configurable to match the unique requirements and coding conventions of the project
• Simplicity: Written in pure Markdown, no special syntax or configuration rules required

File Naming and Placement

Project-level AGENTS.md

The AGENTS.md file should be placed in the project root directory. An example directory structure is as follows:

my-project/
├── AGENTS.md  # Primary configuration file (recommended)
├── src/
├── package.json
└── README.md

File Name Priority (in order of recognition):

1. AGENTS.md (plural uppercase, recommended)
2. AGENT.md (singular uppercase, fallback)

⚠️ Filename Case Rule:

The filename must be in all uppercase (AGENTS.md); lowercase formats (agents.md) are not supported. This design ensures consistency across different operating systems and development tools.

Subdirectory-level AGENTS.md

Developers may also place AGENTS.md files in subdirectories to define context-specific instructions. An example directory structure is as follows:

my-project/
├── AGENTS.md          # Root-level global instructions
├── src/
│   └── backend/
│       └── AGENTS.md  # Backend module-specific instructions
└── docs/
    └── AGENTS.md      # Documentation module-specific instructions

When developing within a subdirectory, the VJSP tool loads both the root AGENTS.md and the current subdirectory's AGENTS.md. In case of conflicting instructions, the subdirectory file takes precedence.

File Protection Mechanism

In the VJSP tool, both AGENTS.md and AGENT.md are write-protected files. The specific rules are:

• AI agents cannot modify these files without explicit user authorization
• The tool will prompt for confirmation; modifications require manual user approval
• This mechanism prevents accidental tampering of project AI configuration files by AI agents

Basic Syntax and File Structure

AGENTS.md is written in standard Markdown syntax with no mandatory structure. However, organizing content with headings and lists improves the efficiency and accuracy of AI model parsing.

Recommended File Structure

# Project Name

Brief description and core purpose of the project.

## Coding Style

- All new files to be developed in TypeScript
- Strict adherence to ESLint configuration
- Indentation using 2 spaces

## Architecture Design

- Follow MVC design pattern
- Component code limited to 200 lines or less
- Adopt dependency injection pattern

## Testing Standards

- All business logic code requires unit tests
- Maintain code coverage above 80%
- Use Jest as the unified testing framework

## Security Guidelines

- Prohibit committing API keys or sensitive information to the repository
- All user input must undergo validation
- Use parameterized queries for database operations

Best Practices for Writing

• Clarity: Use specific, quantifiable rules (e.g., "Cyclomatic complexity limit of 10") instead of vague statements like "Write high-quality code"
• Examples: Embed code snippets to demonstrate standards for error handling, naming conventions, or architecture
• Structure: Group related guidelines under clear headings (e.g., Coding Style, Architecture Design, Testing Standards, Security Guidelines)
• Conciseness: Use bullet points and direct statements, avoiding lengthy paragraphs
• Maintenance: Regularly review and update the file as project conventions evolve

How AGENTS.md Works in VJSP

File Loading Process

When starting a development task in VJSP, the tool performs the following actions:

1. Checks for the presence of AGENTS.md or AGENT.md in the project root directory
2. If detected, loads the content and injects it into the AI agent's context
3. The AI agent follows the instructions throughout the interaction
4. After modifying AGENTS.md, new rules take effect in new tasks (a tool restart may be required)

Priority Relationship with Other Rule Systems

AGENTS.md works in conjunction with VJSP's other configuration systems, with priority ordered from highest to lowest:

Configuration Type	Scope	Path	Core Purpose	Priority
Mode-specific Custom Rules	Project	.vjsp/rules-{mode}/	Rule constraints for specific development modes	1 (Highest)
Custom Rules	Project	.vjsp/rules/	VJSP-specific rule configuration	2
AGENTS.md Rules	Project	Root / Subdirectories	Cross-tool compatible project specifications	3
Global Custom Rules	Global	~/.vjsp/rules/	VJSP global rule configuration	4
Custom Instructions	Global	IDE Settings	Personalized preferences for all projects	5 (Lowest)

Enabling and Disabling

AGENTS.md is enabled by default in VJSP. To disable it, add the following parameter to your settings.json configuration file:

{
  "VJSP.useAgentRules": false
}

Related Modules

• Custom Rules: VJSP-specific rule configuration for fine-grained control
• Custom Modes: Dedicated workflow configurations with specific permissions
• Custom Instructions: Global personalized preferences applicable to all projects