@neyugn/agent-kits 0.5.0 → 0.5.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/README.md +66 -81
  2. package/README.vi.md +79 -52
  3. package/README.zh.md +69 -88
  4. package/common/skills/filter-agent/SKILL.md +33 -45
  5. package/common/skills/filter-skill/SKILL.md +51 -73
  6. package/common/skills/scan-techstack/SKILL.md +30 -36
  7. package/dist/cli.js +85 -0
  8. package/kits/coder/agents/ai-engineer.md +27 -39
  9. package/kits/coder/agents/backend-specialist.md +31 -45
  10. package/kits/coder/agents/cloud-architect.md +31 -45
  11. package/kits/coder/agents/code-reviewer.md +45 -67
  12. package/kits/coder/agents/data-engineer.md +22 -32
  13. package/kits/coder/agents/database-specialist.md +30 -44
  14. package/kits/coder/agents/debugger.md +28 -42
  15. package/kits/coder/agents/devops-engineer.md +35 -53
  16. package/kits/coder/agents/documentation-writer.md +48 -68
  17. package/kits/coder/agents/frontend-specialist.md +30 -46
  18. package/kits/coder/agents/i18n-specialist.md +37 -51
  19. package/kits/coder/agents/integration-specialist.md +38 -54
  20. package/kits/coder/agents/mobile-developer.md +37 -53
  21. package/kits/coder/agents/multi-tenant-architect.md +25 -37
  22. package/kits/coder/agents/orchestrator.md +20 -32
  23. package/kits/coder/agents/performance-analyst.md +43 -65
  24. package/kits/coder/agents/project-planner.md +25 -39
  25. package/kits/coder/agents/queue-specialist.md +26 -38
  26. package/kits/coder/agents/realtime-specialist.md +44 -64
  27. package/kits/coder/agents/security-auditor.md +44 -64
  28. package/kits/coder/agents/test-engineer.md +30 -44
  29. package/kits/coder/agents/ux-researcher.md +26 -38
  30. package/kits/coder/rules/sections/classifier.md +11 -7
  31. package/kits/coder/rules/sections/code.md +5 -4
  32. package/kits/coder/skills/accessibility-patterns/SKILL.md +67 -81
  33. package/kits/coder/skills/ai-rag-patterns/SKILL.md +27 -23
  34. package/kits/coder/skills/api-patterns/SKILL.md +40 -43
  35. package/kits/coder/skills/auth-patterns/SKILL.md +47 -51
  36. package/kits/coder/skills/aws-patterns/SKILL.md +52 -57
  37. package/kits/coder/skills/brainstorming/SKILL.md +26 -23
  38. package/kits/coder/skills/clean-code/SKILL.md +74 -90
  39. package/kits/coder/skills/database-design/SKILL.md +32 -31
  40. package/kits/coder/skills/docker-patterns/SKILL.md +46 -49
  41. package/kits/coder/skills/documentation-templates/SKILL.md +21 -13
  42. package/kits/coder/skills/e2e-testing/SKILL.md +52 -58
  43. package/kits/coder/skills/flutter-patterns/SKILL.md +44 -46
  44. package/kits/coder/skills/frontend-design/SKILL.md +28 -24
  45. package/kits/coder/skills/github-actions/SKILL.md +43 -45
  46. package/kits/coder/skills/gitlab-ci-patterns/SKILL.md +35 -33
  47. package/kits/coder/skills/graphql-patterns/SKILL.md +35 -33
  48. package/kits/coder/skills/i18n-localization/SKILL.md +37 -35
  49. package/kits/coder/skills/kubernetes-patterns/SKILL.md +35 -33
  50. package/kits/coder/skills/mermaid-diagrams/SKILL.md +54 -60
  51. package/kits/coder/skills/mobile-design/SKILL.md +51 -61
  52. package/kits/coder/skills/monitoring-observability/SKILL.md +32 -30
  53. package/kits/coder/skills/multi-tenancy/SKILL.md +16 -8
  54. package/kits/coder/skills/nodejs-best-practices/SKILL.md +19 -14
  55. package/kits/coder/skills/performance-profiling/SKILL.md +31 -29
  56. package/kits/coder/skills/plan-writing/SKILL.md +52 -59
  57. package/kits/coder/skills/postgres-patterns/SKILL.md +39 -39
  58. package/kits/coder/skills/prompt-engineering/SKILL.md +40 -42
  59. package/kits/coder/skills/queue-patterns/SKILL.md +22 -16
  60. package/kits/coder/skills/react-native-patterns/SKILL.md +35 -33
  61. package/kits/coder/skills/react-patterns/SKILL.md +46 -52
  62. package/kits/coder/skills/realtime-patterns/SKILL.md +44 -46
  63. package/kits/coder/skills/redis-patterns/SKILL.md +35 -33
  64. package/kits/coder/skills/security-fundamentals/SKILL.md +45 -46
  65. package/kits/coder/skills/seo-patterns/SKILL.md +56 -62
  66. package/kits/coder/skills/systematic-debugging/SKILL.md +38 -39
  67. package/kits/coder/skills/tailwind-patterns/SKILL.md +21 -13
  68. package/kits/coder/skills/terraform-patterns/SKILL.md +53 -57
  69. package/kits/coder/skills/testing-patterns/SKILL.md +42 -47
  70. package/kits/coder/skills/typescript-patterns/SKILL.md +54 -68
  71. package/kits/coder/skills/ui-ux-pro-max/SKILL.md +362 -364
  72. package/package.json +1 -1
