Build 6 — Multi-Day Agentic Feature

# Build 6 — Multi-Day Agentic Feature ## The brief Pick a substantial feature (a few hours of "normal" coding) and build it primarily with an agent (Claude Code or Cursor agent mode). The goal: experience the full agentic workflow on real work. ## Suggested features Pick one (or your own ~half-day feature): 1. **Add comment threads to the Notes API** (from FastAPI Build 1). 2. **Add tagging system to TODO API** (from AI-Coding Build 1). 3. **Build a small file storage service** with S3 presigned uploads. 4. **Add a moderation queue** to a content app. 5. **Build a webhook delivery system** for an API. Choose based on what you have a codebase for. ## Step 1: Spec (20 min) Before involving the agent, write a clear spec. For comment threads on Notes: ```markdown # Feature: Comment Threads on Notes ## User stories - As a note owner, I can enable comments on a note. - As an authenticated user, I can comment on a note (if comments enabled). - As an authenticated user, I can reply to a comment. - As a comment author, I can edit or delete my comment within 5 minutes of posting. - As a note owner, I can delete any comment on my note. ## Data model - Comment: id, note_id, author_id, parent_id (nullable for replies), content, created_at, updated_at, deleted_at (soft delete). - Note: add `comments_enabled` boolean (default true). ## Endpoints - POST /notes/:note_id/comments — create comment. - GET /notes/:note_id/comments — list comments (threaded). - PATCH /comments/:id — edit (author only, within 5min). - DELETE /comments/:id — delete (author or note owner). ## Out of scope (for now) - Notifications. - Mentions (@username). - Editing history. ## Definition of done - Endpoints work; tests pass. - Validation: empty content rejected; max length enforced. - Authz: only author can edit; author or note owner can delete. - Soft delete (comment shown as "[deleted]" in lists). ``` ## Step 2: Brief the agent (10 min) Open Claude Code in your project. Brief: > "I'm adding comment threads to the Notes API. Spec is in spec_comments.md (just created). Implement: > 1. SQLAlchemy model. > 2. Alembic migration. > 3. Pydantic schemas. > 4. Routes. > 5. Tests. > > Follow our patterns (use CLAUDE.md). Run the migration and tests after. Commit each substantial step. Plan your work first; show me the plan before executing." ## Step 3: Review the plan Agent responds with a plan. Review: - Files it'll touch: right ones? - Order of work: makes sense? - Anything it's missing? If something's off, redirect: > "Stop. Don't add notifications yet — that's out of scope. Focus on the CRUD + tests." ## Step 4: Let it work (30-60 min) Agent works. You can: - Watch the log (helpful, not necessary). - Do other work in parallel. - Check back when it pauses or finishes. While agent works, it should: - Create files. - Run migration. - Add tests. - Run tests. - Commit each meaningful chunk. ## Step 5: Review the output (30-45 min) When agent finishes (or you stop it): ``` git log # see what was committed git diff main..HEAD # full diff pytest # do all tests pass? ``` Read every commit: - Are the models right? - Are the routes correct? - Are tests meaningful? - Does the migration look right? Spot check: - Manually call the endpoints (curl or Swagger). - Try edge cases agent should have handled. ## Step 6: Iterate You'll find issues: - Some tests missing. - A bug in delete behavior. - Edge case not handled. Either: - Have agent fix: "There's a bug — when X happens, Y. Investigate and fix." - Fix yourself: drive mode for tricky parts. Most multi-hour agent runs need 30-60 min of human refinement after. ## Step 7: Production-ize (20 min) After functional: - Check tests cover edge cases you expected. - Add manual integration tests. - Update docs. - Review for security (especially around authz). - Add any missing logging. ## Step 8: Reflect ```markdown # Agent Build Reflection ## Feature: [name] ## Time breakdown: - Spec: __ - Agent setup: __ - Agent autonomous work: __ - Review + iterate: __ - Polish: __ - Total: __ ## What the agent did well: - ... ## What the agent did poorly: - ... ## What I had to take over for: - ... ## Bugs in agent's output: - ... ## Speedup vs solo coding: Estimated solo time: __ Actual (with agent): __ Speedup: __x ## Would I do this again with an agent? Why? - ... ## Tips for next time: - ... ``` ## What this build teaches Most AI-coding learning is in single-file or chat. Agentic builds reveal: - How to spec well (agents need clear targets). - How to monitor without micromanaging. - How to review agent output efficiently. - Where agents shine (scaffolding, tests, mechanical work). - Where they need handholding (subtle logic, novel decisions). - Real time savings (or losses). ## Deliverables - Feature implemented and working. - Tests pass. - Git log showing agent's work. - Reflection document. ## What you'll learn - Specifying a feature for an agent. - Trusting the agent ap