Pre-Deployment Refactoring Sprint

In this lab, you will run a structured pre-deployment refactoring sprint on your Pro-Tasker capstone: Claude Code, acting in the Builder role, audits your entire codebase and executes only the improvements you approve, while you act as the Engineering Manager making release decisions under a deadline. Triaging an audit, approving low-risk high-value changes, and rejecting risky ones days before a launch is a core professional judgment skill, and it is graded here exactly as it is evaluated on real teams: by the quality of your decision log.

Scenario

Pro-Tasker is feature-complete. The startup’s launch date is set, and Phase 4 (deployment to Render) begins in days. Before anything ships, the CTO wants a pre-deployment audit and cleanup pass, with strict change control:

• An AI agent may propose and execute refactors, but nothing reaches main without human review.
• The release is close, so risky refactors are deferred, not attempted. Saying “no” to a good idea at the wrong time is part of the job.

You are the Engineering Manager for this sprint. Complete this lab after finishing Phase 3 (your frontend is complete and connected to your backend) and immediately before Phase 4 (deployment), so the sprint finalizes the application you are about to deploy.

Estimated time: 45 minutes.

Objectives

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

• Direct Claude Code in the AI as Builder role to audit a full-stack codebase for performance, redundancy, and deployment readiness.
• Triage an AI-generated refactoring plan as a release manager: approve high-value low-risk items and reject or defer the rest with written rationale.
• Supervise autonomous execution with a one-commit-per-item workflow, reviewing every diff and verifying against regressions.
• Verify deployment readiness (environment variables, production builds, CORS, configurable API URLs) before opening a pull request.
• Produce a REFACTOR-REPORT.md audit and decision log, and merge the sprint through a reviewed pull request.

Prerequisites

• Your Pro-Tasker repository is complete through Phase 3: backend API, React frontend, authentication flow, and full project and task CRUD all work locally.
• The repository contains both the backend and the frontend (for example in server/ and client/ directories), is pushed to GitHub, and git status reports a clean working tree.
• Claude Code is installed and authenticated with your Per Scholas-provided Claude Pro account.
• Optional but recommended: if you completed the Builder agent lab in the backend project module (se/419), your Jest and Supertest suite is your regression gate for this sprint.

The Builder Role: Ground Rules

In the AI as Builder role, the agent works autonomously, but you own the release. Two rules are absolute in this lab:

1. The agent never works directly on main. All agent work happens on a dedicated branch and reaches main only through a pull request you review and merge.
2. You must reject or defer at least one audit item, with a written rationale. A manager who approves everything is not managing.

You will enforce the role through the CLAUDE.md file at your repository root, which Claude Code reads at the start of every session.

Setup (5 minutes)

1. Open a terminal at your Pro-Tasker repository root (the directory that contains both the backend and frontend code).

2. Confirm a clean working tree, then create the sprint branch:

   git status
   git checkout -b pre-deploy-refactor

3. Create a file named CLAUDE.md at the repository root (or add this section to it if the file already exists). Paste in this exact role-enforcement prompt:

   # Refactoring Sprint Ground Rules
    
   You are a Builder agent performing a pre-deployment refactor under my
   direction. I am the Engineering Manager for this release.
    
   - Work only on the pre-deploy-refactor branch. Never modify code while
     main is checked out.
   - Implement exactly one item at a time from REFACTOR-REPORT.md, and
     only items I have marked Approved.
   - Do not add features, change API routes, or alter behavior that users
     can observe.
   - Never run git commit or git push. I review every diff and make every
     commit myself.
   - If a change turns out to be riskier than the plan suggested, stop
     and report to me instead of continuing.

   Commit this file now, so that the audit step that follows leaves the working tree otherwise clean:

   git add CLAUDE.md
   git commit -m "Add refactoring sprint ground rules"

4. Start Claude Code in the repository root 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 Full-Codebase Audit (10 minutes)

The agent’s first job is analysis, not action. You will run this step in Plan Mode so nothing is edited while the audit happens.

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.

2. Give the agent this audit prompt:

   Analyze this entire codebase (backend and frontend) and produce a
   written pre-deployment refactoring plan. Do not change any code.
   
   Organize findings into exactly three categories:
   
   1. Performance
      - Mongoose queries missing .lean() or .select() where documents
        are read-only
      - Missing indexes on fields used in frequent queries
      - Unnecessary React re-renders and missing or incorrect useEffect
        dependency arrays
      - Unused imports or dependencies inflating the frontend bundle
   
   2. Redundancy
      - Dead code and leftover scaffold files
      - Dependencies listed in either package.json that are never used
      - Duplicated fetch or API logic in components that belongs in a
        custom hook or a shared API module
   
   3. Deployment readiness
      - Hardcoded localhost URLs anywhere in the frontend or backend
      - Stray console.log statements in production code paths
      - CORS configuration that would block a deployed frontend origin
      - Secrets or configuration not read from environment variables
      - Missing or broken production build scripts
   
   For every finding, give: the file path, a one-sentence description of
   the issue, the proposed fix, a risk level (low, medium, or high), and
   an effort estimate (small, medium, or large). Number the findings so
   I can approve or reject them by number.