@@ -6,22 +6,29 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash
6
6
 
7
7
  # AWS Patterns - Cloud Infrastructure Management
8
8
 
9
- > **Philosophy:** Security-first, automation-ready, and production-proven patterns for AWS services.
9
+ ## Quick Reference
10
+
11
+ - **IAM**: Least privilege · No root · MFA everywhere · Temporary credentials (STS) · No `"Action": "*"` or `"Resource": "*"`
12
+ - **S3**: Always block public access · Enable versioning + encryption · Use lifecycle policies
13
+ - **EC2**: No `0.0.0.0/0` for SSH (port 22) · IMDSv2 required · EBS encrypted
14
+ - **Lambda**: Least privilege roles · KMS for env vars · VPC config for internal resources
15
+ - **Security**: CloudTrail enabled (multi-region) · All secrets in Secrets Manager not env vars
16
+ - **Deployments**: CloudFormation/Terraform only · Never manual → infra as code
17
+
18
+ ---
10
19
 
11
20
  ---
12
21
 
13
22
  ## 📑 Content Map
14
23
 
15
- | Section | When to Read |
16
- | ----------------------- | --------------------------------------- |
17
- | AWS CLI Basics | Setting up CLI, configuration, profiles |
18
- | IAM Security Patterns | Users, roles, policies, access control |
19
- | S3 Patterns | Bucket management, object storage, sync |
20
- | EC2 Patterns | Instance management, security groups |
21
- | Lambda Patterns | Serverless functions, deployment |
22
- | CloudFormation Patterns | Infrastructure as Code |
23
- | Security Checklist | Pre-deployment security validation |
24
- | Troubleshooting | Common issues and solutions |
24
+ - AWS CLI Basics: Setting up CLI, configuration, profiles
25
+ - IAM Security Patterns: Users, roles, policies, access control
26
+ - S3 Patterns: Bucket management, object storage, sync
27
+ - EC2 Patterns: Instance management, security groups
28
+ - Lambda Patterns: Serverless functions, deployment
29
+ - CloudFormation Patterns: Infrastructure as Code
30
+ - Security Checklist: Pre-deployment security validation
31
+ - Troubleshooting: Common issues and solutions
25
32
 
26
33
  ---
27
34
 
@@ -53,12 +60,10 @@ aws sts get-caller-identity
53
60
 
54
61
  ### Profile Management
55
62
 
56
- | Pattern | Command |
57
- | --------------- | -------------------------------------------------------------------------------------------------- |
58
- | Use profile | `aws s3 ls --profile production` |
59
- | Export profile | `export AWS_PROFILE=production` |
60
- | Override region | `aws ec2 describe-instances --region us-west-2` |
61
- | MFA session | `aws sts get-session-token --serial-number arn:aws:iam::123456789012:mfa/user --token-code 123456` |
63
+ - Use profile: `aws s3 ls --profile production`
64
+ - Export profile: `export AWS_PROFILE=production`
65
+ - Override region: `aws ec2 describe-instances --region us-west-2`
66
+ - MFA session: `aws sts get-session-token --serial-number arn:aws:iam::123456789012:mfa/user --token-code 123456`
62
67
 
