@silbaram/artifact-driven-agent 0.1.7 → 0.2.3

package/core/skills/testing-patterns/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: testing-patterns
+description: 테스트 코드 작성 시 적용되는 패턴. 단위/통합/E2E 테스트 구조, 네이밍 규칙, 모킹 전략을 포함한다.
+---
+
+# Testing Patterns
+
+이 스킬은 테스트 코드를 작성하거나 기존 테스트를 수정할 때 적용됩니다.
+언어/프레임워크에 무관하게 적용되는 보편 원칙입니다.
+
+## 핵심 규칙
+
+1. **테스트는 독립적이어야 한다**: 각 테스트는 다른 테스트에 의존하지 않고 단독 실행 가능해야 한다.
+2. **하나의 테스트는 하나의 동작만 검증한다**: 여러 동작을 한 테스트에 넣지 않는다.
+3. **테스트 이름만으로 의도를 파악할 수 있어야 한다**: 실패 시 이름만 보고 원인을 추론할 수 있어야 한다.
+4. **외부 의존성은 반드시 격리한다**: DB, 네트워크, 파일시스템 등은 모킹하거나 테스트용 인스턴스를 사용한다.
+5. **테스트 코드도 프로덕션 코드와 동일한 품질 기준을 적용한다**: 중복 제거, 가독성, 유지보수성을 유지한다.
+
+## 패턴 및 예시
+
+### 패턴 1: AAA (Arrange-Act-Assert)
+
+모든 테스트는 3단계로 구성한다. 단계 사이에 빈 줄로 구분하여 가독성을 확보한다.
+
+```
+test "장바구니에 상품 추가 시 총액이 갱신된다":
+  // Arrange - 테스트 전제 조건 설정
+  cart = new Cart()
+  item = { id: "item-1", name: "키보드", price: 50000 }
+
+  // Act - 테스트 대상 동작 실행
+  cart.addItem(item)
+
+  // Assert - 결과 검증
+  assert cart.totalPrice == 50000
+  assert cart.items.length == 1
+```
+
+### 패턴 2: 테스트 네이밍 규칙
+
+테스트 이름은 **[대상]_[조건]_[기대결과]** 또는 자연어 서술 형식을 사용한다.
+
+```
+// 형식 1: 구조화된 네이밍
+test "calculateDiscount_회원등급이_VIP일때_20퍼센트_할인"
+
+// 형식 2: 자연어 서술 (권장)
+test "VIP 회원은 20% 할인을 받는다"
+
+// 형식 3: 그룹 + 개별 테스트 조합
+group "할인 계산":
+  test "VIP 회원은 20% 할인을 받는다"
+  test "일반 회원은 할인이 없다"
+  test "쿠폰과 등급 할인은 중복 적용되지 않는다"
+```
+
+### 패턴 3: 테스트 픽스처 (Test Fixture)
+
+반복되는 설정은 헬퍼 함수로 추출한다. 단, 테스트 내에서 핵심 값은 명시적으로 보여야 한다.
+
+```
+// 팩토리 함수 - 기본값 + 오버라이드
+function createUser(overrides):
+  return merge({
+    id: "user-1",
+    name: "테스트유저",
+    email: "test@example.com",
+    role: "member",
+  }, overrides)
+
+test "관리자는 사용자를 삭제할 수 있다":
+  admin = createUser({ role: "admin" })   // 핵심 값 명시
+  target = createUser({ id: "user-2" })
+
+  result = deleteUser(admin, target.id)
+
+  assert result.success == true
+```
+
+### 패턴 4: 모킹 전략
+
+외부 의존성의 모킹 범위를 최소한으로 유지한다.
+
+```
+// 의존성 주입 방식 (권장)
+test "주문 생성 시 결제 서비스를 호출한다":
+  mockPayment = mock({ charge: returns({ success: true }) })
+  orderService = new OrderService(mockPayment)
+
+  orderService.createOrder({ amount: 10000 })
+
+  assert mockPayment.charge.calledOnce == true
+
+// 모듈 모킹 (외부 라이브러리)
+// 프레임워크별 방식을 따르되, 모킹 범위를 테스트 단위로 제한한다.
+```
+
+### 패턴 5: 경계값 테스트
+
+비즈니스 로직의 경계 조건을 명시적으로 테스트한다.
+
+```
+group "비밀번호 검증":
+  // 경계값: 최소 길이
+  test "7자 비밀번호는 거부된다":
+    assert validatePassword("1234567") == false
+
+  test "8자 비밀번호는 허용된다":
+    assert validatePassword("12345678") == true
+
+  // 특수 케이스
+  test "빈 문자열은 거부된다":
+    assert validatePassword("") == false
+```
+
+## 테스트 유형별 가이드
+
+### 단위 테스트 (Unit)
+- 단일 함수/클래스의 로직 검증
+- 외부 의존성 전부 모킹
+- 실행 시간: 각 테스트 100ms 이내
+- 커버리지 목표: 비즈니스 로직 80% 이상
+
+### 통합 테스트 (Integration)
+- 여러 모듈 간 상호작용 검증
+- 실제 DB/파일시스템 사용 가능 (테스트용 인스턴스)
+- 테스트 간 상태 격리 필수 (setup/teardown)
+
+### E2E 테스트 (End-to-End)
+- 사용자 시나리오 기반 전체 흐름 검증
+- 핵심 사용자 경로(happy path)에 집중
+- 불안정한 테스트(flaky test)는 즉시 수정하거나 격리
+
+## 주의사항
+
+- 구현 세부사항이 아닌 **동작(행위)**을 테스트한다
+- 100% 커버리지를 목표로 하지 않는다. 의미 있는 테스트에 집중한다
+- 테스트가 깨지면 프로덕션 코드보다 먼저 확인한다
+- 테스트 실행 속도가 느려지면 병렬 실행, 모킹 범위 조정 등을 검토한다
+- sleep/delay 기반의 대기 테스트는 피한다. 이벤트/폴링 기반으로 대체한다

