ai-nexus 1.5.0 → 1.5.1

package/README.ko.md

@@ -407,6 +407,18 @@ node bin/ai-nexus.cjs test "your prompt"
 
 Claude Code만 쓰고 스킬로 충분하면 ai-nexus가 필요 없을 수도 있습니다.
 
+**CLAUDE.md나 AGENTS.md에 다 넣으면 되지 않나요?**
+
+넣을 수는 있지만 규모가 커지면 문제가 됩니다. CLAUDE.md는 뭘 하든 매 프롬프트마다 전부 로드됩니다. 룰이 5개면 괜찮지만, 50개 이상이면 커밋 메시지 쓸 때 Docker best practices까지 같이 로드되는 거예요. [ETH Zurich 연구](https://arxiv.org/pdf/2602.11988)에서도 이게 성능과 비용 둘 다 악화시킨다고 나왔습니다.
+
+ai-nexus는 프롬프트당 관련 있는 2-3개 룰만 로드하고, 나머지는 비활성 상태로 둡니다.
+
+**Claude Code 스킬 쓰면 룰이 필요 없지 않나요?**
+
+스킬은 `/commit`, `/review`처럼 직접 호출하는 작업 워크플로우에 좋습니다. 하지만 룰을 대체하지는 못해요. 룰은 코딩 컨벤션, 보안 기준, 네이밍 패턴처럼 자동으로 적용되는 가이드라인입니다. 코드 짤 때마다 `/security-checklist`를 기억해서 호출할 수는 없잖아요.
+
+ai-nexus는 룰과 스킬 둘 다 프롬프트 기반으로 라우팅해서, 직접 호출하지 않아도 필요한 컨텍스트가 자동으로 로드됩니다.
+
 ---
 
 ## 지원하기

package/README.md

@@ -407,6 +407,18 @@ Skills already handle on-demand loading within Claude Code. ai-nexus is for a di
 
 If you only use Claude Code and skills cover your needs, you may not need ai-nexus.
 
+**Why not just put everything in CLAUDE.md or AGENTS.md?**
+
+You can — but it doesn't scale. CLAUDE.md loads on every prompt regardless of what you're doing. With 5 rules, that's fine. With 50+, you're burning tokens on Docker best practices while writing a commit message. The [ETH Zurich study](https://arxiv.org/pdf/2602.11988) shows this hurts both performance and cost.
+
+ai-nexus solves this by loading only 2-3 relevant rules per prompt, while keeping the rest parked.
+
+**Why not just use Claude Code skills instead of rules?**
+
+Skills are great for on-demand workflows you explicitly invoke (`/commit`, `/review`). But they don't replace rules — rules are passive guidelines that apply automatically (coding conventions, security standards, naming patterns). You shouldn't have to remember to invoke `/security-checklist` every time you write code.
+
+ai-nexus handles both: it routes rules *and* skills based on your prompt, so the right context loads automatically without you thinking about it.
+
 ---
 
 ## Support

package/config/skills/database.md

@@ -54,4 +54,4 @@ const result = await db.query(
 ```
 - Apply least-privilege for DB users
 - Avoid storing secrets; use connection strings from env
-- Audit sensitive operations (DDL, bulk deletes)
+- Audit sensitive operations (DDL, bulk deletes)

package/config/skills/mongodb.md

@@ -0,0 +1,182 @@
+---
+description: Practical MongoDB / NoSQL best practices for schema design, indexing, aggregation pipeline optimization, and secure production usage.
+keywords: [mongodb, nosql, mongoose, aggregation, index, indexing, compound, ttl, text, schema, embedding, referencing, sharding, transactions, performance, query, pipeline]
+---
+
+# MongoDB (NoSQL)
+
+Practical guidance for building efficient, maintainable, and secure MongoDB-backed applications. Focus is on actionable rules, decision heuristics, and small examples.
+
+## When to activate
+- Building or optimizing MongoDB queries or aggregations
+- Designing collection/document schemas
+- Adding or auditing indexes
+- Implementing security for stored data or connections
+- Working on sharding, transactions, or time-series data
+
+---
+
+## Indexing: when & which type
+- **Single-field**: good for high-cardinality single-field lookups.  
+- **Compound**: use when queries filter/sort by multiple fields. Put the most selective / most-filtered field first.
+  - Example: `{ age: 1, status: 1 }` helps queries with `age` and `status`.
+  - Order matters: `{ status: 1, age: 1 }` won't help a query that only filters by `age`.
+- **Text index**: use for full-text search across string fields. Avoid over-indexing — use dedicated search (e.g., Atlas Search) if heavy usage.
+- **TTL index**: use for expiring ephemeral data (sessions, caches). Set `expireAfterSeconds`.
+- **Wildcard index**: `{ "$**": 1 }` — use sparingly for schemas with many dynamic fields; increases write latency ~15-30% and storage 2-5x.
+- **Practical checks**
+  - Run `db.collection.explain('executionStats')` to check index usage.
+  - Avoid indexes on very high-write, low-read fields.
+  - Remove unused indexes (costly on writes & storage): `db.collection.getIndexes()` + `dropIndex()`.
+
+### Mongoose index snippets
+```javascript
+// Compound index (background build to avoid blocking)
+userSchema.index({ email: 1, status: 1 }, { background: true });
+
+// TTL index for auto-expiry (e.g., sessions expire after 24h)
+sessionSchema.index({ createdAt: 1 }, { expireAfterSeconds: 86400 });
+
+// Text index with field weights
+postSchema.index({ title: 'text', body: 'text' }, { weights: { title: 3, body: 1 } });
+
+// Sparse index for optional fields (only indexes docs where field exists)
+profileSchema.index({ twitterHandle: 1 }, { sparse: true });
+```
+
+---
+
+## Embedding vs Referencing — practical decision rules
+- **Embed** when:
+  - One-to-few relationships (comments on a post <100).
+  - Data accessed together most of the time.
+  - Example: post with small list of tags, metadata.
+- **Reference** when:
+  - One-to-many with large or growing lists (orders, logs).
+  - The child is large or independently updated.
+  - Many-to-many relationships.
+- **Hybrid approach**:
+  - Denormalize frequently-read fields (e.g., username snapshot on comment) but keep authoritative source in referenced doc.
+- **Quick rule**: model around access patterns, not perfectly normalized schema.
+
+### Mongoose embedding example with validation
+```javascript
+postSchema.add({
+  comments: [{
+    userId: { type: Schema.Types.ObjectId, ref: 'User', required: true },
+    text: { type: String, maxlength: 500, required: true },
+    createdAt: { type: Date, default: Date.now }
+  }],
+  commentCount: { 
+    type: Number, 
+    validate: { 
+      validator: v => v <= 100, 
+      message: 'Max 100 embedded comments; use referencing for more' 
+    }
+  }
+});
+```
+
+---
+
+## Data modeling patterns (common practical patterns)
+- **Bucket pattern**: group many small time-series events into monthly/day buckets to avoid huge arrays.
+  ```javascript
+  // Example: metrics bucketed by day
+  {
+    _id: deviceId,
+    bucketDate: ISODate("2026-03-08"),
+    readings: [ { ts: ..., value: ... }, ... ] // capped at ~1000 docs
+  }
+  ```
+- **Outlier pattern**: keep typical documents compact; move unusually large data to separate collection with reference.
+- **Polymorphic / type-discriminator**: use a `type` field + sparse fields per type, index `type` + commonly-queried fields.
+- **Time-series**: prefer MongoDB time-series collections (5.0+) or bucket pattern for high-frequency data.
+
+---
+
+## Aggregation pipeline optimization
+- **$match early**: filter as soon as possible to reduce pipeline volume.
+- **$project early**: drop unneeded fields prior to heavy stages like `$group`.
+- **Use indexes before aggregation**: if possible, use `$match` on indexed fields so the engine can use indexes.
+- **Avoid memory spikes**: `$group` can be memory heavy; add `$limit` / `$sort` with proper indexes.
+- **Use `allowDiskUse:true`** for large jobs, but prefer pre-filtering.
+- **Pipeline ordering cheat sheet**: `$match` → `$project` → `$lookup` (if needed) → `$group` → `$sort` → `$limit`.
+
+```javascript
+// Example: aggregation to compute per-customer revenue (optimized)
+db.orders.aggregate([
+  { $match: { status: "completed", createdAt: { $gte: ISODate("2026-01-01") } } }, // indexed filters first
+  { $project: { customerId: 1, amount: 1, _id: 0 } }, // remove heavy/unneeded fields
+  { $group: { _id: "$customerId", total: { $sum: "$amount" } } },
+  { $sort: { total: -1 } },
+  { $limit: 100 }
+], { allowDiskUse: false });
+```
+
+---
+
+## ❌ Common anti-patterns to avoid
+- Storing unbounded arrays (e.g., activity logs) → use bucket pattern or separate collection
+- Using `$where` or client-side evaluation → blocks indexing, slow, security risk
+- Over-using `$lookup` in high-traffic aggregations → denormalize hot paths or pre-aggregate
+- Creating indexes on low-cardinality fields alone (e.g., `gender: 1`) → rarely selective, wastes write capacity
+- Ignoring document size limit (16MB) → monitor with `$objSize` or schema validation
+
+---
+
+## Transactions, consistency & sharding (practical notes)
+- Use multi-document transactions only when necessary — they add latency (~2-3x) and complexity.
+- Favor single-document atomic operations (atomic by design) when possible.
+- For sharding:
+  - Choose shard key based on write and query patterns (avoid monotonically increasing keys like `createdAt` alone).
+  - Use hashed shard keys for even distribution if queries don't filter by range.
+  - Monitor chunk distribution and balancing via `sh.status()`.
+  - Test transactions/sharding in staging with representative data sizes.
+
+---
+
+## Production & security considerations
+- Never expose MongoDB directly to the internet — use private networks, VPC peering, or Atlas private endpoints.
+- Authentication & RBAC: enable SCRAM / x.509 and use least-privilege roles.
+- Field-level encryption: consider for highly sensitive fields (PII, tokens) using MongoDB Client-Side Field Level Encryption (CSFLE).
+- Secrets: store connection strings / credentials in environment variables or secret manager; do not embed in code.
+- TLS: require TLS for all connections (`tls=true` in connection string).
+- Backups & PITR: ensure regular backups; test restore procedures quarterly.
+- Audit & logging: enable audit logs for sensitive operations where compliance requires.
+
+---
+
+## Monitoring & performance checks
+- Use Profiler and `system.profile` to find slow queries:  
+  `db.setProfilingLevel(1, { slowms: 100 })`
+- Monitor `db.serverStatus()` metrics: `opcounters`, `asserts`, `connections`, `mem`, `metrics.document`.
+- Regularly review index usage: `db.collection.aggregate([{ $indexStats: {} }])`.
+- Plan index changes after schema or query changes — test with `explain('executionStats')`.
+
+---
+
+## Quick checklists (for PRs/Code Reviews)
+- [ ] Queries have appropriate filters and projections (no `find({})` without limits)
+- [ ] Critical fields are indexed (and compound indexes tested with real query patterns)
+- [ ] Aggregations place `$match` and `$project` early in pipeline
+- [ ] Large arrays or documents have outlier/bucket handling
+- [ ] No hardcoded connection strings or secrets in code
+- [ ] TLS and authentication are enforced in production config
+- [ ] Schema validation rules added for critical collections (optional but recommended)
+
+---
+
+## Example prompts (helps semantic router match this file)
+```
+"mongodb aggregation pipeline optimization"
+"optimize mongoose query performance"
+"mongodb ttl index sessions"
+"embedding vs referencing mongodb"
+"mongo shard key best practices"
+"mongodb compound index order best practices"
+"how to avoid aggregation memory limit"
+"mongoose populate vs embedding performance"
+"mongodb field level encryption example"
+"time-series collection vs bucket pattern"
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-nexus",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "Claude Code loads all rules every session - ai-nexus loads only what you need, syncing rules across Claude, Cursor, and Codex",
   "main": "dist/index.js",
   "bin": {