63
68
  ### Output Formats
64
69
 
@@ -82,13 +87,11 @@ aws ec2 describe-instances | jq '.Reservations[].Instances[].InstanceId'
82
87
 
83
88
  ### Core Principles (2024-2025)
84
89
 
85
- | Principle | Implementation |
86
- | ------------------------- | ------------------------------------------ |
87
- | **Least Privilege** | Grant only minimum required permissions |
88
- | **Temporary Credentials** | Use IAM roles, avoid long-term access keys |
89
- | **MFA Everywhere** | Require MFA for console access + API calls |
90
- | **No Root User** | Never use root for daily tasks |
91
- | **Regular Audits** | Review unused roles/users every 90 days |
90
+ - **Least Privilege**: Grant only minimum required permissions
91
+ - **Temporary Credentials**: Use IAM roles, avoid long-term access keys
92
+ - **MFA Everywhere**: Require MFA for console access + API calls
93
+ - **No Root User**: Never use root for daily tasks
94
+ - **Regular Audits**: Review unused roles/users every 90 days
92
95
 
93
96
  ### IAM User Management
94
97
 
@@ -155,13 +158,11 @@ aws sts assume-role \
155
158
 
156
159
  ### Policy Best Practices
157
160
 
158
- | Don't | Do |
159
- | -------------------- | ---------------------- |
160
- | `"Resource": "*"` | Specify exact ARNs |
161
- | `"Action": "*"` | List specific actions |
162
- | Attach to users | Attach to groups/roles |
163
- | Hardcode credentials | Use IAM roles + STS |
164
- | Skip MFA for admins | Require MFA always |
161
+ - `"Resource": "*"`: Specify exact ARNs
162
+ - `"Action": "*"`: List specific actions
163
+ - Attach to users: Attach to groups/roles
164
+ - Hardcode credentials: Use IAM roles + STS
165
+ - Skip MFA for admins: Require MFA always
165
166
 
166
167
  ---
167
168
 
@@ -524,14 +525,12 @@ aws logs put-retention-policy \
524
525
 
525
526
  ## 🔧 Troubleshooting
526
527
 
527
- | Issue | Solution |
528
- | ------------------------------ | --------------------------------------------------------------- |
529
- | `Unable to locate credentials` | Run `aws configure` or check `~/.aws/credentials` |
530
- | `Access Denied` | Check IAM policy, verify resource ARN, check STS assume-role |
531
- | `Region not specified` | Add `--region` flag or set `AWS_DEFAULT_REGION` |
532
- | `Invalid JSON` | Use `--cli-binary-format raw-in-base64-out` for Lambda payloads |
533
- | `ExpiredToken` | Get new STS session token if using MFA/assumed role |
534
- | `NoSuchBucket` | Check bucket name and region, S3 is globally unique |
528
+ - `Unable to locate credentials`: Run `aws configure` or check `~/.aws/credentials`
529
+ - `Access Denied`: Check IAM policy, verify resource ARN, check STS assume-role
530
+ - `Region not specified`: Add `--region` flag or set `AWS_DEFAULT_REGION`
531
+ - `Invalid JSON`: Use `--cli-binary-format raw-in-base64-out` for Lambda payloads
532
+ - `ExpiredToken`: Get new STS session token if using MFA/assumed role
533
+ - `NoSuchBucket`: Check bucket name and region, S3 is globally unique
535
534
 
536
535
  ### Debug Mode
537
536
 
@@ -547,29 +546,25 @@ aws s3 ls --debug 2>&1 | grep "Making request"
547
546
 
548
547
  ## Anti-Patterns
549
548
 
550
- | Don't | Do |
551
- | ---------------------------- | ---------------------------------------------- |
552
- | Hardcode access keys in code | Use IAM roles for EC2/Lambda |
553
- | Use `0.0.0.0/0` for SSH | Restrict to specific IP ranges |
554
- | Create access keys for root | Never use root, use IAM users |
555
- | Skip MFA for admin accounts | Require MFA for all privileged access |
556
- | Use long-term credentials | Prefer STS temporary credentials |
557
- | Store secrets in env vars | Use AWS Secrets Manager or SSM Parameter Store |
558
- | Manual deployments | Use CloudFormation/Terraform/CDK |
559
- | Single region deployment | Multi-region for DR-critical apps |
549
+ - Hardcode access keys in code: Use IAM roles for EC2/Lambda
550
+ - Use `0.0.0.0/0` for SSH: Restrict to specific IP ranges
551
+ - Create access keys for root: Never use root, use IAM users
552
+ - Skip MFA for admin accounts: Require MFA for all privileged access
553
+ - Use long-term credentials: Prefer STS temporary credentials
554
+ - Store secrets in env vars: Use AWS Secrets Manager or SSM Parameter Store
555
+ - Manual deployments: Use CloudFormation/Terraform/CDK
556
+ - Single region deployment: Multi-region for DR-critical apps
560
557
 
