a4e667de10
Single-commit clean baseline after security scrub of niche-tells, project codenames, internal jargon, and contributor-email leaks. Contents: - 100 Rust crates (_primitives/_rust/) - 37 agent manifests (_manifests/) + generated specs (_generated/) - 67 user-invocable skills (skills/) - 33 hooks (hooks/) - Composition blocks (_blocks/) - Documentation (docs/, README.md) - TS adapter packages (_ts_packages/) - Assembler (_assembler/) - Roles (_roles/) - Templates (_templates/) - Forgejo CI (.forgejo/) Author: Denis Parfionovich <info@greendragon.info> License: see LICENSE.
106 lines
3.8 KiB
Markdown
106 lines
3.8 KiB
Markdown
# Pre-Implementation Architecture Checklist
|
|
|
|
## Run BEFORE writing any code
|
|
|
|
### 1. Requirements Clarity
|
|
- [ ] What EXACTLY should this do? (not vague "improve X")
|
|
- [ ] What are the inputs and outputs?
|
|
- [ ] What are the edge cases?
|
|
- [ ] What happens on failure?
|
|
- [ ] What are the performance requirements?
|
|
|
|
### 2. Existing Code Check
|
|
- [ ] Does similar functionality already exist in codebase?
|
|
- [ ] Can existing code be extended instead of writing new?
|
|
- [ ] What patterns does the codebase already use?
|
|
- [ ] What conventions must be followed?
|
|
|
|
### 3. Duplication Prevention
|
|
- [ ] Search codebase for similar patterns (grep, find)
|
|
- [ ] Check shared/ and lib/ for reusable utilities
|
|
- [ ] If creating new utility — will 2+ modules use it?
|
|
- [ ] If yes → put in shared/. If no → keep local
|
|
|
|
### 4. Dependency Direction
|
|
- [ ] Draw dependency arrows — do they point inward (clean)?
|
|
- [ ] No circular dependencies?
|
|
- [ ] Upper layers don't know about lower layer implementation?
|
|
- [ ] Domain logic has ZERO framework imports?
|
|
|
|
### 5. Pattern Selection
|
|
- [ ] Consult patterns.md — which pattern fits?
|
|
- [ ] Is the pattern justified by complexity? (don't over-engineer)
|
|
- [ ] Does the codebase already use this pattern?
|
|
- [ ] If new pattern — is it worth the learning curve for team?
|
|
|
|
### 6. Stack Compatibility
|
|
- [ ] Check stack-compat.md for version constraints
|
|
- [ ] No anti-compatible combinations?
|
|
- [ ] New dependency needed? Check bundle size, maintenance status, license
|
|
- [ ] Prefer stdlib/existing deps over new packages
|
|
|
|
### 7. Security
|
|
- [ ] Input validation at system boundaries
|
|
- [ ] SQL/NoSQL injection prevention (parameterized queries)
|
|
- [ ] XSS prevention (sanitize output)
|
|
- [ ] Auth/authz checks on all endpoints
|
|
- [ ] No secrets in code (use env vars)
|
|
- [ ] No internal IDs exposed in public APIs
|
|
|
|
### 8. Data Flow
|
|
- [ ] Where does data enter the system?
|
|
- [ ] How is it validated and transformed?
|
|
- [ ] Where is it stored?
|
|
- [ ] How is it retrieved and presented?
|
|
- [ ] What happens to stale/expired data?
|
|
|
|
### 9. Error Handling Strategy
|
|
- [ ] What errors are expected? (user input, network, DB)
|
|
- [ ] What errors are unexpected? (bugs)
|
|
- [ ] Error response format consistent with existing API?
|
|
- [ ] Errors logged with enough context to debug?
|
|
- [ ] No swallowed errors (empty catch blocks)
|
|
|
|
### 10. Testability
|
|
- [ ] Can each component be tested in isolation?
|
|
- [ ] Dependencies injectable (not hardcoded)?
|
|
- [ ] Side effects isolated (DB, network, filesystem)?
|
|
- [ ] Happy path + edge cases + error cases covered?
|
|
|
|
## Run AFTER writing code
|
|
|
|
### 11. Post-Implementation Review
|
|
- [ ] Re-check duplication — did I create any new duplicates?
|
|
- [ ] Anti-pattern scan (see antipatterns.md)
|
|
- [ ] All functions < 50 lines? (extract if not)
|
|
- [ ] All files < 300 lines? (split if not)
|
|
- [ ] Cyclomatic complexity < 10 per function?
|
|
- [ ] No dead code left behind
|
|
- [ ] No commented-out code
|
|
- [ ] No TODO/FIXME without ticket reference
|
|
|
|
### 12. Performance Basics
|
|
- [ ] No N+1 queries (check ORM calls in loops)
|
|
- [ ] Indexes on queried columns
|
|
- [ ] No blocking I/O in async paths
|
|
- [ ] Large lists paginated
|
|
- [ ] Heavy operations use queue (not request handler)
|
|
|
|
### 13. Deploy Readiness
|
|
- [ ] Check error-patterns.json for recurring issues
|
|
- [ ] Environment variables documented
|
|
- [ ] Database migrations created and tested
|
|
- [ ] Rollback plan if deploy fails
|
|
- [ ] Health check endpoint works
|
|
|
|
## Complexity Budget
|
|
|
|
| Metric | Green | Yellow | Red |
|
|
|--------|-------|--------|-----|
|
|
| Function length | < 30 lines | 30-50 lines | > 50 lines |
|
|
| File length | < 200 lines | 200-300 lines | > 300 lines |
|
|
| Function params | 1-3 | 4-5 | > 5 (use object) |
|
|
| Nesting depth | 1-2 | 3 | > 3 (extract) |
|
|
| Cyclomatic complexity | 1-5 | 6-10 | > 10 (simplify) |
|
|
| Dependencies per module | 1-5 | 6-8 | > 8 (split module) |
|
|
| Test coverage | > 80% | 60-80% | < 60% |
|