package/dist/bin/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/cli.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+import { program } from 'commander';
+import { setup } from '../src/commands/setup.js';
+import { status } from '../src/commands/status.js';
+import { reset } from '../src/commands/reset.js';
+import { validate } from '../src/commands/validate.js';
+import { sessions } from '../src/commands/sessions.js';
+import { logs } from '../src/commands/logs.js';
+import { run } from '../src/commands/run.js';
+import { config } from '../src/commands/config.js';
+import { interactive } from '../src/commands/interactive.js';
+import { upgrade } from '../src/commands/upgrade.js';
+import { monitor } from '../src/commands/monitor.js';
+import sprint from '../src/commands/sprint.js';
+import docs from '../src/commands/docs.js';
+import { skills } from '../src/commands/skills.js';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const { version } = require('../../package.json');
+program
+    .name('ada')
+    .description('Artifact-Driven AI Agent Framework\nAI가 규칙을 어기지 못하게 하는 문서 기반 개발')
+    .version(version)
+    .option('-m, --monitor', 'UI 모드 실행 (인터랙티브 인터페이스)');
+// Setup command
+program
+    .command('setup [template]')
+    .description('프로젝트 템플릿 세팅 (web, library, game, cli)')
+    .action(setup);
+// Status command
+program
+    .command('status')
+    .description('현재 세팅 상태 확인')
+    .action(status);
+// Reset command
+program
+    .command('reset')
+    .description('ai-dev-team 초기화')
+    .option('-f, --force', '확인 없이 강제 초기화')
+    .action(reset);
+// Upgrade command
+program
+    .command('upgrade')
+    .description('작업공간을 최신 버전으로 업그레이드')
+    .option('-f, --force', '확인 없이 강제 업그레이드')
+    .option('--dry-run', '변경 사항 미리보기 (실제 변경 없음)')
+    .option('--rollback', '이전 백업으로 롤백')
+    .action(upgrade);
+// Validate command
+program
+    .command('validate [doc]')
+    .description('문서 검증 (plan, project, backlog, sprint 또는 전체)')
+    .action(validate);
+// Sessions command
+program
+    .command('sessions')
+    .description('AI 실행 세션 목록')
+    .option('-w, --watch', '실시간 모니터링 모드')
+    .option('-c, --clean', '완료된 세션 정리')
+    .action(sessions);
+// Logs command
+program
+    .command('logs [sessionId]')
+    .description('세션 로그 확인')
+    .action(logs);
+// Sprint command
+program
+    .command('sprint <action> [tasks...]')
+    .description('스프린트 관리 (create, add, close, list)')
+    .action(sprint);
+// Docs command
+program
+    .command('docs <action>')
+    .description('문서 관리 (init, generate, publish, serve)')
+    .option('-g, --generator <type>', '문서 생성기 (mkdocs, jekyll)')
+    .action(docs);
+// Skills command
+program
+    .command('skills [action] [args...]')
+    .description('스킬 관리 (list, info, apply, remove, status, ui)')
+    .action(skills);
+// Monitor command (UI 모드)
+program
+    .command('monitor')
+    .alias('m')
+    .description('UI 모드 (인터랙티브 인터페이스)')
+    .action(monitor);
+// Config command
+program
+    .command('config [action] [key] [value]')
+    .description('설정 조회/변경 (대화형), show, get <key>, set <key> <value>')
+    .action(config);
+// Run command
+program
+    .command('run <role> [tool]')
+    .description('AI 에이전트 실행 (예: run backend [claude])')
+    .action(run);
+// Parse arguments
+const args = process.argv.slice(2);
+// 명령어 목록
+const COMMANDS = ['setup', 'status', 'reset', 'upgrade', 'validate', 'sessions', 'logs', 'run', 'sprint', 'docs', 'skills', 'config', 'monitor', 'm'];
+if (args.length === 0) {
+    // 인자 없으면 대화형 모드
+    interactive();
+}
+else if (args.includes('-m') || args.includes('--monitor')) {
+    // -m 또는 --monitor 옵션이 있으면 대시보드 실행
+    monitor();
+}
+else if (args.length === 2 && !args[0].startsWith('-') && !COMMANDS.includes(args[0])) {
+    // 두 개의 인자가 명령어가 아니면 role tool로 간주 (간편 실행)
+    run(args[0], args[1]);
+}
+else if (args.length === 1 && !args[0].startsWith('-') && !COMMANDS.includes(args[0])) {
+    // 인자가 하나면 role로 간주하고 도구는 자동 선택
+    run(args[0]);
+}
+else {
+    program.parse();
+}
+//# sourceMappingURL=cli.js.map

