From a5fa47a328aa214adf9e0ecb5296e1f67884c3eb Mon Sep 17 00:00:00 2001 From: Orik Date: Wed, 22 Apr 2026 20:22:49 +0000 Subject: [PATCH] Enhance AI coding harnesses with memory mastery details and cross-tool file standards --- 04_Topics/AI-Assisted_Coding_Harnesses.md | 160 ++++++++++++++++++++-- 1 file changed, 149 insertions(+), 11 deletions(-) diff --git a/04_Topics/AI-Assisted_Coding_Harnesses.md b/04_Topics/AI-Assisted_Coding_Harnesses.md index 42586a8..2da6410 100644 --- a/04_Topics/AI-Assisted_Coding_Harnesses.md +++ b/04_Topics/AI-Assisted_Coding_Harnesses.md @@ -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