@walwal-harness/cli 5.5.3 → 5.6.1

package/README.md

@@ -92,7 +92,17 @@ npx walwal-harness team
 - 단축키: `tmux prefix + 방향키` 로 패널 이동, `prefix + z` 로 확대/축소.
 - 종료: `npx walwal-harness team --kill`.
 
-### Step 5. Gotcha 등록 — 같은 실수 반복 막기
+### Step 5. Feedback 등록 — 학습 누적
+
+대화 중 사용자 피드백은 **성격에 따라 3개 저장소** 중 하나로 자동 분류됩니다.
+
+| 유형 | 성격 | 시그널 | 저장 위치 | ID |
+|------|------|--------|----------|-----|
+| **Gotcha** | 에이전트 실수(부정) | "~하지 마", "잘못됐어" | `.harness/gotchas/<agent>.md` | `G-NNN` |
+| **Convention** | 하우스 스타일(긍정) | "~해야 해", "이렇게 해줘" | `.harness/conventions/<scope>.md` | `C-NNN` |
+| **Memory** | 전체 공통 교훈 | "모든 에이전트가~" | `.harness/memory.md` | `M-NNN` |
+
+#### 5a. Gotcha — "이러면 안 돼"
 
 사용자가 에이전트의 실수를 지적하면 Dispatcher 가 해당 에이전트의 `.harness/gotchas/<agent>.md` 에 자동 append. 다음 세션부터 그 에이전트는 세션 시작 시 자기 gotcha 파일을 읽고 같은 실수를 피합니다.
 
@@ -122,7 +132,60 @@ Dispatcher 는 자동으로 분류:
 - **Applies to**: generator-backend
 ```
 
-#### 공유 메모리 (프로젝트 전체 규칙)
+#### 5b. Convention — "이렇게 해줘"
+
+긍정 가이드는 하우스 스타일로 등록됩니다:
+
+```
+API 응답 필드는 전부 snake_case 로 해야 해. FE TS 모델이
+snake_case 로 정의돼 있어서 변환 레이어를 두기 싫어.
+```
+
+Dispatcher 자동 분류:
+- **스코프**: `generator-backend` (API 응답 → BE 스코프)
+- **저장 위치**: `.harness/conventions/generator-backend.md`
+- **ID 할당**: `[C-001]` (해당 파일의 기존 최댓값 + 1)
+
+기록 포맷 (자동 작성):
+
+```markdown
+### [C-001] API 응답 필드는 snake_case
+- **Date**: 2026-04-22
+- **Scope**: generator-backend
+- **Rule**: 모든 API 응답 JSON 필드는 snake_case (created_at, user_id 등).
+- **Rationale**: FE TS 모델이 snake_case 로 정의돼 있어 변환 레이어 불필요.
+- **Applies to**: generator-backend, libs/shared-dto
+- **Added from**: user prompt (2026-04-22 16:12)
+```
+
+#### 스코프 판별 (Convention)
+
+| 키워드 | 스코프 (파일) |
+|--------|-------------|
+| backend, API, controller, service, DTO, NestJS | `generator-backend.md` |
+| frontend, React, Next.js, UI, component, hook | `generator-frontend.md` |
+| plan, sprint, feature-list | `planner.md` |
+| Playwright, E2E, browser | `evaluator-functional.md` |
+| layout, screenshot, a11y, responsive | `evaluator-visual.md` |
+| code quality, lint, architecture | `evaluator-code-quality.md` |
+| 매칭 실패 + 에이전트 국한 | `shared.md` |
+| 프로젝트 철학 (예: "우리는 TDD") | 루트 `CONVENTIONS.md` 권고 |
+
+#### 에이전트 와이어링
+
+각 에이전트는 세션 시작 시 다음 순서로 읽고 적용:
+
+```
+1. CONVENTIONS.md              (루트, 최상위 원칙)
+2. .harness/conventions/shared.md      (공통)
+3. .harness/conventions/<self>.md      (자기 스코프)
+4. .harness/gotchas/<self>.md          (과거 실수)
+5. .harness/memory.md                  (공유 교훈)
+```
+
+충돌 시 우선순위: `<self>` > `shared` > 루트.
+
+#### 5c. Memory — 프로젝트 전체 규칙
 
 한 에이전트 실수가 아니라 **모든 에이전트에 적용할 구조적 교훈** 이면 `.harness/memory.md` 로 승격:
 
@@ -136,7 +199,18 @@ Dispatcher 는 자동으로 분류:
 
 #### 주의 — 데이터 보존
 
-v5.5.2 부터 `npm install` postinstall 이 `### [G-NNN]` 엔트리가 있는 gotcha 파일을 **절대 덮어쓰지 않습니다**. 그 이전 버전에서는 업데이트 시 누적 기록이 템플릿으로 초기화되는 버그가 있었습니다 — 반드시 `5.5.2+` 를 사용하세요.
+`npm install` postinstall 은 **누적 엔트리(`[G-NNN]` 또는 `[C-NNN]`)가 있는 파일을 절대 덮어쓰지 않습니다**. 스캐폴드 템플릿인 경우에만 갱신됩니다. v5.5.2 이전 버전은 gotchas 에 이 버그가 있었으므로 `5.6.0+` 사용을 권장합니다.
+
+#### 기존 프로젝트 마이그레이션 (첫 설치 시 자동)
+
+기존 `CLAUDE.md` / `AGENTS.md` 에 Convention/Gotcha 성격의 섹션(`Conventions`, `Coding Standards`, `Best Practices`, `Gotchas`, `Don't`, `주의사항`, `금지사항` 등)이 있다면 첫 설치 시 자동으로 추출되어:
+
+- **Convention 성격** → `.harness/conventions/<scope>.md` 에 `[C-NNN]` 으로 이관
+- **Gotcha 성격** → `.harness/gotchas/<agent>.md` 에 `[G-NNN]` 으로 이관
+- **원본** → `.harness/archive/pre-harness-*.md.bak` 에 백업
+- **리포트** → `.harness/MIGRATION_REPORT.md` 에 이관 내역 + 수동 확인 요청 사항 기록
+
+마이그레이션은 heuristic(키워드 기반)이므로 리포트를 확인해 스코프 재배정이 필요한지 검토하세요. 이미 하네스 서명(`[BE]`/`[FE]`/`[HARNESS]`)이 있는 문서는 skip 됩니다.
 
 ---
 
