Slim down AGENTS.md and update lamport.md for machine-specific output

AGENTS.md changes:
- Removed redundant sections that duplicated README.md:
  - System Overview (crate table)
  - File Structure Quick Reference
  - Testing Strategy
  - Pointers to Documentation
  - Architecture Decisions
- Kept unique machine-specific sections:
  - Critical Invariants (merged Performance Constraints)
  - Recommended Entry Points
  - Dangerous/Subtle Code Paths
  - Do's and Don'ts for Automated Changes
  - Common Incorrect Assumptions
  - Dependency Analysis Artifacts
- Reduced from ~220 lines to ~116 lines

lamport.md changes:
- Rewrote AGENTS.md section with explicit instructions
- Added REQUIRED sections list (5 sections only)
- Added DO NOT include list to prevent README duplication
- AGENTS.md now points to README for architecture/usage
This commit is contained in:
Dhanji R. Prasanna
2026-01-06 12:46:40 +11:00
parent 6d2cab93f5
commit e2fffaab94
2 changed files with 46 additions and 117 deletions

View File

@@ -268,16 +268,48 @@ you may create or update AGENTS.md.
Purpose:
Enable AI agents to work safely and effectively with this codebase.
Include:
- Machine-oriented system overview
- Stable vs volatile areas
- Recommended entrypoints
- Dangerous or subtle code paths
- Invariants that MUST hold
- Performance or correctness constraints
- Dos and donts for automated changes
- Pointers to architecture and decision docs
- Explicit warnings about likely incorrect assumptions
CRITICAL: AGENTS.md must contain ONLY machine-specific instructions.
Do NOT duplicate content from README.md.
AGENTS.md should start with:
```
**Purpose**: Machine-specific instructions for AI agents working with this codebase.
**For project overview, architecture, and usage**: See [README.md](README.md)
```
REQUIRED sections (include ONLY these):
1. **Critical Invariants**
- MUST hold constraints (e.g., "Tool calls must be valid JSON")
- MUST NOT do constraints (e.g., "Never block the async runtime")
- Performance constraints that affect correctness
2. **Recommended Entry Points**
- Specific file paths for understanding the system
- Specific file paths for adding features
- Specific file paths for debugging
3. **Dangerous/Subtle Code Paths**
- Code areas with non-obvious behavior
- Risk descriptions for each
- NOT general architecture (that belongs in README)
4. **Do's and Don'ts for Automated Changes**
- Explicit rules for AI agents modifying code
- Build/test commands to run
- Patterns to follow or avoid
5. **Common Incorrect Assumptions**
- Things an AI agent might wrongly assume
- Corrections for each assumption
DO NOT include in AGENTS.md:
- Architecture overview (use README)
- Crate/module descriptions (use README)
- File structure diagrams (derivable from codebase)
- Documentation links (use README's Documentation Map)
- Testing instructions beyond "run cargo test" (trivial)
- How to use the project (use README)
------------------------------------------------------------
ACCURACY CHECKS