Edit a Multi-Module Repository With Generated Code Without Overstepping Approvals

## Read the Root and Folder Instructions Before Editing Begin by locating the repository guidance that governs the files you may change. Treat project documentation and nested instruction files as the authority for local conventions rather than assuming ecosystem defaults. - Read the root guidance and any more specific instructions in the target directory. - Review the repository overview, contribution guide, developer setup, testing guidance, and release documentation relevant to the task. - Follow the nearest applicable instruction when repository-wide and module-specific guidance differ. - Resolve referenced policies from maintained project files instead of relying on remembered commands. - Identify ownership files and the reviewers responsible for the affected area. - Record the supported workflow, required approvals, and validation expectations before editing. - Ask only when authoritative sources conflict or a consequential decision remains unresolved. ## Find the Module That Owns the Change and Who Reviews It Understand how the codebase is divided before choosing where to implement behavior. In a multi-module repository, build boundaries, dependency manifests, generated areas, examples, tests, and release units may differ by directory. - Locate the module that owns the public behavior and the lower-level components it depends on. - Distinguish handwritten implementation from generated code, templates, specifications, fixtures, and examples. - Inspect module manifests to understand direct and indirect dependency boundaries. - Use ownership rules to identify maintainers for code, services, and shared infrastructure. - Trace whether a change affects one package, a module family, or a shared compatibility surface. - Match the established directory layout and naming patterns instead of inventing parallel structures. - Keep unrelated modules outside the change unless a verified dependency requires coordinated updates. ## Use the Project's Declared Tool Versions and Task Commands Use the toolchain declared by the repository and the target module. Version support, task runners, generators, and environment preparation are project decisions, not values to infer from the newest local installation. - Confirm the currently supported language and tool versions from maintained policy or configuration. - Prefer repository-managed tasks over direct language commands when they perform additional setup. - Run commands from the module or workspace directory expected by the documented workflow. - Preserve environment selection, compatibility options, generated assets, and other setup performed by canonical tasks. - Install global prerequisites only when the documented workflow explicitly requires them. - Keep generator and compiler versions aligned with the project’s pinned or supported versions. - Report missing prerequisites as a concrete blocker rather than silently changing the workflow. ## Ask Before Releases, CI Changes, or Using Credentials Agents may read code, explain behavior, propose changes, implement authorized edits, add tests, improve documentation, and assist with issue or review analysis. Higher-impact operations remain subject to explicit human authority. - Do not trigger releases, approve release stages, or publish packages without approval. - Do not modify continuous integration, deployment pipelines, or workflow controls as an incidental part of another change. - Do not alter licensing, legal notices, or compliance policy without explicit authorization. - Do not use credentials, contact external services, or mutate remote state beyond the granted task. - Treat issue triage, label suggestions, and duplicate detection as recommendations unless state changes are authorized. - Stop before destructive operations or protected-environment changes and request the required decision. - Continue ordinary in-scope implementation and validation without asking for unnecessary confirmation. ## Change the Spec and Regenerate Instead of Editing Generated Files Generated packages require a different change path from handwritten code. Manual edits to generated output are usually overwritten and can separate the implementation from its authoritative specification. - Identify generated files through repository markers, manifests, location files, or documented directory rules. - Do not manually patch generated output when the project requires specification-driven regeneration. - Change the authoritative specification, template, or generator input when that is the documented source of truth. - Use the project’s prescribed generation command and required tool versions. - Review the generated diff for unexpected files, formatting churn, or unrelated API changes. - Keep manual extension points separate from generated regions according to repository patterns. - If regeneration is unavailable or unauthorized, explain the limitation instead of disguising a temporary edit as a durable fix. ## Make Small Changes That Keep Backward Compatibility Favor focused changes that follow established code conventions and preserve compatibility. A narrow, reviewable patch is safer than a broad refactor when both satisfy the requirement. - Read nearby implementations before selecting helpers, names, error patterns, and file placement. - Preserve backward compatibility unless a breaking change is explicitly approved and documented. - Follow local conventions for exported names, acronyms, comments, and public API documentation. - Use descriptive errors that retain useful context without exposing secrets. - Keep required copyright and license headers intact. - Follow module dependency policy and avoid adding an external dependency for behavior already available locally. - Separate unrelated cleanup from the requested change so reviewers can evaluate intent clearly. ## Build and Test the Target Module First, Then Widen Only if Needed Run the smallest commands that exercise the affected module, then broaden validation only when shared behavior or repository policy requires it. A successful command is meaningful only when it covers the changed path. - Build the target module using its documented task or language command. - Run the directly relevant unit tests before wider package or workspace suites. - Add type checks, static analysis, formatting, and generated-file verification when the module requires them. - Confirm that test selection actually included the intended package and cases. - Inspect required environment variables before attempting integration or live tests. - Do not claim validation from a command that skipped targets or relied on unavailable external state. - Record the commands run, observed results, and any checks that could not be completed. ## Write Tests Free of Network and Order Dependence, Plus Runnable Examples Tests should prove the behavior change and remain reliable across machines. Examples should demonstrate supported usage while following the repository’s executable example conventions. - Reuse the assertion library and test structure already established in the module. - When fixing a defect, confirm the new test fails for the intended reason before applying the fix. - Keep unit tests independent of networks, credentials, time-sensitive state, and execution order. - Store fixtures in the designated test-data location and keep them minimal. - Isolate live-test settings in approved environment files and never commit secrets. - Add assertion messages when they materially improve diagnosis. - Place examples in the expected naming and package structure, and ensure they compile or run under the documented test workflow. ## Update Module Docs and the Changelog When Behavior Changes Documentation is part of the implementation surface. Update it when users, maintainers, or release tooling would otherwise receive an incomplete or misleading view of the change. - Update the module overview when setup, supported behavior, or public usage changes. - Add or revise API comments according to the project’s documentation style. - Record user-visible changes in the required change history. - Provide examples for new public APIs when repository policy expects them. - Keep setup, generation, migration, and release instructions synchronized with actual commands. - Verify that references remain valid and do not point readers to private or obsolete locations. - Avoid documentation churn when the behavior and workflow are unchanged. ## Open a Change Request From the Approved Branch After Reviewing the Full Diff Use the repository’s approved contribution path and make the complete change easy to inspect. A contribution should connect implementation, tests, documentation, and rationale without changing protected shared history. - Create work from the approved base branch and publish through the authorized fork or remote. - Review the complete branch diff before opening a change request. - Use a descriptive title and reference related work when available. - Include tests that protect against future regressions and documentation required by policy. - Address review feedback with traceable follow-up changes unless maintainers request another history strategy. - Verify all required automated checks and investigate failures rather than bypassing them. - Leave protected branches, release branches, and shared history unchanged without explicit authorization. ## Review Code for Breaking Changes and Generated-File Mistakes Code review should prioritize correctness, compatibility, generation integrity, test quality, security, and maintainability. Apply project-specific guidelines rather than a generic style checklist. - Check that the change belongs in the selected module and follows its architecture. - Look for breaking API or behavioral changes, including subtle default changes. - Verify tests cover success, failure, boundaries, and repeatability where relevant. - Confirm generated files came from the approved source and generation workflow. - Inspect dependency and manifest changes for policy violations or unnecessary additions. - Check documentation and change records for completeness and accuracy. - Route findings to the responsible owners and distinguish blocking defects from optional improvements. ## Report Security Issues Privately and Hand Off Test Results Security reports, releases, pipeline approvals, licenses, and credentials require dedicated handling. Finish ordinary work with an evidence-based handoff while keeping protected operations with authorized humans. - Report security vulnerabilities through the project’s private channel, not a public issue or discussion. - Never include secrets, private contact details, or sensitive reproduction data in public artifacts. - Leave release triggers, deployment approvals, and licensing decisions to explicitly authorized maintainers. - Explain important implementation choices and link them to applicable project guidance. - Summarize changed paths, tests performed, observed results, and remaining limitations. - Identify the appropriate code or service owners when further review is required. - State clearly when external access, unavailable tooling, or an approval boundary prevented complete verification.