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:
90
AGENTS.md
90
AGENTS.md
@@ -1,7 +1,8 @@
|
||||
# AGENTS.md - Machine Instructions for g3
|
||||
|
||||
**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
|
||||
|
||||
@@ -24,77 +25,35 @@
|
||||
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
|
||||
|
||||
## 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)
|
||||
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
|
||||
## Dangerous Code Paths
|
||||
|
||||
### 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/`
|
||||
2. **New provider**: `crates/g3-providers/src/` → implement `LLMProvider` trait
|
||||
3. **New CLI mode**: `crates/g3-cli/src/lib.rs`
|
||||
4. **New config option**: `crates/g3-config/src/lib.rs`
|
||||
| Area | Risk |
|
||||
|------|------|
|
||||
| **Context window management** | Incorrect token estimates cause context overflow |
|
||||
| **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
|
||||
|
||||
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's and Don'ts
|
||||
|
||||
### Do
|
||||
|
||||
- ✅ Run `cargo check` after modifications
|
||||
- ✅ Run `cargo test` before committing
|
||||
- ✅ Update tool definitions when adding tools
|
||||
- ✅ Add tests for new functionality
|
||||
- ✅ Use existing patterns for similar features
|
||||
- ✅ Keep functions under 80 lines
|
||||
- ✅ Update documentation for user-facing changes
|
||||
|
||||
### Don't
|
||||
|
||||
- ❌ Modify `Cargo.toml` dependencies without justification
|
||||
- ❌ Add blocking code in async contexts
|
||||
- ❌ Store sensitive data in plain text
|
||||
- ❌ Ignore error handling
|
||||
@@ -108,18 +67,3 @@
|
||||
3. **"Tool results are always small"** - File reads can return megabytes
|
||||
4. **"Sessions persist across runs"** - Sessions are ephemeral by default
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user