104 lines
4.8 KiB
Markdown
104 lines
4.8 KiB
Markdown
# Agent Policy
|
|
|
|
**Base Policy Version:** 1.0
|
|
|
|
**Last Updated**: 2026-09-23
|
|
|
|
## Purpose
|
|
|
|
Agents working in this repository must read and adhere to the following house rules.
|
|
|
|
## Implementation Discipline
|
|
|
|
**KEY PRINCIPLES:** Write the simplest idiomatic code that satisfies the user's
|
|
request. Do not implicitly strengthen requirements, restrictions, or guarantees
|
|
beyond what the user actually requested.
|
|
|
|
**Keep implementation machinery proportionate.** Use straightforward,
|
|
idiomatic code and introduce only the machinery needed to support the requested
|
|
behavior and flexibility. Optimize for conceptual simplicity and
|
|
maintainability, not for the fewest lines, fewest options, or narrowest product
|
|
surface.
|
|
|
|
**Do not invent restrictions.** Do not reject, prohibit, constrain, cap,
|
|
harden, or otherwise narrow behavior unless required by the user, an explicit
|
|
repository contract, or an unavoidable correctness constraint. Preserve
|
|
operator and caller choice where policy has not been established. If an
|
|
additional restriction appears advisable, present it as a decision rather than
|
|
silently implementing it.
|
|
|
|
**Do not invent guarantees.** Do not strengthen public contracts, guarantees,
|
|
or invariants beyond those expressly requested by the user.
|
|
|
|
**Use the standard library.** For example: in almost every case, the best
|
|
approach to copying files is to use the standard library. Writing custom code to
|
|
implement power-loss protection at the application level, or to guard against
|
|
bad actors with privileged and concurrent access to the host's filesystem,
|
|
is wasteful, unnecessary, and not idiomatic. Stick to the simple, standard, and
|
|
idiomatic approach unless another path is expressly requested by the user.
|
|
|
|
**An implementation detail is not repository policy.** Tests and documentation
|
|
must not elevate incidental behavior into a durable guarantee or restriction
|
|
unless that behavior was expressly selected as part of the contract.
|
|
|
|
## Codebase Discovery
|
|
|
|
This project uses codebase-memory-mcp to maintain a knowledge graph of the
|
|
codebase. Always prefer its graph tools over grep, glob, or file search for code discovery.
|
|
If the project is not indexed, run `index_repository` first.
|
|
|
|
Use this order:
|
|
|
|
1. `search_graph` to find functions, classes, routes, and variables by pattern.
|
|
2. `trace_path` to trace callers and callees.
|
|
3. `get_code_snippet` to read a specific function or class.
|
|
4. `query_graph` for complex graph queries.
|
|
5. `get_architecture` for the high-level project summary.
|
|
|
|
Fall back to grep or glob for string literals, error messages, configuration
|
|
values, non-code files, or when the graph tools return insufficient results.
|
|
|
|
Examples:
|
|
|
|
- Find a handler: `search_graph(name_pattern=".*OrderHandler.*")`.
|
|
- Find callers: `trace_path(function_name="OrderHandler", direction="inbound")`.
|
|
- Read source: `get_code_snippet(qualified_name="pkg/orders.OrderHandler")`.
|
|
|
|
## Git Commit Policy
|
|
|
|
This policy applies to all coding agents and agent harnesses working in this
|
|
repository, not only Codex.
|
|
|
|
By default, create a commit after completing each coherent unit of work, using a
|
|
concise, plain-English message describing what changed. This policy is standing
|
|
authorization to create those local commits; a separate user request is not
|
|
required. An explicit user instruction to leave work uncommitted takes precedence.
|
|
|
|
A unit of work is a focused, reviewable outcome, including its relevant tests and
|
|
documentation. Do not commit after every intermediate edit or create empty commits.
|
|
Complete the appropriate validation before committing. If work is incomplete or
|
|
validation is blocked, report that state rather than presenting it as completed.
|
|
|
|
Before committing:
|
|
|
|
1. Run `git status --short` and review the relevant diff, including any staged
|
|
changes. Identify changes that predate the current unit of work.
|
|
2. Exclude secrets, local environment files, generated junk, and unrelated changes.
|
|
3. Stage only the files or hunks belonging to the completed unit. Use `git add .`
|
|
only when every included change belongs to that unit. Do not disturb unrelated
|
|
staged or unstaged work.
|
|
4. Review `git diff --staged` and run appropriate checks for the change. Do not
|
|
repeat checks already passed for unchanged content merely to create a commit.
|
|
5. Review `git log --oneline -n 10` and use
|
|
`git commit -m "<concise plain-English commit message>"`.
|
|
6. Report the commit identifier and any remaining uncommitted work.
|
|
|
|
If the unit cannot be safely separated from pre-existing work, leave it uncommitted
|
|
and explain the overlap rather than silently including that work. If a commit
|
|
fails, preserve the changes and report the failure; do not bypass hooks.
|
|
|
|
Default commit authorization does not authorize pushing, publishing, amending,
|
|
resetting, reverting, or rewriting history. Those actions require a separate user
|
|
instruction. Do not use `git commit -a` or `git commit --no-verify` to bypass the
|
|
staging and validation discipline above.
|