561
558
  ---
562
559
 
563
560
  ## Related Skills
564
561
 
565
- | Need | Skill |
566
- | ---------------------- | -------------------------- |
567
- | Infrastructure as Code | `terraform-patterns` |
568
- | Kubernetes on AWS | `kubernetes-patterns` |
569
- | Docker/ECS | `docker-patterns` |
570
- | CI/CD with AWS | `github-actions` |
571
- | Security hardening | `security-fundamentals` |
572
- | Monitoring | `monitoring-observability` |
562
+ - Infrastructure as Code: `terraform-patterns`
563
+ - Kubernetes on AWS: `kubernetes-patterns`
564
+ - Docker/ECS: `docker-patterns`
565
+ - CI/CD with AWS: `github-actions`
566
+ - Security hardening: `security-fundamentals`
567
+ - Monitoring: `monitoring-observability`
573
568
 
574
569
  ---
575
570
 
@@ -6,7 +6,16 @@ allowed-tools: Read, Write, Edit
6
6
 
7
7
  # Brainstorming - Socratic Discovery Protocol
8
8
 
9
- > **Philosophy:** Understanding precedes implementation. Ask first, build second.
9
+ ## Quick Reference
10
+
11
+ - **Ask before build**: New feature/vague request → Stop and ask 3+ clarifying questions first
12
+ - **Socratic questions**: Goal · Users · Scope · Constraints · Priority (MVP vs nice-to-have)
13
+ - **Never assume**: 1% unclear → ask · Assumptions cause rework
14
+ - **Context gathering**: Purpose → Users → Scope → Constraints → then plan
15
+ - **Output**: Clear requirements doc before any implementation begins
16
+
17
+ ---
18
+
10
19
 
11
20
  ---
12
21
 
@@ -290,16 +299,14 @@ Surface hidden assumptions before implementation
290
299
 
291
300
  ## 🚨 Anti-Patterns
292
301
 
293
- | Don't | Do |
294
- | ------------------------------- | ---------------------------------------------------- |
295
- | Ask 10+ questions at once | Group into 3-5 most important |
296
- | Ask obvious questions | Ask where there's genuine ambiguity |
297
- | Re-ask answered questions | Read conversation context |
298
- | Block on every detail | Make reasonable default assumptions for minor things |
299
- | Question simple requests | Apply judgment on when questions add value |
300
- | Ask then ignore answers | Incorporate answers into your approach |
301
- | Pretend to understand | Admit confusion and ask for clarity |
302
- | Assume user knows best approach | Offer expert guidance with questions |
302
+ - Ask 10+ questions at once: Group into 3-5 most important
303
+ - Ask obvious questions: Ask where there's genuine ambiguity
304
+ - Re-ask answered questions: Read conversation context
305
+ - Block on every detail: Make reasonable default assumptions for minor things
306
+ - Question simple requests: Apply judgment on when questions add value
307
+ - Ask then ignore answers: Incorporate answers into your approach
308
+ - Pretend to understand: Admit confusion and ask for clarity
309
+ - Assume user knows best approach: Offer expert guidance with questions
303
310
 
304
311
  ---
305
312
 
@@ -347,23 +354,19 @@ Before major implementation:
347
354
 
348
355
  **Question effectiveness:**
349
356
 
350
- | Question Type | When Valuable |
351
- | ------------- | ----------------------------------- |
352
- | Clarifying | When terms are ambiguous |
353
- | Probing | When surface answer is insufficient |
354
- | Hypothetical | When exploring edge cases |
355
- | Comparative | When choosing between options |
356
- | Reflective | When validating understanding |
357
+ - Clarifying: When terms are ambiguous
358
+ - Probing: When surface answer is insufficient
359
+ - Hypothetical: When exploring edge cases
360
+ - Comparative: When choosing between options
361
+ - Reflective: When validating understanding
357
362
 