@@ -298,14 +372,23 @@ your-project/
 │   │   ├── evaluation-code-quality.md
 │   │   ├── evaluation-functional.md
 │   │   └── evaluation-visual.md
-│   ├── archive/                       # 완료 스프린트 보관 (불변)
-│   └── gotchas/                       # 에이전트 실수 기록 (누적 보존)
-│       ├── planner.md
-│       ├── generator-backend.md
-│       ├── generator-frontend.md
-│       ├── evaluator-code-quality.md
-│       ├── evaluator-functional.md
-│       └── evaluator-visual.md
+│   ├── archive/                       # 완료 스프린트 보관 (불변, 마이그레이션 백업도 여기)
+│   ├── gotchas/                       # 에이전트 실수 기록 [G-NNN] (누적 보존)
+│   │   ├── planner.md
+│   │   ├── generator-backend.md
+│   │   ├── generator-frontend.md
+│   │   ├── evaluator-code-quality.md
+│   │   ├── evaluator-functional.md
+│   │   └── evaluator-visual.md
+│   ├── conventions/                   # 하우스 스타일 [C-NNN] (v5.6+, 누적 보존)
+│   │   ├── shared.md
+│   │   ├── planner.md
+│   │   ├── generator-backend.md
+│   │   ├── generator-frontend.md
+│   │   ├── evaluator-code-quality.md
+│   │   ├── evaluator-functional.md
+│   │   └── evaluator-visual.md
+│   └── MIGRATION_REPORT.md            # 첫 설치 시 기존 문서 이관 내역 (있을 때만)
 ├── .claude/
 │   ├── skills/harness-*/              # 에이전트 스킬 (8개)
 │   ├── commands/harness-*.md          # 모드 제어 커맨드 (3개)
@@ -323,7 +406,8 @@ your-project/
 │   ├── harness-prompt-history.sh      # 프롬프트 히스토리
 │   └── lib/                           # 공유 라이브러리
 ├── AGENTS.md                          # 프로젝트 컨텍스트 (IA-MAP)
