Agent Operating Protocol
Operating protocol
Before making a non-trivial change, an AI agent should:
- Understand the user's actual intent.
- Inspect the existing implementation.
- Read relevant project documentation.
- Review architecture invariants and relevant ADRs (Architecture Governance).
- Check the existing toolchain and project conventions.
- Prefer existing dependencies and patterns.
- Make the smallest complete change that solves the requirement.
- Avoid unrelated cleanup.
- Run relevant validation.
- Review the resulting diff.
- Confirm that no accidental files or unrelated changes were introduced.
- Explain significant architectural, dependency, security, or behavioral changes.
Do not rewrite working code merely because you prefer another style.
Do not add an abstraction just because similar code appears twice; add one only when it solves a real maintenance, correctness, or architecture problem.
Memory behavior
Agents with persistent memory should record that the project uses these guidelines.
Use memory to locate the relevant guidance. Treat repository files as the source of truth; they always take precedence over remembered rules or summaries.
During larger tasks, re-read the relevant guideline sections, especially:
- At the beginning of substantial project work
- Before architectural changes
- Before adding or replacing dependencies
- Before modifying CI/CD
- Before changing toolchain configuration
- Before changing UI language behavior
- When existing project conventions are unclear
- When remembered information conflicts with the repository
Never rely on a remembered summary when the repository has the current rule.
Hard rules quick reference
The following behaviors are prohibited. Each item links to the document that defines the rule; keep this list synchronized with those documents whenever a rule changes.
- Replace mandatory standardized tools without explicit user approval. (core-principles)
- Use npm or yarn instead of pnpm. (typescript)
- Use ESLint as the project linter instead of oxlint. (typescript)
- Use Prettier instead of oxfmt. (typescript)
- Use Pipenv or Poetry instead of uv. (python)
- Use flake8 or black instead of ruff. (python)
- Use pre-commit or Lefthook instead of prek. (quality-gates)
- Replace Cocogitto with another Conventional Commits validator without a reason and approval. (git)
- Ignore lint or validation problems without understanding them. (core-principles)
- Disable useful rules just to make checks pass. (core-principles)
- Over-engineer rapid validation projects. (core-principles)
- Introduce unnecessary dependencies. (dependencies)
- Create redundant files or modules. (coding-standards)
- Silently violate an ADR. (architecture-governance)
- Accidentally change architectural invariants. (architecture-governance)
- Use non-English identifiers or comments in source code. (language-policy)
- Use Japanese romaji or Chinese pinyin as code identifiers. (language-policy)
- Infer UI language from conversation language. (language-policy)
- Produce low-quality literal translations in cross-language UI work. (language-policy)
- Upgrade GitHub Actions blindly, without reviewing compatibility. (github-actions)
- Commit secrets or sensitive information. (security)
- Force push shared history without approval. (git)
- Treat a green CI as proof that the implementation is correct. (change-discipline)
- Pin GitHub Actions to commit SHAs rather than current major-version tags, without a stated supply-chain policy. (github-actions)