This repository demonstrates a structured approach for providing AI agents with essential context about unfamiliar operating environments. The pattern facilitates effective human-AI collaboration by establishing clear communication channels and context sharing.
env-docs/
├── README.md # This file - explains the pattern
├── rules.md # Guidelines for AI agents about env docs purpose and formatting
├── system-metadata.json # Core system specifications and configuration
├── for-agent/ # Documentation written FOR AI agents
│ ├── agent-instructions.md # Primary instructions and context for agents
│ └── context-notes.md # Specific context, patterns, and troubleshooting
└── for-human/ # Documentation provided BY agents TO humans
└── environment-updates.md # Timestamped log of system changes
This documentation pattern serves to:
- Provide Context: Give AI agents essential information about the operating environment
- Establish Conventions: Document preferred tools, workflows, and patterns
- Track Changes: Maintain a log of environment modifications that may affect operations
- Enable Continuity: Allow agents to understand the environment state across sessions
- Facilitate Troubleshooting: Provide quick reference for common issues and solutions
Meta-documentation that provides AI agents with:
- Context about the purpose and scope of the env-docs repository
- Guidelines for creating and maintaining environment documentation
- Formatting standards for timestamps and file naming conventions
- Documentation scope parameters to distinguish environment docs from project-specific documentation
- Instructions for maintaining selective, organized documentation that avoids information overload
Core system information in structured format:
- Operating system details and version
- Hardware specifications (CPU, RAM, GPU, storage)
- Network configuration and topology
- Development tools and authenticated services
- User context and preferences
Documentation specifically written for AI agents:
Primary instructions containing:
- Environment overview and key context
- Development preferences and tool priorities
- Authentication and secrets management
- Network services and deployment patterns
- Best practices and communication guidelines
Detailed context including:
- Current environment state and recent changes
- Task-specific workflows and patterns
- Common troubleshooting procedures
- Resource utilization guidelines
- Emergency procedures and recovery steps
Documentation provided by agents to humans:
Timestamped log of:
- System updates and package installations/removals
- Configuration changes and network modifications
- Development environment updates
- Security updates and authentication changes
- Notes for future reference
- Start Here: Read
system-metadata.jsonfor core system understanding - Follow Instructions: Use
for-agent/agent-instructions.mdas primary guidance - Check Context: Review
for-agent/context-notes.mdfor specific patterns - Monitor Changes: Check
for-human/environment-updates.mdfor recent modifications - Document Updates: Log significant changes in the appropriate files
- Provide Context: Update
for-agent/files with new requirements or preferences - Monitor Changes: Review
for-human/environment-updates.mdfor agent-made modifications - Maintain Currency: Keep
system-metadata.jsonupdated with system changes - Add Instructions: Update agent instructions based on recurring issues or new patterns
- System Changes: Update
system-metadata.jsonwhen hardware/software changes - Tool Updates: Modify agent instructions when preferences change
- Pattern Evolution: Document new successful workflows in context notes
- Issue Resolution: Add troubleshooting steps for recurring problems
- Keep Current: Regular updates ensure accuracy and relevance
- Be Specific: Detailed information prevents misunderstandings
- Document Changes: Log modifications with timestamps and reasoning
- Review Regularly: Periodic review ensures continued effectiveness
This pattern can be adapted for different environments:
- Modify
system-metadata.jsonfor OS-specific details - Update tool preferences and installation methods
- Adjust network configuration patterns
- Development Environments: Focus on build tools and deployment patterns
- Production Systems: Emphasize monitoring, security, and maintenance
- Research Environments: Highlight data processing and analysis tools
- Personal Systems: Include personal preferences and workflow patterns
- Individual Use: Simple structure with personal preferences
- Team Use: Include team conventions and shared resources
- Enterprise Use: Add compliance requirements and security policies
- Agent reads
system-metadata.jsonfor system overview - Reviews
agent-instructions.mdfor operational guidelines - Checks
environment-updates.mdfor recent changes - Proceeds with task using documented preferences and patterns
- Human performs system update
- Agent logs changes in
environment-updates.md - Human updates
system-metadata.jsonif specifications changed - Agent instructions updated if new tools or patterns emerge
- Agent encounters issue
- Checks
context-notes.mdfor known solutions - Reviews
environment-updates.mdfor recent changes that might cause issues - Documents solution in appropriate file for future reference
This environment documentation pattern is designed to work seamlessly with AI coding assistants and can be integrated with existing system prompts and custom instructions.
This pattern has been tested and works well with:
- Windsurf (Roo) - Codeium's AI coding assistant
- Cline - VS Code extension for AI-powered development
- Cursor - AI-first code editor
- Continue - Open-source AI coding assistant
- Other Claude/GPT-based coding tools
Add references to your environment docs in your system prompts:
# Environment Context
Before starting any task, check the following files for environment-specific context:
- `env-docs/system-metadata.json` - Core system specifications
- `env-docs/for-agent/agent-instructions.md` - Primary operational guidelines
- `env-docs/for-agent/context-notes.md` - Current environment state and patternsFor tools like Windsurf/Roo, incorporate environment docs into your custom instructions:
# Environment Documentation
This project includes structured environment documentation in `env-docs/`.
Always consult these files for:
- System specifications and capabilities
- Tool preferences and authentication
- Network topology and deployment patterns
- Recent changes and current environment stateMany AI assistants support workspace-specific settings. You can:
- Reference environment docs in workspace configuration files
- Set up automatic context loading from environment documentation
- Configure tool preferences based on documented specifications
- AI assistants understand your specific environment constraints
- Reduces need to repeatedly explain system specifications
- Enables more accurate tool and approach recommendations
- Maintains context between different AI assistant sessions
- Ensures consistent tool preferences and workflows
- Reduces configuration drift over time
- AI assistants can reference documented solutions
- Faster resolution of environment-specific issues
- Better understanding of system limitations and capabilities
# In your Windsurf custom instructions:
Environment Context: This system uses the env-docs pattern for environment documentation.
Always check env-docs/system-metadata.json for system specs and env-docs/for-agent/
for current instructions and context before proceeding with tasks.// In your Cline configuration:
{
"systemMessage": "Check env-docs/ folder for environment context before starting tasks. Use documented tool preferences and follow established patterns.",
"contextFiles": [
"env-docs/system-metadata.json",
"env-docs/for-agent/agent-instructions.md"
]
}- Configure AI assistants to check environment docs at session start
- Include environment context in initial prompts
- Update AI assistant configurations when environment docs change
- Use the same environment documentation across all AI tools
- Keep AI assistant configurations synchronized with documented preferences
- Update both environment docs and AI configurations together
- Set up automatic context loading where supported
- Use workspace-specific configurations for different projects
- Configure AI assistants to log changes in environment update files
- Track how well AI assistants follow documented preferences
- Update environment documentation based on AI assistant feedback
- Refine integration based on actual usage patterns
This integration approach ensures that your AI coding assistants have consistent, up-to-date context about your environment, leading to more effective collaboration and better results.