358
363
  ---
359
364
 
360
365
  ## 🔗 Related Skills
361
366
 
362
- | Need | Skill |
363
- | ---------------------------- | ---------------------- |
364
- | Writing implementation plans | `plan-writing` |
365
- | Debugging with questions | `systematic-debugging` |
366
- | Clean code standards | `clean-code` |
367
+ - Writing implementation plans: `plan-writing`
368
+ - Debugging with questions: `systematic-debugging`
369
+ - Clean code standards: `clean-code`
367
370
 
368
371
  ---
369
372
 
@@ -8,32 +8,36 @@ priority: CRITICAL
8
8
 
9
9
  # Clean Code - Pragmatic AI Coding Standards
10
10
 
11
- > **Philosophy:** Be **concise, direct, and solution-focused**. The user wants working code, not programming lessons.
11
+ ## Quick Reference
12
+
13
+ - **SRP + DRY + KISS**: 1 function = 1 thing · no duplication · simplest solution
14
+ - **Naming**: `verb+noun` functions · `noun` variables · `is/has` booleans · no abbreviations
15
+ - **Functions**: ≤20 lines · ≤3 params · return early · no side effects hidden
16
+ - **No over-engineering**: No abstractions without 3+ uses · No premature optimization
17
+ - **Error handling**: Never silent catch · always typed errors · fail fast
18
+
19
+ ---
12
20
 
13
21
  ---
14
22
 
15
23
  ## Core Principles
16
24
 
17
- | Principle | Rule |
18
- | ------------- | ---------------------------------------------------------- |
19
- | **SRP** | Single Responsibility - each function/class does ONE thing |
20
- | **DRY** | Don't Repeat Yourself - extract duplicates, reuse |
21
- | **KISS** | Keep It Simple - simplest solution that works |
22
- | **YAGNI** | You Aren't Gonna Need It - don't build unused features |
23
- | **Boy Scout** | Leave code cleaner than you found it |
25
+ - **SRP**: Single Responsibility - each function/class does ONE thing
26
+ - **DRY**: Don't Repeat Yourself - extract duplicates, reuse
27
+ - **KISS**: Keep It Simple - simplest solution that works
28
+ - **YAGNI**: You Aren't Gonna Need It - don't build unused features
29
+ - **Boy Scout**: Leave code cleaner than you found it
24
30
 
25
31
  ---
26
32
 
27
33
  ## Naming Rules
28
34
 
29
- | Element | Convention |
30
- | ------------- | ----------------------------------------------------- |
31
- | **Variables** | Reveal intent: `userCount` not `n` |
32
- | **Functions** | Verb + noun: `getUserById()` not `user()` |
33
- | **Booleans** | Question form: `isActive`, `hasPermission`, `canEdit` |
34
- | **Constants** | SCREAMING_SNAKE: `MAX_RETRY_COUNT` |
35
- | **Classes** | PascalCase nouns: `UserService`, `PaymentGateway` |
36
- | **Files** | kebab-case or camelCase based on project convention |
35
+ - **Variables**: Reveal intent: `userCount` not `n`
36
+ - **Functions**: Verb + noun: `getUserById()` not `user()`
37
+ - **Booleans**: Question form: `isActive`, `hasPermission`, `canEdit`
38
+ - **Constants**: SCREAMING_SNAKE: `MAX_RETRY_COUNT`
39
+ - **Classes**: PascalCase nouns: `UserService`, `PaymentGateway`
40
+ - **Files**: kebab-case or camelCase based on project convention
37
41
 
38
42
  > **Rule:** If you need a comment to explain a name, rename it.
39
43
 
@@ -41,26 +45,22 @@ priority: CRITICAL
41
45
 
42
46
  ## Function Rules
43
47
 
44
- | Rule | Description |
45
- | ---------------------- | ------------------------------------- |
46
- | **Small** | Max 20 lines, ideally 5-10 |
47
- | **One Thing** | Does one thing, does it well |
48
- | **One Level** | One level of abstraction per function |
49
- | **Few Args** | Max 3 arguments, prefer 0-2 |
50
- | **No Side Effects** | Don't mutate inputs unexpectedly |
51
- | **Pure When Possible** | Same input → same output |
48
+ - **Small**: Max 20 lines, ideally 5-10
49
+ - **One Thing**: Does one thing, does it well
50
+ - **One Level**: One level of abstraction per function
51
+ - **Few Args**: Max 3 arguments, prefer 0-2
52
+ - **No Side Effects**: Don't mutate inputs unexpectedly
53
+ - **Pure When Possible**: Same input same output
52
54
 
