Builder Agent Controllers and Test Suites

In this lab, you will direct Claude Code as an autonomous Builder agent: it will implement the TaskMaster Tasks API and generate a complete automated test suite while you act as the Engineering Manager who specifies the work, reviews every diff, requests revisions, and approves the final result. Delegating implementation to an AI agent and then verifying that work with automated tests is exactly how professional engineering teams operate today, and the review discipline you practice here is the skill employers now screen for.

Scenario

You are still the junior backend developer at “Productivity Inc.,” and the TaskMaster API is nearly finished: authentication and the Projects API (Phases 1 through 4) are complete and working. Your team lead has approved the use of an AI coding agent for the remaining Tasks API (Phase 5), on two conditions:

1. Every change the agent makes must be reviewed by a human engineer before it is committed, and
2. The API must gain an automated test suite, because manually clicking through Insomnia or Postman before every release does not scale.

You are the Engineering Manager for this agent. The agent writes the code; you own the outcome.

Complete this lab after finishing Phase 4 of the TaskMaster project and before starting Phase 5. The agent-written Tasks controller produced in this lab is permitted for the Phase 5 portion of the project rubric, because you are graded here on the specification, review, and audit trail rather than on hand-typing the code.

Estimated time: 45 minutes.

Objectives

By the end of this lab, you will be able to:

• Operate Claude Code in the AI as Builder role while you act as the Engineering Manager.
• Write a precise implementation specification for an AI agent, including authorization rules and error semantics.
• Review AI-generated changes with git diff, identify defects or weaknesses, and require at least one revision.
• Direct an agent to build a Jest and Supertest test suite that includes negative authorization tests.
• Triage failing tests by deciding whether the defect is in the test or in the application code.
• Document an engineering audit trail in AI-REVIEW.md.

Prerequisites

• Your TaskMaster repository is complete through Phase 4: registration, login, JWT authentication middleware, and the full Projects API with ownership checks all work.
• All work is committed and git status reports a clean working tree.
• The repository exists on GitHub and is configured as the origin remote of your local repository. You will push a branch to it in Part 3, so create the GitHub repository and push main now if you have not already done so.
• Node.js 18 or later is installed (you already have this from earlier modules).
• Claude Code is installed and authenticated with your Per Scholas-provided Claude Pro account.

The Builder Role: Ground Rules

In the AI as Builder role, the agent writes code autonomously. You never type the implementation yourself; instead you specify, review, audit, test, and approve. Two rules are absolute in this lab:

1. Nothing is committed without your review. You will read every diff before staging anything.
2. You must reject or revise at least one aspect of the agent’s work. A manager who approves everything without pushback is not reviewing.

You will enforce the Builder role through the CLAUDE.md file at your repository root. Claude Code reads this file at the start of every session, so the constraints apply to everything the agent does in your project.

Setup (5 minutes)

1. Open a terminal in your TaskMaster repository root.

2. Verify Claude Code is installed:

   claude --version

   If it is not installed, install it globally:

   npm install -g @anthropic-ai/claude-code

3. Confirm your working tree is clean, then create a dedicated branch for the agent’s work:

   git status
   git checkout -b ai-builder-lab

4. Create a file named CLAUDE.md at the repository root (or add this section to it if the file already exists, for example from running /init). Paste in this exact role-enforcement prompt:

   # Builder Agent Ground Rules
    
   You are a Builder agent working under my direction. I am the Engineering
   Manager for this repository.
    
   - Implement only the task I give you. Do not expand the scope.
   - Do not modify any file in `models/` unless I explicitly instruct you to.
   - Match the code style, module system, and error-handling patterns already
     used in `routes/api/` and `utils/`.
   - Never run `git commit`, `git push`, or any other command that changes
     git history. I review every diff and make every commit myself.
   - If any requirement is ambiguous, stop and ask me before writing code.

   Commit this file now, so that every diff you review later contains only the agent’s work:

   git add CLAUDE.md
   git commit -m "Add builder agent ground rules"