package/dist/bin/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../bin/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AACjD,OAAO,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AACvD,OAAO,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAC/C,OAAO,EAAE,GAAG,EAAE,MAAM,wBAAwB,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAC7D,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AACrD,OAAO,MAAM,MAAM,2BAA2B,CAAC;AAC/C,OAAO,IAAI,MAAM,yBAAyB,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAElD,OAAO;KACJ,IAAI,CAAC,KAAK,CAAC;KACX,WAAW,CAAC,iEAAiE,CAAC;KAC9E,OAAO,CAAC,OAAO,CAAC;KAChB,MAAM,CAAC,eAAe,EAAE,wBAAwB,CAAC,CAAC;AAErD,gBAAgB;AAChB,OAAO;KACJ,OAAO,CAAC,kBAAkB,CAAC;KAC3B,WAAW,CAAC,uCAAuC,CAAC;KACpD,MAAM,CAAC,KAAK,CAAC,CAAC;AAEjB,iBAAiB;AACjB,OAAO;KACJ,OAAO,CAAC,QAAQ,CAAC;KACjB,WAAW,CAAC,aAAa,CAAC;KAC1B,MAAM,CAAC,MAAM,CAAC,CAAC;AAElB,gBAAgB;AAChB,OAAO;KACJ,OAAO,CAAC,OAAO,CAAC;KAChB,WAAW,CAAC,iBAAiB,CAAC;KAC9B,MAAM,CAAC,aAAa,EAAE,cAAc,CAAC;KACrC,MAAM,CAAC,KAAK,CAAC,CAAC;AAEjB,kBAAkB;AAClB,OAAO;KACJ,OAAO,CAAC,SAAS,CAAC;KAClB,WAAW,CAAC,qBAAqB,CAAC;KAClC,MAAM,CAAC,aAAa,EAAE,gBAAgB,CAAC;KACvC,MAAM,CAAC,WAAW,EAAE,uBAAuB,CAAC;KAC5C,MAAM,CAAC,YAAY,EAAE,YAAY,CAAC;KAClC,MAAM,CAAC,OAAO,CAAC,CAAC;AAEnB,mBAAmB;AACnB,OAAO;KACJ,OAAO,CAAC,gBAAgB,CAAC;KACzB,WAAW,CAAC,8CAA8C,CAAC;KAC3D,MAAM,CAAC,QAAQ,CAAC,CAAC;AAEpB,mBAAmB;AACnB,OAAO;KACJ,OAAO,CAAC,UAAU,CAAC;KACnB,WAAW,CAAC,aAAa,CAAC;KAC1B,MAAM,CAAC,aAAa,EAAE,aAAa,CAAC;KACpC,MAAM,CAAC,aAAa,EAAE,WAAW,CAAC;KAClC,MAAM,CAAC,QAAQ,CAAC,CAAC;AAEpB,eAAe;AACf,OAAO;KACJ,OAAO,CAAC,kBAAkB,CAAC;KAC3B,WAAW,CAAC,UAAU,CAAC;KACvB,MAAM,CAAC,IAAI,CAAC,CAAC;AAEhB,iBAAiB;AACjB,OAAO;KACJ,OAAO,CAAC,4BAA4B,CAAC;KACrC,WAAW,CAAC,oCAAoC,CAAC;KACjD,MAAM,CAAC,MAAM,CAAC,CAAC;AAElB,eAAe;AACf,OAAO;KACJ,OAAO,CAAC,eAAe,CAAC;KACxB,WAAW,CAAC,wCAAwC,CAAC;KACrD,MAAM,CAAC,wBAAwB,EAAE,yBAAyB,CAAC;KAC3D,MAAM,CAAC,IAAI,CAAC,CAAC;AAEhB,iBAAiB;AACjB,OAAO;KACJ,OAAO,CAAC,2BAA2B,CAAC;KACpC,WAAW,CAAC,+CAA+C,CAAC;KAC5D,MAAM,CAAC,MAAM,CAAC,CAAC;AAElB,0BAA0B;AAC1B,OAAO;KACJ,OAAO,CAAC,SAAS,CAAC;KAClB,KAAK,CAAC,GAAG,CAAC;KACV,WAAW,CAAC,qBAAqB,CAAC;KAClC,MAAM,CAAC,OAAO,CAAC,CAAC;AAEnB,iBAAiB;AACjB,OAAO;KACJ,OAAO,CAAC,+BAA+B,CAAC;KACxC,WAAW,CAAC,oDAAoD,CAAC;KACjE,MAAM,CAAC,MAAM,CAAC,CAAC;AAElB,cAAc;AACd,OAAO;KACJ,OAAO,CAAC,mBAAmB,CAAC;KAC5B,WAAW,CAAC,sCAAsC,CAAC;KACnD,MAAM,CAAC,GAAG,CAAC,CAAC;AAEf,kBAAkB;AAClB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAEnC,SAAS;AACT,MAAM,QAAQ,GAAG,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;AAEtJ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;IACtB,gBAAgB;IAChB,WAAW,EAAE,CAAC;AAChB,CAAC;KAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;IAC7D,kCAAkC;IAClC,OAAO,EAAE,CAAC;AACZ,CAAC;KAAM,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACxF,0CAA0C;IAC1C,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACxB,CAAC;KAAM,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACxF,+BAA+B;IAC/B,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACf,CAAC;KAAM,CAAC;IACN,OAAO,CAAC,KAAK,EAAE,CAAC;AAClB,CAAC"}

package/dist/src/commands/config.d.ts

@@ -0,0 +1,4 @@
+/**
+ * [CLI] 설정 관리 명령어
+ */
+export declare function config(action?: string, key?: string, ...values: string[]): Promise<void>;