purpose: Deep dive into Through-Agent Leverage Points (5-12) type: technical-reference domain: agentic-coding category: through-agent-leverage audience: LLM-optimized last-updated: 2025-09-30 Through-Agent Leverage Points optimize the environment surrounding the agent rather than the agent itself. These points create persistent infrastructure that compounds benefits over time, scales across multiple agents/developers, and enables systematic velocity improvements. Unlike In-Agent points (tactical), Through-Agent points are strategic investments. DOCUMENTATION: Agent-specific context critical 9/10 environmental-infrastructure Agent-specific documentation provides persistent knowledge bases optimized for LLM consumption. Unlike human documentation (tutorials, explanations), agent documentation is structured data: architecture maps, decision rationale, constraints, patterns, and conventions. This is the agent's external memory. Project-level instructions and conventions Project root and ~/.claude/ Coding standards and patterns Architecture overview Common workflows Tool usage preferences Security requirements "# CRITICAL: Store decisions in ken-you-remember # Use TypeScript strict mode # Tests with Vitest, not Jest # Store passwords with bcrypt, min 12 rounds" Layered domain knowledge ~/.claude/context/ tools/ - Available capabilities patterns/ - Reusable solutions domain/ - Business logic context Agent hydrates only relevant context per task Why decisions were made "# ADR-001: Use PostgreSQL over MongoDB Date: 2025-01-15 Decision: PostgreSQL for ACID guarantees Rationale: Financial transactions require consistency Consequences: Requires schema migrations" Endpoint specifications for agent consumption OpenAPI/Swagger schemas over prose descriptions Structure for machine parsing, not human reading XML tags for hierarchical structure Bullet lists over paragraphs Code examples over explanations Explicit constraints ("NEVER do X", "ALWAYS do Y") Human doc: "When handling user input, it's important to consider security..." Agent doc: "USER INPUT RULES: - ALWAYS validate type/length/format - NEVER trust client-side validation - Use parameterized queries for SQL" Update docs as code evolves 1. Make architectural decision 2. store_fr3k: Record decision 3. Update CLAUDE.md or ADR 4. Agent sees updated context in next session Hierarchical organization prevents context bloat README.md (human overview) ├── CLAUDE.md (agent project context) ├── docs/architecture/ (system design) ├── docs/patterns/ (implementation patterns) └── docs/api/ (endpoint specs) Agent loads README + CLAUDE.md always, others on-demand Writing documentation for humans when agent is consumer Stale docs that contradict current codebase Verbose explanations that waste context window Start with CLAUDE.md in project root Add ADRs for major decisions Full UFC context hierarchy TYPES: Structured information high 8/10 validation-infrastructure Type systems provide machine-readable contracts that enable agents to validate correctness automatically. Strong typing reduces hallucination by making invalid code syntactically impossible. Types are documentation that compilers enforce. Autocomplete/IntelliSense shows valid operations Without types: agent guesses user.getName() exists With types: agent knows user has only user.name property Catch mistakes at write-time, not runtime TypeScript: Type 'string' is not assignable to type 'number' Agent sees error immediately, corrects before generating more code Type checker validates changes across codebase Rename function parameter → TypeScript finds all call sites Agent can refactor confidently without breaking code Types document expected shapes interface User { id: string; email: string; role: 'admin' | 'user'; } Agent knows exactly what User contains Gradual typing - adopt incrementally Rich inference - types without annotations Ecosystem support - DefinitelyTyped JavaScript projects wanting safety Runtime validation via Pydantic Data parsing with automatic conversion FastAPI integration from pydantic import BaseModel class User(BaseModel): id: int email: str role: Literal['admin', 'user'] # Agent knows structure + gets validation user = User(id="123", email="test@test.com", role="admin") # Raises ValidationError - id must be int Compile-time guarantees - no null, no data races Ownership system prevents entire bug classes Rust compiler is agent's pair programmer Types for data persistence CREATE TABLE users ( id UUID PRIMARY KEY, email VARCHAR(255) UNIQUE NOT NULL, role user_role NOT NULL ); Agent knows: - id is UUID, not arbitrary string - email must be unique and present - role must match enum Types for service boundaries Agent can validate requests/responses automatically Start with minimal types, expand over time Type function signatures Type data models/DTOs Type internal functions Enable strict mode Enforce types where data enters system API requests (Zod, Joi, Pydantic) Database queries (ORM types) External service responses User input const userSchema = z.object({ email: z.string().email(), age: z.number().min(18) }); // Agent knows validation rules const validated = userSchema.parse(input); Define types first, implement second 1. Define data structures as types 2. Define function signatures 3. Let type checker guide implementation 4. Agent fills in implementation knowing contracts Type-safe enums and variants type Result = | { success: true; data: T } | { success: false; error: string }; // Agent knows to check success before accessing data if (result.success) { console.log(result.data); // TypeScript knows this is safe } Reduces hallucination - invalid code won't compile Speeds up iteration - agent catches errors immediately Enables confident refactoring - type checker validates changes Improves agent understanding - types document intent ARCHITECTURE: Code-based navigation high 8/10 organizational-infrastructure Architecture determines how easily agents can understand system boundaries, dependencies, and where to make changes. Well-architected code is self-documenting; poorly architected code requires extensive context loading and explanation. Clear separation of concerns src/ ├── api/ # HTTP handlers ├── services/ # Business logic ├── models/ # Data structures ├── utils/ # Pure functions └── tests/ # Test files Agent knows where to find/add functionality Clear import hierarchy Core <- Services <- API <- UI (Inner layers have no knowledge of outer layers) Agent understands impact radius of changes One file/function does one thing Bad: userController.js (handles auth, CRUD, validation, emails) Good: userAuth.js, userCrud.js, userValidation.js, userEmails.js Agent can reason about changes in isolation Predictable file/function names Services: *Service.ts (userService.ts, orderService.ts) Controllers: *Controller.ts Models: *.model.ts Tests: *.test.ts Agent can find related files without guidance Domain-driven design modules src/ ├── auth/ # All authentication logic ├── payments/ # All payment logic └── inventory/ # All inventory logic Agent understands domain boundaries core/ # Business logic (pure) ports/ # Interfaces adapters/ # Implementations (DB, API, etc.) Clear boundary between logic and infrastructure features/ ├── user-registration/ │ ├── api.ts │ ├── service.ts │ ├── validation.ts │ └── tests.ts └── order-processing/ └── ... All related code co-located Entities (domain models) Use Cases (application logic) Interface Adapters (controllers, presenters) Frameworks & Drivers (UI, DB, external services) Dependency inversion makes testing easy README.md maps major components # Codebase Structure - `api/` - REST endpoints (Express) - `services/` - Business logic - `db/` - Database access (Prisma) - Entry: `src/index.ts` Visualize dependencies dependency-cruiser, madge Agent sees system topology Predictable patterns reduce explanation Agent assumes: *Service.ts files in services/ directory No need to explain: "Services are in services/ folder" Files with 1000+ lines doing everything Agent overwhelmed, changes risky A imports B imports A Agent cannot reason about change impact Every module organized differently Agent must learn structure per module Global state, singletons, implicit coupling Agent makes changes unaware of side effects Time to locate relevant code: 80% reduction with clear architecture Incorrect file modifications: 60% reduction Refactoring confidence: Dramatic increase with modular design TESTS: Validation and self-correction critical 10/10 validation-infrastructure Tests enable agents to validate their own work autonomously. Without tests, agents require human verification for every change. With tests, agents self-correct through rapid iteration, dramatically increasing autonomy and velocity. Validate individual functions in isolation Fast feedback on logic correctness test('calculateDiscount returns correct percentage', () => { expect(calculateDiscount(100, 0.2)).toBe(20); }); // Agent runs test after implementation // If fails, agent sees exact assertion failure and fixes Validate component interactions Catches interface mismatches test('API returns 401 for invalid token', async () => { const res = await request(app) .get('/api/user') .set('Authorization', 'invalid'); expect(res.status).toBe(401); }); Validate full user flows Ensures no regression in critical paths test('User can complete purchase flow', async () => { await page.goto('/products'); await page.click('[data-testid="add-to-cart"]'); await page.click('[data-testid="checkout"]'); await page.fill('[name="card"]', '4242424242424242'); await page.click('[data-testid="complete-order"]'); await expect(page).toHaveURL('/order-confirmation'); }); Validate behavior across input range Finds edge cases automatically test('sort is idempotent', () => { fc.assert( fc.property(fc.array(fc.integer()), (arr) => { const sorted1 = sort(arr); const sorted2 = sort(sorted1); expect(sorted1).toEqual(sorted2); }) ); }); Agent implements feature Agent runs tests via Bash tool Mark task complete Read test output Identify failure cause Fix implementation Re-run tests Repeat until pass store_fr3k: Record solution pattern Agent iterates to solution without human intervention Average 3-5 iterations to passing tests vs 10+ without Write test before implementation Test defines success criteria clearly 1. Human writes failing test 2. Agent implements until test passes 3. Agent knows exactly when done Test name documents expected behavior Bad: test('user test') Good: test('createUser throws ValidationError when email is invalid') Agent understands requirement from test name Include context in assertion failures expect(result.status).toBe(200, `Expected success but got ${result.status}: ${result.error}`); Agent sees exact failure context without reading code Tests must run in seconds, not minutes Unit tests: <100ms each, Integration: <1s each Enables rapid iteration loops Identify untested code paths 1. Agent adds new function 2. Runs coverage report 3. Sees function uncovered 4. Adds test for function Tests are executable specifications Tests enable autonomous validation Tests reduce hallucination via rapid feedback Tests make refactoring safe First-attempt success rate: 30% → 75% with comprehensive tests Debugging time: 60% reduction (agent sees exact failure) Regression rate: 80% reduction (tests catch breaks) Agent cannot validate work, human becomes bottleneck Agent avoids running tests, misses errors Tests fail on irrelevant changes, agent learns to ignore expect(result).toBeTruthy() Agent doesn't understand what broke PLANNING: Meta-work for agents high 8/10 cognitive-infrastructure Planning is the process of decomposing complex tasks into structured steps before implementation. Agents without planning hallucinate, lose context, and produce inconsistent work. Agents with systematic planning maintain coherence across multi-step tasks. Track task decomposition and progress { content: "Imperative: Fix auth bug", activeForm: "Present continuous: Fixing auth bug", status: "pending" | "in_progress" | "completed" } Create todos for all subtasks Mark ONE todo in_progress before starting Complete immediately after finishing Add new todos as discovered during work Prevents agent from losing track mid-task Persist plans across context resets store_fr3k: "Plan: 1) Add JWT refresh endpoint 2) Update middleware 3) Add tests 4) Update docs" Agent retrieves plan after context loss Full task lifecycle with validation workflow todo → coding_done → validated → complete (with needs_fixes loop) Structured workflow prevents premature completion Break complex task into hierarchical subtasks Task: Implement user authentication ├── 1. Design auth architecture │ ├── 1.1 Choose JWT vs session │ └── 1.2 Design token refresh flow ├── 2. Implement backend │ ├── 2.1 Login endpoint │ ├── 2.2 Token validation middleware │ └── 2.3 Refresh endpoint ├── 3. Add tests └── 4. Update documentation Clear roadmap prevents wandering Sequence tasks by prerequisites Cannot write tests before implementation Cannot deploy before tests pass Cannot update docs before feature complete Prevents out-of-order work Define validation points throughout task 1. Implement login endpoint → Checkpoint: Endpoint returns 200 2. Add validation → Checkpoint: Invalid input returns 400 3. Add tests → Checkpoint: All tests pass 4. Complete → Checkpoint: Manual login succeeds Clear success criteria at each step Tackle highest-risk/unknowns first Fail fast if approach won't work Task: Add real-time notifications 1. Spike: Test WebSocket library (unknown) 2. Implement connection handling (risky) 3. Add message routing (straightforward) 4. Add UI components (easy) Planning forces explicit thinking before action Agent states plan, human approves before code Agent: "Here's my plan: 1) Modify auth.ts 2) Update middleware 3) Add tests. Proceed?" Human: "Approved" or "No, also update the config" Catches misunderstandings before wasted work Record what NOT to do in plan Todo: "Add JWT refresh ONLY to auth.ts. DO NOT modify user.model.ts or database schema." Prevents scope creep and unintended changes Agent records what was done and why store_fr3k: "Completed JWT refresh. Used 7-day expiry per security req. Token stored in DB refresh_tokens table." Context preservation for later sessions Jump directly to implementation Missed requirements, inconsistent approach, context loss Spend 90% time planning, 10% doing Analysis paralysis, outdated plans Create TodoWrite, then ignore it Defeats purpose of planning Todo: "Fix the thing" Agent doesn't know when task is complete Consistency: 90% improvement with planning vs none Context retention: 3x better with TodoWrite tracking Scope adherence: 80% fewer unintended changes AI DEVELOPER WORKFLOWS (ADWs) medium 7/10 process-infrastructure AI Developer Workflows are repeatable, documented procedures for common development scenarios. ADWs capture proven approaches and enable consistent, high-quality execution by agents across diverse tasks. They are the difference between ad-hoc problem-solving and systematic mastery. 1. recall_fr3k: Check if bug encountered before 2. Reproduce: Read error logs, stack trace 3. Locate: Grep for error source, read relevant files 4. Diagnose: Identify root cause (not symptom) 5. Fix: Edit code with minimal change 6. Validate: Run tests, verify fix 7. Prevent: Add test for bug if missing 8. store_fr3k: Record bug pattern and solution Systematic debugging prevents guess-and-check 1. Clarify: Understand requirements, ask if ambiguous 2. Research: Check existing patterns in codebase 3. Design: Identify files to modify, new files needed 4. Plan: TodoWrite with subtasks 5. Implement: Code per plan, one todo at a time 6. Test: Write/run tests for new functionality 7. Document: Update relevant docs 8. Validate: Complete todo, mark task coding_done 1. Safety: Ensure tests exist and pass 2. Scope: Define exact files/functions to refactor 3. Constraint: NO behavior changes, structure only 4. Incremental: Small, testable refactorings 5. Validate: Run tests after each change 6. Commit: Git commit each successful refactoring Safe refactoring without breaking changes 1. git status: Check uncommitted changes 2. git diff: Review changes 3. git add: Stage relevant files 4. git commit: Commit with descriptive message 5. git push: Push to remote branch 6. gh pr create: Create PR with title and body 7. Link issues: Reference related issues/tasks 1. Review: Check changelog for breaking changes 2. Update: Modify package.json/requirements.txt 3. Install: Run npm install / pip install 4. Migrate: Update code for breaking changes 5. Test: Run full test suite 6. Validate: Manual testing of affected features CLAUDE.md (common workflows) ~/.claude/context/workflows/ (detailed ADWs) UFC system context files # Workflow: Bug Fixing STEPS: 1. recall_fr3k: Prior solutions 2. Reproduce: Error logs + stack trace 3. Locate: Grep source 4. Fix: Minimal edit 5. Validate: Run tests 6. store_fr3k: Record solution CONSTRAINTS: - Fix root cause, not symptom - Add test if missing - No refactoring during bug fix Human triggers workflow by name Human: "Follow the Bug Fixing Workflow for the login error" Agent: Executes steps systematically Link workflows for complex scenarios 1. Feature Implementation Workflow (build feature) 2. Testing Workflow (validate feature) 3. PR Creation Workflow (ship feature) Improve workflows based on outcomes 1. Execute workflow 2. Identify inefficiencies 3. Update workflow documentation 4. store_fr3k: Record improvement Encode workflows as /commands /debug → Bug Fixing Workflow /check → Testing + Validation Workflow /api → API Development Workflow One-word workflow invocation Consistency: Same approach every time Quality: Proven workflows avoid common mistakes Velocity: No decision fatigue, immediate action Knowledge capture: Best practices encoded permanently AGENTIC CODING KPIs medium 6/10 measurement-infrastructure Agentic Coding KPIs are metrics that quantify agent effectiveness and guide optimization decisions. What gets measured gets improved. KPIs transform intuition into data-driven strategy. % of tasks completed correctly without revision 75%+ (with optimized leverage points) Track tasks marked "validated" without "needs_fixes" % of prompts that succeed without clarification 60%+ Better Context (LP#1), Better Prompts (LP#3) % of agent-generated code that passes tests first try 80%+ Types (LP#6), Better Tests (LP#8) % of provided context actually used in solution 70-90% (higher = better targeting) Track which files/docs agent references Average # of follow-up questions per task <2 Better Prompts (LP#3), Documentation (LP#5) Average # of attempts before success 5-7 without optimization 1-2 with optimization Seconds from prompt to initial response Model choice (LP#2), Context size (LP#1) % of agent outputs containing invented facts/APIs <5% Types (LP#6), Tests (LP#8), Planning (LP#9) % of agent changes that break existing functionality <2% Tests (LP#8), Architecture (LP#7) % of agent-generated PRs approved without changes 90%+ % of agent errors fixed autonomously (via tests) 80%+ Tests (LP#8), Planning (LP#9) Average # of human corrections per task <1 % of tool calls that succeed first attempt 95%+ Better Prompts (LP#3), Documentation (LP#5) Spreadsheet logging of outcomes Low initial, high ongoing Individual developers, early-stage Code tracks metrics automatically - Log agent tool calls and outcomes - Track task status transitions (hey-daddy) - Parse test results - Measure response times High initial, low ongoing Teams, mature setups Weekly/monthly retrospective analysis Which tasks succeeded first-attempt this week? Which required multiple iterations? What were common failure patterns? Which leverage points need optimization? Measure: Track KPIs for baseline Identify: Find lowest-performing metrics Hypothesize: Which leverage point(s) to optimize? Intervene: Improve targeted leverage point Measure: Track KPI change post-intervention Iterate: Repeat for next bottleneck First-attempt success rate: 40% - High clarification rate (4 questions per task) - Context utilization: 30% (most provided context unused) Context over-provisioning, vague prompts 1. Optimize LP#1 Context: Provide only relevant files 2. Optimize LP#3 Prompt: Add explicit constraints - First-attempt success: 40% → 72% - Clarification rate: 4 → 1.5 - Context utilization: 30% → 75% KPIs transform agentic coding from art to engineering. Data-driven decisions beat intuition. Systematic improvement compounds over time. ONE-SHOT SUCCESS high 10/10 emergent-capability One-Shot Success is the ability for an agent to complete a task correctly on the first attempt, without clarifying questions, failed tests, or revisions. This is the ultimate goal of agentic coding optimization and the emergent property of all 11 preceding leverage points working in harmony. LP#1 Context: Agent sees all relevant information upfront LP#2 Model: Appropriate LLM for task complexity LP#3 Prompt: Clear, constrained, with examples LP#4 Tools: Agent can execute necessary actions LP#5 Documentation: Agent has persistent knowledge LP#6 Types: Agent validates correctness automatically LP#7 Architecture: Agent navigates codebase easily LP#8 Tests: Agent self-validates output LP#9 Planning: Agent approaches systematically LP#10 ADWs: Agent follows proven procedures LP#11 KPIs: Continuous measurement and improvement Zero clarifying questions Zero test failures Zero human corrections First output is final output Complete, not partial solution Agent has everything needed before starting Prompt: "Add password reset feature" Context provided: - Existing auth implementation (for consistency) - Email service setup (for sending reset emails) - Token generation pattern (for reset tokens) - Test examples (for validation) Result: Agent implements complete feature correctly first try No room for interpretation or guessing Vague: "Make login faster" Precise: "Add Redis caching for user sessions. Cache for 1 hour. Invalidate on logout." Clear boundaries prevent scope creep "Add JWT refresh endpoint to auth/routes.ts. DO NOT modify auth/middleware.ts. DO NOT change database schema. Use existing token generation function." Agent can verify correctness autonomously Type checking catches errors at write-time Tests validate behavior automatically Linters enforce code standards Task matches documented workflows Task: "Add new API endpoint" Agent recognizes: This is Feature Implementation Workflow Agent executes: Proven procedure for API additions Core Four In-Agent Points Master Context provision (LP#1) Write clear, constrained Prompts (LP#3) Ensure agent has necessary Tools (LP#4) First-attempt success: 30% → 50% Through-Agent Points Create CLAUDE.md documentation (LP#5) Add comprehensive tests (LP#8) Use TodoWrite consistently (LP#9) First-attempt success: 50% → 70% Advanced leverage points Add types where missing (LP#6) Document common workflows (LP#10) Track and optimize KPIs (LP#11) First-attempt success: 70% → 85%+ One-Shot Success as default Continuous KPI monitoring Workflow refinement based on failures Leverage point optimization per task type One-Shot Success Rate: 60%+ of all tasks Trying for one-shot before foundations exist Frustration, inconsistent results Build leverage points 1-9 first Assuming agent will "figure it out" Clarification questions, iterations Over-provide context initially, refine based on KPIs Open-ended prompts expecting mind-reading Agent guesses, likely wrong direction Explicit constraints, examples, success criteria 10x increase in implementation speed Consistent, predictable outcomes Human trusts agent to work autonomously Same principles apply across projects One-Shot Success is not about agent perfection. It's about human-agent system optimization. Every leverage point contributes to the whole. Mastery emerges from systematic improvement. Through-Agent points build the environment for sustained excellence: - Documentation (5) gives agents memory - Types (6) give agents validation - Architecture (7) gives agents navigation - Tests (8) give agents self-correction - Planning (9) gives agents coherence - ADWs (10) give agents procedures - KPIs (11) give agents improvement - One-Shot (12) emerges from all above Through-Agent points require upfront effort but compound returns: - In-Agent optimizations: Immediate wins, must repeat - Through-Agent optimizations: Delayed wins, permanent benefits Choose one Through-Agent point to implement this week Start with Documentation (LP#5) or Tests (LP#8) for highest ROI Measure baseline KPIs before optimization Iterate through leverage points systematically Track progress toward One-Shot Success