repo-setup

Repo Setup

Agents take shortcuts and copy nearby patterns. Shape the repository so the shortest, most obvious implementation follows the intended architecture. Make important wrong paths impossible or fail early instead of relying on reminders.

Understand The Repository

Read the source, build and test entrypoints, CI, static-analysis configuration, and existing instructions. Trace representative product flows to learn:

• where a new feature naturally belongs;
• which modules can change persistent state;
• which shortcuts or recurring mistakes would be costly;
• where external data is validated;
• which local command proves a change is safe.

Separate the architecture the code currently has from the architecture the user actually wants. Present a concise mental model and the important choices before making judgment-heavy or broad structural changes. Ask only questions that can materially change the product or architecture.

Establish The Contract

Agree on the important rules for the repository. Focus on rules that prevent real confusion, coupling, or recurring mistakes, such as:

• one obvious place to add each kind of feature;
• one clear module or API that writes each persistent value;
• simple code paths that make important invariants hard to bypass;
• validation at external boundaries rather than scattered through the system;
• one canonical local verification command that CI also runs.

Do not copy another repository's layout blindly. Use its principles only when they fit this product and codebase.

Make The Correct Path Easy

Remove misleading, duplicate, and bypass paths when safe. Prefer the strongest proportional mechanism that fits the rule:

1. code structure, data models, or types that make the mistake impossible;
2. dependency rules, lint, or static analysis that fail the build;
3. one canonical API, helper, generator, or extension convention;
4. focused tests or runtime checks;
5. written instructions only when the decision requires human judgment.