Skip to content
This repository was archived by the owner on Apr 11, 2026. It is now read-only.

Commit 778f42f

Browse files
z23ccclaude
z23cc
and
claude
committed
feat: add references/ directory with 4 universal checklists
Stack-agnostic reference checklists for testing patterns, security, performance, and code review. Adapted from agent-skills patterns. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 6f6c878 commit 778f42f

4 files changed

Lines changed: 470 additions & 0 deletions

File tree

‎references/code-review-checklist.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# Code Review Checklist
2+
3+
Quick reference for structured code review. Covers five axes: correctness, readability, architecture, security, and performance.
4+
5+
## Table of Contents
6+
7+
- [Before Reviewing](#before-reviewing)
8+
- [Correctness](#correctness)
9+
- [Readability](#readability)
10+
- [Architecture](#architecture)
11+
- [Security](#security)
12+
- [Performance](#performance)
13+
- [Testing](#testing)
14+
- [Review Communication](#review-communication)
15+
- [Common Review Anti-Patterns](#common-review-anti-patterns)
16+
17+
## Before Reviewing
18+
19+
- [ ] Understand the purpose (read PR description, linked issue, or spec)
20+
- [ ] Check the diff size (>400 lines = request split unless justified)
21+
- [ ] Run the code locally or verify CI passes
22+
- [ ] Review commits in logical order (not just the final diff)
23+
24+
## Correctness
25+
26+
- [ ] Logic matches stated requirements and acceptance criteria
27+
- [ ] Edge cases handled (empty inputs, nil/null, boundary values, overflow)
28+
- [ ] Error paths return appropriate errors (not silently swallowed)
29+
- [ ] Concurrent access is safe (race conditions, data races)
30+
- [ ] State transitions are valid (no impossible states representable)
31+
- [ ] Backward compatibility maintained (or breaking change documented)
32+
- [ ] Database migrations are reversible and safe for rollback
33+
34+
## Readability
35+
36+
- [ ] Names are descriptive and consistent with codebase conventions
37+
- [ ] Functions do one thing at one level of abstraction
38+
- [ ] No dead code, commented-out code, or TODO without issue reference
39+
- [ ] Complex logic has explanatory comments (why, not what)
40+
- [ ] Magic numbers replaced with named constants
41+
- [ ] Nesting depth <= 3 levels (extract functions or early-return)
42+
- [ ] File length reasonable (<300 lines, split if larger)
43+
- [ ] Public API has documentation (function signatures, types, constraints)
44+
45+
## Architecture
46+
47+
- [ ] Change is in the right layer (not business logic in HTTP handler)
48+
- [ ] No unnecessary coupling between modules
49+
- [ ] Dependency direction follows architecture (no upward dependencies)
50+
- [ ] Abstractions are justified (no premature generalization)
51+
- [ ] Existing patterns followed (or deviation justified in PR description)
52+
- [ ] No duplication that should be extracted (DRY at module boundaries)
53+
- [ ] Configuration is externalized (not hardcoded values)
54+
- [ ] New dependencies justified and minimal
55+
56+
## Security
57+
58+
- [ ] User input validated at system boundaries
59+
- [ ] No secrets, tokens, or credentials in code
60+
- [ ] SQL/command injection prevented (parameterized queries, no shell interpolation)
61+
- [ ] Authorization checked on every resource access
62+
- [ ] Sensitive data not logged or exposed in error responses
63+
- [ ] File paths validated (no path traversal)
64+
- [ ] Deserialization is type-restricted (no arbitrary object creation)
65+
66+
## Performance
67+
68+
- [ ] No N+1 queries or unbounded fetches
69+
- [ ] Algorithmic complexity appropriate for expected data size
70+
- [ ] No unnecessary allocations in hot paths
71+
- [ ] Database queries use indexes (check query plan for new queries)
72+
- [ ] Caching has eviction strategy and bounded size
73+
- [ ] No blocking I/O in async contexts
74+
- [ ] Pagination used for list endpoints
75+
76+
## Testing
77+
78+
- [ ] New code has tests (unit and/or integration as appropriate)
79+
- [ ] Tests cover happy path AND error/edge cases
80+
- [ ] Tests are deterministic (no flaky time/order dependencies)
81+
- [ ] Test names describe behavior, not implementation
82+
- [ ] Mocks are at boundaries only (not testing internal wiring)
83+
- [ ] Existing tests updated if behavior changed
84+
- [ ] No test-only code paths in production code
85+
86+
## Review Communication
87+
88+
- [ ] Comments are specific and actionable ("rename X to Y" not "this is confusing")
89+
- [ ] Distinguish blocking issues from suggestions (prefix: "nit:", "suggestion:", "blocking:")
90+
- [ ] Ask questions before assuming intent ("Is this intentional?" not "This is wrong")
91+
- [ ] Praise good patterns when you see them
92+
- [ ] Limit review rounds (aim for <=2 rounds before approval)
93+
94+
## Common Review Anti-Patterns
95+
96+
| Anti-Pattern | Problem | Better Approach |
97+
|---|---|---|
98+
| Rubber-stamping | Bugs and debt slip through | Review every diff, even small ones |
99+
| Style nitpicking only | Misses logic and design bugs | Use linters for style, review for logic |
100+
| Blocking on preference | Stalls velocity without quality gain | Approve with suggestion, not block |
101+
| Reviewing without running | Misses runtime issues | Run locally or check CI output |
102+
| Rewriting in review | Demoralizing, scope creep | Suggest direction, let author implement |
103+
| Ignoring test quality | Tests pass but don't verify anything | Review tests as carefully as production code |
104+
| Delayed reviews (>24h) | Blocks author, context decays | Review within 4 hours during work hours |
105+
| Drive-by partial review | Author thinks it's approved | Review entire PR or say what you skipped |

‎references/performance-checklist.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# Performance Checklist
2+
3+
Quick reference for application performance. Stack-agnostic — covers backend, CLI, and system-level patterns.
4+
5+
## Table of Contents
6+
7+
- [Measurement First](#measurement-first)
8+
- [Algorithmic Efficiency](#algorithmic-efficiency)
9+
- [Memory Management](#memory-management)
10+
- [Concurrency](#concurrency)
11+
- [Database Performance](#database-performance)
12+
- [Network and I/O](#network-and-io)
13+
- [Caching](#caching)
14+
- [Build and Deploy](#build-and-deploy)
15+
- [Common Anti-Patterns](#common-anti-patterns)
16+
17+
## Measurement First
18+
19+
- [ ] Performance targets defined before optimizing (latency p50/p95/p99, throughput)
20+
- [ ] Benchmarks exist for hot paths (reproducible, tracked in CI)
21+
- [ ] Profiler used before guessing bottleneck location
22+
- [ ] Before/after measurements accompany every optimization PR
23+
24+
| Language | Profiler | Benchmark Tool |
25+
|----------|---------|---------------|
26+
| Rust | `perf`, `flamegraph`, `cargo-flamegraph` | `criterion`, `#[bench]` |
27+
| Python | `cProfile`, `py-spy` | `pytest-benchmark`, `timeit` |
28+
| Go | `pprof` (built-in) | `testing.B` (built-in) |
29+
| TypeScript | Chrome DevTools, `clinic.js` | `vitest bench`, `tinybench` |
30+
31+
## Algorithmic Efficiency
32+
33+
- [ ] Hot-path algorithms are appropriate complexity (no O(n^2) where O(n log n) works)
34+
- [ ] Data structures match access patterns (hashmap for lookup, sorted array for range)
35+
- [ ] No redundant computation in loops (hoist invariants out)
36+
- [ ] String concatenation in loops uses builder/buffer pattern
37+
- [ ] Sorting uses appropriate algorithm for data characteristics
38+
39+
## Memory Management
40+
41+
- [ ] No unbounded growth (buffers, caches, queues have size limits)
42+
- [ ] Large allocations reuse buffers where possible
43+
- [ ] Streaming used for large data (not loading entire files into memory)
44+
- [ ] Object pools used for frequently allocated/freed objects in hot paths
45+
- [ ] Memory leaks checked (event listeners, timers, closures holding references)
46+
47+
| Language | Leak Detection |
48+
|----------|---------------|
49+
| Rust | `valgrind`, `miri`, ownership system prevents most leaks |
50+
| Python | `tracemalloc`, `objgraph` |
51+
| Go | `pprof heap`, `runtime.MemStats` |
52+
| TypeScript | Chrome DevTools heap snapshot, `--inspect` |
53+
54+
## Concurrency
55+
56+
- [ ] I/O-bound work uses async/non-blocking patterns
57+
- [ ] CPU-bound work parallelized across cores where beneficial
58+
- [ ] Shared state minimized; prefer message passing or immutable data
59+
- [ ] Lock granularity appropriate (no global locks in hot paths)
60+
- [ ] Connection pools sized for expected concurrency
61+
- [ ] Backpressure implemented for producer-consumer patterns
62+
63+
## Database Performance
64+
65+
- [ ] No N+1 query patterns (use joins, batch loading, or eager loading)
66+
- [ ] Queries have appropriate indexes (check query plans)
67+
- [ ] List endpoints paginated (never unbounded SELECT)
68+
- [ ] Connection pooling configured and sized
69+
- [ ] Slow query logging enabled (identify regressions)
70+
- [ ] Bulk operations used instead of row-by-row inserts/updates
71+
- [ ] Read replicas used for read-heavy workloads (if applicable)
72+
- [ ] Transactions held for minimum duration
73+
74+
## Network and I/O
75+
76+
- [ ] API response times < 200ms (p95 target)
77+
- [ ] Response compression enabled (gzip/brotli)
78+
- [ ] Batch APIs available for multi-resource operations
79+
- [ ] No synchronous blocking in async handlers
80+
- [ ] File I/O uses buffered readers/writers
81+
- [ ] DNS and connection reuse via keep-alive / connection pooling
82+
- [ ] Timeouts set on all outbound calls (prevent hanging)
83+
84+
## Caching
85+
86+
- [ ] Cache invalidation strategy defined (TTL, event-based, or versioned keys)
87+
- [ ] Cache hit rate monitored (< 80% hit rate = review strategy)
88+
- [ ] Hot data cached close to consumer (in-process > local > distributed)
89+
- [ ] Cache stampede protection (singleflight, probabilistic early expiry)
90+
- [ ] Cache size bounded (LRU or similar eviction policy)
91+
- [ ] Cached data has freshness expectations documented
92+
93+
## Build and Deploy
94+
95+
- [ ] Release builds use full optimizations (not debug builds in prod)
96+
- [ ] Binary size minimized (strip symbols, LTO where appropriate)
97+
- [ ] Startup time measured and optimized (lazy initialization)
98+
- [ ] Health check endpoints respond quickly (no heavy initialization)
99+
- [ ] Graceful shutdown drains in-flight requests
100+
101+
## Common Anti-Patterns
102+
103+
| Anti-Pattern | Impact | Fix |
104+
|---|---|---|
105+
| N+1 queries | Linear DB load growth | Use joins or batch loading |
106+
| Unbounded queries | Memory exhaustion, timeouts | Always paginate, add LIMIT |
107+
| Missing indexes | Slow reads as data grows | Add indexes for filtered/sorted columns |
108+
| Premature optimization | Wasted effort, worse readability | Profile first, optimize measured bottlenecks |
109+
| Global locks in hot paths | Serialized throughput | Fine-grained locks or lock-free structures |
110+
| Allocating in tight loops | GC pressure, cache thrashing | Pre-allocate, reuse buffers |
111+
| Synchronous I/O in async code | Thread starvation | Use async I/O or spawn blocking tasks |
112+
| No timeouts on network calls | Resource exhaustion on failure | Set timeouts on every outbound call |
113+
| Caching without eviction | Unbounded memory growth | Set max size with LRU eviction |
114+
| Logging in hot paths | I/O bottleneck | Sample or batch log writes |

‎references/security-checklist.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# Security Checklist
2+
3+
Quick reference for application security. Stack-agnostic — applies to Rust, Python, Go, TypeScript, and beyond.
4+
5+
## Table of Contents
6+
7+
- [Pre-Commit Checks](#pre-commit-checks)
8+
- [Authentication](#authentication)
9+
- [Authorization](#authorization)
10+
- [Input Validation](#input-validation)
11+
- [Cryptography](#cryptography)
12+
- [Data Protection](#data-protection)
13+
- [Dependency Security](#dependency-security)
14+
- [Error Handling](#error-handling)
15+
- [Infrastructure](#infrastructure)
16+
- [OWASP Top 10 Quick Reference](#owasp-top-10-quick-reference)
17+
18+
## Pre-Commit Checks
19+
20+
- [ ] No secrets in code (passwords, API keys, tokens, private keys)
21+
- [ ] `.gitignore` covers: `.env`, `*.pem`, `*.key`, `credentials.*`
22+
- [ ] `.env.example` uses placeholder values only
23+
- [ ] No hardcoded connection strings or endpoints
24+
- [ ] Secret scanning enabled in CI (e.g., `gitleaks`, `trufflehog`)
25+
26+
## Authentication
27+
28+
- [ ] Passwords hashed with bcrypt (>=12 rounds), scrypt, or argon2
29+
- [ ] Session tokens are cryptographically random (>=256 bits)
30+
- [ ] Session expiration configured with reasonable max-age
31+
- [ ] Rate limiting on login endpoints (<=10 attempts per 15 minutes)
32+
- [ ] Password reset tokens: time-limited (<=1 hour), single-use
33+
- [ ] Account lockout after repeated failures (with notification)
34+
- [ ] MFA supported for sensitive operations
35+
36+
## Authorization
37+
38+
- [ ] Every protected endpoint checks authentication first
39+
- [ ] Every resource access checks ownership or role (prevents IDOR)
40+
- [ ] Admin endpoints require admin role verification
41+
- [ ] API keys/tokens scoped to minimum necessary permissions
42+
- [ ] JWT tokens validated: signature, expiration, issuer, audience
43+
- [ ] Default deny: new endpoints are protected unless explicitly public
44+
- [ ] Service-to-service calls authenticated (mTLS, signed tokens)
45+
46+
## Input Validation
47+
48+
- [ ] All user input validated at system boundaries
49+
- [ ] Validation uses allowlists, not denylists
50+
- [ ] String lengths constrained (min/max)
51+
- [ ] Numeric ranges validated and bounds-checked
52+
- [ ] File uploads: type restricted, size limited, content verified
53+
- [ ] SQL queries parameterized (no string concatenation)
54+
- [ ] Output encoded/escaped for context (HTML, SQL, shell, URLs)
55+
- [ ] URLs validated before redirect (prevent open redirect)
56+
- [ ] Deserialization restricted to expected types (no arbitrary object creation)
57+
58+
## Cryptography
59+
60+
- [ ] TLS 1.2+ for all network communication
61+
- [ ] No custom crypto implementations (use audited libraries)
62+
- [ ] Symmetric encryption: AES-256-GCM or ChaCha20-Poly1305
63+
- [ ] Asymmetric: RSA >=2048 bits or Ed25519
64+
- [ ] Random values from CSPRNG, not `rand()` or `Math.random()`
65+
- [ ] Keys rotated on schedule and on compromise
66+
67+
| Language | Crypto Library | CSPRNG |
68+
|----------|---------------|--------|
69+
| Rust | `ring`, `rustls` | `rand::rngs::OsRng` |
70+
| Python | `cryptography` | `secrets` module |
71+
| Go | `crypto/*` stdlib | `crypto/rand` |
72+
| TypeScript | `crypto` (Node) | `crypto.randomBytes` |
73+
74+
## Data Protection
75+
76+
- [ ] Sensitive fields excluded from API responses (password hashes, tokens)
77+
- [ ] Sensitive data not logged (passwords, tokens, PII)
78+
- [ ] PII encrypted at rest (if required by regulation)
79+
- [ ] Database backups encrypted
80+
- [ ] Data retention policy defined and enforced
81+
- [ ] Personally identifiable data deletable on request
82+
83+
## Dependency Security
84+
85+
- [ ] Dependencies audited regularly for known vulnerabilities
86+
- [ ] Lockfile committed and used in CI (reproducible builds)
87+
- [ ] Automated alerts for vulnerable dependencies enabled
88+
- [ ] Minimal dependency policy (fewer deps = smaller attack surface)
89+
90+
| Language | Audit Command |
91+
|----------|--------------|
92+
| Rust | `cargo audit` |
93+
| Python | `pip-audit`, `safety check` |
94+
| Go | `govulncheck ./...` |
95+
| TypeScript | `npm audit`, `yarn audit` |
96+
97+
## Error Handling
98+
99+
- [ ] Production errors are generic (no stack traces, SQL, or internals)
100+
- [ ] Errors logged server-side with correlation IDs
101+
- [ ] Error messages do not reveal user existence (login/signup)
102+
- [ ] Panic/crash recovery does not expose sensitive state
103+
- [ ] Rate-limited error responses (prevent enumeration attacks)
104+
105+
## Infrastructure
106+
107+
- [ ] HTTPS enforced (redirect HTTP to HTTPS)
108+
- [ ] Security headers set (CSP, HSTS, X-Content-Type-Options, X-Frame-Options)
109+
- [ ] CORS restricted to known origins (never `*` in production)
110+
- [ ] Containers run as non-root user
111+
- [ ] Network segmentation between services and databases
112+
- [ ] Secrets managed via vault/KMS, not environment variables in code
113+
114+
## OWASP Top 10 Quick Reference
115+
116+
| # | Vulnerability | Prevention |
117+
|---|---|---|
118+
| 1 | Broken Access Control | Auth checks on every endpoint, ownership verification |
119+
| 2 | Cryptographic Failures | HTTPS, strong hashing, no secrets in code |
120+
| 3 | Injection | Parameterized queries, input validation |
121+
| 4 | Insecure Design | Threat modeling, spec-driven development |
122+
| 5 | Security Misconfiguration | Security headers, minimal permissions, audit deps |
123+
| 6 | Vulnerable Components | Audit deps, keep updated, minimize dependencies |
124+
| 7 | Auth Failures | Strong passwords, rate limiting, session management |
125+
| 8 | Data Integrity Failures | Verify updates/dependencies, signed artifacts |
126+
| 9 | Logging Failures | Log security events, don't log secrets |
127+
| 10 | SSRF | Validate/allowlist URLs, restrict outbound requests |

0 commit comments

Comments
 (0)