mirror of
https://github.com/itme-brain/agent-team.git
synced 2026-03-23 12:09:44 -04:00
79 lines
3.9 KiB
Markdown
79 lines
3.9 KiB
Markdown
---
|
|
name: conventions
|
|
description: Core coding conventions and quality priorities for all projects.
|
|
---
|
|
|
|
## Quality priorities (in order)
|
|
|
|
1. **Documentation** — dual documentation strategy:
|
|
- **Inline:** comments next to code explaining what it does
|
|
- **External:** markdown files suitable for mdbook. Every module/component gets a corresponding `.md` doc covering purpose, usage, and design decisions.
|
|
- **READMEs:** each major directory gets a README explaining why it exists and what it contains
|
|
- **Exception:** helper/utility functions only need inline docs, not external docs
|
|
2. **Maintainability** — code is easy to read, modify, and debug. Favor clarity over cleverness.
|
|
3. **Reusability** — extract shared logic into well-defined interfaces. Don't duplicate. Helper functions specifically should be easy to cleanly isolate for reuse across the codebase.
|
|
4. **Modularity** — clean separation of duties and logic. Each file/module should have a *cohesive* purpose — not necessarily a single purpose, but a group of related responsibilities that belong together. Avoid both god files and excessive fragmentation.
|
|
|
|
## Naming
|
|
|
|
- Default to `snake_case` unless the language has a stronger convention (e.g., `camelCase` in JavaScript, `PascalCase` for C++ classes)
|
|
- Language-specific formats take precedence over personal preference
|
|
- Names should be descriptive — no abbreviations unless universally understood
|
|
- No magic numbers — extract to named constants
|
|
|
|
## Commits
|
|
|
|
- Use conventional commit format: `type(scope): description`
|
|
- Types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `style`, `perf`
|
|
- Scope is optional but recommended (e.g., `feat(auth): add JWT middleware`)
|
|
- Description is imperative mood, lowercase, no period
|
|
- One logical change per commit — don't bundle unrelated changes
|
|
- Commit message body (optional) explains **why**, not what
|
|
|
|
## Error handling
|
|
|
|
- Return codes: `0` for success, non-zero for error
|
|
- Error messaging uses three verbosity tiers:
|
|
- **Default:** concise, user-facing message (what went wrong)
|
|
- **Verbose:** adds context (where it went wrong, what was expected)
|
|
- **Debug:** full diagnostic detail (stack traces, variable state, internal IDs)
|
|
- Propagate errors explicitly — don't silently swallow failures
|
|
- Match the project's existing error patterns before introducing new ones
|
|
|
|
## Logging
|
|
|
|
- Follow the same verbosity tiers as error messaging (default/verbose/debug)
|
|
- Log at boundaries: entry/exit of major operations, external calls, state transitions
|
|
- Never log secrets, credentials, or sensitive user data
|
|
|
|
## Testing
|
|
|
|
- New functionality gets tests. Bug fixes get regression tests.
|
|
- Tests should be independent — no shared mutable state between test cases
|
|
- Test the interface, not the implementation — tests shouldn't break on internal refactors
|
|
- Name tests to describe the behavior being verified, not the function being called
|
|
|
|
## Interface design
|
|
|
|
- Public APIs should be stable — think before exposing. Easy to extend, hard to break.
|
|
- Internal interfaces can evolve freely — don't over-engineer internal boundaries
|
|
- Validate at system boundaries (user input, external APIs, IPC). Trust internal code.
|
|
|
|
## Security
|
|
|
|
- Never trust external input — validate and sanitize at system boundaries
|
|
- No hardcoded secrets, credentials, or keys
|
|
- Prefer established libraries over hand-rolled crypto, auth, or parsing
|
|
|
|
## File organization
|
|
|
|
- Directory hierarchy should make ownership and dependencies obvious
|
|
- Each major directory gets a README explaining its purpose
|
|
- If you can't tell what a directory contains from its path, reorganize
|
|
- Group related functionality cohesively — don't fragment for the sake of "single responsibility"
|
|
|
|
## General
|
|
|
|
- Clean separation of duties — no god files, no mixed concerns
|
|
- Read existing code before writing new code — match the project's patterns
|
|
- Minimize external dependencies — vendor what you use, track versions
|