100 lines
2.7 KiB
Markdown
100 lines
2.7 KiB
Markdown
# Development Guidelines
|
|
|
|
Universal development practices for all Svrnty/a-gent repositories.
|
|
|
|
## Engineering Principles
|
|
|
|
### KISS (Keep It Simple)
|
|
- Prefer straightforward control flow over clever meta-programming
|
|
- Keep error paths obvious and localized
|
|
|
|
### YAGNI (You Aren't Gonna Need It)
|
|
- Do not add features without concrete accepted use case
|
|
- Do not introduce speculative abstractions
|
|
|
|
### DRY + Rule of Three
|
|
- Duplicate small logic when it preserves clarity
|
|
- Extract shared utilities only after 3+ repeated patterns
|
|
|
|
### SRP + ISP (Single Responsibility + Interface Segregation)
|
|
- Keep each module focused on one concern
|
|
- Avoid "god modules" mixing multiple responsibilities
|
|
|
|
### Fail Fast + Explicit Errors
|
|
- Prefer explicit errors for unsupported states
|
|
- Document fallback behavior when intentional
|
|
|
|
### Secure by Default
|
|
- Deny-by-default for access boundaries
|
|
- Never log secrets or sensitive payloads
|
|
|
|
## Agent Workflow
|
|
|
|
1. **Read before write** - Inspect existing code before editing
|
|
2. **Define scope** - One concern per PR
|
|
3. **Implement minimal patch** - Apply KISS/YAGNI explicitly
|
|
4. **Validate** - Run lint, format, test before commit
|
|
5. **Document impact** - Note behavior changes and risks
|
|
|
|
## Branch Strategy
|
|
|
|
- All repos use `JP` branch for active development
|
|
- Always verify current branch before committing
|
|
|
|
## Commit Rules
|
|
|
|
### Allowed Authors
|
|
Only these emails are permitted for commits:
|
|
- `jp@svrnty.io` (Jean-Philippe Brule)
|
|
- `mathias@svrnty.io` (Mathias Beaulieu-Duncan)
|
|
|
|
Configure with: `git config user.email jp@svrnty.io`
|
|
|
|
### AI-Assisted Commits
|
|
All AI-authored commits MUST include:
|
|
```
|
|
Co-Authored-By: Svrnty Inc. <jp@svrnty.io>
|
|
```
|
|
|
|
NEVER use third-party AI tool/company names in commits.
|
|
|
|
### Git Hooks Setup
|
|
Install lefthook to enforce commit standards:
|
|
```bash
|
|
brew install lefthook
|
|
lefthook install
|
|
```
|
|
|
|
The hooks automatically:
|
|
- Validate author email is in allowed list
|
|
- Append Co-Authored-By footer
|
|
- Warn on conventional commit format violations
|
|
|
|
## PR Discipline
|
|
|
|
- Clear, scoped commit messages
|
|
- Small PRs preferred
|
|
- Never commit personal/sensitive data
|
|
- Reference related repos for cross-repo changes
|
|
|
|
## Validation
|
|
|
|
Run before every commit:
|
|
- Format check (language-specific)
|
|
- Lint check (language-specific)
|
|
- Test suite
|
|
|
|
## Anti-Patterns
|
|
|
|
- Do NOT add heavy dependencies for minor convenience
|
|
- Do NOT mix formatting-only with functional changes
|
|
- Do NOT modify unrelated modules "while here"
|
|
- Do NOT bypass failing checks without explanation
|
|
|
|
## Cross-Repo Changes
|
|
|
|
- Each repo is standalone with its own build configuration
|
|
- Reference related repos in commit messages for cross-repo changes
|
|
- Coordinate multi-repo changes via matching branch names
|
|
- Test each repo independently before pushing
|