53
55
  ---
54
56
 
55
57
  ## Code Structure
56
58
 
57
- | Pattern | Apply |
58
- | ------------------ | ----------------------------------------- |
59
- | **Guard Clauses** | Early returns for edge cases |
60
- | **Flat > Nested** | Avoid deep nesting (max 2 levels) |
61
- | **Composition** | Small functions composed together |
62
- | **Colocation** | Keep related code close |
63
- | **Vertical Slice** | Feature files together, not by layer type |
59
+ - **Guard Clauses**: Early returns for edge cases
60
+ - **Flat > Nested**: Avoid deep nesting (max 2 levels)
61
+ - **Composition**: Small functions composed together
62
+ - **Colocation**: Keep related code close
63
+ - **Vertical Slice**: Feature files together, not by layer type
64
64
 
65
65
  ### Guard Clause Example
66
66
 
@@ -90,33 +90,27 @@ function processUser(user) {
90
90
 
91
91
  ## AI Coding Style
92
92
 
93
- | Situation | Action |
94
- | ------------------------- | ------------------------------------------ |
95
- | User asks for feature | Write it directly |
96
- | User reports bug | Fix it, don't explain first |
97
- | No clear requirement | Ask, don't assume |
98
- | Multiple valid approaches | Pick one, mention alternatives if critical |
93
+ - User asks for feature: Write it directly
94
+ - User reports bug: Fix it, don't explain first
95
+ - No clear requirement: Ask, don't assume
96
+ - Multiple valid approaches: Pick one, mention alternatives if critical
99
97
 
100
98
  ### Output Quality Rules
101
99
 
102
- | Rule | Description |
103
- | -------------------- | ------------------------------------------- |
104
- | **No Preamble** | Skip "Here's the code..." - just write code |
105
- | **No Postamble** | Skip "This code does..." - let code speak |
106
- | **Minimal Comments** | Only for complex/non-obvious business logic |
107
- | **Complete Code** | No `// ... rest of code` placeholders |
108
- | **Test Immediately** | Run/verify code before claiming complete |
100
+ - **No Preamble**: Skip "Here's the code..." - just write code
101
+ - **No Postamble**: Skip "This code does..." - let code speak
102
+ - **Minimal Comments**: Only for complex/non-obvious business logic
103
+ - **Complete Code**: No `// ... rest of code` placeholders
104
+ - **Test Immediately**: Run/verify code before claiming complete
109
105
 
110
106
  ---
111
107
 
112
108
  ## Error Handling Patterns
113
109
 
114
- | Pattern | When to Use |
115
- | ------------------ | --------------------------------------- |
116
- | **Return Early** | Validation failures, missing data |
117
- | **Throw Specific** | Domain errors, use custom error classes |
118
- | **Try/Catch** | External calls, I/O operations |
119
- | **Result Type** | Complex operations, functional style |
110
+ - **Return Early**: Validation failures, missing data
111
+ - **Throw Specific**: Domain errors, use custom error classes
112
+ - **Try/Catch**: External calls, I/O operations
113
+ - **Result Type**: Complex operations, functional style
120
114
 
121
115
  ### Error Handling Example
122
116
 
@@ -133,18 +127,16 @@ throw new InsufficientFundsError(amount, balance);
133
127
 
134
128
  ## Anti-Patterns (DON'T)
135
129
 
136
- | Pattern | Fix |
137
- | --------------------------- | ----------------------- |
138
- | Comment every line | Delete obvious comments |
139
- | Helper for one-liner | Inline the code |
140
- | Factory for 2 objects | Direct instantiation |
141
- | utils.ts with 1 function | Put code where used |
142
- | "First we import..." | Just write code |
143
- | Deep nesting (3+ levels) | Guard clauses |
144
- | Magic numbers | Named constants |
145
- | God functions (50+ lines) | Split by responsibility |
146
- | Premature optimization | Make it work first |
147
- | Helper folder with 20 files | Colocate with features |
130
+ - Comment every line: Delete obvious comments
131
+ - Helper for one-liner: Inline the code
132
+ - Factory for 2 objects: Direct instantiation
133
+ - utils.ts with 1 function: Put code where used
134
+ - "First we import...": Just write code
135
+ - Deep nesting (3+ levels): Guard clauses
136
+ - Magic numbers: Named constants
137
+ - God functions (50+ lines): Split by responsibility
138
+ - Premature optimization: Make it work first
139
+ - Helper folder with 20 files: Colocate with features
148
140
 
149
141
  ---
150
142
 
@@ -152,12 +144,10 @@ throw new InsufficientFundsError(amount, balance);
152
144
 
153
145
  **Before changing a file, ask yourself:**
154
146
 
155
- | Question | Why |
156
- | ------------------------------- | ------------------------ |
157
- | **What imports this file?** | They might break |
158
- | **What does this file import?** | Interface changes |
159
- | **What tests cover this?** | Tests might fail |
160
- | **Is this a shared component?** | Multiple places affected |
147
+ - **What imports this file?**: They might break
148
+ - **What does this file import?**: Interface changes
149
+ - **What tests cover this?**: Tests might fail
150
+ - **Is this a shared component?**: Multiple places affected
161
151
 
162
152
  **Quick Check:**
163
153
 
@@ -174,15 +164,13 @@ File to edit: UserService.ts
174
164
 
175
165
  ## Summary
176
166
 
177
- | Do | Don't |
178
- | ---------------------- | -------------------------- |
179
- | Write code directly | Write tutorials |
180
- | Let code self-document | Add obvious comments |
181
- | Fix bugs immediately | Explain the fix first |
182
- | Inline small things | Create unnecessary files |
183
- | Name things clearly | Use abbreviations |
184
- | Keep functions small | Write 100+ line functions |
185
- | Verify code works | Claim done without testing |
167
+ - Write code directly: Write tutorials
168
+ - Let code self-document: Add obvious comments
169
+ - Fix bugs immediately: Explain the fix first
170
+ - Inline small things: Create unnecessary files
171
+ - Name things clearly: Use abbreviations
172
+ - Keep functions small: Write 100+ line functions
173
+ - Verify code works: Claim done without testing
186
174
 
187
175
  ---
188
176
 
@@ -190,13 +178,11 @@ File to edit: UserService.ts
190
178
 
191
179
  **Before saying "task complete", verify:**
192
180
 
193
- | Check | Question |
194
- | ------------------------- | --------------------------------- |
195
- | ✅ **Goal met?** | Did I do exactly what user asked? |
196
- | ✅ **Files edited?** | Did I modify all necessary files? |
197
- | ✅ **Code works?** | Did I test/verify the change? |
198
- | ✅ **No errors?** | Lint and TypeScript pass? |
199
- | ✅ **Nothing forgotten?** | Any edge cases missed? |
181
+ - **Goal met?**: Did I do exactly what user asked?
182
+ - **Files edited?**: Did I modify all necessary files?
183
+ - ✅ **Code works?**: Did I test/verify the change?
184
+ - ✅ **No errors?**: Lint and TypeScript pass?
185
+ - ✅ **Nothing forgotten?**: Any edge cases missed?
200
186
 
201
187
  > 🔴 **Rule:** If ANY check fails, fix it before completing.
202
188
 
@@ -228,12 +214,10 @@ Is logic non-obvious?
228
214
 
229
215
  ## Related Skills
230
216
 
231
- | Need | Skill |
232
- | -------------------- | ---------------------- |
233
- | API design patterns | `api-patterns` |
234
- | Testing methodology | `testing-patterns` |
235
- | Systematic debugging | `systematic-debugging` |
236
- | Database design | `database-design` |
217
+ - API design patterns: `api-patterns`
218
+ - Testing methodology: `testing-patterns`
219
+ - Systematic debugging: `systematic-debugging`
220
+ - Database design: `database-design`
237
221
 
238
222
  ---
239
223
 
@@ -7,7 +7,16 @@ version: 2.0
7
7
 
8
8
  # Database Design - Principles & Decision Making
9
9
 
10
- > **Philosophy:** Choose the right database and design for the context. Learn to THINK, not copy SQL patterns.
10
+ ## Quick Reference
11
+
12
+ - **DB selection**: Prototype → SQLite · Standard → PostgreSQL · Serverless → Neon · AI/embeddings → PG+pgvector
13
+ - **ORM**: TS+DX → Prisma · TS+Edge/perf → Drizzle · Python → SQLAlchemy 2.0
14
+ - **Schema**: 3NF normalization · UUIDs for distributed/exposed · CUID2/ULID for sortable · soft deletes with `deleted_at`
15
+ - **Indexes**: Every FK · every WHERE column · composite = leftmost rule · use `EXPLAIN ANALYZE`
16
+ - **Migrations**: Reversible · test on staging first · backup before prod · `ADD NULLABLE` before `NOT NULL`
17
+ - **N+1**: Use `include`/joins · batch requests · avoid row-per-row loops
18
+
19
+ ---
11
20
 
12
21
  ---
13
22
 
@@ -54,13 +63,11 @@ What are your requirements?
54
63
 
55
64
  ### When to Denormalize
56
65
 
57
- | Scenario | Consider Denormalization |
58
- | ----------------------------- | ------------------------ |
59
- | Frequent JOINs on same tables | ✅ Yes |
60
- | Read-heavy workload | Yes |
61
- | Real-time analytics | Yes |
62
- | Write-heavy workload | ❌ No |
63
- | Data integrity critical | ❌ No |
66
+ - Frequent JOINs on same tables: ✅ Yes
67
+ - Read-heavy workload: Yes
68
+ - Real-time analytics: ✅ Yes
69
+ - Write-heavy workload: No
70
+ - Data integrity critical: ❌ No
64
71
 
65
72
  ---
66
73
 
@@ -94,13 +101,11 @@ What are your requirements?
94
101
 
95
102
  ### Indexing Rules
96
103
 
97
- | Index | Don't Index |
98
- | ------------------------ | ---------------------------- |
99
- | WHERE clause columns | Low cardinality (bool, enum) |
100
- | JOIN condition columns | Frequently updated columns |
101
- | ORDER BY columns | Small tables (<1000 rows) |
102
- | Foreign keys | Columns rarely queried |
103
- | High cardinality columns | Already indexed via PK |
104
+ - WHERE clause columns: Low cardinality (bool, enum)
105
+ - JOIN condition columns: Frequently updated columns
106
+ - ORDER BY columns: Small tables (<1000 rows)
107
+ - Foreign keys: Columns rarely queried
108
+ - High cardinality columns: Already indexed via PK
104
109
 
105
110
  ### Composite Index Order
106
111
 
@@ -213,16 +218,14 @@ EXPLAIN ANALYZE SELECT * FROM users WHERE email = 'test@example.com';
213
218
 
214
219
  ## Anti-Patterns
215
220
 
216
- | Don't | Do |
217
- | ------------------------------------ | ------------------------ |
218
- | Default to PostgreSQL for everything | Choose based on needs |
219
- | Use `SELECT *` in production | Select specific columns |
220
- | Skip indexing | Index WHERE/JOIN columns |
221
- | Store structured data as JSON | Use proper columns |
222
- | Ignore N+1 queries | Use eager loading |
223
- | Run migrations without testing | Test on prod-like data |
224
- | Store dates as strings | Use proper DATE types |
225
- | No foreign key constraints | Define relationships |
221
+ - Default to PostgreSQL for everything: Choose based on needs
222
+ - Use `SELECT *` in production: Select specific columns
223
+ - Skip indexing: Index WHERE/JOIN columns
224
+ - Store structured data as JSON: Use proper columns
225
+ - Ignore N+1 queries: Use eager loading
226
+ - Run migrations without testing: Test on prod-like data
227
+ - Store dates as strings: Use proper DATE types
228
+ - No foreign key constraints: Define relationships
226
229
 
227
230
  ---
228
231
 
@@ -243,12 +246,10 @@ Before implementation:
243
246
 
244
247
  ## Related Skills
245
248
 
246
- | Need | Skill |
247
- | ----------------- | ----------------------- |
248
- | API design | `api-patterns` |
249
- | Backend patterns | `nodejs-best-practices` |
250
- | Query performance | `performance-profiling` |
251
- | Security | `security-fundamentals` |
249
+ - API design: `api-patterns`
250
+ - Backend patterns: `nodejs-best-practices`
251
+ - Query performance: `performance-profiling`
252
+ - Security: `security-fundamentals`
252
253
 
253
254
  ---
254
255