AI coding agents
Repository Orientation Checklist
Build a verified map of a repository before asking an AI coding agent to plan or modify it.
- Format
- Checklist
- Level
- Beginner
- Audience
- Practitioner, Developer, Operator
- Owner
- Project42 Editorial
- Review cadence
- Every 30 days
- Prerequisites
- Read access to a version-controlled repository
Start with scope and authority
Confirm the repository root, active branch, clean or dirty worktree, remotes, and the exact paths in scope. Read the repository's agent instructions from broadest to most specific, then record which file governs each target. Instructions guide the agent, but enforced permissions, branch protections, and review rules remain the real control boundaries.
Do not treat neighboring repositories, generated files, build output, dependency caches, credentials, or unrelated local changes as implicitly in scope. If instructions conflict, stop at the conflict and ask the authorized owner instead of choosing the most convenient rule.
Map the system before proposing work
Identify entry points, package and workspace boundaries, build and test commands, deployment configuration, data stores, migrations, security-sensitive paths, ownership files, and continuous-integration checks. Trace one representative request or content item from source to output so the map reflects behavior rather than filenames alone.
Use read-only discovery first. Record facts with file paths, commands, and observed results; label architectural conclusions as inferences. Never open secret values merely to prove a secret store exists.
Repository and root: [NAME, ABSOLUTE OR WORKSPACE-RELATIVE ROOT]
Requested outcome: [BOUNDED OUTCOME]
In-scope paths: [PATHS]
Out-of-scope paths: [PATHS]
Governing instructions: [FILE -> TARGET PATH]
Branch and worktree state: [BRANCH, CLEAN | EXISTING CHANGES]
Runtime and package boundaries: [COMPONENT -> STACK]
Entry points and data flow: [SOURCE -> PROCESS -> OUTPUT]
Standard checks: [COMMAND -> EXPECTED RESULT]
Sensitive or generated paths: [PATH -> HANDLING RULE]
Unknowns and conflicts: [QUESTION -> OWNER]
Rollback/recovery: [HOW TO RESTORE THE VERIFIED BASELINE]
Evidence captured: [FILE, COMMAND OUTPUT, OR LINK]Expected evidence and verification
The expected evidence is a repository map that another contributor can use to locate the governing instructions, main components, verification commands, risky boundaries, existing changes, and unresolved unknowns without rerunning broad discovery.
Verify every named path exists, every proposed command is documented or safely inspected, and the worktree baseline is preserved. Ask a reviewer to trace one representative flow using only the record. Refresh the map after a branch, dependency, instruction, architecture, or deployment change.