Tighten AGENTS.md: remove redundant content covered by Memory

Removed sections that duplicate Workspace Memory:
- Recommended Entry Points (Memory has precise file/line locations)
- For Debugging paths (Memory has session/error log details)
- Dependency Analysis Artifacts (reference info, not actionable)

Kept essential guardrails:
- Critical Invariants (MUST/MUST NOT rules)
- Dangerous Code Paths (risk warnings, not locations)
- Do/Dont coding standards
- Common Incorrect Assumptions

Reduction: 125 lines → 69 lines (~45% smaller, ~650 tokens saved)
This commit is contained in:
Dhanji R. Prasanna
2026-01-29 11:13:25 +11:00
parent 7bfb9efa19
commit 9a998e201a

View File

@@ -1,7 +1,8 @@
# AGENTS.md - Machine Instructions for g3 # AGENTS.md - Machine Instructions for g3
**Purpose**: Machine-specific instructions for AI agents working with this codebase. **Purpose**: Machine-specific instructions for AI agents working with this codebase.
**For project overview, architecture, and usage**: See [README.md](README.md) **For code locations**: See Workspace Memory (loaded automatically)
**For project overview**: See [README.md](README.md)
## Critical Invariants ## Critical Invariants
@@ -24,77 +25,35 @@
4. **Never assume tool results fit in context** - Large results are thinned automatically 4. **Never assume tool results fit in context** - Large results are thinned automatically
5. **Never use byte-index string slicing on text with potential multi-byte characters** - Causes panics on emoji, CJK, box-drawing chars 5. **Never use byte-index string slicing on text with potential multi-byte characters** - Causes panics on emoji, CJK, box-drawing chars
## Recommended Entry Points ## Adding Features
### For Understanding the System - **New tool**: Add definition in `tool_definitions.rs`, implement in `tools/`, add dispatch case
- **New provider**: Implement `LLMProvider` trait in `g3-providers`
- **New CLI mode**: Add to CLI args, implement handler in `g3-cli`
- **New config option**: Add to `g3-config` structs
1. `src/main.rs` - Entry point (trivial) ## Dangerous Code Paths
2. `crates/g3-cli/src/lib.rs` - CLI logic and execution modes
3. `crates/g3-core/src/lib.rs` - Agent struct and orchestration
4. `crates/g3-providers/src/lib.rs` - Provider trait definition
### For Adding Features These areas have subtle bugs if modified incorrectly:
1. **New tool**: `crates/g3-core/src/tool_definitions.rs``crates/g3-core/src/tools/` | Area | Risk |
2. **New provider**: `crates/g3-providers/src/` → implement `LLMProvider` trait |------|------|
3. **New CLI mode**: `crates/g3-cli/src/lib.rs` | **Context window management** | Incorrect token estimates cause context overflow |
4. **New config option**: `crates/g3-config/src/lib.rs` | **Streaming parser** | Partial JSON across chunks causes parsing failures |
| **Tool dispatch** | Missing dispatch cases cause silent failures |
| **Retry logic** | Aggressive retries hit rate limits harder |
| **Parser sanitization** | Inline JSON can trigger false tool call detection |
### For Debugging ## Do's and Don'ts
1. Session logs: `.g3/sessions/<session_id>/session.json`
2. Error logs: `.g3/errors/`
3. Context state: Use `/stats` command in interactive mode
## Dangerous/Subtle Code Paths
### Context Window Management (`g3-core/src/context_window.rs`)
- **Thinning**: Automatically replaces large tool results with file references
- **Summarization**: Compresses conversation history at 80% capacity
- **Token estimation**: Uses character-based heuristics, not exact tokenization
- **Risk**: Incorrect token estimates can cause context overflow
### Streaming Parser (`g3-core/src/streaming_parser.rs`)
- Parses LLM responses in real-time for tool calls
- Must handle partial JSON across chunk boundaries
- **Risk**: Malformed responses can cause parsing failures
### Tool Dispatch (`g3-core/src/tool_dispatch.rs`)
- Routes tool calls to implementations
- Handles both native and JSON-based tool calling
- **Risk**: Missing dispatch cases cause silent failures
### Retry Logic (`g3-core/src/retry.rs`)
- Exponential backoff with jitter
- Different configs for interactive vs autonomous mode
- **Risk**: Aggressive retries can hit rate limits harder
### Parser Sanitization (`g3-core/src/streaming_parser.rs`)
- Sanitizes inline tool-call JSON patterns to prevent parser poisoning
- Replaces `{` with fullwidth `` (U+FF5B) when patterns appear inline (not on their own line)
- Real tool calls from LLMs always appear on their own line
- **Risk**: Inline JSON examples in prose can trigger false tool call detection without sanitization
## Do's and Don'ts for Automated Changes
### Do ### Do
- ✅ Run `cargo check` after modifications - ✅ Run `cargo check` after modifications
- ✅ Run `cargo test` before committing - ✅ Run `cargo test` before committing
- ✅ Update tool definitions when adding tools - ✅ Update tool definitions when adding tools
- ✅ Add tests for new functionality - ✅ Add tests for new functionality
- ✅ Use existing patterns for similar features
- ✅ Keep functions under 80 lines - ✅ Keep functions under 80 lines
- ✅ Update documentation for user-facing changes
### Don't ### Don't
- ❌ Modify `Cargo.toml` dependencies without justification
- ❌ Add blocking code in async contexts - ❌ Add blocking code in async contexts
- ❌ Store sensitive data in plain text - ❌ Store sensitive data in plain text
- ❌ Ignore error handling - ❌ Ignore error handling
@@ -108,18 +67,3 @@
3. **"Tool results are always small"** - File reads can return megabytes 3. **"Tool results are always small"** - File reads can return megabytes
4. **"Sessions persist across runs"** - Sessions are ephemeral by default 4. **"Sessions persist across runs"** - Sessions are ephemeral by default
5. **"All platforms are equal"** - macOS has more features (Vision, Accessibility) 5. **"All platforms are equal"** - macOS has more features (Vision, Accessibility)
## Dependency Analysis Artifacts
The `analysis/deps/` directory contains static analysis artifacts generated by the Euler agent:
| File | Purpose |
|------|--------|
| `graph.json` | Raw dependency graph data (crate and file-level edges with evidence) |
| `graph.summary.md` | Overview metrics: crate counts, edge counts, fan-in/fan-out rankings |
| `sccs.md` | Strongly Connected Components analysis (cycle detection via Tarjan's algorithm) |
| `layers.observed.md` | Mechanically-derived layer diagram showing crate hierarchy and intra-crate module structure |
| `hotspots.md` | Coupling hotspots: files/crates with disproportionate fan-in or fan-out (>2× average) |
| `limitations.md` | Known limitations of the static analysis (conditional compilation, macros, re-exports) |
These artifacts are useful for understanding coupling, planning refactors, and identifying architectural boundaries.