Manage large projects

The most common problem in a large task is not that the model cannot write code. It is that the scope keeps expanding, the context becomes confused, and eventually no one can prove which parts are actually complete.

Build a project map first

Before making changes, have the Agent identify:

• user entry points and core data flows;
• relevant modules and their owners;
• protocol, configuration, or database boundaries;
• the smallest relevant tests and the full quality gates;
• changes that already exist in the current workspace.

Ask for citations to key files, but do not scan every file at the outset. You can follow Understand an existing project directly.

Divide the objective into milestones

A reliable sequence is usually:

1. contract or behavior definition;
2. core implementation;
3. interface or integration;
4. tests;
5. documentation and release checks.

Each milestone should produce an independently verifiable output. After completing a phase, have the Agent summarize again from the current files and tests instead of relying only on the early plan.

Decide between sequential and parallel work

Before using Multi-Agent, ask three questions:

• Can the subtask make progress without the result of another workstream?
• Can each workstream receive a clear deliverable?
• Does the root Agent have a way to cross-check the results?

If every answer is yes, parallel investigation or review can work well. A large implementation that shares the same files is usually better handled sequentially by one Agent to avoid overwriting changes.

Control the change surface

• Specify which directories may be modified and which areas must not be touched.
• Record existing uncommitted changes before starting; they must not be presented as Agent output.
• Run the smallest relevant tests first, then decide whether full validation is needed.
• Inspect the diff at every phase to catch unrelated formatting or generated files early.
• Use version control to create recoverable checkpoints for important changes.

Manage context

Long conversations compress older history. Do not leave critical facts only in the chat. Put stable conventions in project documentation, turn reusable working methods into Skills, and write phase conclusions into explicit deliverable files.

When a conversation reaches a natural milestone, ask the Agent to output “confirmed facts, completed work, incomplete work, risks, and next steps,” then start a more focused conversation for the next phase. A new conversation does not automatically contain every detail from the old one, so provide required material through project files or a clear summary.

Keep an evidence ledger

At final review, check three columns:

Do not treat “the Agent says it ran the test” as evidence. Preserve actual command results or reproducible steps.

When to stop and replan

• The approach requires a substantial expansion of permissions or scope.
• A critical assumption contradicts the code.
• An external side effect enters an unknown-outcome state.
• The context can no longer distinguish changes from this turn and older changes.
• The test baseline is unstable, making regressions impossible to assess.

Stopping is not failure. Preserve the facts and diff, then begin the next phase with clearer boundaries. This is usually faster than continuing to stack patches on top of uncertainty.