79 lines
4.0 KiB
Markdown
79 lines
4.0 KiB
Markdown
# Working in this repository
|
|
|
|
Treat the repository's code, tests, documentation, build configuration, and
|
|
existing conventions as the source of truth. Read nearby files before changing
|
|
them, prefer established patterns over introducing parallel ones, and keep the
|
|
work limited to the user's request.
|
|
|
|
## Before editing
|
|
|
|
1. Find the repository boundary and read any more specific agent instructions.
|
|
2. Check the worktree status and preserve all pre-existing changes, including
|
|
staged changes and untracked files.
|
|
3. Identify the smallest set of files that owns the requested behavior and the
|
|
narrowest useful checks for it.
|
|
4. Note whether the change crosses repository, package, service, or public
|
|
interface boundaries. Keep independently versioned repositories separate.
|
|
|
|
Do not perform unrelated cleanup, refactoring, dependency upgrades, formatting
|
|
sweeps, or generated-file refreshes merely because they are convenient. Never
|
|
discard, overwrite, or include unrelated user work in a commit.
|
|
|
|
## Implementation and verification
|
|
|
|
- Make the smallest coherent change that fully implements the requested
|
|
behavior.
|
|
- Match the surrounding architecture, naming, style, error handling, and test
|
|
organization.
|
|
- Add or update focused tests with behavior changes. Prefer the closest existing
|
|
test location over new infrastructure.
|
|
- Treat external input and process, network, filesystem, and serialization
|
|
boundaries as fallible. Return actionable errors without exposing secrets.
|
|
- Use the project's declared toolchain and lockfiles. Do not install into the
|
|
system environment or add dependencies when existing tools are sufficient.
|
|
- Run focused checks while iterating, then the relevant formatter, tests,
|
|
linter, build, and documentation checks before handoff.
|
|
- Do not claim a check passed when it was skipped, unavailable, or only partly
|
|
run. Record limitations explicitly.
|
|
|
|
## Small, reviewable commits
|
|
|
|
Small commits are part of the deliverable, not optional cleanup at the end.
|
|
|
|
- Commit each completed logical change as soon as it is coherent and its
|
|
relevant checks pass.
|
|
- Give every commit one clear purpose. Do not combine a feature, unrelated
|
|
cleanup, dependency churn, and formatting changes in one commit.
|
|
- Keep every commit buildable and independently reviewable whenever the project
|
|
permits it. Tests and documentation required by a behavior change belong in
|
|
the same commit as that behavior.
|
|
- Split work at natural boundaries rather than by file count. A small coherent
|
|
cross-file change is better than several incomplete file-by-file commits.
|
|
- When multiple repositories are involved, create separate commits in each
|
|
repository. Never create a cross-repository commit or hide one repository's
|
|
incomplete state behind another's commit.
|
|
- Stage files explicitly and inspect the staged diff before committing. Never
|
|
sweep pre-existing or unrelated changes into the task commit.
|
|
- Follow the repository's existing commit-message convention. If none is
|
|
documented, use a short imperative subject describing the outcome.
|
|
- Use additive history. Do not amend, squash, rebase, reset, force-push, or
|
|
otherwise rewrite existing commits unless the user explicitly requests it.
|
|
- Do not push, publish, tag, create a release, or modify remotes unless the user
|
|
explicitly requests that external action.
|
|
|
|
Unless the user or a higher-priority instruction says not to commit, completing
|
|
an in-scope repository change includes creating the focused commit or commits.
|
|
Do not leave finished work only in the worktree. If a coherent commit cannot be
|
|
created, explain the exact blocker instead of making a knowingly broken
|
|
checkpoint commit.
|
|
|
|
## Handoff
|
|
|
|
Before reporting completion:
|
|
|
|
1. Review the final diff for accidental churn, generated artifacts, secrets,
|
|
debug output, and changes outside the requested scope.
|
|
2. Verify each created commit and check the final worktree status.
|
|
3. Report the changed behavior, checks actually run, commit IDs, and any
|
|
remaining limitations or intentionally uncommitted pre-existing work.
|