makdoong2-team 1.3.0

package/gates/stage8-post-review-verify.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# stage8-post-review-verify.sh <issue> — 8단계(리뷰 코멘트) post-execution 게이트
+#
+# 원칙: entry gate 는 전제조건, post-verify 는 완료 조건. publisher 가 §3-2 마지막에
+# .done=true 를 기록하기 직전 본 스크립트를 호출한다. 실패 시 exit 2 로 publisher
+# 재작업 loop 를 유도한다 (Bitbucket 에 부족한 코멘트 재 posting).
+#
+# 검사 항목 (완료조건):
+#   1) review-comment-plan.json 존재 (LLM 사전 설계 아티팩트)
+#   2) plan.commit_count == atomic_review.count_commits (계획된 커밋 수 = 실제 커밋 수)
+#   3) plan.plan[] 모든 항목의 comments 배열 길이 >= 1 (계획 단계에서 커밋당 최소 1개)
+#   4) comments_per_commit 마커의 모든 값 >= 1 (실제 posting 결과가 커밋당 최소 1개)
+#   5) comments 총합 == comments_per_commit 값들의 합 (합계 정합성)
+#   6) all_comments_inline == true (인라인 앵커 자기선언 — verifier 가 Bitbucket 재조회로 교차검증)
+#   7) .stages.3_delivery.substages.review.done == true
+set -euo pipefail
+HERE="$(cd "$(dirname "$0")" && pwd)"
+ISSUE="${1:?usage: stage8-post-review-verify.sh <issue>}"
+P="$("$HERE/../scripts/state.sh" root)/.makdoong2-team/$ISSUE/state.json"
+fail(){ echo "MAKDOONG2-POSTGATE BLOCKED [3_delivery.review_post]: $1" >&2; exit 2; }
+[ -f "$P" ] || fail "state.json 없음"
+q(){ "$HERE/../scripts/state.sh" get "$ISSUE" "$1" 2>/dev/null || echo "__MISSING__"; }
+
+CC="$(q '.stages."3_delivery".substages."commit".atomic_review.count_commits')"
+case "$CC" in
+  ''|null|__MISSING__) fail "commit.atomic_review.count_commits 미기록 — commit substage 를 먼저 완료" ;;
+esac
+[ "$CC" -ge 1 ] 2>/dev/null || fail "count_commits 가 정수 아니거나 <1: $CC"
+
+PLAN_REL_RAW="$(q '.stages."3_delivery".substages."review".plan_path')"
+PLAN_REL="$(printf '%s' "$PLAN_REL_RAW" | tr -d '"')"
+case "$PLAN_REL_RAW" in
+  ''|null|__MISSING__) fail "review.plan_path 미기록 — publisher 가 review-comment-plan.json 을 먼저 산출해야 함" ;;
+esac
+if [[ "$PLAN_REL" == /* ]]; then
+  PLAN_PATH="$PLAN_REL"
+else
+  PLAN_PATH="$("$HERE/../scripts/state.sh" root)/$PLAN_REL"
+fi
+[ -f "$PLAN_PATH" ] || fail "review-comment-plan.json 파일 없음: $PLAN_PATH"
+
+jq -e . "$PLAN_PATH" >/dev/null 2>&1 || fail "review-comment-plan.json JSON parse 실패: $PLAN_PATH"
+
+PLAN_CC="$(jq -r '.commit_count // empty' "$PLAN_PATH")"
+[ -n "$PLAN_CC" ] || fail "plan.commit_count 필드 없음"
+[ "$PLAN_CC" = "$CC" ] \
+  || fail "plan.commit_count($PLAN_CC) != atomic_review.count_commits($CC) — 계획된 커밋 수 불일치"
+
+PLAN_LEN="$(jq -r '.plan | length' "$PLAN_PATH")"
+[ "$PLAN_LEN" = "$CC" ] || fail "plan.plan 배열 길이($PLAN_LEN) != count_commits($CC)"
+
+UNDER_PLAN="$(jq -r '[.plan[] | select((.comments // [] | length) < 1)] | length' "$PLAN_PATH")"
+[ "$UNDER_PLAN" = "0" ] || fail "계획 단계에서 $UNDER_PLAN 개 커밋에 코멘트가 0개 — 커밋당 최소 1개 필요"
+
+CPC="$(q '.stages."3_delivery".substages."review".comments_per_commit')"
+case "$CPC" in
+  ''|null|__MISSING__|'{}') fail "comments_per_commit 마커 미기록 또는 빈 객체 — 실제 posting 결과를 커밋별로 집계해야 함" ;;
+esac
+
+CPC_LEN="$(printf '%s' "$CPC" | jq -r 'length' 2>/dev/null || echo 0)"
+[ "$CPC_LEN" = "$CC" ] \
+  || fail "comments_per_commit 항목 수($CPC_LEN) != count_commits($CC) — 모든 커밋에 코멘트 매핑 필요"
+
+CPC_UNDER="$(printf '%s' "$CPC" | jq -r '[to_entries[] | select((.value|tonumber) < 1)] | length' 2>/dev/null || echo -1)"
+[ "$CPC_UNDER" = "0" ] || fail "$CPC_UNDER 개 커밋의 실제 앵커 코멘트 수가 0개 — 재작성 필요"
+
+CPC_SUM="$(printf '%s' "$CPC" | jq -r '[.[] | tonumber] | add' 2>/dev/null || echo -1)"
+COMMENTS="$(q '.stages."3_delivery".substages."review".comments')"
+[ "$COMMENTS" = "$CPC_SUM" ] \
+  || fail "review.comments($COMMENTS) != Σcomments_per_commit($CPC_SUM) — 합계 불일치"
+
+AI="$(q '.stages."3_delivery".substages."review".all_comments_inline')"
+[ "$AI" = "true" ] \
+  || fail "all_comments_inline=$AI — 모든 코멘트가 filePath+line 앵커를 가져야 함"
+
+D="$(q '.stages."3_delivery".substages."review".done')"
+[ "$D" = "true" ] || fail "review.done 이 true 아님(=$D) — publisher 가 완료 마킹을 누락"
+
+# [comment.status 전수 검증] status 필드가 존재하는 plan 에서만 적용 (하위 호환)
+NOT_POSTED="$(jq -r '[.plan[].comments[] | select(has("status") and .status != "posted")] | length' "$PLAN_PATH")"
+[ "$NOT_POSTED" = "0" ] \
+  || fail "plan.json 에 status가 \"posted\" 가 아닌 comment 가 ${NOT_POSTED}개 남아 있음 — 미완료 코멘트 posting 후 status 갱신 필요"
+
+echo "MAKDOONG2-POSTGATE OK: 3_delivery.review_post"

package/gates/stage8-review-verify.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# stage8-review-verify.sh <issue> — 8단계(리뷰 코멘트) 진입 게이트
+#
+# 원칙: entry gate 는 substage 진입 "전제조건" 만 검사한다.
+# 완료 조건(코멘트 개수, per-commit 매핑, 인라인 앵커 여부 등)은 publisher 가 substage
+# 수행 후 stage8-post-review-verify.sh + verifier 에서 검증된다.
+#
+# 검사 항목 (전제조건):
+#   1) state.json 존재
+#   2) pr substage 산출물: draft_url, body_validation 3항목, reviewer 마커
+#   3) HITL: auto_approve 미설정 시 사용자 승인 완료
+#
+# 제거된 조건 (완료조건 → post-verify 로 이동):
+#   * .stages.3_delivery.substages.review.comments >= 1
+#   * .stages.3_delivery.substages.review.all_comments_inline == true
+#   → 두 값 모두 publisher 가 §8-2 에서 인라인 코멘트를 작성한 뒤에 기록하는 완료 마커이므로
+#     entry gate 에 두면 first-entry 자체가 불가능(chicken-and-egg).
+set -euo pipefail
+HERE="$(cd "$(dirname "$0")" && pwd)"
+ISSUE="${1:?usage: stage8-review-verify.sh <issue>}"
+P="$("$HERE/../scripts/state.sh" root)/.makdoong2-team/$ISSUE/state.json"
+fail(){ echo "MAKDOONG2-GATE BLOCKED [3_delivery.review]: $1" >&2; exit 2; }
+[ -f "$P" ] || fail "state.json 없음 — planning phase부터 시작하라"
+q(){ "$HERE/../scripts/state.sh" get "$ISSUE" "$1" 2>/dev/null || echo "__MISSING__"; }
+U="$(q '.stages."3_delivery".substages."pr".draft_url')"
+{ [ -n "$U" ] && [ "$U" != "null" ] && [ "$U" != "__MISSING__" ]; } || fail "pr substage (Draft PR) 미생성"
+for k in no_orphan_scenarios template_match section_content_match; do
+  v="$(q ".stages.\"3_delivery\".substages.\"pr\".body_validation.$k")"
+  [ "$v" = "true" ] || fail "PR 본문 검증 미통과(body_validation.$k=$v) — PR substage 세 검증을 모두 통과 후 기록해야 함"
+done
+
+REVIEWER_ADDED="$(q '.stages."3_delivery".substages."pr".reviewer_added')"
+REVIEWER_SELF_SKIPPED="$(q '.stages."3_delivery".substages."pr".reviewer_self_skipped')"
+if [ "$REVIEWER_ADDED" != "true" ] && [ "$REVIEWER_SELF_SKIPPED" != "true" ]; then
+  fail "PR에 reviewer 미추가(reviewer_added=$REVIEWER_ADDED, reviewer_self_skipped=$REVIEWER_SELF_SKIPPED) — 08-pr.md §7-4에 따라 토큰 소유자를 reviewer로 추가(reviewer_added=true)하거나, 토큰 소유자가 PR 작성자와 동일하여 추가가 불가한 경우 reviewer_self_skipped=true 를 기록해야 함"
+fi
+
+if [ "$(q '.policy.auto_approve."3_delivery.pr"')" != "true" ]; then
+  [ "$(q '.stages."3_delivery".substages."pr".approved_by_user')" = "true" ] \
+    || fail "pr substage 사용자 미승인 — Draft PR 검토 후 approved_by_user를 기록하라 (또는 .policy.auto_approve.\"3_delivery.pr\" 미설정)"
+  if [ "$(q '.stages."3_delivery".substages."pr".verification_pending')" = "true" ]; then
+    fail "pr substage 검증 대기 중(verification_pending) — 사용자 승인 후 approved_by_user를 기록하고 verification_pending을 false로 해소하라"
+  fi
+fi
+echo "MAKDOONG2-GATE OK: 3_delivery.review"

package/gates/verify.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# verify.sh <issue> <target_stage> — 단계별 검증 게이트 디스패처.
+# 각 단계의 검증 로직은 stage{N}-*-verify.sh에 위임한다.
+# 의존: jq, git (각 하위 스크립트에서 사용)
+set -euo pipefail
+HERE="$(cd "$(dirname "$0")" && pwd)"
+ISSUE="${1:?usage: verify.sh <issue> <stage>}"
+TARGET="${2:?usage: verify.sh <issue> <stage>}"
+
+case "$TARGET" in
+  1_planning.jira)
+    JIRA_DONE="$("$HERE/../scripts/state.sh" get "$ISSUE" '.stages."1_planning".substages."jira".done' 2>/dev/null || echo "false")"
+    if [ "$JIRA_DONE" = "true" ]; then
+      echo "MAKDOONG2-GATE BLOCKED [1_planning.jira]: 이미 done=true 완료됨 — auto_advance_stage 로 다음 단계 진행" >&2
+      exit 2
+    fi
+    echo "MAKDOONG2-GATE OK: $TARGET (jira validation handled by extension gate)" ;;
+  1_planning.requirements)
+    "$HERE/stage2-requirements-verify.sh" "$ISSUE" ;;
+  1_planning.scope)
+    "$HERE/stage3-scope-verify.sh" "$ISSUE" ;;
+  2_implementation.analysis)
+    "$HERE/stage-analysis-verify.sh" "$ISSUE" ;;
+  2_implementation.dev)
+    "$HERE/stage4-dev-verify.sh" "$ISSUE" ;;
+  2_implementation.dev_post)
+    "$HERE/stage4-dev-post-verify.sh" "$ISSUE" ;;
+  2_implementation.test)
+    "$HERE/stage5-test-verify.sh" "$ISSUE" ;;
+  3_delivery.commit)
+    "$HERE/stage6-commit-verify.sh" "$ISSUE" ;;
+  3_delivery.commit_post | 6_commit_post)
+    "$HERE/stage6-post-commit-verify.sh" "$ISSUE" ;;
+  3_delivery.pr)
+    "$HERE/stage7-pr-verify.sh" "$ISSUE" ;;
+  3_delivery.pr_post)
+    "$HERE/stage7-post-pr-verify.sh" "$ISSUE" ;;
+  3_delivery.review)
+    "$HERE/stage8-review-verify.sh" "$ISSUE" ;;
+  3_delivery.review_post)
+    "$HERE/stage8-post-review-verify.sh" "$ISSUE" ;;
+  *)
+    echo "MAKDOONG2-GATE OK: $TARGET" ;;
+esac

package/opencode.json.example

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": [
+    "~/.config/opencode/custom_instructions.md"
+  ],
+  "autoupdate": false,
+  "_comment_plugin": "makdoong2-team install이 자동으로 npm 패키지 이름(makdoong2-team)을 주입한다. 직접 편집 불필요.",
+  "plugin": [
+    "makdoong2-team"
+  ],
+  "permission": {
+    "bash": {
+      "*": "allow",
+      "git commit*": "deny",
+      "git push*": "deny",
+      "git push --force*": "deny",
+      "git reset --hard*": "ask",
+      "git branch -D*": "ask",
+      "git worktree remove*": "ask",
+      "git worktree add*": "ask",
+      "rm -rf*": "ask"
+    }
+  },
+  "mcp": {
+    "_comment": "Site-wide MCP only. Per-stage MCP (works/repos/docs) is embedded in skills/*/SKILL.md for lazy loading.",
+    "chrome-devtools-mcp": {
+      "type": "local",
+      "command": ["npx", "-y", "chrome-devtools-mcp@latest"],
+      "enabled": true
+    }
+  },
+  "tools": {
+    "chrome-devtools-mcp*": true,
+    "verify_stage": true,
+    "dispatch_stage": true,
+    "dispatch_verifier": true,
+    "auto_advance_stage": true,
+    "get_fallback_model": true
+  }
+}

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "makdoong2-team",
+  "version": "1.3.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "내 일을 대신해주는 막둥이들. Self-contained opencode plugin for 사내 workflow: per-stage specialist agents, deterministic shell gates, primary-only enforcement, and a model fallback advisor.",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "plugin",
+    "agent",
+    "workflow",
+    "jira",
+    "multi-agent",
+    "makdoong2"
+  ],
+  "type": "module",
+  "main": "dist/opencode-plugin.js",
+  "types": "dist/opencode-plugin.d.ts",
+  "bin": {
+    "makdoong2-team": "bin/cli.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/opencode-plugin.js",
+      "types": "./dist/opencode-plugin.d.ts"
+    },
+    "./schema.json": "./assets/makdoong2-team.schema.json"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "src/hooks",
+    "agents",
+    "gates",
+    "stages",
+    "references",
+    "scripts",
+    "skills",
+    "assets",
+    "opencode.json.example",
+    "postinstall.mjs"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/y00njinuk/makdoong2-team.git"
+  },
+  "license": "MIT",
+  "engines": {
+    "opencode": ">=1.18.0",
+    "node": ">=20.0.0",
+    "tmux": ">=3.0"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "^1.18.0"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "1.18.15",
+    "@opencode-ai/sdk": "1.18.15",
+    "@types/node": "^22.20.1",
+    "husky": "^9.0.0",
+    "typescript": "^5.7.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "node -e \"import('node:fs').then(({rmSync})=>rmSync('dist',{recursive:true,force:true}))\"",
+    "prepack": "npm run clean && npm run build",
+    "postinstall": "node postinstall.mjs",
+    "prepare": "husky install",
+    "test": "XDG_CONFIG_HOME=\"$(mktemp -d)\" XDG_CACHE_HOME=\"$(mktemp -d)\" npm run test:all",
+    "test:all": "npm run build && bash scripts/lint-agent-prompts.sh && node scripts/smoke-test.mjs && bash scripts/gate-policy-test.sh && node test/install-lib.test.mjs && node test/skill-mcp-registry.test.mjs && node --test test/state-write-guard.test.mjs && node --test test/state-sh-schema.test.mjs && node --test test/state-sh-init-review-shape.test.mjs && node --test test/doctor-phantom-scan.test.mjs && node --test test/mcp-secret-injector.test.mjs && node --test test/poll-sub-session.test.mjs && node --test test/tmux-monitor.test.mjs && node --test test/gate-already-done-block.test.mjs && node --test test/gate-hybrid-first-entry.test.mjs && node --test test/gate-post-pr-verify.test.mjs && node --test test/gate-post-review-verify.test.mjs && node --test test/worktree-sync-gate.test.mjs && node --test test/planner-prompt-early-exit.test.mjs && node --test test/plugin-bug-fixes.test.mjs && node --test test/omo-tmux-detection.test.mjs && node --test test/empty-output-done-override.test.mjs && node --test test/tmux-monitor-orphan.test.mjs && node --test test/poll-permission-scope.test.mjs && node --test test/dispatch-review-fixes.test.mjs && node --test test/dispatch-stage-redispatch.test.mjs && node --test test/dispatch-stage-dev-resume-prompt.test.mjs && node --test test/logger.test.mjs && node --test test/redact-secrets.test.mjs && node --test test/commit-atomicity-verify.test.mjs && node --test test/verdict-reason-injection.test.mjs && node --test test/verdict-hash-normalize.test.mjs && node --test test/session-index-fallback.test.mjs && node --test test/plugin-exports-shape.test.mjs && node --test test/stale-worktree-recovery.test.mjs && node --test test/rollback-commits.test.mjs && node --test test/config-dir-home-fallback.test.mjs && node --test test/state-path-migration.test.mjs && node --test test/state-path-relative.test.mjs && node --test test/with-fallback-no-bun.test.mjs && node --test test/doctor-exit-code.test.mjs && node --test test/example-config-portability.test.mjs",
+    "test:install": "node test/install-lib.test.mjs",
+    "test:postinstall": "node scripts/test-postinstall.mjs",
+    "release": "bash scripts/release.sh",
+    "release:patch": "bash scripts/release.sh patch",
+    "release:minor": "bash scripts/release.sh minor",
+    "release:major": "bash scripts/release.sh major"
+  },
+  "homepage": "https://github.com/y00njinuk/makdoong2-team#readme",
+  "bugs": {
+    "url": "https://github.com/y00njinuk/makdoong2-team/issues"
+  }
+}

package/postinstall.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// postinstall.mjs — Auto-install on npm install -g
+//
+// Runs ONLY when:
+//   - npm_config_global === "true" (global install), OR
+//   - MAKDOONG2_AUTO_INSTALL === "1" (opt-in for local-dep scenarios)
+//
+// Skips when:
+//   - CI environment (unless MAKDOONG2_AUTO_INSTALL=1)
+//   - Local install (unless MAKDOONG2_AUTO_INSTALL=1)
+//
+// On failure: warns and exits 0 (don't break npm install)
+
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { install, resolveConfigDir } from "./scripts/install-lib.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+function shouldRun() {
+  const isGlobal = process.env.npm_config_global === "true";
+  const optIn = process.env.MAKDOONG2_AUTO_INSTALL === "1";
+  const isCI = process.env.CI === "true" || process.env.CONTINUOUS_INTEGRATION === "true";
+
+  if (isCI && !optIn) {
+    console.log("[makdoong2-team] postinstall: CI detected — skipping. Run `makdoong2-team install` manually.");
+    return false;
+  }
+  if (!isGlobal && !optIn) {
+    console.log("[makdoong2-team] postinstall: local install detected — skipping. Run `makdoong2-team install` to deploy, or set MAKDOONG2_AUTO_INSTALL=1.");
+    return false;
+  }
+  return true;
+}
+
+function main() {
+  if (!shouldRun()) return;
+
+  try {
+    const configDir = resolveConfigDir(undefined);
+    console.log(`[makdoong2-team] postinstall: deploying to ${configDir}`);
+    install({
+      configDir,
+      pkgRoot: HERE,
+      force: false,
+      patchOpencode: "idempotent",
+    });
+    console.log("[makdoong2-team] postinstall: done. Run `makdoong2-team doctor` to verify.");
+  } catch (err) {
+    console.warn(`[makdoong2-team] postinstall: ${err.message}`);
+    console.warn("[makdoong2-team] postinstall: install incomplete — run `makdoong2-team install` to retry.");
+    process.exit(0);
+  }
+}
+
+main();

package/references/commit-convention.md

@@ -0,0 +1,130 @@
+# Git Commit Message Convention
+
+주인이 제공한 팀 커밋 컨벤션. makdoong2-team 스킬의 6단계에서 참조한다.
+
+## 참조
+- [How to write a git commit message](https://cbea.ms/git-commit/)
+- [How to write better git commit messages (freeCodeCamp)](https://www.freecodecamp.org/news/how-to-write-better-git-commit-messages/)
+- [robertpainsi/commit-message-guidelines (gist)](https://gist.github.com/robertpainsi/b632364184e70900af4ab688decf6f53)
+
+---
+
+## 주요 원칙
+
+### 제목과 본문 구조
+- 제목과 본문은 **빈 줄**로 구분한다.
+- 본문은 필요할 경우에만 작성한다.
+- 제목은 **50자로 제한**한다 (한글은 25자 내외).
+  - 요약이 어렵다면 한 번에 너무 많은 변경사항을 커밋하는 것은 아닌지 고민하고, **atomic commit**을 고려한다.
+- 제목은 **대문자로 시작**한다 (Type 부분).
+- 제목 끝에 **마침표를 붙이지 않는다**.
+- 제목은 **명령조(imperative)**로 작성한다. 한글도 명령조를 유지한다 ("추가한다" 대신 "추가").
+- 본문은 한글 기준 줄당 약 40자 (영문 72자 상당).
+
+### 본문 작성 원칙
+본문은 "어떻게"보다 **"무엇을, 왜"**에 집중한다.
+- 왜 이렇게 변경했는가?
+- 변경사항이 어떤 영향을 미쳤는가?
+- 왜 변화가 필요했는가?
+
+---
+
+## Type 일람
+
+| Type | 설명 |
+|------|------|
+| **Feat** | 새로운 기능 추가 |
+| **Fix** | 버그 수정 |
+| **Chore** | fix/feature와 관계없고 src 또는 test 파일을 수정하지 않는 변경 (의존성 업데이트 등) |
+| **Refactor** | 버그 수정이나 기능 추가가 아닌 리팩토링 |
+| **Docs** | 문서 업데이트 (README 등 마크다운 파일 포함) |
+| **Style** | 코드 의미에 영향을 주지 않는 변경 (공백, 세미콜론 누락 등 포매팅) |
+| **Test** | 테스트 추가 또는 기존 테스트 수정 |
+| **Perf** | 성능 개선 |
+| **Ci** | CI(Continuous Integration) 관련 |
+| **Build** | 빌드 시스템 또는 외부 의존성에 영향을 주는 변경 |
+| **Revert** | 이전 커밋 되돌리기 |
+
+---
+
+## 이슈 종료(Close) 키워드
+
+- `close`, `closes`, `closed`
+- `fix`, `fixes`, `fixed`
+- `resolve`, `resolves`, `resolved`
+
+**사용 구분**:
+- 내부 이슈 → `close`, `fix`
+- 외부 요청에 의한 이슈 → `resolve`
+
+해당 커밋이 master로 커밋되거나, 커밋의 브랜치가 master로 머지될 때 자동으로 이슈가 종료된다.
+
+---
+
+## 커밋 운영 가이드
+
+- 로컬 브랜치 커밋은 자유롭게 하되, PR 전에 **커밋을 정리**한다 (rebase, squash 등).
+- 수정 목적이 일관된 하나의 기능 또는 요구사항이면 **1 PR 1 Commit**을 권장한다.
+- 분량이 많으면 기능을 적절히 분리하여(**atomic commit**) 작은 단위로 만든다.
+- 이슈와 기능을 **잘게 쪼개야 한다**.
+
+---
+
+## 커밋 메시지 포맷
+
+### 기본 포맷
+```
+<Type>: [이슈키] <명령조 요약>
+
+[본문: 왜, 무엇을]
+
+[Footer: 이슈 링크]
+```
+
+### 예시 1 — 이슈를 footer에 기재
+```
+Feat: 기능 구현
+
+이러이러한 이유로 이렇게 수정한다
+
+[RV] PROJ-00000
+[AI] 100%
+```
+
+### 예시 2 — 이슈를 제목에 포함
+```
+Feat: PROJ-00000 - 기능 구현
+
+이러이러한 이유로 이렇게 수정한다
+
+[RV] PROJ-00000
+[AI] 100%
+```
+
+### 예시 3 — 간단한 수정 (한 줄)
+```
+Docs: PROJ-00000 - 기능 설명 추가
+```
+
+### 예시 4 — 한글 본문 포함
+```
+Feat: PROJ-38356 - 상품 캐시 조회 API 구현
+
+클라이언트에서 캐시 조회 요청이 들어오면 요청 파라미터
+기반으로 캐시 키를 계산하여 Redis 캐시를 조회한다.
+
+기존에는 Cassandra만 조회했지만 최근 변경 내역의 지연을
+줄이기 위해 Redis를 1차 조회 대상으로 사용한다.
+
+- Redis Cache Entity와 Cassandra Entity 간 변환을 정의한다
+- Redis Cache Key 생성 함수를 추가한다
+- 캐시 미스가 발생하면 Cassandra fallback을 유지한다
+
+[RV] PROJ-38356
+[AI] 100%
+```
+
+---
+
+## 기타
+- **Git 사용은 command line을 권장**한다.