5. Start Claude Code inside the repository and log in with your Per Scholas account when prompted:

   claude

   If you are not logged in, run /login inside Claude Code.

Part 1: The Builder Implements the Tasks API (15 minutes)

Your first delegation is the Phase 5 Tasks API. A Builder agent is only as good as its specification, so you will give it a precise one.

1. In Claude Code, press Shift+Tab to cycle permission modes until you reach Plan Mode. In Plan Mode, Claude Code proposes a plan without editing any files, which lets you approve the approach before any code exists.

2. Give the agent this specification. Adapt file names to match your project if they differ, but keep every requirement:

   Implement the Tasks API for this project in routes/api/taskRoutes.js,
   registered in server.js, following the existing modular structure.
   Do not modify anything in models/.
   
   Endpoints:
   1. POST /api/projects/:projectId/tasks
      Create a task for the given project.
   2. GET /api/projects/:projectId/tasks
      List all tasks for the given project.
   3. PUT /api/tasks/:taskId
      Update a task's title, description, or status.
   4. DELETE /api/tasks/:taskId
      Delete a task.
   
   Authorization rules (apply to every endpoint):
   - All routes require a valid JWT via the existing authentication
     middleware. Requests without a valid token receive 401.
   - For the :projectId routes, load the project first. If it does not
     exist, return 404. If it exists but req.user is not its owner,
     return 403.
   - For the :taskId routes, the check is a chain: find the task (404 if
     missing), then find its parent project (404 if missing), then verify
     req.user owns that parent project (403 if not).
   - Validation failures (for example a missing title or an invalid
     status value) return 400 with a JSON error message.
   - Error responses use the same JSON shape as the existing routes.

3. Read the plan the agent proposes. If it stays within the specification, approve it and let the agent exit Plan Mode to make the edits. If the plan proposes changing your models or adding endpoints you did not ask for, reject it and restate the boundary. Claude Code asks permission before editing each file; read each request and approve deliberately.

4. When the agent reports it is finished, review everything it did:

   git status
   git add --intent-to-add .
   git diff

   The git add --intent-to-add command marks the agent’s brand-new files (such as taskRoutes.js) so that git diff displays their full contents; plain git diff shows only changes to files that already existed. You may also review the changes in the Source Control panel in VS Code if you prefer a side-by-side view. Check each item:

   • Is the parent-project ownership check present on all four routes?
   • Are the status codes correct? A missing task or project must produce 404, an authenticated non-owner must produce 403, and a missing or invalid token must produce 401. A common agent mistake is returning 403 for a resource that does not exist, or 404 for a resource the user simply does not own.
   • Does the code match the style of your existing route files (same module system, same async error handling, same JSON error shape)?
   • Does git status show changes only to the files you expected? If models/ changed, the agent broke a ground rule: revert and redo.

5. Request at least one revision. This is mandatory, and there is always something. Strong candidates:

   • The task and project ownership chain is likely duplicated in the PUT and DELETE handlers; direct the agent to extract it into a reusable helper or middleware (a utils/ function is a good home).
   • Error responses may be inconsistent ({ message } in one place, { error } in another); direct the agent to standardize them.
   • The status field may accept any string; direct the agent to validate it against your schema’s allowed values and return 400 otherwise.

   Give the revision instruction in plain language, then re-run the review commands from step 4 and confirm the revision is what you asked for and nothing more.

6. Commit the reviewed work yourself:

   git add .
   git commit -m "Add Tasks API via reviewed AI builder work"

Part 2: The Builder Generates the Test Suite (15 minutes)

Manual Insomnia testing was acceptable for development, but your team lead wants a regression suite that runs with one command. You will delegate that too, and this delegation is where the review skill pays off: a test suite you do not read is worse than no test suite, because it creates false confidence.

