@wooojin/forgen 0.4.8 → 0.4.9

package/assets/dev-guide/be/skills/node/be-security/SKILL.md

@@ -0,0 +1,355 @@
+---
+name: be-security-node
+description: Node.js/TypeScript 서비스를 OWASP API Security Top 10 기준으로 진단. 카테고리별 체크리스트와 픽스 패턴을 제공한다.
+---
+
+# be-security (Node.js)
+
+> **호출 시점**: "이 핸들러 보안 검토해줘", "OWASP 관점에서 체크해줘", "보안 감사 준비해줘".
+> **선행 로딩**: `principles/common.md` (E섹션 Security Baseline) + `principles/node.md` 필수.
+
+## 0. 절대 금지
+
+1. "보안은 나중에" 금지 — 설계 단계부터 체크리스트 적용.
+2. 보안 이슈를 [LOW]로 다운그레이드 금지 — OWASP Top 10은 모두 [HIGH].
+3. 취약점 발견 후 "일단 배포" 금지 — 패치 후 배포.
+
+## 1. 워크플로우
+
+### Step 1 — 공격 표면 파악
+
+```markdown
+## 공격 표면 목록
+- 공개 엔드포인트: GET /api/orders, POST /api/payments, ...
+- 인증 필요: PUT /api/orders/:id, DELETE /api/...
+- 관리자 전용: POST /api/admin/...
+- 외부 입력: req.body, req.params, req.query, req.headers
+- 파일 업로드: POST /api/uploads
+```
+
+### Step 2 — OWASP Top 10 순서로 진단
+
+각 카테고리를 순서대로 실행. 발견 즉시 기록.
+
+### Step 3 — 취약점 보고
+
+```
+[HIGH] src/orders/order.controller.ts:42 — API1: 소유권 검증 없음, req.user.id vs params.userId 비교 누락
+[HIGH] src/auth/auth.controller.ts:88 — API6: 로그인 엔드포인트에 rate limit 없음
+```
+
+### Step 4 — 픽스 + 검증
+
+픽스 후 해당 패턴 재검증. 테스트 케이스 추가 권장.
+
+## 2. OWASP API Top 10 체크리스트 (2023)
+
+### API1 — Broken Object Level Authorization
+
+**"내 리소스만 접근 가능한가?"**
+
+```typescript
+// WRONG: URL params userId를 그대로 신뢰
+app.get('/api/orders/:orderId', async (req, res) => {
+  const order = await orderRepo.findById(req.params.orderId);
+  res.json(order);  // 다른 유저 주문도 접근 가능!
+});
+
+// RIGHT: 요청자 소유권 확인
+app.get('/api/orders/:orderId', authenticate, async (req, res) => {
+  const order = await orderRepo.findById(req.params.orderId);
+  if (!order) return res.status(404).json({ error: { code: 'NOT_FOUND' } });
+  if (order.userId !== req.user.id) {  // 소유권 검증 필수
+    return res.status(403).json({ error: { code: 'FORBIDDEN' } });
+  }
+  res.json(order);
+});
+```
+
+체크:
+```
+[ ] 모든 리소스 접근에 소유권 검증 존재
+[ ] JWT에서 userId 추출 (req.params.userId 신뢰 금지)
+[ ] 관리자 우회 경로에도 권한 검증
+```
+
+### API2 — Broken Authentication
+
+**"토큰이 진짜인가? 만료됐는가?"**
+
+```typescript
+import jwt from 'jsonwebtoken';
+
+// WRONG: 알고리즘 명시 안 함 (none 알고리즘 공격 위험)
+jwt.verify(token, secret);
+
+// RIGHT: 알고리즘 명시
+jwt.verify(token, process.env.JWT_PUBLIC_KEY!, {
+  algorithms: ['RS256'],  // HS256도 가능하지만 RS256 권장 (비대칭)
+  issuer: 'auth.example.com',
+  audience: 'api.example.com',
+});
+```
+
+체크:
+```
+[ ] JWT 알고리즘 명시 (algorithms: ['RS256'])
+[ ] 토큰 만료 검증 (exp claim)
+[ ] 시크릿/키가 env에서 로드 (하드코딩 금지)
+[ ] Refresh token rotation 구현 (refresh 후 구 토큰 무효화)
+[ ] 로그아웃 시 토큰 블랙리스트 또는 단기 만료
+```
+
+### API3 — Broken Object Property Level Authorization
+
+**"응답에 불필요한 필드가 포함되는가?"**
+
+```typescript
+// WRONG: DB 모델 그대로 반환
+const user = await prisma.user.findUnique({ where: { id } });
+res.json(user);  // password hash, internal flags 등 노출!
+
+// RIGHT: allowlist projection
+const user = await prisma.user.findUnique({
+  where: { id },
+  select: { id: true, name: true, email: true },  // 필요한 것만
+});
+res.json(user);
+
+// 또는 직렬화 레이어
+function serializeUser(user: User): PublicUser {
+  const { passwordHash, internalFlags, ...publicFields } = user;
+  return publicFields;
+}
+```
+
+체크:
+```
+[ ] 응답 스키마 allowlist 정의 (전체 모델 반환 금지)
+[ ] password, hash, secret, internal 필드 응답 제외
+[ ] mass assignment 방지 (req.body를 DB에 spread 금지)
+```
+
+### API4 — Unrestricted Resource Consumption
+
+**"무한 요청/대용량 페이로드를 막는가?"**
+
+```typescript
+import rateLimit from 'express-rate-limit';
+
+// Rate limiting
+const limiter = rateLimit({
+  windowMs: 15 * 60 * 1000,  // 15분
+  max: 100,                    // 최대 100 요청
+  standardHeaders: true,
+  legacyHeaders: false,
+  handler: (req, res) => {
+    res.status(429).json({
+      error: { code: 'TOO_MANY_REQUESTS', message: '요청 한도 초과' },
+    });
+  },
+});
+
+// 페이로드 크기 제한
+app.use(express.json({ limit: '1mb' }));
+app.use(express.urlencoded({ extended: true, limit: '1mb' }));
+
+// 파일 업로드 크기 제한
+import multer from 'multer';
+const upload = multer({ limits: { fileSize: 10 * 1024 * 1024 } });  // 10MB
+```
+
+체크:
+```
+[ ] Rate limiting — 전역 + 민감 엔드포인트별 강화
+[ ] Request body 크기 제한 (1MB 이하 권장)
+[ ] 파일 업로드 크기 제한
+[ ] 페이지네이션 limit 상한 (limit=10000 같은 무한 요청 방지)
+[ ] Retry-After 헤더 (429 응답 시)
+```
+
+### API5 — Broken Function Level Authorization
+
+**"관리자 기능을 일반 유저가 호출할 수 없는가?"**
+
+```typescript
+// 역할 기반 미들웨어
+function requireRole(...roles: string[]) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    if (!roles.includes(req.user.role)) {
+      return res.status(403).json({ error: { code: 'FORBIDDEN' } });
+    }
+    next();
+  };
+}
+
+app.delete('/api/admin/users/:id', authenticate, requireRole('admin'), deleteUser);
+app.get('/api/admin/stats', authenticate, requireRole('admin', 'analyst'), getStats);
+```
+
+체크:
+```
+[ ] 관리자 엔드포인트 별도 인가 미들웨어
+[ ] HTTP 메서드별 권한 분리 (GET vs DELETE 다른 권한)
+[ ] 숨겨진 관리자 경로 (/api/internal, /debug) 외부 노출 여부
+[ ] 권한 검사를 비즈니스 로직 내부에도 (미들웨어 우회 가능성 고려)
+```
+
+### API6 — Unrestricted Access to Sensitive Flows
+
+**"로그인/OTP/비밀번호 재설정에 무차별 대입 방어가 있는가?"**
+
+```typescript
+// 로그인 전용 강화 rate limit
+const authLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000,
+  max: 10,  // 15분에 10회
+  skipSuccessfulRequests: true,
+  keyGenerator: (req) => req.ip + ':' + req.body?.email,  // IP + 이메일 조합
+});
+
+app.post('/api/auth/login', authLimiter, loginHandler);
+app.post('/api/auth/forgot-password', authLimiter, forgotPasswordHandler);
+
+// 계정 잠금 (DB에서 실패 횟수 추적)
+async function loginHandler(req: Request, res: Response) {
+  const user = await userRepo.findByEmail(req.body.email);
+  if (user && user.failedAttempts >= 5 && user.lockedUntil > new Date()) {
+    return res.status(429).json({ error: { code: 'ACCOUNT_LOCKED' } });
+  }
+  // ...
+}
+```
+
+체크:
+```
+[ ] 로그인 엔드포인트 rate limit (IP + 이메일 조합)
+[ ] OTP/인증코드 rate limit
+[ ] 계정 잠금 정책 (N회 실패 → 잠금)
+[ ] 비밀번호 재설정 토큰 단기 만료 (15분)
+[ ] 비밀번호 재설정 토큰 1회 사용 후 무효화
+```
+
+### API7 — Server Side Request Forgery (SSRF)
+
+**"사용자가 지정한 URL로 서버가 요청을 보내는가?"**
+
+```typescript
+import { URL } from 'node:url';
+
+const ALLOWED_HOSTS = new Set(['api.trustedpartner.com', 'webhooks.example.com']);
+
+function validateWebhookUrl(url: string): boolean {
+  try {
+    const parsed = new URL(url);
+    if (!['https:'].includes(parsed.protocol)) return false;
+    if (!ALLOWED_HOSTS.has(parsed.hostname)) return false;
+    // private IP 차단
+    const ip = await resolveHostname(parsed.hostname);
+    if (isPrivateIP(ip)) return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+```
+
+체크:
+```
+[ ] 사용자 입력 URL fetch 전 allowlist 검증
+[ ] private IP (10.x, 172.16.x, 192.168.x, 127.x) 접근 차단
+[ ] protocol 검증 (https만 허용)
+[ ] redirect follow 제한
+```
+
+### API8 — Security Misconfiguration
+
+```typescript
+// Helmet.js — 보안 헤더 자동 설정
+import helmet from 'helmet';
+app.use(helmet());  // CSP, HSTS, X-Frame-Options 등
+
+// CORS — allowlist 기반
+import cors from 'cors';
+app.use(cors({
+  origin: ['https://app.example.com', 'https://admin.example.com'],
+  methods: ['GET', 'POST', 'PUT', 'DELETE'],
+  credentials: true,
+}));
+
+// 개발 전용 엔드포인트 프로덕션 노출 금지
+if (process.env.NODE_ENV !== 'production') {
+  app.get('/debug/health-detail', debugHandler);
+}
+```
+
+체크:
+```
+[ ] CORS origin이 * 아님 (allowlist)
+[ ] Helmet.js 또는 동등한 보안 헤더
+[ ] 스택 trace가 에러 응답에 포함되지 않음 (production)
+[ ] 디버그/내부 엔드포인트 프로덕션 비활성화
+[ ] 불필요한 HTTP 메서드 비활성화
+[ ] X-Powered-By 헤더 제거 (프레임워크 노출)
+```
+
+### API9 — Improper Inventory Management
+
+```
+[ ] API 버전 목록 문서화 (deprecated 포함)
+[ ] 구 버전 /v0, /v1 폐기 계획 및 Sunset 날짜
+[ ] 스테이징/개발 엔드포인트 인터넷 노출 여부
+[ ] API 게이트웨이에서 활성 엔드포인트 목록 관리
+```
+
+### API10 — Unsafe Consumption of APIs
+
+**"외부 API 응답을 그대로 신뢰하는가?"**
+
+```typescript
+// WRONG: 외부 응답 신뢰
+const externalData = await fetch(externalApiUrl).then(r => r.json());
+await db.insert(externalData);  // 외부 데이터를 검증 없이 삽입!
+
+// RIGHT: 외부 응답도 Zod로 검증
+const ExternalResponseSchema = z.object({
+  id: z.string(),
+  amount: z.number().positive(),
+  status: z.enum(['pending', 'completed', 'failed']),
+});
+
+const raw = await fetch(externalApiUrl).then(r => r.json());
+const validated = ExternalResponseSchema.parse(raw);  // 검증 후 사용
+```
+
+체크:
+```
+[ ] 외부 API 응답 스키마 검증 (Zod 등)
+[ ] 외부 API 타임아웃 설정
+[ ] 외부 API 실패 시 fallback 또는 에러 전파
+[ ] 외부 API SSL 인증서 검증 (rejectUnauthorized: false 금지)
+```
+
+## 3. 출력 형식
+
+```
+## 보안 감사 결과
+
+### 공격 표면: N개 엔드포인트
+
+### 발견된 취약점
+[HIGH] API1 src/orders/order.controller.ts:42 — 소유권 검증 없음
+[HIGH] API6 src/auth/auth.controller.ts:15 — 로그인 rate limit 없음
+
+### 통과한 항목
+- API2: JWT RS256 + 만료 검증 ✅
+- API4: Rate limit (전역 100/15min) ✅
+
+### 권고 사항
+- API8: helmet.js 미적용 → 즉시 적용 권장
+```
+
+## 4. 관련 문서
+
+- 원칙: [`principles/common.md`](../../../principles/common.md) E섹션
+- 코퍼스: `sources/owasp-api/`

