petere
b8b2ba8da1
Add project configuration, documentation and development tooling: - flake.nix dev shell with Go, golangci-lint, turbojpeg - .envrc sourcing sops-encrypted .secrets.env - golangci-lint v2 config - opencode.json MCP + LSP wiring - AGENTS.md development guidelines
45 lines
2.4 KiB
Markdown
45 lines
2.4 KiB
Markdown
# AGENTS.md
|
|
|
|
Development guidelines for all agents and contributors working in this repository.
|
|
|
|
## Core Development Principles
|
|
|
|
1. **Do not repeat yourself (DRY)** - All development must avoid code duplication. Extract shared logic into reusable functions, modules, or components.
|
|
2. **Language best practices** - All development must follow the idiomatic style and best practices for the chosen language.
|
|
3. **Well-commented code** - All development must be clearly commented so that someone new to the project can understand the intent and flow of the code.
|
|
|
|
## Git Workflow
|
|
|
|
1. **Test before commit** - Changes must be tested locally before they are committed. Do not commit broken or untested code.
|
|
2. **No remote push without confirmation** - Changes are committed locally only. Nothing is pushed to the remote repository until explicitly confirmed by the user.
|
|
3. **Small atomic commits** - Keep commits focused. One logical change per commit. Do not bundle unrelated changes.
|
|
4. **Run the linter before committing** - Always run the project's linting and formatting checks before creating a commit. Fix any warnings or errors.
|
|
5. **Failing builds never merge** - No change that breaks the build, tests, or linting may be merged or pushed.
|
|
|
|
### Commit Messages
|
|
|
|
Use [Conventional Commits](https://www.conventionalcommits.org/) format:
|
|
|
|
```
|
|
feat: add user authentication
|
|
fix: resolve race condition in queue
|
|
refactor: extract validation logic
|
|
docs: update setup instructions
|
|
test: add unit tests for teleport fling
|
|
```
|
|
|
|
Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`. Optionally include a scope: `feat(auth): ...`.
|
|
|
|
## Testing
|
|
|
|
1. **Test-first development** - Write tests alongside new features. Test coverage should reflect the functionality being added or changed.
|
|
2. **Full suite before commit** - Run the complete test suite (not just incremental tests) before committing to ensure nothing is broken.
|
|
|
|
## Security
|
|
|
|
1. **Never commit secrets** - No API keys, passwords, tokens, connection strings, or credentials of any kind in code, config files, or git history. Use environment variables or secret management tools.
|
|
2. **Review `.gitignore`** - Ensure files containing potential secrets are excluded from version control.
|
|
|
|
## Documentation
|
|
|
|
1. **Keep docs in sync** - Update relevant documentation (README, comments, examples) alongside any behavioral change. Documentation that describes outdated behavior is a bug. |