orikbot/second-brain
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Enhance AI coding harnesses with memory mastery details and cross-tool file standards

Browse Source
This commit is contained in:
Orik
2026-04-22 20:22:49 +00:00
parent 1181c13b6a
commit a5fa47a328
1 changed files with 149 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

160
04_Topics/AI-Assisted_Coding_Harnesses.md
View File

@@ -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: 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`) **The four layers:**
- **Scoped memory**: subtree/domain rules (in `.github/instructions/*.md`)
- **Volatile memory**: current task summary, open decisions, blocker, next step (in `notes/current-task.md`) | Layer | Purpose | Example Files |
- **Retrieval over replay**: load a 20-line task brief, not 50k tokens of old chat |-------|---------|---------------|
| **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. **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: AI writes, systems verify. Proven guardrails:
- Force tests, linters, typecheck, diff review into the loop - 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 ## Recommended File Layout
### Cross-Tool Standard (AGENTS.md)
The emerging standard is hierarchical instruction files that work across tools:
``` ```
repo/ 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/ ├── .github/
│ ├── copilot-instructions.md │ ├── copilot-instructions.md # repo-wide instructions
│ └── instructions/ │ └── instructions/
│ ├── backend.instructions.md │ ├── backend.instructions.md # path-scoped (applyTo: "**/*.py")
│ └── frontend.instructions.md │ └── typescript.instructions.md # path-scoped (applyTo: "**/*.ts")
├── packages/
│ ├── api/
│ │ └── AGENTS.md # subsystem rules (nearest takes precedence)
│ └── web/
│ └── AGENTS.md
├── notes/ ├── notes/
│ ├── current-task.md # objective, files, failure, next step │ ├── current-task.md # objective, files, failure, next step
│ ├── decisions.md # non-obvious choices and why │ ├── decisions.md # non-obvious choices and why
@@ -360,6 +410,94 @@ repo/
└── pre-commit.sh # auto-run checks └── 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 ## My Recommendation for Claudio