A weekly coding agent routine for technical debt

Writing the cleanup got cheap. Deciding whether it's safe didn't. Technical debt tickets survive because that second part is hard to fit between feature changes. Removing an old helper sounds simple until someone asks whether an external script still imports it. A feature flag looks obsolete until the release owner remembers a customer still uses the alternate path.

An agent can do the repository investigation and prepare a patch. Give it a small category of work and a clear point where it should return a question. Otherwise, a weekly maintenance routine can turn into a weekly argument about a very large diff.

Pick one category of debt

Start with a maintenance task whose evidence is mostly available in the codebase. An internal helper with no references may be a candidate. So might a redundant test fixture or a dependency the team has already approved for a patch update.

Flag removal needs more context. A repository search can find references, but it may not show rollout state or use by external systems. Supply that information or keep the task investigative. Likewise, a public export with no internal callers can still have downstream consumers.

Keep a short list of approved categories in project instructions. Name the areas that need an owner, such as authentication behavior, migrations, billing, or infrastructure. The purpose is to let a useful run finish without asking the agent to invent your risk tolerance.

Split finding from fixing

For the first week, ask for candidates and evidence. No patch is necessary.

Inspect the approved maintenance areas and identify up to two small candidates. For each, explain the current behavior, the evidence supporting a change, likely external dependencies, and the checks needed. Do not edit files. Prefer reporting no suitable candidate over suggesting a speculative cleanup.

Review that result with someone who knows the repository. If the candidates are consistently useful, permit one patch per run in a narrower category.

A hypothetical unused helper illustrates the distinction. Static search might find no callers, but the helper could be loaded by a naming convention. Ask the agent to inspect dynamic imports, registration code, package exports, and relevant scripts before concluding it is unused. When the evidence remains incomplete, a short investigation saves more work than a deletion PR.

Schedule one reviewable change

Schedule the assignment for a time when a reviewer can inspect the result the same day. The agent may still need approval for a command or a sensitive change, and a run that waited three days on a permission prompt isn't a routine.

If you don't want to run the schedule yourself, Hoplite automations run this prompt weekly in a sandbox with your test suite. Each week you get a small draft PR, or a run that reports it found nothing.

For an approved cleanup category, an example assignment is:

Find one candidate within the approved maintenance scope. Check open PRs for overlapping work. Explain why the change preserves behavior, prepare the smallest useful patch, and run the relevant checks. Open a draft PR with the evidence and test results. If the baseline fails, external usage is uncertain, or the change grows beyond the original candidate, stop and report. Do not merge.

Keep auto-merge off for this routine and use branch protections to require human review. Check the repository's merge settings before enabling the schedule.

Keep recurring procedures in the repository, where a scheduled run can load them. Instructions stored in one person's local setup won't be there at 2 a.m.

Put the evidence in the PR

A good maintenance PR explains what disappeared and why the application no longer needs it. Ask for the relevant references, affected tests, and any unresolved assumptions. Avoid descriptions that merely repeat the diff.

For a dependency update, include the version change and compatibility checks. For a removed helper, explain how the agent searched for callers and verified the affected behavior. For a flag, include the owner's rollout confirmation. Different maintenance tasks need different evidence.

When the final summary leaves a question open, read the agent's commands and edits rather than asking it to summarize again. Return specific feedback so the agent can address the actual concern without broadening the patch.

Keep the routine small

Track accepted changes, rejected suggestions, and reviewer time. A routine that creates five PRs nobody wants to review is adding queue management to the maintenance backlog.

After a few runs, look at why work was rejected. If the agent repeatedly suggests cosmetic changes, tighten the category. If it keeps hitting missing context, document that context or move the category back to investigation only.

Begin with one internal cleanup candidate in a familiar part of the repository. Review the evidence and the patch before giving the next run more scope. Leave weeks with no suitable change empty; the scheduler doesn't need a souvenir.