89 lines
3.6 KiB
Markdown
89 lines
3.6 KiB
Markdown
# AGENTS.md
|
|
|
|
## Purpose
|
|
This file defines the default working agreement for AI coding agents and contributors in this repository.
|
|
|
|
## Documentation Language
|
|
Project language is English. All documentation, issues, pull requests, commit messages, and code comments should be written in English.
|
|
All newly created documentation in this project must be written in English.
|
|
All project documentation files must be stored under `docs/`, except `README.md` and `AGENTS.md`.
|
|
|
|
## Working Principles
|
|
1. Keep changes minimal and focused on the requested task.
|
|
2. Preserve existing public APIs unless a breaking change is explicitly requested.
|
|
3. Prefer clear, maintainable code over clever shortcuts.
|
|
4. Do not modify unrelated files.
|
|
5. Never add secrets, credentials, or tokens to the repository.
|
|
|
|
## Testing Expectations
|
|
1. Add or update tests for behavior changes.
|
|
2. Keep tests deterministic and fast.
|
|
3. Prefer table-driven tests where they improve readability.
|
|
4. Run relevant tests locally before finishing changes.
|
|
5. For Go projects, use `github.com/smartystreets/goconvey` as the standard test library.
|
|
|
|
## Build Artifacts and Reports
|
|
1. Builder logs and generated reports must be created under `.build/`.
|
|
2. The `.build/` directory must be excluded from version control via `.gitignore`.
|
|
|
|
## Git and Script Standards
|
|
1. Shell scripts (`*.sh`) must use LF line endings.
|
|
2. Shell scripts committed to the repository must be executable in Git index (mode `100755`).
|
|
3. When adding a new shell script, set execute permissions before commit: `git add --chmod=+x path/to/script.sh`.
|
|
|
|
## Git Bash Execution Defaults
|
|
1. Repository maintenance scripts are executed with Git Bash shell on Windows.
|
|
2. Default repository root is `~/git`.
|
|
3. The repository root can be overridden via `GO_GIT_ROOT`.
|
|
4. The standards repository defaults to `$ROOT_PATH/project-standards`.
|
|
5. The standards repository path can be overridden via `GO_PROJECT_STANDARDS`.
|
|
|
|
## Definition of Done (DoD)
|
|
|
|
### Purpose
|
|
The Definition of Done defines the minimum quality bar for every completed change in this repository.
|
|
|
|
### Mandatory Criteria
|
|
1. Tests
|
|
- Every code change is covered by tests where applicable.
|
|
- New functionality includes new tests.
|
|
- Bug fixes include at least one regression test.
|
|
- For Go projects, tests use `github.com/smartystreets/goconvey`.
|
|
- Automated test coverage is at least 80%.
|
|
|
|
1. Functional documentation
|
|
- Implemented functionality is documented.
|
|
- Public API-relevant changes are reflected in README and/or docs.
|
|
|
|
1. Documentation standards
|
|
- Documentation is written in English.
|
|
- Documentation files are placed under `docs/`.
|
|
- Exceptions: `README.md` and `AGENTS.md` remain at repository root.
|
|
|
|
### Technical Completion Criteria
|
|
1. Build and test status
|
|
- The project builds successfully.
|
|
- Relevant test commands run successfully.
|
|
|
|
1. No unresolved critical issues
|
|
- No new blocking errors are introduced.
|
|
- Known non-blocking warnings are acceptable only if unrelated to the change or documented.
|
|
|
|
1. SonarQube status
|
|
- No SonarQube errors are present.
|
|
|
|
1. Documentation structure
|
|
- Links to moved or newly added docs are valid.
|
|
- Documentation structure remains consistent with project rules.
|
|
|
|
### Review Checklist (Quick)
|
|
- [ ] Change is implemented and meets acceptance criteria.
|
|
- [ ] Tests were added/updated and pass.
|
|
- [ ] Go tests use `github.com/smartystreets/goconvey`.
|
|
- [ ] Automated test coverage is at least 80%.
|
|
- [ ] Functionality is documented.
|
|
- [ ] Documentation is in English.
|
|
- [ ] Documentation is located under `docs/` (except `README.md` and `AGENTS.md`).
|
|
- [ ] No SonarQube errors are present.
|
|
- [ ] No critical regressions found.
|