package/assets/dev-guide/be/sources/12factor/INDEX.md

@@ -0,0 +1,53 @@
+---
+title: 12-Factor App 문서 인덱스
+fetched: 예정 (2026-05-18 스캐폴드)
+license: CC BY 4.0 (https://12factor.net)
+priority: 1 (출처 우선순위 최상위)
+---
+
+# 12-Factor App
+
+> 클라우드 네이티브 애플리케이션을 위한 12가지 방법론.
+> 이식성, 운영 안정성, 스케일 아웃 설계의 기준.
+
+## 출처
+
+| URL | 설명 |
+|-----|------|
+| https://12factor.net/ko/ | 한국어 공식 번역 |
+| https://12factor.net/ | 영문 원본 |
+
+## 라이선스
+
+Creative Commons Attribution 4.0 (CC BY 4.0)
+
+## 수집일
+
+예정 (2026-05-18 스캐폴드)
+
+## 참조 우선순위
+
+1 (common.md 출처 우선순위 최상위)
+
+## 문서 목록 (수집 예정)
+
+| 파일명 (예정) | Factor | 제목 |
+|--------------|--------|------|
+| 01-codebase.md | I | Codebase — 하나의 코드베이스, 다수 배포 |
+| 02-dependencies.md | II | Dependencies — 의존성 명시 및 격리 |
+| 03-config.md | III | Config — 환경변수에 설정 저장 |
+| 04-backing-services.md | IV | Backing Services — 부착된 리소스로 취급 |
+| 05-build-release-run.md | V | Build/Release/Run — 엄격한 단계 분리 |
+| 06-processes.md | VI | Processes — 무상태(stateless) 프로세스 |
+| 07-port-binding.md | VII | Port Binding — 포트 바인딩으로 서비스 노출 |
+| 08-concurrency.md | VIII | Concurrency — 프로세스 모델로 스케일 아웃 |
+| 09-disposability.md | IX | Disposability — 빠른 시작 + 우아한 종료 |
+| 10-dev-prod-parity.md | X | Dev/Prod Parity — 개발/스테이징/프로덕션 일관성 |
+| 11-logs.md | XI | Logs — 이벤트 스트림으로 취급 (stdout) |
+| 12-admin-processes.md | XII | Admin Processes — 일회성 프로세스 실행 |
+
+## 핵심 참조 원칙 (principles/common.md 연결)
+
+- Factor III (Config) → Security E.3 비밀 관리 (env 기반)
+- Factor IX (Disposability) → Node N2 graceful shutdown
+- Factor XI (Logs) → Observability C.1 구조화 로그 (stdout 출력)

package/assets/dev-guide/be/sources/api-design/INDEX.md

@@ -0,0 +1,56 @@
+---
+title: API 설계 가이드 문서 인덱스
+fetched: 예정 (2026-05-18 스캐폴드)
+license: 복합 (항목별 명시)
+priority: 6 (출처 우선순위)
+---
+
+# API 설계 — Stripe API + GitHub API + Google AIP
+
+> 실전 API 설계 기준. Stripe(결제), GitHub(개발자 API), Google AIP(대규모 API 표준).
+
+## 출처
+
+| URL | 설명 | 라이선스 |
+|-----|------|----------|
+| https://stripe.com/docs/api | Stripe API Reference | Stripe 저작권 (공개 문서) |
+| https://docs.github.com/en/rest | GitHub REST API | CC BY 4.0 |
+| https://google.aip.dev/ | Google API Improvement Proposals | Apache-2.0 |
+| https://opensource.google/documentation/reference/thirdparty/licenses | Google 오픈소스 라이선스 | — |
+
+## 라이선스
+
+- Stripe 문서: 공개 참조 가능, 재배포 금지
+- GitHub 문서: CC BY 4.0
+- Google AIP: Apache-2.0
+
+## 수집일
+
+예정 (2026-05-18 스캐폴드)
+
+## 참조 우선순위
+
+6 (common.md 출처 우선순위)
+
+## 문서 목록 (수집 예정)
+
+| 파일명 (예정) | 출처 | 주제 |
+|--------------|------|------|
+| stripe-pagination.md | Stripe | 커서 기반 페이지네이션 |
+| stripe-idempotency.md | Stripe | Idempotency-Key 멱등성 패턴 |
+| stripe-errors.md | Stripe | 구조화 에러 응답 (code/type/param) |
+| stripe-versioning.md | Stripe | API 버전 관리 (날짜 기반) |
+| github-rest-conventions.md | GitHub | RESTful 리소스 명명 규칙 |
+| github-pagination.md | GitHub | Link 헤더 기반 페이지네이션 |
+| aip-0121-resource-names.md | Google AIP-121 | 리소스 이름 표준 |
+| aip-0131-standard-methods.md | Google AIP-131 | 표준 메서드 (List/Get/Create/...) |
+| aip-0180-backwards-compat.md | Google AIP-180 | 하위 호환성 정책 |
+| aip-0193-errors.md | Google AIP-193 | 에러 모델 표준 |
+
+## 핵심 참조 원칙 (principles/common.md 연결)
+
+- Stripe 에러 → Error Model B.1 구조화 에러
+- Stripe 멱등성 → Idempotency D.1 Idempotency-Key
+- GitHub 명명 → API 설계 A.2 일관성 (복수형 명사)
+- Google AIP-180 → API 설계 A.4 진화가능성 (하위 호환)
+- Google AIP-193 → Error Model B.2 4xx/5xx 경계

package/assets/dev-guide/be/sources/ddia/INDEX.md

@@ -0,0 +1,55 @@
+---
+title: DDIA (Designing Data-Intensive Applications) 문서 인덱스
+fetched: 예정 (2026-05-18 스캐폴드)
+license: O'Reilly 저작권 — 공개 발췌 없음. 요약/원칙만 수록
+priority: 5 (출처 우선순위)
+---
+
+# Designing Data-Intensive Applications — Martin Kleppmann
+
+> 데이터 집약적 애플리케이션 설계. 복제, 파티셔닝, 트랜잭션, 분산 시스템 기초.
+
+## 출처
+
+| URL | 설명 |
+|-----|------|
+| https://dataintensive.net/ | 공식 사이트 |
+| https://www.oreilly.com/library/view/designing-data-intensive/9781491903063/ | O'Reilly |
+| https://github.com/ept/ddia-references | 챕터별 참조 논문 |
+
+## 라이선스
+
+O'Reilly 저작권 보호 도서. 직접 텍스트 수록 불가.
+이 sources 디렉토리에는 **원칙 요약과 핵심 패턴만** 기록. 원문은 도서 구매 필요.
+
+## 수집일
+
+예정 (2026-05-18 스캐폴드)
+
+## 참조 우선순위
+
+5 (common.md 출처 우선순위)
+
+## 문서 목록 (원칙 요약 예정 — 원문 미포함)
+
+| 파일명 (예정) | 챕터 | 주제 |
+|--------------|------|------|
+| ch01-foundations.md | 1 | 신뢰성·확장성·유지보수성 정의 |
+| ch02-data-models.md | 2 | 관계형 vs 문서 vs 그래프 |
+| ch03-storage-retrieval.md | 3 | 인덱스 구조 (B-Tree, LSM) |
+| ch04-encoding.md | 4 | 인코딩/스키마 진화 (Avro, Protobuf) |
+| ch05-replication.md | 5 | 복제 — 리더/팔로워, 동기/비동기 |
+| ch06-partitioning.md | 6 | 파티셔닝 (샤딩) |
+| ch07-transactions.md | 7 | 트랜잭션 격리 수준, ACID vs BASE |
+| ch08-trouble.md | 8 | 분산 시스템의 문제 (시계, 네트워크) |
+| ch09-consistency.md | 9 | 일관성과 합의 (Linearizability, Paxos, Raft) |
+| ch10-batch.md | 10 | 배치 처리 (MapReduce) |
+| ch11-stream.md | 11 | 스트림 처리 (Kafka, 이벤트 소싱) |
+| ch12-future.md | 12 | 데이터 시스템의 미래 |
+
+## 핵심 참조 원칙 (principles/common.md 연결)
+
+- Ch7 (Transactions) → DB G.1 트랜잭션 경계
+- Ch4 (Schema Evolution) → DB G.2 Expand/Contract 마이그레이션
+- Ch3 (Indexes) → DB G.3 인덱스 의도 주석
+- Ch5 (Replication Lag) → 분산 시스템 일관성 주의사항

package/assets/dev-guide/be/sources/go-runtime/INDEX.md

@@ -0,0 +1,62 @@
+---
+title: Go 런타임 성능/진단 문서 인덱스
+fetched: 예정 (2026-05-18 스캐폴드)
+license: BSD-3-Clause (Go 공식) + 각 출처별
+priority: 6 (출처 우선순위)
+---
+
+# Go 런타임 — 공식 문서 + Effective Go + 성능 가이드
+
+> Go 스케줄러, 메모리 모델, GC, pprof 진단, goroutine 패턴.
+
+## 출처
+
+| URL | 설명 | 라이선스 |
+|-----|------|----------|
+| https://go.dev/doc/effective_go | Effective Go | BSD-3-Clause |
+| https://go.dev/ref/spec | Go Language Specification | BSD-3-Clause |
+| https://go.dev/doc/diagnostics | Diagnostics 가이드 | BSD-3-Clause |
+| https://go.dev/blog/pprof | pprof 프로파일링 | BSD-3-Clause |
+| https://go.dev/doc/gc-guide | GC 가이드 | BSD-3-Clause |
+| https://go.dev/blog/concurrency-timeouts | Timeouts/Cancellation | BSD-3-Clause |
+| https://github.com/dgryski/go-perfbook | Go 성능 최적화 북 | — |
+| https://pkg.go.dev/golang.org/x/sync/errgroup | errgroup | BSD-3-Clause |
+| https://go.dev/blog/race-detector | Race Detector | BSD-3-Clause |
+| https://golangci-lint.run/ | golangci-lint | GPL-3.0 |
+
+## 라이선스
+
+BSD-3-Clause (Go 공식 문서)
+
+## 수집일
+
+예정 (2026-05-18 스캐폴드)
+
+## 참조 우선순위
+
+6 (common.md 출처 우선순위)
+
+## 문서 목록 (수집 예정)
+
+| 파일명 (예정) | 출처 | 주제 |
+|--------------|------|------|
+| effective-go.md | Effective Go | Go 관용 표현, 에러, 인터페이스 |
+| scheduler.md | Go 공식 | GMP 스케줄러 동작 원리 |
+| gc-guide.md | Go 공식 | GC 파라미터 (GOGC, GOMEMLIMIT) |
+| pprof.md | Go 공식 | CPU / 메모리 / goroutine 프로파일 |
+| race-detector.md | Go 공식 | -race 플래그, 레이스 컨디션 탐지 |
+| memory-model.md | Go 공식 | Happens-before, sync 보장 |
+| goroutine-patterns.md | 참조 | goroutine 생명주기 패턴 |
+| context-patterns.md | 참조 | context.Context 전파 패턴 |
+| errgroup.md | golang.org/x | errgroup 사용법 |
+| golangci-lint-config.md | golangci-lint | .golangci.yml 권장 설정 |
+| go-perf-book-summary.md | go-perfbook | 핵심 최적화 패턴 요약 |
+
+## 핵심 참조 원칙 (principles/go.md 연결)
+
+- Effective Go 에러 패턴 → G1 에러는 값
+- context 패턴 → G2 context 전파
+- goroutine 패턴 → G3 goroutine 생명주기
+- pprof → be-perf Go 진단 절차
+- gc-guide → be-perf GC pause 카테고리
+- golangci-lint → G7 정적 분석

package/assets/dev-guide/be/sources/node-runtime/INDEX.md

@@ -0,0 +1,60 @@
+---
+title: Node.js 런타임 성능/진단 문서 인덱스
+fetched: 예정 (2026-05-18 스캐폴드)
+license: MIT (Node.js docs: https://github.com/nodejs/node/blob/main/LICENSE)
+priority: 6 (출처 우선순위)
+---
+
+# Node.js 런타임 — 공식 문서 + Fastify + NestJS
+
+> Event Loop, 메모리, 스트림, 성능 진단, 프레임워크 패턴.
+
+## 출처
+
+| URL | 설명 | 라이선스 |
+|-----|------|----------|
+| https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick | Event Loop 가이드 | MIT |
+| https://nodejs.org/en/docs/guides/dont-block-the-event-loop | Event Loop 차단 방지 | MIT |
+| https://nodejs.org/api/stream.html | Streams API | MIT |
+| https://nodejs.org/api/worker_threads.html | Worker Threads | MIT |
+| https://clinic.js.org/ | Clinic.js 진단 도구 | MIT |
+| https://www.fastify.io/docs/latest/ | Fastify 공식 문서 | MIT |
+| https://docs.nestjs.com/ | NestJS 공식 문서 | MIT |
+| https://pino.js.org/ | Pino 로거 | MIT |
+| https://github.com/nicolo-ribaudo/tc39-proposal-async-context | Async Context 제안 | — |
+
+## 라이선스
+
+MIT (Node.js, Fastify, Pino) / MIT (NestJS)
+
+## 수집일
+
+예정 (2026-05-18 스캐폴드)
+
+## 참조 우선순위
+
+6 (common.md 출처 우선순위)
+
+## 문서 목록 (수집 예정)
+
+| 파일명 (예정) | 출처 | 주제 |
+|--------------|------|------|
+| event-loop.md | Node.js | Event Loop 상세 (phases, timers) |
+| dont-block.md | Node.js | Event Loop 차단 패턴과 해결 |
+| streams.md | Node.js | Readable/Writable/Transform + backpressure |
+| worker-threads.md | Node.js | CPU 병렬화 (worker_threads) |
+| diagnostic-report.md | Node.js | 진단 리포트 생성 |
+| clinic-setup.md | Clinic.js | Doctor / Flame / Heap profiler |
+| fastify-lifecycle.md | Fastify | Request 생명주기 (hooks) |
+| fastify-schema-validation.md | Fastify | JSON Schema 기반 입력 검증 |
+| nestjs-modules.md | NestJS | 모듈/DI 패턴 |
+| nestjs-interceptors.md | NestJS | 인터셉터 (로깅, 캐싱, 변환) |
+| pino-setup.md | Pino | 구조화 로그 설정 (redact, transport) |
+
+## 핵심 참조 원칙 (principles/node.md 연결)
+
+- Event Loop 가이드 → N3 Event Loop 차단 금지
+- Worker Threads → N3.2 CPU Heavy 격리
+- Streams → N4 Backpressure
+- Clinic.js → be-perf 진단 절차
+- Pino → N8 구조화 로그

package/assets/dev-guide/be/sources/otel/INDEX.md

@@ -0,0 +1,53 @@
+---
+title: OpenTelemetry 문서 인덱스
+fetched: 예정 (2026-05-18 스캐폴드)
+license: Apache-2.0 (https://opentelemetry.io)
+priority: 4 (출처 우선순위)
+---
+
+# OpenTelemetry (OTel)
+
+> 관찰가능성(Observability) 표준. Traces + Metrics + Logs 통합 계측.
+
+## 출처
+
+| URL | 설명 |
+|-----|------|
+| https://opentelemetry.io/docs/ | OTel 공식 문서 |
+| https://opentelemetry.io/docs/languages/js/ | JavaScript/Node.js SDK |
+| https://opentelemetry.io/docs/languages/go/ | Go SDK |
+| https://opentelemetry.io/docs/concepts/signals/ | Signals 개념 (Traces/Metrics/Logs) |
+| https://opentelemetry.io/docs/specs/otel/ | 명세 |
+| https://w3c.github.io/trace-context/ | W3C TraceContext (traceparent 헤더) |
+
+## 라이선스
+
+Apache-2.0
+
+## 수집일
+
+예정 (2026-05-18 스캐폴드)
+
+## 참조 우선순위
+
+4 (common.md 출처 우선순위)
+
+## 문서 목록 (수집 예정)
+
+| 파일명 (예정) | 주제 |
+|--------------|------|
+| concepts-traces.md | Traces, Spans, TraceContext |
+| concepts-metrics.md | Metrics — Counters, Histograms, Gauges |
+| concepts-logs.md | Structured Logs + Log Correlation |
+| sdk-node-setup.md | Node.js SDK 설정 + 자동 계측 |
+| sdk-go-setup.md | Go SDK 설정 + 자동 계측 |
+| propagation.md | Context Propagation (W3C TraceContext) |
+| semantic-conventions.md | HTTP/DB 속성 명명 규칙 |
+| exporters.md | OTLP, Jaeger, Prometheus exporter |
+
+## 핵심 참조 원칙 (principles/common.md 연결)
+
+- Traces → Observability C.3 분산 트레이스
+- W3C TraceContext → C.3 traceparent 헤더 전파
+- Metrics → C.2 RED Method 계측
+- Semantic Conventions → 속성 이름 표준화