Edit an AI Agent Document Generator Without Mixing Up Its Current and Legacy Stacks
Use when an AI changes a multi-agent app that generates documents and still carries an older stack. It finds the real startup command, trusts code over outdated docs, keeps config names working, follows changes across Python and Node, and runs the smallest useful tests.
To use this AI rule
## Find the Real Startup Commands and Config in the Code First
Start with package metadata, console entrypoints, configuration loaders, environment-variable handling, and code that creates runtime workspaces. These executable surfaces outrank prose documentation when they conflict.
- Confirm which command launches the primary application.
- Confirm which command exposes any legacy or MCP-compatible service.
- Trace each command to its actual module and function.
- Locate configuration templates and default workspace behavior.
- Verify that every referenced path exists in the current checkout.
Treat an outdated overview as historical context, not as proof of the current startup path.
## Decide Whether the Current or the Legacy Stack Owns the Change
A repository may ship a current product stack alongside an earlier generation library that still serves a specialized endpoint. Identify the owning stack before editing.
The current stack may own:
- the command-line interface and onboarding flow;
- orchestration and multi-agent execution;
- research, generation, and design agents;
- MCP-style tools for search, reflection, conversion, and task management;
- configuration, logging, and workspace utilities;
- browser-based HTML conversion and a Node helper;
- integration-oriented tests.
The legacy stack may still own template-driven generation, layout induction, parsing, evaluation, and a compatibility server. Do not assume that changing a shared concept in one stack updates the other.
## Keep the Design Simple with Fewer Special Cases and Short Functions
Prefer designs that turn edge cases into ordinary cases instead of accumulating conditional branches. Solve the actual repository problem rather than a hypothetical architecture problem.
- Choose a direct, operationally light solution when it meets the real requirement.
- Keep functions short, focused, and plainly named.
- Treat unnecessary complexity as a defect.
- More than 3 levels of indentation is a signal to restructure the code.
- Do not hide normal control flow inside broad exception wrappers without a concrete failure mode.
- Keep criticism technical and directed at code, design, or assumptions rather than people.
Good judgment is visible in fewer special cases, smaller surfaces, and behavior that is easy to verify.
## Add Type Hints and Keep Dependencies to a Minimum
Apply consistent conventions across the maintained stack:
- add type annotations to functions and methods;
- write technical documentation and code comments in the repository's declared language;
- use the current dependency manager, repository search tools, language features, and supported library APIs;
- prefer current serialization and validation interfaces over deprecated forms;
- minimize dependencies and total code;
- keep the root package definition focused on the primary product;
- place dependencies for genuinely isolated subprojects in their local dependency files.
Do not move a dependency merely for tidiness. Separate it only when the runtime and maintenance boundary is real.
## Trace a Change Through Every Linked Part, Including Python and Node
Inspect the complete owning path for the behavior being changed:
- for command-line behavior, inspect command definitions, shared command helpers, and configuration loading together;
- for orchestration, inspect the main coordinator and the relevant agent implementation;
- for MCP behavior, decide whether ownership belongs to current tool servers or the legacy compatibility server;
- for export and conversion, inspect both the Python orchestration side and the Node conversion side;
- for duplicated generation concepts, change only the owning stack unless the task explicitly spans both.
Keep the change scoped. Do not refactor both stacks simply because similar names appear in each.
## Keep Existing Config Names and Workspace Locations Working
Existing configuration keys, environment variables, onboarding behavior, example configurations, and workspace locations form a runtime contract. Preserve their names unless the task explicitly includes a migration.
Browser and container dependencies may be normal runtime requirements for conversion paths rather than optional development extras. Native conversion tools, model credentials, browser automation, and container images can also determine which integration tests are runnable.
When changing a runtime path:
1. Identify every configuration source and default.
2. Trace how onboarding and examples populate those values.
3. Check the Python caller and any external conversion helper.
4. Preserve compatibility or provide an explicit migration path.
## Check Old Docs Against the Code and Sort Tests by What They Need
Verify documentation claims against the current file tree and executable entrypoints before relying on them. Older documents may still explain useful concepts while naming removed files or obsolete startup flows.
Classify tests by what they require:
- unit tests for isolated logic;
- parser or marked tests for specialized data paths;
- integration tests for sandbox tools, browser or PDF conversion, image processing, and external utilities;
- model-backed tests that require credentials or networked services.
A missing browser, container image, native converter, or model credential is a validation limitation, not evidence that unrelated code is broken.
## Run the Smallest Useful Tests and Report What Could Not Run
Use a focused change sequence:
1. Confirm which stack and entrypoint own the behavior.
2. Edit the smallest complete surface.
3. Run the narrowest meaningful test subset.
4. Expand only to directly coupled Python, Node, browser, container, or compatibility paths.
5. Report any dependency or environment requirement that prevented validation.
Review the final diff for accidental changes to the other stack, renamed configuration contracts, stale documentation references, unrelated refactoring, and untested cross-language boundaries.
Report what changed, which path was exercised, which checks passed, and which checks could not run. Do not claim complete validation when a required runtime dependency was unavailable.