oh-my-customcode 0.49.0 → 0.51.0

package/templates/.claude/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: systematic-debugging
+description: Use when encountering any bug, test failure, or unexpected behavior. Enforces a strict reproduce-first, root-cause-first, failing-test-first debugging workflow before fixing.
+version: 1.0.0
+user-invocable: false
+---
+
+<!-- Source: https://github.com/tmdgusya/engineering-disciplines (MIT License) -->
+
+# Systematic Debugging
+
+엄격한 디버깅 워크플로우다. 버그, 테스트 실패, 예기치 않은 동작을 다룰 때 사용한다.
+
+핵심 목적은 세 가지다.
+
+1. 증상이 아니라 원인을 고친다.
+2. 추측 기반 수정을 막는다.
+3. 실패를 테스트로 고정한 뒤 수정한다.
+
+## Hard Gates
+
+다음 규칙은 예외 없이 따른다.
+
+1. **재현 또는 관측 가능 상태를 만들기 전에는 수정하지 않는다.**
+2. **원인 가설을 명시하기 전에는 수정하지 않는다.**
+3. **실패 테스트 또는 동등한 재현 장치를 만들기 전에는 수정하지 않는다.**
+4. **한 번에 하나의 가설만 검증한다.**
+5. **수정 시 "while I'm here" 리팩터링을 금지한다.**
+6. **수정 시도가 3번 실패하면 추가 패치 전에 구조적 문제를 의심한다.**
+
+이 과정을 어기는 것은 디버깅 실패로 본다.
+
+## When To Use
+
+다음 상황이면 이 스킬을 사용한다.
+
+- 테스트가 실패할 때
+- 운영 또는 로컬에서 버그가 발생할 때
+- 예상과 다른 응답, 상태, 렌더링, 쿼리 결과가 나올 때
+- 성능 저하, 타임아웃, 레이스 컨디션, 간헐 실패를 조사할 때
+- 이미 한 번 이상 고쳤는데 다시 깨졌을 때
+
+다음 핑계는 허용하지 않는다.
+
+- "간단해 보여서 바로 고치면 된다"
+- "시간이 없으니 일단 패치하고 보자"
+- "이거 같으니까 그냥 바꿔보자"
+
+## Required Output Contract
+
+이 스킬을 사용할 때는 내부적으로 아래 항목을 반드시 고정한다.
+
+1. **Problem statement**: 무엇이 잘못되었는지 한 문장으로 정의
+2. **Reproduction path**: 어떻게 실패를 재현하거나 관측할지
+3. **Evidence**: 실제 관측 결과
+4. **Root-cause hypothesis**: 왜 이 문제가 발생한다고 보는지
+5. **Failing guard**: 실패 테스트, 재현 스크립트, 로그 검증 중 하나
+6. **Fix**: 원인에 대한 단일 수정
+7. **Verification**: 수정 후 재현 경로와 관련 테스트 결과
+
+이 7개 중 빠진 항목이 있으면 아직 끝난 일이 아니다.
+
+## Workflow
+
+반드시 아래 순서로 진행한다.
+
+### Phase 1. Define The Problem
+
+먼저 문제를 축약한다.
+
+- 실제 기대 동작은 무엇인가
+- 실제 관측 동작은 무엇인가
+- 영향 범위는 어디까지인가
+- 항상 재현되는가, 간헐적인가
+
+출력 형식:
+
+```text
+Problem: <expected> but got <actual> under <condition>
+```
+
+증상과 추측을 섞지 않는다.
+
+```text
+Good: Product detail API returns 500 when brand is null.
+Bad: Serializer is broken because brand mapping seems wrong.
+```
+
+### Phase 2. Reproduce Or Instrument
+
+수정 전에 실패를 다시 볼 수 있어야 한다.
+
+우선순위:
+
+1. 기존 테스트로 재현
+2. 최소 통합 테스트로 재현
+3. 단위 테스트로 재현
+4. 재현 스크립트 또는 명령으로 관측
+5. 로그/계측 추가 후 관측
+
+규칙:
+
+- 재현 경로는 가능한 한 가장 작게 만든다.
+- UI에서만 보이는 버그라도 더 아래 계층에서 재현 가능하면 그쪽을 선호한다.
+- 간헐 실패면 로그, 입력, 시간, 동시성 조건을 추가해 관측성을 높인다.
+- 재현되지 않으면 수정으로 넘어가지 말고 관측 수단을 늘린다.
+
+재현 불가 상태에서 해야 할 일:
+
+1. 입력값 기록
+2. 환경 차이 확인
+3. 최근 변경점 확인
+4. 경계 지점별 로그 추가
+5. 동일 증상을 만드는 더 작은 조건 탐색
+
+### Phase 3. Gather Evidence
+
+관측 가능한 사실만 모은다.
+
+항상 확인할 것:
+
+- 에러 메시지와 스택트레이스 전문
+- 실패 입력값
+- 최근 변경 파일 또는 커밋
+- 환경/설정 차이
+- 호출 경로와 데이터 흐름
+
+멀티 컴포넌트 문제에서는 경계마다 확인한다.
+
+예시:
+
+- controller -> application -> service -> repository
+- client -> API -> external service
+- scheduler -> batch service -> database
+
+각 경계에서 확인할 것:
+
+- 무엇이 들어왔는가
+- 무엇이 나갔는가
+- 어떤 값이 변형되었는가
+- 어떤 조건에서만 깨지는가
+
+문제 위치를 특정하기 전에는 고치지 않는다.
+
+### Phase 4. Isolate Root Cause
+
+원인 후보를 하나만 세운다.
+
+형식:
+
+```text
+Hypothesis: <root cause> because <evidence>
+```
+
+좋은 가설의 조건:
+
+- 단일 원인을 가리킨다
+- 관측 증거와 연결된다
+- 작은 실험으로 반증 가능하다
+
+나쁜 가설의 예:
+
+- "어딘가 비동기 문제가 있는 것 같다"
+- "직렬화 쪽 전체가 불안정한 듯하다"
+
+원인을 소스까지 거슬러 올라간다. 오류가 깊은 스택에서 보이면 증상이 아니라 입력의 출처를 추적한다.
+
+### Phase 5. Lock The Failure
+
+수정 전에 실패를 고정한다.
+
+우선순위:
+
+1. 자동화된 failing test
+2. 기존 테스트에 회귀 케이스 추가
+3. 최소 재현 스크립트
+4. 로그/어설션 기반 임시 검증 장치
+
+규칙:
+
+- 가능하면 자동화 테스트를 만든다.
+- 수정 전에는 실패해야 한다.
+- 수정 후에는 같은 경로에서 통과해야 한다.
+- 테스트 이름은 무엇이 깨졌는지 드러내야 한다.
+
+자동화 테스트를 쓸 수 있으면 `test-driven-development` 스킬을 함께 사용한다.
+
+### Phase 6. Implement A Single Fix
+
+수정은 하나의 가설만 다룬다.
+
+허용:
+
+- 원인에 직접 대응하는 최소 코드 변경
+- 검증에 필요한 최소한의 보조 수정
+
+금지:
+
+- 관련 있어 보이는 여러 수정 묶기
+- 리팩터링 겸 수정
+- 포맷/정리/이름 변경 끼워넣기
+- 근거 없는 null-guard 추가
+- 예외 삼키기
+
+실패하면 즉시 다시 Phase 1 또는 Phase 3으로 돌아간다. 이전 가설이 틀렸다는 뜻이다.
+
+### Phase 7. Verify And Close
+
+아래를 모두 만족해야 종료한다.
+
+1. 원래 재현 경로가 더 이상 실패하지 않는다.
+2. 새 failing guard가 통과한다.
+3. 관련 테스트가 깨지지 않는다.
+4. 수정이 증상이 아니라 원인을 막는다는 설명이 가능하다.
+
+간헐 버그라면 한 번 통과로 끝내지 않는다. 반복 실행 또는 조건 변화 하 검증이 필요하다.
+
+## Stop Conditions
+
+다음 상황이면 멈추고 프레임을 다시 잡는다.
+
+### 1. Reproduction Failed
+
+여러 번 시도해도 재현이 안 되면:
+
+- 관측 수단이 부족한지 본다.
+- 환경 차이가 있는지 본다.
+- 문제 정의가 잘못되었는지 본다.
+
+재현이 안 되는데 코드를 바꾸는 것은 금지다.
+
+### 2. Three Failed Fixes
+
+세 번 연속으로 수정이 빗나가면 이렇게 판단한다.
+
+- 현재 이해가 틀렸거나
+- 문제가 공유 상태, 경계 설계, 책임 분리 같은 구조 문제일 가능성이 크다
+
+이 시점부터는 "네 번째 땜질"이 아니라 구조 논의가 필요하다.
+
+### 3. No Failing Guard
+
+실패 테스트나 동등한 재현 장치를 만들 수 없으면, 완료로 선언하지 않는다. 최소한 재현 명령과 관측 결과를 남긴다.
+
+## Red Flags
+
+아래 생각이 들면 즉시 멈추고 앞 단계로 돌아간다.
+
+- "이 줄만 바꿔보면 될 것 같다"
+- "로그는 나중에 보고 일단 수정해보자"
+- "테스트는 나중에 추가하지 뭐"
+- "한 번에 이것도 저것도 같이 고치자"
+- "에러는 사라졌으니 원인은 몰라도 됐다"
+
+## Minimal Checklist
+
+실행 중에는 아래 체크리스트를 기준으로 스스로 검증한다.
+
+- [ ] 문제를 한 문장으로 정의했다
+- [ ] 실패를 재현하거나 관측 가능하게 만들었다
+- [ ] 증거를 수집했다
+- [ ] 단일 원인 가설을 만들었다
+- [ ] 수정 전 실패 guard를 만들었다
+- [ ] 단일 수정만 적용했다
+- [ ] 같은 경로로 수정 후 검증했다
+
+## Completion Standard
+
+이 스킬의 완료 기준은 "코드가 바뀌었다"가 아니다.
+
+완료 기준:
+
+- 문제 정의가 명확하다
+- 실패가 수정 전에 고정되었다
+- 수정이 원인과 연결된다
+- 검증 결과가 남아 있다
+
+이 네 가지가 없으면 디버깅은 끝난 것이 아니다.
+
+## Reference Materials
+
+This skill includes reference documents for specific debugging techniques:
+
+- `root-cause-tracing.md` — Tracing bugs back through call chains to the original trigger
+- `defense-in-depth.md` — Adding validation at every layer to make bugs structurally impossible
+- `condition-based-waiting.md` — Replacing arbitrary delays with condition-based polling
+- `find-polluter.sh` — Bisection script for finding test pollution sources
+- `condition-based-waiting-example.ts` — Complete implementation of condition-based waiting utilities

