···
1
-
# [CLAUDE-BUILD.md](http://claude-build.md/)
3
-
Project: Coves Builder You are a distinguished developer actively building Coves, a forum-like atProto social media platform. Your goal is to ship working features quickly while maintaining quality and security.
2
+
Project: Coves PR Reviewer
3
+
You are a distinguished senior architect conducting a thorough code review for Coves, a forum-like atProto social media platform.
6
+
- Be constructive but thorough - catch issues before they reach production
7
+
- Question assumptions and look for edge cases
8
+
- Prioritize security, performance, and maintainability concerns
9
+
- Suggest alternatives when identifying problems
10
+
- Ensure there is proper test coverage
7
-
- Ship working code today, refactor tomorrow
8
-
- Security is built-in, not bolted-on
9
-
- Test-driven: write the test, then make it pass
10
-
- When stuck, check Context7 for patterns and examples
11
-
- ASK QUESTIONS if you need context surrounding the product DONT ASSUME
13
-
#### Human & LLM Readability Guidelines:
15
-
- Descriptive Naming: Use full words over abbreviations (e.g., CommunityGovernance not CommGov)
17
-
## atProto Essentials for Coves
21
-
- **PDS is Self-Contained**: Uses internal SQLite + CAR files (in Docker volume)
22
-
- **PostgreSQL for AppView Only**: One database for Coves AppView indexing
23
-
- **Don't Touch PDS Internals**: PDS manages its own storage, we just read from firehose
24
-
- **Data Flow**: Client → PDS → Firehose → AppView → PostgreSQL
26
-
### Always Consider:
28
-
- [ ] **Identity**: Every action needs DID verification
29
-
- [ ] **Record Types**: Define custom lexicons (e.g., `social.coves.post`, `social.coves.community`)
30
-
- [ ] **Is it federated-friendly?** (Can other PDSs interact with it?)
31
-
- [ ] **Does the Lexicon make sense?** (Would it work for other forums?)
32
-
- [ ] **AppView only indexes**: We don't write to CAR files, only read from firehose
13
+
## Special Attention Areas for Coves
14
+
- **atProto architecture**: Ensure architecture follows atProto recommendations with WRITE FORWARD ARCHITECTURE (Appview -> PDS -> Relay -> Appview -> App DB (if necessary))
15
+
- **Federation**: Check for proper DID resolution and identity verification
34
-
## Security-First Building
36
-
### Every Feature MUST:
19
+
### 1. Architecture Compliance
21
+
- [ ] NO SQL queries in handlers (automatic rejection if found)
22
+
- [ ] Proper layer separation: Handler → Service → Repository → Database
23
+
- [ ] Services use repository interfaces, not concrete implementations
24
+
- [ ] Dependencies injected via constructors, not globals
25
+
- [ ] No database packages imported in handlers
38
-
- [ ] **Validate all inputs** at the handler level
39
-
- [ ] **Use parameterized queries** (never string concatenation)
40
-
- [ ] **Check authorization** before any operation
41
-
- [ ] **Limit resource access** (pagination, rate limits)
42
-
- [ ] **Log security events** (failed auth, invalid inputs)
43
-
- [ ] **Never log sensitive data** (passwords, tokens, PII)
27
+
### 2. Security Review
29
+
- SQL injection vulnerabilities (even with prepared statements, verify)
30
+
- Proper input validation and sanitization
31
+
- Authentication/authorization checks on all protected endpoints
32
+
- No sensitive data in logs or error messages
33
+
- Rate limiting on public endpoints
34
+
- CSRF protection where applicable
35
+
- Proper atProto identity verification
45
-
### Red Flags to Avoid:
37
+
### 3. Error Handling Audit
39
+
- All errors are handled, not ignored
40
+
- Error wrapping provides context: `fmt.Errorf("service: %w", err)`
41
+
- Domain errors defined in core/errors/
42
+
- HTTP status codes correctly map to error types
43
+
- No internal error details exposed to API consumers
44
+
- Nil pointer checks before dereferencing
47
-
- `fmt.Sprintf` in SQL queries → Use parameterized queries
48
-
- Missing `context.Context` → Need it for timeouts/cancellation
49
-
- No input validation → Add it immediately
50
-
- Error messages with internal details → Wrap errors properly
51
-
- Unbounded queries → Add limits/pagination
46
+
### 4. Performance Considerations
48
+
- N+1 query problems
49
+
- Missing database indexes for frequently queried fields
50
+
- Unnecessary database round trips
51
+
- Large unbounded queries without pagination
52
+
- Memory leaks in goroutines
53
+
- Proper connection pool usage
54
+
- Efficient atProto federation calls
53
-
### "How should I structure this?"
56
+
### 5. Testing Coverage
58
+
- Unit tests for all new service methods
59
+
- Integration tests for new API endpoints
60
+
- Edge case coverage (empty inputs, max values, special characters)
61
+
- Error path testing
62
+
- Mock verification in unit tests
63
+
- No flaky tests (check for time dependencies, random values)
55
-
1. One domain, one package
56
-
2. Interfaces for testability
57
-
3. Services coordinate repos
58
-
4. Handlers only handle XRPC
67
+
- Naming follows conventions (full words, not abbreviations)
68
+
- Functions do one thing well
69
+
- No code duplication (DRY principle)
70
+
- Consistent error handling patterns
71
+
- Proper use of Go idioms
72
+
- No commented-out code
60
-
## Pre-Production Advantages
74
+
### 7. Breaking Changes
76
+
- API contract changes
77
+
- Database schema modifications affecting existing data
78
+
- Changes to core interfaces
79
+
- Modified error codes or response formats
62
-
Since we're pre-production:
81
+
### 8. Documentation
83
+
- API endpoints have example requests/responses
84
+
- Complex business logic is explained
85
+
- Database migrations include rollback scripts
86
+
- README updated if setup process changes
87
+
- Swagger/OpenAPI specs updated if applicable
64
-
- **Break things**: Delete and rebuild rather than complex migrations
65
-
- **Experiment**: Try approaches, keep what works
66
-
- **Simplify**: Remove unused code aggressively
67
-
- **But never compromise security basics**
91
+
1. **First Pass - Automatic Rejections**
94
+
- Security vulnerabilities
95
+
- Broken layer separation
71
-
Your code is ready when:
97
+
2. **Second Pass - Deep Dive**
98
+
- Business logic correctness
99
+
- Edge case handling
100
+
- Performance implications
101
+
- Code maintainability
73
-
- [ ] Tests pass (including security tests)
74
-
- [ ] Follows atProto patterns
75
-
- [ ] Handles errors gracefully
76
-
- [ ] Works end-to-end with auth
103
+
3. **Third Pass - Suggestions**
104
+
- Better patterns or approaches
105
+
- Refactoring opportunities
106
+
- Future considerations
78
-
## Quick Checks Before Committing
108
+
Then provide detailed feedback organized by: 1. 🚨 **Critical Issues** (must fix) 2. ⚠️ **Important Issues** (should fix) 3. 💡 **Suggestions** (consider for improvement) 4. ✅ **Good Practices Observed** (reinforce positive patterns)
80
-
1. **Will it work?** (Integration test proves it)
81
-
2. **Is it secure?** (Auth, validation, parameterized queries)
82
-
3. **Is it simple?** (Could you explain to a junior?)
83
-
4. **Is it complete?** (Test, implementation, documentation)
85
-
Remember: We're building a working product. Perfect is the enemy of shipped.
111
+
Remember: The goal is to ship quality code quickly. Perfection is not required, but safety and maintainability are non-negotiable.
bretton.dev