3. Read the proposed plan. When you are satisfied it is analysis only, exit Plan Mode and give the agent one narrowly scoped instruction: save the audit, exactly as presented, to a new file named REFACTOR-REPORT.md at the repository root, changing no other files.

4. Verify the boundary held:

   git status

   Only REFACTOR-REPORT.md should appear. If anything else changed, revert it before continuing.

Part 2: The Engineering Manager Review (10 minutes)

Now triage the audit the way a manager triages before a release: value versus risk, with a deadline days away.

1. Read every finding in REFACTOR-REPORT.md.

2. Approve three to five items that are high value and low risk. Deployment-readiness items should be your first priority, because Phase 4 depends on them; a hardcoded localhost URL is a guaranteed production failure, while a missed .lean() is only a missed optimization.

3. Reject or defer at least one item, and write a one-sentence rationale for each rejection or deferral. This is mandatory. Good rationales sound like real release decisions: “Too risky this close to the deadline,” “Out of scope for a pre-deployment pass,” or “Valuable, but deferred until after launch because it touches the auth flow.”

4. Record your decisions in a Decision Log section at the top of REFACTOR-REPORT.md, in this format:

   ## Decision Log
    
   | #   | Finding                                    | Decision | Rationale                                             |
   | :-- | :----------------------------------------- | :------- | :----------------------------------------------------- |
   | 3   | Hardcoded localhost URL in API module      | Approved | Guaranteed production failure on Render.               |
   | 7   | Duplicated fetch logic in three components | Approved | Low risk; extracting a shared hook simplifies Phase 4 debugging. |
   | 9   | Restructure Context into a reducer         | Deferred | Touches the auth flow; too risky before the deadline.  |

5. Commit the report and decision log before any code changes, so your history proves the decisions came first:

   git add REFACTOR-REPORT.md
   git commit -m "Add pre-deployment audit and decision log"

Part 3: Autonomous Execution and Diff Review (15 minutes)

Execute the approved items one at a time. The loop below is the whole discipline of this lab; do not batch it.

For each approved item, in order:

1. Direct the agent to implement only that item, referencing it by number from the decision log, for example: “Implement approved item 3 from REFACTOR-REPORT.md. Change nothing else.”

2. Review the change before anything is committed:

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

   The git add --intent-to-add command marks any brand-new files the agent created (for example an extracted custom hook) so that git diff displays their full contents; plain git diff shows only changes to files that already existed. You may instead review the changes in the Source Control panel in VS Code, or ask Claude Code to walk you through its own diff, but you must read every changed line. Confirm the change matches the finding and nothing more.

3. Verify no regressions:

   • Start the backend and the frontend locally.

   • Exercise the critical paths by hand: log in, create and edit a project, create and edit a task.

   • If you completed the se/419 Builder agent lab, also run your test suite from the backend directory as your regression gate:

     npm test

4. If anything regressed, send it back: describe the failing behavior to the agent, have it fix the regression, and re-review the diff. Do not move to the next item with a known regression in place.

5. Commit the verified item, one commit per item, with a descriptive message:

   git add .
   git commit -m "Refactor: extract shared API fetch logic into a custom hook (item 7)"

Repeat until every approved item is implemented, verified, and committed.

Part 4: Finalize for Deployment (5 minutes)

1. Ask the agent to run a final deployment-readiness check against this checklist and report the result of each line:

   Check this codebase against the following deployment checklist and
   report pass or fail for each item, with file references. Do not
   change any code.
   
   1. All secrets and configuration are read from environment variables,
      and every .env file is listed in .gitignore.
   2. The frontend production build succeeds: npm run build completes
      without errors.
   3. No console.log statements remain in production code paths.
   4. The frontend API base URL is configurable rather than hardcoded
      (for a Vite app, an environment variable such as VITE_API_URL read
      via import.meta.env).
   5. Backend CORS configuration will accept the deployed frontend
      origin once both are on Render.

2. Confirm the build claim yourself by running npm run build in your frontend directory. If any checklist item fails, treat the fix as one more approved item and run it through the Part 3 loop.

3. Paste the checklist results into a Deployment Readiness section of REFACTOR-REPORT.md, then commit and publish the branch:

   git add REFACTOR-REPORT.md
   git commit -m "Add deployment readiness verification"
   git push -u origin pre-deploy-refactor

4. On GitHub, open a pull request from pre-deploy-refactor into main. Read the Files changed tab as your final end-to-end review, then merge the pull request. Copy the pull request URL; you will submit it.

5. Pull the merged result locally and proceed to Phase 4. Your capstone deployment now runs on the refactored code:

   git checkout main
   git pull origin main

Submission Guidelines

Submit via Canvas:

1. The link to your Pro-Tasker GitHub repository (the same repository you will submit for the capstone).
2. The URL of your merged pull request, pasted into the Canvas submission comment.

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