Tutorial: Your First Agentic Workflow

This tutorial walks you through a complete agentic development workflow on a real-world task: adding rate limiting to an API. You’ll practice the Research → Plan → Implement pattern with proper context management.

Prerequisites

• A project with an API (any language/framework)
• An AI coding agent installed and configured (e.g., Claude Code, Cursor, Copilot Workspace)
• An agent configuration file set up — see the Quick Start guide

The Task

Add rate limiting to your API endpoints to prevent abuse. We’ll use this as a vehicle to practice the full three-phase workflow.

Phase 1: Research

Goal: Understand how your current API handles requests, what middleware patterns exist, and what rate limiting approaches fit.

1. Start a new agent session

   Open your AI coding agent and start a fresh session.

2. Delegate research to sub-agents

   Use sub-agents to investigate:
   1. How the current middleware stack works (entry point, order, patterns)
   2. What existing middleware we have and how they're structured
   3. Whether any rate limiting or throttling exists already
   4. How the test infrastructure works for middleware
   
   Save findings to .sdlc/research/rate-limiting.md

   The sub-agents explore your codebase in their own context windows. Your main context stays clean — receiving only the summary.

3. Review the research

   Read .sdlc/research/rate-limiting.md and summarize the key points.

   Verify the research is accurate. If something looks wrong, ask for clarification or additional investigation.

4. Compact before planning

   Compact your context, preserving key information. See Tool Configuration Reference for your tool’s compact command.

   Compact your context. Preserve: research findings location (.sdlc/research/rate-limiting.md),
   project structure understanding. Discard: sub-agent coordination details.

Tip

After this phase, your context should be under 30% utilized. The research document exists as a file, independent of the context window.

Phase 2: Planning

Goal: Create a detailed, step-by-step implementation plan that could be followed by a fresh agent.

1. Switch to planning mode

   Switch to your tool’s planning or read-only mode before generating the plan.

2. Create the plan

   Based on .sdlc/research/rate-limiting.md, create a detailed plan
   for adding rate limiting to our API.
   
   For each step, specify:
   - Which file to modify or create
   - What the change does
   - Dependencies on other steps
   - How to verify it works
   
   Consider:
   - Sliding window algorithm for accuracy
   - Redis for distributed state (we already use it for sessions)
   - Fail-open when Redis is down
   - Different limits for different endpoint groups
   
   Save to .sdlc/plans/rate-limiting.md

3. Review and edit the plan

   Open the plan in your editor. This is your highest-leverage review point:

   • Are the steps in the right order?
   • Are edge cases covered?
   • Do the verification criteria make sense?
   • Is anything missing?

   Edit directly before proceeding.

4. Compact before implementation

   Compact your context, preserving key information:

   Compact your context. Preserve: plan location (.sdlc/plans/rate-limiting.md),
   research location (.sdlc/research/rate-limiting.md).
   Discard: planning discussion details.

Phase 3: Implementation

Goal: Execute the plan with TDD verification at each step.

1. Switch back to editing mode and implement

   Follow the plan in .sdlc/plans/rate-limiting.md.
   
   For each step:
   1. Write failing tests first (if applicable)
   2. Implement the minimum code to pass
   3. Run tests and verify
   4. Mark the step as complete in the plan
   
   Start with step 1.

2. Monitor progress

   Watch the context utilization. If it passes 60%, consider:

   • Compacting with progress preservation
   • Starting a fresh session with the plan file

3. Verify each step

   After the agent completes each step, verify:

   • Tests pass (the agent should run them)
   • TypeScript compiles (hooks should check)
   • The change makes sense

4. Use a reviewer after implementation

   Use a sub-agent to review the rate limiting implementation.
   Check for:
   - Race conditions in the sliding window logic
   - Proper error handling when Redis is down
   - Correct Retry-After header calculation
   - Test coverage completeness

5. Commit

   Commit all changes with a descriptive message.
   Create a PR with a summary of the rate limiting implementation.

What You Practiced

Technique	Where Used
Sub-agent research	Phase 1 — codebase exploration
Context isolation	Sub-agents for research and review
Proactive compaction	Between each phase
Plan Mode	Phase 2 — architecture before code
Human review at leverage points	Research and plan review
TDD	Phase 3 — tests before implementation
Separate reviewer	Post-implementation review

Common Issues

Issue	Solution
Context fills during implementation	Compact with step progress, or start fresh session
Tests fail after implementation	Don’t skip — debug with the agent’s help
Plan doesn’t match reality	Update the plan, don’t abandon it
Sub-agent misses important files	Provide more specific guidance for what to search

Next Steps

• Tutorial: Large Codebase Setup
• Tutorial: Multi-Agent Feature
• Context Engineering deep dive