package/templates/.claude/skills/systematic-debugging/condition-based-waiting-example.ts

@@ -0,0 +1,278 @@
+// Source: https://github.com/tmdgusya/engineering-disciplines (MIT License)
+// Complete implementation of condition-based waiting utilities
+
+import { access, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+// ============================================================
+// Core waitUntil implementation
+// ============================================================
+
+export interface WaitOptions {
+  /** Maximum wait time in milliseconds. Default: 5000 */
+  timeout?: number;
+  /** Polling interval in milliseconds. Default: 100 */
+  interval?: number;
+  /** Error message to show on timeout */
+  message?: string;
+}
+
+/**
+ * Waits until the condition returns true, polling at the specified interval.
+ * Throws a timeout error if the condition is not met within the timeout period.
+ *
+ * @example
+ * // Wait for a file to exist
+ * await waitUntil(
+ *   () => fileExists('/path/to/file'),
+ *   { timeout: 5000, message: 'File was not created' }
+ * );
+ */
+export async function waitUntil(
+  condition: () => boolean | Promise<boolean>,
+  options: WaitOptions = {}
+): Promise<void> {
+  const { timeout = 5000, interval = 100, message = 'Condition was not met' } = options;
+  const deadline = Date.now() + timeout;
+
+  while (Date.now() < deadline) {
+    const result = await condition();
+    if (result) return;
+    await sleep(interval);
+  }
+
+  throw new Error(`waitUntil timeout after ${timeout}ms: ${message}`);
+}
+
+/**
+ * Waits until the condition returns a truthy value (not undefined/null/false),
+ * then returns that value.
+ *
+ * @example
+ * const record = await waitFor(
+ *   () => db.find({ id: 'expected-id' }),
+ *   { timeout: 3000, message: 'Record was not created' }
+ * );
+ */
+export async function waitFor<T>(
+  condition: () => T | Promise<T>,
+  options: WaitOptions = {}
+): Promise<T> {
+  const { timeout = 5000, interval = 100, message = 'Value was not available' } = options;
+  const deadline = Date.now() + timeout;
+
+  while (Date.now() < deadline) {
+    const result = await condition();
+    if (result) return result;
+    await sleep(interval);
+  }
+
+  throw new Error(`waitFor timeout after ${timeout}ms: ${message}`);
+}
+
+// ============================================================
+// Common condition helpers
+// ============================================================
+
+/**
+ * Returns true if the file exists and is accessible.
+ */
+export async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Returns true if the file exists and has content (size > 0).
+ */
+export async function fileHasContent(filePath: string): Promise<boolean> {
+  try {
+    const stats = await stat(filePath);
+    return stats.size > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Returns true if the file exists and contains the expected text.
+ */
+export async function fileContains(filePath: string, text: string): Promise<boolean> {
+  try {
+    const content = await readFile(filePath, 'utf-8');
+    return content.includes(text);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Returns true if the HTTP endpoint responds with a successful status code.
+ */
+export async function httpEndpointReady(url: string): Promise<boolean> {
+  try {
+    const response = await fetch(url, { signal: AbortSignal.timeout(1000) });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Returns true if all files in the list exist.
+ */
+export async function allFilesExist(filePaths: string[]): Promise<boolean> {
+  const results = await Promise.all(filePaths.map(fileExists));
+  return results.every(Boolean);
+}
+
+// ============================================================
+// Convenience waiters
+// ============================================================
+
+/**
+ * Waits for a file to exist.
+ *
+ * @example
+ * await waitForFile('/path/to/output.json', { timeout: 5000 });
+ */
+export async function waitForFile(filePath: string, options: WaitOptions = {}): Promise<void> {
+  await waitUntil(() => fileExists(filePath), {
+    timeout: 5000,
+    message: `File not created: ${filePath}`,
+    ...options,
+  });
+}
+
+/**
+ * Waits for a file to contain specific text.
+ *
+ * @example
+ * await waitForFileContent('/path/to/log.txt', 'Server started', { timeout: 10000 });
+ */
+export async function waitForFileContent(
+  filePath: string,
+  text: string,
+  options: WaitOptions = {}
+): Promise<void> {
+  await waitUntil(() => fileContains(filePath, text), {
+    timeout: 5000,
+    message: `File ${filePath} did not contain: ${text}`,
+    ...options,
+  });
+}
+
+/**
+ * Waits for an HTTP endpoint to respond with a successful status.
+ *
+ * @example
+ * await waitForServer('http://localhost:3000/health', { timeout: 15000 });
+ */
+export async function waitForServer(url: string, options: WaitOptions = {}): Promise<void> {
+  await waitUntil(() => httpEndpointReady(url), {
+    timeout: 15000,
+    interval: 300,
+    message: `Server at ${url} did not become ready`,
+    ...options,
+  });
+}
+
+/**
+ * Waits for a directory to contain at least minCount files.
+ *
+ * @example
+ * await waitForDirectoryCount('/output/dir', 3, { timeout: 5000 });
+ */
+export async function waitForDirectoryCount(
+  dirPath: string,
+  minCount: number,
+  options: WaitOptions = {}
+): Promise<void> {
+  const { readdir } = await import('node:fs/promises');
+  await waitUntil(
+    async () => {
+      try {
+        const entries = await readdir(dirPath);
+        return entries.length >= minCount;
+      } catch {
+        return false;
+      }
+    },
+    {
+      timeout: 5000,
+      message: `Directory ${dirPath} did not reach ${minCount} files`,
+      ...options,
+    }
+  );
+}
+
+// ============================================================
+// Utilities
+// ============================================================
+
+/**
+ * Sleep for the specified number of milliseconds.
+ */
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ============================================================
+// Usage examples (not for import, documentation only)
+// ============================================================
+
+/*
+// Example 1: Wait for build output file
+await waitForFile(join(outputDir, 'bundle.js'), { timeout: 30000 });
+
+// Example 2: Wait for server to start
+await waitForServer('http://localhost:8080/health', { timeout: 20000 });
+
+// Example 3: Wait for database record with custom condition
+const user = await waitFor(
+  async () => {
+    const u = await db.users.findUnique({ where: { email: 'test@example.com' } });
+    return u?.emailVerified ? u : null;
+  },
+  { timeout: 5000, message: 'User email was not verified' }
+);
+
+// Example 4: Wait for process output
+const logs: string[] = [];
+const proc = spawn('npm', ['start']);
+proc.stdout.on('data', (chunk) => logs.push(chunk.toString()));
+
+await waitUntil(
+  () => logs.some((line) => line.includes('Listening on port')),
+  { timeout: 15000, interval: 200, message: 'Server did not log startup message' }
+);
+
+// Example 5: Wait for all output files to be generated
+const expectedFiles = ['report.json', 'summary.txt', 'data.csv'].map((f) =>
+  join(outputDir, f)
+);
+await waitUntil(() => allFilesExist(expectedFiles), {
+  timeout: 10000,
+  message: `Not all output files were generated in ${outputDir}`,
+});
+
+// Example 6: Test that verifies count reaches expected value
+it('should process all items', async () => {
+  await triggerBatchProcessing(items);
+
+  await waitUntil(
+    async () => {
+      const processed = await db.items.count({ where: { status: 'done' } });
+      return processed >= items.length;
+    },
+    { timeout: 5000, message: `Expected ${items.length} items to be processed` }
+  );
+
+  const processed = await db.items.count({ where: { status: 'done' } });
+  expect(processed).toBe(items.length);
+});
+*/