9a998e201a
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)
70 lines
3.1 KiB
Markdown
70 lines
3.1 KiB
Markdown
# AGENTS.md - Machine Instructions for g3
|
|
|
|
**Purpose**: Machine-specific instructions for AI agents working with this codebase.
|
|
**For code locations**: See Workspace Memory (loaded automatically)
|
|
**For project overview**: See [README.md](README.md)
|
|
|
|
## Critical Invariants
|
|
|
|
### MUST Hold
|
|
|
|
1. **Tool calls must be valid JSON** - The streaming parser expects well-formed tool calls
|
|
2. **Context window limits must be respected** - Exceeding limits causes API errors
|
|
3. **Provider trait implementations must be Send + Sync** - Required for async runtime
|
|
4. **Session IDs must be unique** - Used for log file paths and TODO scoping
|
|
5. **File paths in tools support tilde expansion** - `~` expands to home directory
|
|
6. **Streaming is preferred** - Non-streaming requests block UI
|
|
7. **Tool results are size-limited** - Large outputs are truncated or thinned automatically
|
|
8. **String slicing must be UTF-8 safe** - Use `chars().take(n)` or `char_indices()`, never byte slicing like `&s[..n]` on user-facing strings
|
|
|
|
### MUST NOT Do
|
|
|
|
1. **Never block the async runtime** - Use `tokio::spawn` for CPU-intensive work
|
|
2. **Never store secrets in logs** - API keys are redacted in error logs
|
|
3. **Never modify files outside working directory without explicit permission**
|
|
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
|
|
|
|
## Adding Features
|
|
|
|
- **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
|
|
|
|
## Dangerous Code Paths
|
|
|
|
These areas have subtle bugs if modified incorrectly:
|
|
|
|
| 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 |
|
|
|
|
## 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
|
|
- ✅ Keep functions under 80 lines
|
|
|
|
### Don't
|
|
- ❌ Add blocking code in async contexts
|
|
- ❌ Store sensitive data in plain text
|
|
- ❌ Ignore error handling
|
|
- ❌ Create deeply nested conditionals (>6 levels)
|
|
- ❌ Add external dependencies for simple tasks
|
|
|
|
## Common Incorrect Assumptions
|
|
|
|
1. **"All providers support tool calling"** - Embedded models use JSON fallback
|
|
2. **"Context window is unlimited"** - Each provider has limits (4k-200k tokens)
|
|
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)
|