-└── CLAUDE.md → AGENTS.md              # 심볼릭 링크
+├── CLAUDE.md → AGENTS.md              # 심볼릭 링크
+└── CONVENTIONS.md                     # 최상위 원칙 (사용자 자유 기술, 하위는 .harness/conventions/)
 ```
 
 ---

package/assets/templates/config.json

@@ -1,8 +1,8 @@
 {
   "harness": {
     "name": "7-Agent Production Harness",
-    "version": "5.5.0",
-    "description": "Solo/Team 통합 하네스 — Dispatcher + 3-Evaluator Chain (Code-Quality → Functional → Visual) + NestJS MSA + React/Next.js + Playwright",
+    "version": "5.6.0",
+    "description": "Solo/Team 통합 하네스 — Dispatcher + 3-Evaluator Chain (Code-Quality → Functional → Visual) + Hierarchical Conventions/Gotchas + NestJS MSA + React/Next.js + Playwright",
     "source": "https://www.anthropic.com/engineering/harness-design-long-running-apps"
   },
   "agents": {
@@ -368,11 +368,17 @@
     "statuses": ["start", "complete", "fail", "pass", "skip", "warn"]
   },
   "conventions": {
-    "comment": "CONVENTIONS.md — 사용자가 자유 형식으로 작성하는 프로젝트 컨벤션. 모든 에이전트가 세션 시작 시 직접 읽음. Gotcha/AGENTS.md에 복사하지 않음.",
-    "file": "CONVENTIONS.md",
+    "comment": "House-style registry. 루트 CONVENTIONS.md(사용자 자유 기술) + .harness/conventions/<scope>.md(Dispatcher 자동 누적). 모든 에이전트가 세션 시작 시 읽고 적용한다. Gotcha 의 긍정 대칭판.",
+    "root_file": "CONVENTIONS.md",
+    "scoped_dir": ".harness/conventions/",
+    "scopes": ["shared", "planner", "generator-backend", "generator-frontend", "evaluator-code-quality", "evaluator-functional", "evaluator-visual"],
+    "entry_id_prefix": "C",
     "read_by": "all_agents",
-    "write_by": "user_only",
-    "read_timing": "session_start"
+    "read_order": ["CONVENTIONS.md", ".harness/conventions/shared.md", ".harness/conventions/<self>.md", ".harness/gotchas/<self>.md", ".harness/memory.md"],
+    "conflict_priority": "self > shared > root",
+    "write_by": "dispatcher (auto-append C-NNN) or user_only (manual edit)",
+    "read_timing": "session_start",
+    "preserve_on_postinstall": true
   },
   "recommended_skills": {
     "comment": "Claude Code에 설치하면 하네스 품질이 향상되는 외부 스킬 목록",

package/bin/init.js

@@ -90,16 +90,162 @@ function log(msg) {
   console.log(`[walwal-harness] ${msg}`);
 }
 
+// ─────────────────────────────────────────
+// First-install migration — extract Convention/Gotcha-shaped sections from
+// existing CLAUDE.md / AGENTS.md into .harness/conventions and .harness/gotchas.
+// Conservative: only triggers when these docs are NOT already harness-scaffolded
+// (detected by IA-MAP tags like "[BE]" or "[HARNESS]").
+// ─────────────────────────────────────────
+function migrateExistingDocs() {
+  // Match heading titles. Use (?=\s|$) instead of \b — Korean chars are
+  // not "word" in JS regex, so \b produces inconsistent matches.
+  const CONVENTION_HEADINGS = /^#{1,4}\s+(Conventions?|Coding Standards?|Style Guide|Rules|Guidelines|Best Practices|Do's and Don'ts|규칙|하우스 스타일|명명 규칙|코딩 규칙|코드 스타일)(?=[\s:]|$)/im;
+  const GOTCHA_HEADINGS = /^#{1,4}\s+(Gotchas?|Anti[- ]?patterns?|Don'?ts?|Avoid|Pitfalls?|주의사항|금지사항|실수|함정|안티[- ]?패턴)(?=[\s:]|$)/im;
+  const HARNESS_SIGNATURE = /\[(BE|FE|HARNESS|META|INFRA|ROOT)\]|walwal-harness|harness-dispatcher/;
+
+  const candidates = [
+    path.join(PROJECT_ROOT, 'CLAUDE.md'),
+    path.join(PROJECT_ROOT, 'AGENTS.md')
+  ];
+
+  const report = [];
+  const extractedConv = { counter: 0, byScope: {} };
+  const extractedGotcha = { counter: 0, byAgent: {} };
+
+  const scopeFor = (body) => {
+    const b = body.toLowerCase();
+    if (/\b(backend|api|nestjs|controller|dto|service|msa|repository)\b/.test(b)) return 'generator-backend';
+    if (/\b(frontend|react|next\.?js|ui|component|tsx|tailwind|hook)\b/.test(b)) return 'generator-frontend';
+    if (/\b(planner|plan\.md|sprint|feature-list|api-contract)\b/.test(b)) return 'planner';
+    if (/\b(playwright|e2e|functional test)\b/.test(b)) return 'evaluator-functional';
+    if (/\b(visual|layout|screenshot|a11y|accessibility|responsive)\b/.test(b)) return 'evaluator-visual';
+    if (/\b(code quality|lint|tsc|architecture|typescript strict)\b/.test(b)) return 'evaluator-code-quality';
+    return 'shared';
+  };
+
+  const appendEntry = (filePath, id, kind, title, body, source) => {
+    const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+    const entry = [
+      ``,
+      `### [${id}] ${title}`,
+      `- **Date**: ${new Date().toISOString().split('T')[0]}`,
+      `- **Source**: ${source} (migrated)`,
+      ``,
+      body.trim(),
+      ``
+    ].join('\n');
+    fs.writeFileSync(filePath, existing.replace(/\s*$/, '') + '\n' + entry + '\n');
+  };
+
+  for (const docPath of candidates) {
+    if (!fileExists(docPath)) continue;
+    const content = fs.readFileSync(docPath, 'utf8');
+    if (HARNESS_SIGNATURE.test(content)) {
+      // Already a harness-managed doc — skip
+      continue;
+    }
+
+    // Backup
+    const backupPath = path.join(HARNESS_DIR, 'archive', `pre-harness-${path.basename(docPath)}.bak`);
+    fs.writeFileSync(backupPath, content);
+    report.push(`Backed up: ${docPath} → ${backupPath}`);
+
+    // Split by top-level and H2 headings to get sections
+    // Simple approach: find heading lines, slice until next heading of same-or-higher level
+    const lines = content.split('\n');
+    const sections = [];
+    let current = null;
+    lines.forEach((line, idx) => {
+      const m = /^(#{1,4})\s+(.+?)\s*$/.exec(line);
+      if (m) {
+        if (current) sections.push(current);
+        current = { level: m[1].length, title: m[2], startLine: idx + 1, endLine: idx + 1, body: [] };
+      } else if (current) {
+        current.body.push(line);
+        current.endLine = idx + 1;
+      }
+    });
+    if (current) sections.push(current);
+
+    for (const sec of sections) {
+      const header = `${'#'.repeat(sec.level)} ${sec.title}`;
+      const isConv = CONVENTION_HEADINGS.test(header);
+      const isGotcha = GOTCHA_HEADINGS.test(header);
+      if (!isConv && !isGotcha) continue;
+      const body = sec.body.join('\n').trim();
+      if (!body) continue;
+
+      const sourceRef = `${path.basename(docPath)}:${sec.startLine}-${sec.endLine}`;
+
+      if (isConv) {
+        const scope = scopeFor(sec.title + '\n' + body);
+        extractedConv.counter += 1;
+        const id = `C-${String(extractedConv.counter).padStart(3, '0')}`;
+        const target = path.join(HARNESS_DIR, 'conventions', `${scope}.md`);
+        appendEntry(target, id, 'convention', sec.title, body, sourceRef);
+        extractedConv.byScope[scope] = (extractedConv.byScope[scope] || 0) + 1;
+        report.push(`[${id}] "${sec.title}" → conventions/${scope}.md  (from ${sourceRef})`);
+      } else {
+        const scope = scopeFor(sec.title + '\n' + body);
+        const agent = scope === 'shared' ? 'planner' : scope;  // default shared-gotchas to planner
+        extractedGotcha.counter += 1;
+        const id = `G-${String(extractedGotcha.counter).padStart(3, '0')}`;
+        const target = path.join(HARNESS_DIR, 'gotchas', `${agent}.md`);
+        appendEntry(target, id, 'gotcha', sec.title, body, sourceRef);
+        extractedGotcha.byAgent[agent] = (extractedGotcha.byAgent[agent] || 0) + 1;
+        report.push(`[${id}] "${sec.title}" → gotchas/${agent}.md  (from ${sourceRef})`);
+      }
+    }
+  }
+
+  if (report.length === 0) return;
+
+  const reportPath = path.join(HARNESS_DIR, 'MIGRATION_REPORT.md');
+  const reportContent = [
+    `# Walwal-Harness Migration Report`,
+    ``,
+    `Generated on first install at ${new Date().toISOString()}.`,
+    ``,
+    `## Summary`,
+    ``,
+    `- Conventions extracted: ${extractedConv.counter}`,
+    `- Gotchas extracted: ${extractedGotcha.counter}`,
+    ``,
+    `## Manual Review Required`,
+    ``,
+    `Migration is heuristic (keyword-based). Please review each extracted entry:`,
+    `- Verify scope assignment is correct`,
+    `- Split entries into smaller atomic rules if appropriate`,
+    `- Adjust wording to positive-rule form for conventions, negative/anti-pattern form for gotchas`,
+    ``,
+    `## Entries`,
+    ``,
+    ...report.map(r => `- ${r}`),
+    ``,
+    `## Backups`,
+    ``,
+    `Original documents were preserved in \`.harness/archive/pre-harness-*.md.bak\`.`,
+    ``
+  ].join('\n');
+  fs.writeFileSync(reportPath, reportContent);
+  log(`Migration: ${extractedConv.counter} convention(s), ${extractedGotcha.counter} gotcha(s) extracted.`);
+  log(`Migration report: ${reportPath}`);
+}
+
 // ─────────────────────────────────────────
 // 1. .harness/ scaffolding
 // ─────────────────────────────────────────
 function scaffoldHarness() {
   log('Scaffolding .harness/ directory...');
 
+  // Detect first install BEFORE ensureDir creates the root
+  const isFirstInstall = !fs.existsSync(HARNESS_DIR);
+
   // Core directories
   ensureDir(path.join(HARNESS_DIR, 'actions'));
   ensureDir(path.join(HARNESS_DIR, 'archive'));
   ensureDir(path.join(HARNESS_DIR, 'gotchas'));
+  ensureDir(path.join(HARNESS_DIR, 'conventions'));
 
   // Copy gotchas — preserve any existing file that has accumulated entries.
   // Dispatcher appends `### [G-NNN] ...` entries directly; we must NEVER overwrite
@@ -136,6 +282,39 @@ function scaffoldHarness() {
     }
   }
 
+  // Copy conventions — mirror gotchas preservation: never overwrite files with
+  // accumulated `### [C-NNN]` entries.
+  const conventionsSrc = path.join(PKG_ROOT, 'conventions');
+  if (fs.existsSync(conventionsSrc)) {
+    const CONV_ENTRY = /^### \[C-\d+\]/m;
+    const files = fs.readdirSync(conventionsSrc);
+    for (const file of files) {
+      const destPath = path.join(HARNESS_DIR, 'conventions', file);
+      const srcPath = path.join(conventionsSrc, file);
+      if (!fileExists(destPath)) {
+        copyFile(srcPath, destPath);
+        continue;
+      }
+      if (!file.endsWith('.md')) continue;
+      const existing = fs.readFileSync(destPath, 'utf8');
+      if (CONV_ENTRY.test(existing)) {
+        if (file === 'README.md') copyFile(srcPath, destPath);
+        continue;
+      }
+      copyFile(srcPath, destPath);
+    }
+  }
+
+  // First-install migration: extract Convention/Gotcha-shaped sections from
+  // existing CLAUDE.md / AGENTS.md and copy into the hierarchical stores.
+  if (isFirstInstall) {
+    try {
+      migrateExistingDocs();
+    } catch (e) {
+      log('WARNING: migration failed — ' + e.message);
+    }
+  }
+
   // Copy templates as initial files
   const templateMap = {
     'progress.json.template': path.join(HARNESS_DIR, 'progress.json'),
@@ -232,12 +411,12 @@ function scaffoldHarness() {
     copyFile(memorySrc, memoryDest);
   }
 
-  // Copy CONVENTIONS.md to project root
-  const conventionsSrc = path.join(PKG_ROOT, 'assets', 'templates', 'CONVENTIONS.md');
-  const conventionsDest = path.join(PROJECT_ROOT, 'CONVENTIONS.md');
-  if (fs.existsSync(conventionsSrc) && (!fileExists(conventionsDest) || isForce)) {
-    copyFile(conventionsSrc, conventionsDest);
-    log('CONVENTIONS.md created — edit to define your project conventions');
+  // Copy CONVENTIONS.md to project root (legacy — root still supported)
+  const rootConvSrc = path.join(PKG_ROOT, 'assets', 'templates', 'CONVENTIONS.md');
+  const rootConvDest = path.join(PROJECT_ROOT, 'CONVENTIONS.md');
+  if (fs.existsSync(rootConvSrc) && (!fileExists(rootConvDest) || isForce)) {
+    copyFile(rootConvSrc, rootConvDest);
+    log('CONVENTIONS.md created — edit to define top-level project conventions');
   }
 
   // Create progress.log

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@walwal-harness/cli",
-  "version": "5.5.3",
+  "version": "5.6.1",
   "description": "Production harness for AI agent engineering — Solo/Team mode, Planner, Generator(BE/FE), Evaluator chain (Code-Quality → Functional → Visual), optional Brainstormer. Supports React, Next.js, and Flutter FE stacks.",
   "bin": {
     "walwal-harness": "bin/init.js"
@@ -31,6 +31,14 @@
   ],
   "author": "",
   "license": "MIT",
+  "homepage": "https://github.com/30eggis/walwal-harness#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/30eggis/walwal-harness.git"
+  },
+  "bugs": {
+    "url": "https://github.com/30eggis/walwal-harness/issues"
+  },
   "files": [
     "bin/",
     "skills/",

package/skills/dispatcher/SKILL.md

@@ -46,19 +46,25 @@ Claude 는 기본적으로 Dispatcher 경유로 분류/라우팅해야 한다.
 
 사용자 입력을 먼저 분류합니다:
 
-- **실수 지적** ("아니", "잘못", "그렇게 하면 안 돼", "X로 해야지") → **Gotcha Flow**
+- **실수 지적 (부정)** ("아니", "잘못", "그렇게 하면 안 돼", "~하지 마") → **Gotcha Flow**
+- **긍정 규범** ("~해야 해", "~이렇게 해줘", "항상 ~", "우리는 ~ 방식") → **Convention Flow**
 - **기능 요청** ("만들어", "추가", "시작", PRD, OpenAPI) → **Pipeline Flow**
-- **혼합** → Gotcha 먼저 기록 → Pipeline 이어서
+- **혼합** → Gotcha/Convention 먼저 기록 → Pipeline 이어서
 - **메타/인사/Claude 자체 질문** → Dispatcher skip, 짧은 일반 응답 허용
 
-## 2. Gotcha Flow vs Memory Flow
+**부정 vs 긍정 구분법**: "X 하지 마 / X 가 틀렸어 / 그렇게 하면 안 돼" 는 **Gotcha**. "X 를 해야 해 / X 로 해줘 / 항상 X" 는 **Convention**. 동일 주제도 시그널에 따라 저장 위치가 달라집니다.
 
-사용자의 교정/피드백을 받으면 **먼저 분류**:
+## 2. Feedback Taxonomy — Gotcha / Convention / Memory
 
-| 유형 | 저장 위치 | 예시 |
-|------|----------|------|
-| **에이전트별 실수** (일회성 교정) | `.harness/gotchas/[agent].md` | "API 응답에 created_at은 ISO 8601로" |
-| **프로젝트 공유 규칙** (구조적/반복적) | `.harness/memory.md` | "Playwright 스크린샷은 단계 완료 후 항상 삭제" |
+사용자의 교정/가이드를 받으면 **먼저 분류**:
+
+| 유형 | 성격 | 저장 위치 | ID | 예시 |
+|------|------|----------|-----|------|
+| **Gotcha** | 특정 에이전트의 **일회성 실수(사고)** 기록 (negative) | `.harness/gotchas/<agent>.md` | `[G-NNN]` | "Generator-BE 가 MockServer 무시하고 실 DB 붙지 마" |
+| **Convention** | 에이전트/스코프의 **하우스 스타일(norm)** (positive) | `.harness/conventions/<scope>.md` | `[C-NNN]` | "API 응답 필드는 snake_case" |
+| **Memory** | **모든 에이전트** 공통 구조적 교훈 | `.harness/memory.md` | `[M-NNN]` | "Playwright 스크린샷은 단계 완료 후 항상 삭제" |
+
+Scope 가 특정 에이전트를 넘어서면 Memory. 특정 에이전트에 해당하면 Gotcha(부정) 혹은 Convention(긍정).
 
 ### Gotcha Flow (에이전트별 실수)
 
@@ -67,7 +73,17 @@ Claude 는 기본적으로 Dispatcher 경유로 분류/라우팅해야 한다.
 핵심:
 1. 교정 시그널 감지 (HIGH/MEDIUM만 기록)
 2. 도메인 분석 → 대상 에이전트 판별
-3. `.harness/gotchas/[agent].md`에 항목 추가 (중복 시 Occurrences 증가)
+3. `.harness/gotchas/[agent].md`에 `[G-NNN]` 추가 (중복 시 Occurrences 증가)
+4. 사용자에게 기록 확인
+
+### Convention Flow (에이전트별 하우스 스타일)
+
+긍정 가이드 감지 시 → [Convention 상세 가이드](references/convention-flow.md)
+
+핵심:
+1. 긍정 시그널 감지 ("해야 해", "이렇게 해줘", "항상" 등)
+2. 스코프 판별: 특정 에이전트(`generator-backend` 등) / `shared` / 프로젝트 전체(루트 `CONVENTIONS.md`)
+3. `.harness/conventions/<scope>.md` 에 `[C-NNN]` 추가
 4. 사용자에게 기록 확인
 
 ### Memory Flow (프로젝트 공유 규칙)

package/skills/dispatcher/references/convention-flow.md

@@ -0,0 +1,111 @@
+---
+docmeta:
+  id: convention-flow
+  title: Convention Flow — Positive Guide Classifier
+  type: output
+  createdAt: 2026-04-22T00:00:00Z
+  updatedAt: 2026-04-22T00:00:00Z
+  source:
+    producer: agent
+    skillId: harness-dispatcher
+  inputs:
+    - documentId: harness-dispatcher-skill
+      uri: ../SKILL.md
+      relation: output-from
+      sections:
+        - sourceRange:
+            startLine: 45
+            endLine: 100
+          targetRange:
+            startLine: 30
+            endLine: 140
+  tags:
+    - dispatcher
+    - convention
+    - positive-guidance
+---
+
+# Convention Flow — Positive Guide Classifier
+
+긍정 가이드("~해야 해", "항상 ~", "이렇게 해줘")를 감지하면
+해당 스코프의 `.harness/conventions/<scope>.md` 에 `[C-NNN]` 엔트리로 append.
+
+## 1. 긍정 시그널 감지
+
+다음 패턴 중 하나라도 포함되면 Convention 후보:
+
+- 명령형: "해야 해", "~로 해줘", "이렇게 만들어", "~를 사용해"
+- 원칙 선언: "항상 ~", "모든 ~ 는", "우리는 ~ 방식", "표준은 ~"
+- 하우스 스타일: "이 프로젝트에서는 ~", "컨벤션상 ~", "규칙은 ~"
+- 영어: "always", "must", "should", "we use", "prefer", "standard is"
+
+**부정 시그널과 충돌 시 부정 우선** (Gotcha 로 라우팅). 예: "~ 하지 말고 ~ 해줘" 는 Gotcha.
+
+## 2. Scope 판별
+
+엔트리의 적용 범위를 다음 순서로 판별:
+
+1. **특정 에이전트 명시** → 해당 에이전트 파일
+   - 사용자가 명시적으로 이름 언급 ("Generator-BE 는 ~") 또는 문맥상 확실한 키워드
+2. **도메인 키워드 매칭** → 대응 에이전트
+   | 키워드 | 스코프 |
+   |--------|-------|
+   | backend, API, controller, service, DTO, NestJS, MSA | `generator-backend` |
+   | frontend, React, Next.js, UI, component, hook, Tailwind | `generator-frontend` |
+   | plan, sprint, feature-list, api-contract, roadmap | `planner` |
+   | Playwright, E2E, browser, functional test | `evaluator-functional` |
+   | layout, screenshot, a11y, responsive, viewport, AI slop | `evaluator-visual` |
+   | code quality, lint, tsc, architecture, type safety | `evaluator-code-quality` |
+3. **매칭 실패 + 여전히 에이전트 국한** → `shared.md`
+4. **프로젝트 전체 철학/원칙** (예: "우리는 TDD 한다", "보안 우선") → 루트 `CONVENTIONS.md` 에 사용자 권고 (Dispatcher 직접 수정 금지)
+
+## 3. 중복 감지
+
+대상 파일에서 기존 `[C-NNN]` 엔트리를 읽어:
+- **완전 중복** (같은 rule) → append 하지 않고 기존 엔트리의 Date 를 갱신
+- **부분 중복** (관련 주제) → 새 엔트리로 추가하되 기존 엔트리 ID 를 `Related:` 필드로 참조
+
+## 4. 엔트리 포맷
+
+```markdown
+### [C-NNN] 간결한 제목 (긍정형, 70자 이내)
+- **Date**: YYYY-MM-DD
+- **Scope**: <agent> | shared
+- **Rule**: 사용자가 말한 내용을 긍정 규칙으로 정제. 명령형 문장.
+- **Rationale**: 사용자가 설명한 이유 (없으면 "미지정" 표기, 추정 금지)
+- **Applies to**: 적용 대상 상세 (특정 파일 경로, 특정 상황, 엔드포인트 등)
+- **Added from**: 사용자 프롬프트 (YYYY-MM-DD HH:MM) | migration | manual
+- **Related**: C-XXX, C-YYY (선택)
+```
+
+### ID 할당
+
+대상 파일의 기존 `[C-NNN]` 최댓값 + 1 을 3자리 zero-pad. 예: 기존에 C-001, C-003 이 있으면 다음은 C-004 (비어있는 번호는 재사용하지 않음).
+
+## 5. 루트 CONVENTIONS.md 처리
+
+루트 `CONVENTIONS.md` 는 **사용자가 자유 기술하는 최상위 원칙 파일**. Dispatcher 가 직접 수정하지 않고, 사용자에게 안내:
+
+```
+이 규칙은 프로젝트 전체 철학에 가까워 보여서 CONVENTIONS.md(루트) 에
+직접 추가하시는 게 좋겠습니다. 추가 후 모든 에이전트가 세션 시작 시 읽습니다.
+```
+
+## 6. 사용자 확인 메시지 포맷
+
+```
+Convention 등록 완료:
+- ID: [C-004]
+- Scope: generator-backend
+- Rule: API 응답 필드는 snake_case
+- 저장 위치: .harness/conventions/generator-backend.md
+
+Generator-Backend 는 다음 세션 시작 시 이 규칙을 읽고 적용합니다.
+```
+
+## 7. 금지 사항
+
+- Convention 파일의 기존 엔트리 삭제/수정 (사용자만 가능)
+- `CONVENTIONS.md` (루트) 직접 수정
+- 추정성 rationale 작성 (근거 없으면 "미지정")
+- 에이전트 SKILL.md 자체 수정 (구조적 변경은 사용자 권고)

package/skills/evaluator-code-quality/SKILL.md

@@ -63,13 +63,14 @@ disable-model-invocation: true
 ## Startup
 
 1. `AGENTS.md` 읽기 — IA-MAP (레이어 경계)
-2. `CONVENTIONS.md` 읽기 — 프로젝트 컨벤션 (있을 때만)
-3. `.harness/gotchas/evaluator-code-quality.md` 읽기 — **과거 실수 반복 금지**
-4. `.harness/memory.md` 읽기 — **프로젝트 공유 학습 규칙 적용**
-5. `actions/sprint-contract.md` — 이번 스프린트 변경 범위
-6. `actions/feature-list.json` — 기능 정의
-7. `actions/api-contract.json` — DTO 형태 (계약 vs 구현 일치 확인용)
-8. `.harness/progress.json`
+2. `CONVENTIONS.md` (루트) 읽기 — 프로젝트 최상위 원칙 (있을 때만)
+3. `.harness/conventions/shared.md` + `.harness/conventions/evaluator-code-quality.md` — **긍정 하우스 스타일 (C-NNN) — PASS 판정의 기준이 된다**
+4. `.harness/gotchas/evaluator-code-quality.md` 읽기 — **과거 실수 반복 금지**
+5. `.harness/memory.md` 읽기 — **프로젝트 공유 학습 규칙 적용**
+6. `actions/sprint-contract.md` — 이번 스프린트 변경 범위
+7. `actions/feature-list.json` — 기능 정의
+8. `actions/api-contract.json` — DTO 형태 (계약 vs 구현 일치 확인용)
+9. `.harness/progress.json`
 
 ## Evaluation Steps
 

package/skills/evaluator-functional/SKILL.md

@@ -63,12 +63,14 @@ disable-model-invocation: true
 ## Startup
 
 1. `AGENTS.md` 읽기 — IA-MAP
-2. `.harness/gotchas/evaluator-functional.md` 읽기 — **과거 실수 반복 금지**
-3. `.harness/memory.md` 읽기 — **프로젝트 공유 학습 규칙 적용**
-4. `actions/sprint-contract.md` — BE + FE 성공 기준 전체
-4. `actions/feature-list.json` — 이번 스프린트 범위
-5. `actions/api-contract.json` — 기대 API 동작
-6. `.harness/progress.json`
+2. `CONVENTIONS.md` (루트) 읽기 — 프로젝트 최상위 원칙 (있을 때만)
+3. `.harness/conventions/shared.md` + `.harness/conventions/evaluator-functional.md` — **긍정 하우스 스타일 적용**
+4. `.harness/gotchas/evaluator-functional.md` 읽기 — **과거 실수 반복 금지**
+5. `.harness/memory.md` 읽기 — **프로젝트 공유 학습 규칙 적용**
+6. `actions/sprint-contract.md` — BE + FE 성공 기준 전체
+7. `actions/feature-list.json` — 이번 스프린트 범위
+8. `actions/api-contract.json` — 기대 API 동작
+9. `.harness/progress.json`
 
 ## Feature-Level Mode (Team Mode)
 

package/skills/evaluator-visual/SKILL.md

@@ -56,10 +56,12 @@ disable-model-invocation: true
 ## Startup
 
 1. `AGENTS.md` 읽기
-2. `.harness/gotchas/evaluator-visual.md` 읽기 — **과거 실수 반복 금지**
-3. `.harness/memory.md` 읽기 — **프로젝트 공유 학습 규칙 적용**
-4. `actions/evaluation-functional.md` — Verdict: PASS 확인
-5. **Stack-Adaptive Gate** (v5.2) — `scan-result.json.tech_stack` 으로 스택 확인 후 `.harness/ref/fe-<stack>.md` 의 `validation.visual` 파싱:
+2. `CONVENTIONS.md` (루트) 읽기 — 프로젝트 최상위 원칙 (있을 때만)
+3. `.harness/conventions/shared.md` + `.harness/conventions/evaluator-visual.md` — **긍정 하우스 스타일 적용**
+4. `.harness/gotchas/evaluator-visual.md` 읽기 — **과거 실수 반복 금지**
+5. `.harness/memory.md` 읽기 — **프로젝트 공유 학습 규칙 적용**
+6. `actions/evaluation-functional.md` — Verdict: PASS 확인
+7. **Stack-Adaptive Gate** (v5.2) — `scan-result.json.tech_stack` 으로 스택 확인 후 `.harness/ref/fe-<stack>.md` 의 `validation.visual` 파싱:
    - `visual.enabled == false`: 즉시 **MANUAL_REQUIRED 모드** 로 전환 — 아래 "Visual Skip Flow" 수행 후 종료
    - `visual.enabled == true` (또는 ref-docs 없이 웹 전통 스택): 계속 진행, ref 에 `visual.base_url` 이 있으면 그 URL 로, 없으면 `ref.runner.dev_command` 로 서버 기동 후 Playwright 접속
 

package/skills/generator-backend/SKILL.md

@@ -27,18 +27,23 @@ disable-model-invocation: true
 ## Startup (Adaptive Loading)
 
 1. `AGENTS.md` 읽기 — IA-MAP, 권한 확인
-2. `.harness/actions/scan-result.json` 읽기 → `tech_stack.backend` 또는 `tech_stack.language` 로 현재 스택 확정 (이하 `<stack>`)
-3. **Ref-docs 로드** — `.harness/ref/be-<stack>.md`
+2. `CONVENTIONS.md` (루트) 읽기 — 프로젝트 최상위 원칙 (있을 때만)
+3. **Conventions 로드** — 세 파일 모두 (있는 것만):
+   - `.harness/conventions/shared.md` (모든 에이전트 공통)
+   - `.harness/conventions/generator-backend.md` (BE 스코프)
+   - `.harness/conventions/generator-backend-<stack>.md` (스택별, 선택)
+4. `.harness/actions/scan-result.json` 읽기 → `tech_stack.backend` 또는 `tech_stack.language` 로 현재 스택 확정 (이하 `<stack>`)
+5. **Ref-docs 로드** — `.harness/ref/be-<stack>.md`
    - 파일 없음 → STOP + 안내: `"ref-docs 가 없습니다. bash init.sh init 실행 또는 bash scripts/init-ref-docs.sh --claude-prompt --stack <stack> --role be . 실행하세요."`
    - frontmatter 파싱 실패 → 경고 출력 + 기본값으로 degrade
-4. **Gotchas 로드** — 두 파일 모두 (있는 것만):
+6. **Gotchas 로드** — 두 파일 모두 (있는 것만):
    - `.harness/gotchas/generator-backend.md` (공통)
    - `.harness/gotchas/generator-backend-<stack>.md` (스택별)
-5. `.harness/memory.md` 읽기 — 프로젝트 공유 학습 규칙
-6. `pwd` + `.harness/progress.json` + `git log --oneline -20`
-7. `.harness/actions/api-contract.json` 읽기 — **이 계약이 유일한 BE 외부 인터페이스**
-8. `.harness/actions/feature-list.json` — 지정된 `FEATURE_ID` 또는 `layer: "backend"` 필터
-9. **DB / 외부 의존성 부트스트랩**:
+7. `.harness/memory.md` 읽기 — 프로젝트 공유 학습 규칙
+8. `pwd` + `.harness/progress.json` + `git log --oneline -20`
+9. `.harness/actions/api-contract.json` 읽기 — **이 계약이 유일한 BE 외부 인터페이스**
+10. `.harness/actions/feature-list.json` — 지정된 `FEATURE_ID` 또는 `layer: "backend"` 필터
+11. **DB / 외부 의존성 부트스트랩**:
    - `ref.runner.install_command` 가 있으면 1회 실행
    - `ref.runner.dev_command` 를 백그라운드 실행 (있는 경우)
 

package/skills/generator-frontend/SKILL.md

@@ -27,21 +27,26 @@ disable-model-invocation: true
 ## Startup (Adaptive Loading)
 
 1. `AGENTS.md` 읽기 — IA-MAP, 권한 확인
-2. `.harness/actions/scan-result.json` 읽기 → `tech_stack.fe_stack` 또는 `tech_stack.frontend` 로 현재 스택 확정 (이하 `<stack>`)
-3. **Ref-docs 로드** — `.harness/ref/fe-<stack>.md`
+2. `CONVENTIONS.md` (루트) 읽기 — 프로젝트 최상위 원칙 (있을 때만)
+3. **Conventions 로드** — 세 파일 모두 (있는 것만):
+   - `.harness/conventions/shared.md` (모든 에이전트 공통)
+   - `.harness/conventions/generator-frontend.md` (FE 스코프)
+   - `.harness/conventions/generator-frontend-<stack>.md` (스택별, 선택)
+4. `.harness/actions/scan-result.json` 읽기 → `tech_stack.fe_stack` 또는 `tech_stack.frontend` 로 현재 스택 확정 (이하 `<stack>`)
+5. **Ref-docs 로드** — `.harness/ref/fe-<stack>.md`
    - 파일 없음 → STOP + 안내: `"ref-docs 가 없습니다. bash init.sh init 실행 또는 bash scripts/init-ref-docs.sh --claude-prompt --stack <stack> --role fe . 실행하세요."`
    - frontmatter 파싱 실패 → 경고 출력 + 기본값(runner/paths/api 모두 null)으로 degrade
-4. **Gotchas 로드** — 두 파일 모두 (있는 것만):
+6. **Gotchas 로드** — 두 파일 모두 (있는 것만):
    - `.harness/gotchas/generator-frontend.md` (공통)
    - `.harness/gotchas/generator-frontend-<stack>.md` (스택별)
-5. `.harness/memory.md` 읽기 — 프로젝트 공유 학습 규칙
-6. `pwd` + `.harness/progress.json` + `git log --oneline -20`
-7. `.harness/actions/api-contract.json` 읽기
-8. `.harness/actions/feature-list.json` — 지정된 `FEATURE_ID` 또는 `layer: "frontend"` 필터
-9. **개발 서버 기동**:
-   - `ref.runner.dev_command` 가 `null` 이 아니면 해당 명령 백그라운드 실행
-   - `null` 이면 "개발 서버 기동은 스택 특성상 생략" 로그만 남김
-10. **API Gateway 체크**:
+7. `.harness/memory.md` 읽기 — 프로젝트 공유 학습 규칙
+8. `pwd` + `.harness/progress.json` + `git log --oneline -20`
+9. `.harness/actions/api-contract.json` 읽기
+10. `.harness/actions/feature-list.json` — 지정된 `FEATURE_ID` 또는 `layer: "frontend"` 필터
+11. **개발 서버 기동**:
+    - `ref.runner.dev_command` 가 `null` 이 아니면 해당 명령 백그라운드 실행
+    - `null` 이면 "개발 서버 기동은 스택 특성상 생략" 로그만 남김
+12. **API Gateway 체크**:
     - `ref.api.base_url` 이 `null` 이 아니면 `curl -s <base_url>/health` 로 헬스체크
     - `null` (네이티브 앱 등) 이면 체크 스킵
 

package/skills/planner/SKILL.md

@@ -24,18 +24,20 @@ disable-model-invocation: true
 ## Startup
 
 1. `AGENTS.md` 읽기
-2. `.harness/gotchas/planner.md` 읽기 — **과거 실수 반복 금지**
-3. `.harness/memory.md` 읽기 — **프로젝트 공유 학습 규칙 적용**
-4. `.harness/progress.json` 읽기
-5. `.harness/actions/pipeline.json` 읽기 — `planner_mode`, `fe_stack` 확인
-6. `.harness/actions/scan-result.json` 읽기 — `tech_stack.fe_stack` 확인 (없으면 `react` 기본)
-7. **Brainstorm Spec 우선 로드** — `.harness/actions/brainstorm-spec.md` 가 존재하면
+2. `CONVENTIONS.md` (루트) 읽기 — 프로젝트 최상위 원칙 (있을 때만)
+3. `.harness/conventions/shared.md` + `.harness/conventions/planner.md` — **긍정 하우스 스타일 적용 (feature 분할/AC 작성 시)**
+4. `.harness/gotchas/planner.md` 읽기 — **과거 실수 반복 금지**
+5. `.harness/memory.md` 읽기 — **프로젝트 공유 학습 규칙 적용**
+6. `.harness/progress.json` 읽기
+7. `.harness/actions/pipeline.json` 읽기 — `planner_mode`, `fe_stack` 확인
+8. `.harness/actions/scan-result.json` 읽기 — `tech_stack.fe_stack` 확인 (없으면 `react` 기본)
+9. **Brainstorm Spec 우선 로드** — `.harness/actions/brainstorm-spec.md` 가 존재하면
    **이 파일이 PRD 대체 입력**. Brainstormer 가 이미 사용자와 대화하여 확정한
    결과이므로 **승인된 결정을 뒤엎지 않는다**. 없으면 사용자의 원본 요청 텍스트를 입력으로 사용.
    - brainstorm-spec.md 에 `## Open Questions` 섹션이 있으면 Planner 가 해소 (API 계약으로 확정)
    - brainstorm-spec.md 의 `## 7. 주요 컴포넌트 / 엔티티` → `feature-list.json` 초기 feature 목록 시드
    - brainstorm-spec.md 의 `## 5. 선택된 접근법` / `## 6. 아키텍처 스케치` → MSA 서비스 분할 베이스
-8. **FE Stack 확정** → [FE Stack 결정 가이드](references/fe-stack-detection.md)
+10. **FE Stack 확정** → [FE Stack 결정 가이드](references/fe-stack-detection.md)
    - `pubspec.yaml` + `flutter:` 키 → `fe_stack = "flutter"`
    - 혼재/불명확 → 사용자에게 단 한 번 질문
    - 확정 후 `pipeline.json.fe_stack` 갱신 (없으면 생성)