Enhance AI coding harnesses with memory mastery details and cross-tool file standards
This commit is contained in:
@@ -271,18 +271,54 @@ Meta's advice: concise navigation beats giant docs. They recommend **25-35 line
|
||||
|
||||
The research was clear: output volume ≠ productivity. Here's what actually matters:
|
||||
|
||||
### 1. Mastering Memory (Not Hoarding Context)
|
||||
### 1. Mastering Memory (Layered External Memory)
|
||||
|
||||
The best pattern is **layered memory**, not chat-history hoarding:
|
||||
"Mastering memory" is not about magical long-term recall. It's about building a **layered external memory system** the agent can reload cheaply and consistently.
|
||||
|
||||
- **Stable memory**: coding standards, commands, architecture invariants (in `AGENTS.md`)
|
||||
- **Scoped memory**: subtree/domain rules (in `.github/instructions/*.md`)
|
||||
- **Volatile memory**: current task summary, open decisions, blocker, next step (in `notes/current-task.md`)
|
||||
- **Retrieval over replay**: load a 20-line task brief, not 50k tokens of old chat
|
||||
**The four layers:**
|
||||
|
||||
| Layer | Purpose | Example Files |
|
||||
|-------|---------|---------------|
|
||||
| **Global** | Personal preferences, cross-project conventions | `~/.config/AGENT.md` |
|
||||
| **Repo-wide** | Project constitution, build/test commands | `AGENTS.md`, `CLAUDE.md` |
|
||||
| **Subsystem** | Domain/path-specific rules | `packages/api/AGENTS.md`, `.cursor/rules/backend.mdc` |
|
||||
| **Session** | Active task state, handoffs | `notes/current-task.md`, `session_handoff.md` |
|
||||
|
||||
**Key principles:**
|
||||
- Keep each layer small and specific (root files < 200 lines)
|
||||
- Use imports (`@AGENTS.md`) to avoid duplication
|
||||
- Move deterministic behavior into hooks/scripts, not prompts
|
||||
- Prefer retrieval/search over full-repo preload for large codebases
|
||||
|
||||
**Meta's finding**: Precompute context with specialized agents first, then let execution agents work from that map. They used 50+ specialized agents to build concise context artifacts and got ~40% fewer tool calls per task.
|
||||
|
||||
### 2. Verification Hooks (Not Trust)
|
||||
### 2. Warm-Starting Sessions
|
||||
|
||||
Strong pattern for starting a new session:
|
||||
|
||||
```bash
|
||||
git status
|
||||
git diff --stat
|
||||
cat AGENTS.md CLAUDE.md
|
||||
cat notes/current-task.md notes/session_handoff.md
|
||||
rg -n "TODO|FIXME|HACK" .
|
||||
```
|
||||
|
||||
Then ask: "Based on these files, what are we doing and what's the next step?" This gives the agent exactly the context it needs, nothing more.
|
||||
|
||||
### 3. Token Budget Management
|
||||
|
||||
Proven patterns:
|
||||
- **Reset aggressively**: Use `/clear` between unrelated tasks
|
||||
- **Compact with focus**: Use `/compact` with specific instructions ("keep only the auth-related context")
|
||||
- **Scope instruction files**: Keep root files short, move detailed rules into path-scoped files
|
||||
- **Prefer CLI over MCP**: MCP tool listings add context overhead; use CLI tools when possible
|
||||
- **Model selection**: Sonnet for most work, Haiku for simple subagents, Opus only for synthesis
|
||||
- **Avoid re-feeding**: Don't paste the same repo context into multiple tools
|
||||
|
||||
Anthropic's explicit recommendation: target **under 200 lines** per `CLAUDE.md`. Large files hurt adherence.
|
||||
|
||||
### 4. Verification Hooks (Not Trust)
|
||||
|
||||
AI writes, systems verify. Proven guardrails:
|
||||
- Force tests, linters, typecheck, diff review into the loop
|
||||
@@ -341,14 +377,28 @@ Code that demos well but isn't built like a system:
|
||||
|
||||
## Recommended File Layout
|
||||
|
||||
### Cross-Tool Standard (AGENTS.md)
|
||||
|
||||
The emerging standard is hierarchical instruction files that work across tools:
|
||||
|
||||
```
|
||||
repo/
|
||||
├── AGENTS.md # project constitution (keep < 200 lines)
|
||||
├── AGENTS.md # universal/cross-tool project constitution
|
||||
├── CLAUDE.md # imports AGENTS.md, adds Claude-specific notes
|
||||
├── .cursor/
|
||||
│ └── rules/
|
||||
│ ├── backend.mdc # path-scoped rules (auto-attached by glob)
|
||||
│ └── frontend.mdc
|
||||
├── .github/
|
||||
│ ├── copilot-instructions.md
|
||||
│ ├── copilot-instructions.md # repo-wide instructions
|
||||
│ └── instructions/
|
||||
│ ├── backend.instructions.md
|
||||
│ └── frontend.instructions.md
|
||||
│ ├── backend.instructions.md # path-scoped (applyTo: "**/*.py")
|
||||
│ └── typescript.instructions.md # path-scoped (applyTo: "**/*.ts")
|
||||
├── packages/
|
||||
│ ├── api/
|
||||
│ │ └── AGENTS.md # subsystem rules (nearest takes precedence)
|
||||
│ └── web/
|
||||
│ └── AGENTS.md
|
||||
├── notes/
|
||||
│ ├── current-task.md # objective, files, failure, next step
|
||||
│ ├── decisions.md # non-obvious choices and why
|
||||
@@ -360,6 +410,94 @@ repo/
|
||||
└── pre-commit.sh # auto-run checks
|
||||
```
|
||||
|
||||
### Why This Structure Works
|
||||
|
||||
- **Stable memory** (repo-wide): `AGENTS.md` — coding standards, build commands, architecture invariants
|
||||
- **Scoped memory** (path-specific): `.cursor/rules/*.mdc`, `.github/instructions/*.md` — backend/frontend conventions
|
||||
- **Volatile memory** (session): `notes/current-task.md`, `session_handoff.md` — active task state
|
||||
- **Retrieval over replay**: New sessions load only the 20-line task brief, not 50k tokens of old chat
|
||||
|
||||
### Tool-Specific File Formats
|
||||
|
||||
| File | Tool | Scope | Notes |
|
||||
|------|------|-------|-------|
|
||||
| `AGENTS.md` | Cross-tool | Repo-wide | Universal standard, keep < 200 lines |
|
||||
| `CLAUDE.md` | Claude Code | Repo-wide | Imports `AGENTS.md` via `@AGENTS.md`. Keep < 200 lines. Large files hurt adherence. |
|
||||
| `.cursorrules` | Cursor | Repo-wide | Legacy, being replaced by `.cursor/rules/*.mdc` |
|
||||
| `.cursor/rules/*.mdc` | Cursor | Path-scoped | Auto-attached by glob. Can nest in subdirectories. |
|
||||
| `.github/copilot-instructions.md` | Copilot | Repo-wide | One per repo |
|
||||
| `.github/instructions/*.instructions.md` | Copilot | Path-scoped | Uses frontmatter: `applyTo: "**/*.ts"` |
|
||||
| `AGENT.md` | Emerging | Any | Proposed standard with merge behavior (nearest wins) |
|
||||
|
||||
### Example AGENTS.md (Minimal, Effective)
|
||||
|
||||
```markdown
|
||||
# AGENTS.md
|
||||
|
||||
## Commands
|
||||
- Install: `pnpm install`
|
||||
- Test: `pnpm test`
|
||||
- Lint: `pnpm lint`
|
||||
- Typecheck: `pnpm typecheck`
|
||||
|
||||
## Guardrails
|
||||
- Never edit `src/generated/**`
|
||||
- Prefer `rg` over slower recursive search
|
||||
- Run tests relevant to changed files before finishing
|
||||
|
||||
## Architecture
|
||||
- API handlers: `packages/api/src/handlers`
|
||||
- UI components: `packages/web/src/components`
|
||||
- Shared schemas: `packages/shared/src/schema`
|
||||
|
||||
## Workflow
|
||||
- For multi-file changes, update `session_handoff.md`
|
||||
- Record architectural decisions in `notes/decisions/`
|
||||
```
|
||||
|
||||
### Example session_handoff.md
|
||||
|
||||
```markdown
|
||||
# Session Handoff
|
||||
|
||||
## Last completed
|
||||
- Migrated auth middleware to token refresh flow
|
||||
|
||||
## Decisions
|
||||
- Keep REST externally, internal services move to RPC
|
||||
- Do not delete old middleware until admin routes migrated
|
||||
|
||||
## Next
|
||||
- Update admin route guards
|
||||
- Add integration tests for expired-token refresh
|
||||
|
||||
## Blockers
|
||||
- CI sandbox rate limit on auth provider
|
||||
```
|
||||
|
||||
### Path-Scoped Rules Example
|
||||
|
||||
**`.github/instructions/typescript.instructions.md`**:
|
||||
```markdown
|
||||
---
|
||||
applyTo: "**/*.ts,**/*.tsx"
|
||||
---
|
||||
- Use zod for runtime validation
|
||||
- Prefer functional components
|
||||
- No implicit any
|
||||
```
|
||||
|
||||
**`.cursor/rules/backend.mdc`**:
|
||||
```markdown
|
||||
---
|
||||
description: Backend API conventions
|
||||
globs: "packages/api/**/*.py"
|
||||
---
|
||||
- Use FastAPI dependency injection
|
||||
- All handlers must have type hints
|
||||
- Return Pydantic models, not dicts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## My Recommendation for Claudio
|
||||
|
||||
Reference in New Issue
Block a user