1. Give the agent this task:

   Set up an automated test suite for this API.
   
   1. Install jest, supertest, and mongodb-memory-server as dev
      dependencies.
   2. Add an npm script named "test" so the whole suite runs with a
      single command: npm test. Configure Jest to run test files
      serially against an in-memory MongoDB instance. Tests must never
      touch my development database.
   3. If server.js currently starts the HTTP listener directly, refactor
      so the Express app is exported without starting the listener, and
      the listener starts only when the server is run normally. Do not
      change any runtime behavior.
   4. Create a tests/ directory with suites covering:
      - Registration: success, and rejection of a duplicate email.
      - Login: success returns a JWT; a wrong password is rejected.
      - Authentication: protected routes return 401 with no token and
        with an invalid token.
      - Projects: full CRUD as the authenticated owner.
      - Tasks: full CRUD through the nested routes as the authenticated
        owner.
      - Cross-user authorization: register two users; as User B, attempt
        to read, update, and delete a project and a task owned by
        User A. Every attempt must expect 403.
   5. Do not weaken or change application code to make a failing test
      pass. If you believe the application code is defective, stop,
      report the defect to me, and wait for my decision.

2. Approve the agent’s permission requests deliberately as it installs packages and writes files. The server.js refactor in step 3 of the prompt is an acceptable structural change; review it carefully in the diff, because it is the one place this task touches runtime code.

3. Run the suite:

   npm test

4. Triage every failure. For each one, make an explicit managerial decision: is the defect in the test, or in the application code?

   • If a test asserts behavior your specification never required (for example, expecting a 200 where your API correctly returns 201), the test is wrong: direct the agent to fix the test.
   • If a test exposes a real hole (for example, User B can read User A’s tasks because an ownership check is missing), the application is wrong: direct the agent to fix the application code, then re-run the suite.

   Record each decision; you will need them for your audit report in Part 3.

5. Repeat until the suite passes, then confirm the suite contains at least two negative authorization tests (the cross-user 403 scenarios). If it does not, direct the agent to add them.

6. Review the full diff one last time, marking new files first so the diff includes them, then commit:

   git add --intent-to-add .
   git diff
   git add .
   git commit -m "Add Jest and Supertest suite via reviewed AI builder work"

Part 3: The Engineering Audit Report (10 minutes)

An Engineering Manager leaves a paper trail. Write the audit report yourself, in your own words; do not delegate this part.

1. Create AI-REVIEW.md at the repository root with these sections:

   # AI Builder Audit: Tasks API and Test Suite
    
   ## Prompts Used
    
   (Paste the specification prompts you gave the agent, including any
   revision instructions.)
    
   ## What the Agent Got Right
    
   (Two or three observations.)
    
   ## Issues Found During Review
    
   (Every defect, weakness, or inconsistency you identified in the
   diffs. At least one is required.)
    
   ## Revisions Requested and Outcomes
    
   (What you asked the agent to change, and whether the revision was
   correct.)
    
   ## Test Triage Decisions
    
   (For each failing test: was the defect in the test or in the
   application code, and why.)
    
   ## Final Test Output
    
   (Paste the final passing output of npm test.)

2. Commit the report, publish the branch, and merge it after your final review:

   git add AI-REVIEW.md
   git commit -m "Add AI builder audit report"
   git push origin ai-builder-lab
   git checkout main
   git merge --no-ff ai-builder-lab
   git push origin main

   The --no-ff flag preserves a merge commit, so your history clearly shows that the agent’s work lived on a dedicated branch and was merged only after review.

3. Continue with Phase 5 of the TaskMaster project. Your reviewed Tasks API already satisfies it, and your test suite will catch regressions for the rest of the project.

Submission Guidelines

Submit the link to your TaskMaster GitHub repository via Canvas (the same repository you will submit for the project itself).

This lab is graded complete/incomplete. To earn a Complete, your repository must show all three of the following: