Jean-Philippe Brule
697b36900b
- CLAUDE.md: universal development guidelines - README.md: project description (consistent template) - CONTRIBUTING.md: contribution workflow - CHANGELOG.md: version history Co-Authored-By: Svrnty Inc. <eng@svrnty.com>
80 lines
2.1 KiB
Markdown
80 lines
2.1 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
|
|
|
|
All AI-authored commits MUST use:
|
|
```
|
|
Co-Authored-By: Svrnty Inc. <eng@svrnty.com>
|
|
```
|
|
|
|
NEVER use third-party AI tool/company names in commits.
|
|
|
|
## 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
|
|
|
|
When changes span multiple repos:
|
|
1. Commit to each repo separately
|
|
2. Reference related repo in commit message
|
|
3. Run tests in each affected repo before commit
|