가이드

QJC OS 시스템의 사용법을 안내합니다 — 프로젝트, 태스크, 워크플로우, 스케줄 등

워크플로우 시스템 사용법 PM 스킬

대표 (CLI + 대시보드)

1
/project add "프로젝트명"
프로젝트 생성 → 워크플로우 시작
2
/task add "할일" → /task done 번호
태스크 관리 → 자동 전진
3
/leads → 이메일 생성 → 발송
리드 발굴에서 전환까지

직원 (대시보드 위주)

1
대시보드 홈 (/) 접속
오늘 태스크 + 전체 현황 확인
2
/tasks 페이지에서 체크박스
태스크 완료/상태 변경
3
/projects 페이지에서 카드 클릭
프로젝트 상세 + 워크플로우 확인

3대 원툴 (Sprint 1~3)

1
/meeting <녹음> --project <name>
회의록 + 태스크 + GitHub + Discord 원툴
2
/project-update "메시지" --type=progress
진행/결정/블로커 팀 브로드캐스트
3
/team-sync --push
git push/pull + 큐 drain + AUDIT 알림

기능 카탈로그

3대 원툴 (Phase 5 배포)

상세: .claude/rules/three-tools.md

/meeting— 미팅 후처리

입력

오디오/전사 파일

출력

• os_meetings INSERT (client_reference_id 멱등)
• action_items → os_tasks 배치 (담당자 자동 할당)
• 회의록 GitHub 자동 커밋 (minutes_github_url)
• meeting_summary Discord embed (dedup)

플래그

--project --auto-tasks --dry-run --resume --auto-advance --skip-stt --skip-github --no-broadcast

⚠ 이 명령어 아님 → 미팅 사전 브리핑은 /meeting-prep

/project-update— 진행 브로드캐스트📝 텍스트만 OK

입력

"메시지" (필수) + --type + --project

출력

• os_project_updates INSERT
• project_update notify (Discord + In-App)
• --type=progress 시 advance-stage 서버 판정 호출

플래그

"메시지" [--type=status|milestone|decision|blocker|progress] [--project=name]

⚠ 이 명령어 아님 → 태스크 단건 할당은 /task add

/team-sync— 코드·큐 동기화

입력

(자동 훅) 또는 수동

출력

• dotclaude + 현재 repo git push/pull
• os_command_queue drain (queue/ack)
• Discord AUDIT embed + 팀 현황 출력

플래그

--push / --pull / --status-only / --docs-only / --force / --auto-commit

⚠ 이 명령어 아님 → 코드 리뷰는 /code-review

의사결정 트리

무엇을 하려는가?
├─ 미팅 녹음이 있다 ............. /meeting
├─ 진행/결정/블로커 공지 ........ /project-update
├─ git/큐 동기화 ................ /team-sync
├─ 태스크 1건 할당 .............. /task add "제목" --owner=이름
└─ 신규 프로젝트 시작 ........... /project-launch

Sprint 3 훅 3종 + 알림 정책

훅	이벤트	트리거	출력	쿨다운
post-meeting-commit.sh	PostToolUse (Edit/Write)	*/meetings/YYYYMMDD-.md 파일 편집	stderr 배너 — /meeting --commit-minutes 안내	없음 (fire-and-forget)
team-sync-context.sh	UserPromptSubmit	모든 사용자 프롬프트 제출	본인 os_command_queue pending top 3 priority ASC 주입	5분
pm-orchestrator-preflight.sh	SubagentStart	pm-orchestrator 에이전트 진입	team/live 프리페치 → 활성 프로젝트 top5 + workflow_stage 주입	10분

MENTION_ALLOWLIST (opt-in 7종)

• task_assigned
• project_kickoff
• quotation_pending_approval
• incentive_deadline_warning
• gov_support_deadline_d3
• project_stale_warning
• project_owner_changed

목록 외 타입이 mentionRecipients:true로 호출되면 강제 false + warn 로그.

남용 방지

• 수신자 ≥ 3명 자동 off (스팸 방지)
• meeting_summary는 embed 1건에 집계 (여러 태스크 digest)
• 브로드캐스트 이벤트(weekly_team_summary 등)는 제외

pg_cron 운영 (os_command_queue)

Sprint 3 마이그레이션 20260419_expand_command_queue이drain_command_queue(p_dry_run BOOLEAN) RPC와 pg_cron 15분 주기 스케줄을 등록했다. 1주 dry-run 검증 후실제 UPDATE 모드로 전환한다.

현재 cron job 조회

SELECT jobname, schedule, command, active
  FROM cron.job
  WHERE jobname = 'drain-command-queue-dry-run';

최근 실행 이력 (5건)

SELECT start_time, status, return_message
  FROM cron.job_run_details
  WHERE jobid = (SELECT jobid FROM cron.job WHERE jobname='drain-command-queue-dry-run')
  ORDER BY start_time DESC
  LIMIT 5;

1주 검증 후 실제 실행 모드로 전환

SELECT cron.alter_job(
  (SELECT jobid FROM cron.job WHERE jobname='drain-command-queue-dry-run'),
  command => 'SELECT public.drain_command_queue(false);'
);

⚠ 실행 전 최근 7일 로그에 FAIL 0건 + expired/timeout 카운트가 기대치 이내인지 확인.

신규 사원 온보딩 13단계 (김광오 + 장소영 공통)

company-claude 최초 셋업 시 아래 13단계를 순서대로 진행. 3~6번은 대표가 공유한 시크릿이 필요하며, 8번은 discord:access 스킬로 대표 승인 후 완료된다. 11~13번(2026-04-24 추가)은 설치 이후 실사용 시작을 위한 단계 — 이미 설치 완료된 사원은 11부터 진행.

1
company-claude clone
git clone https://github.com/qjc-office/company-claude ~/qjc-office/company-claude
2
install.sh 실행
cd ~/qjc-office/company-claude && ./install.sh
3
WORKER_API_KEY 입력
~/.claude/settings.local.json (install.sh가 안내)
4
qjc-member.json 생성
~/.claude/qjc-member.json — member_id/name/role
5
GitHub SSH/PAT 설정
ssh-keygen + GitHub 계정 등록
6
Supabase MCP 인증
Claude Code에서 /mcp → supabase authenticate
7
gws CLI 인증
gws auth login -s drive,sheets,docs,chat
8
Discord bot 채널 allowlist
/discord:access 스킬 실행 → 대표(정상록)가 pairing 승인
9
첫 /team-sync --pull
Claude Code 세션 내에서 실행
10
훅 3종 로드 확인
새 세션 시작 → team-sync-context (UserPromptSubmit) + changelog-briefing (SessionStart) 배너 stderr 노출
11
대시보드 /guide 북마크
qjc-internal.vercel.app/guide 접속 → 3탭(워크플로우/시스템/PM 스킬) 모두 확인 → 브라우저 북마크. 모르는 명령어는 먼저 여기부터.
12
WORKER_KEY_{이름} 발급·설정 상세
대표가 Vercel/Supabase에서 WORKER_KEY_KWANGO 또는 WORKER_KEY_SOYOUNG 생성 → Bitwarden으로 전달 → ~/.claude/.env.secrets에 export. 검증: bash ~/qjc-office/qjc-os-스킬/scripts/verify-env-sync.sh (env-sync.md:26-43 참조)
13
첫 스킬 실행 권장 순서
1) /team-sync --pull 2) /sync-all --check-only 3) /task list @본인 4) /checkin 5) (업무) /pm prd, /meeting 등 6) /checkout 7) /save-work

9·10번 완료 후 SessionStart에changelog-briefing.sh가 최근 Phase 5 업데이트를 자동 공지한다.

문서 동기화 훅 3종 (Phase 9~11)

코드(현장)와 문서(도면) 간 드리프트를 자동 감지한다. 건물 시공에서 도면과 현장이 맞지 않으면 감리관이 경고하듯, CLAUDE.md·rules/·PRD가 코드보다 10커밋 이상 뒤쳐지면 SessionStart 배너가 알린다.

claudemd-drift-check.shSessionStart

용도: CLAUDE.md 드리프트 감지

메커니즘: git rev-list --count '${CLAUDE_SHA}..HEAD' (SHA range, exclusive)

임계값: 10커밋 이상: ⚠ 경고 / 20커밋 이상: 🚨 적색 + Top 5 변경 파일

쿨다운: 24시간 (레포별, mkdir atomic lock)

post-merge-sync-docs-check.shPostToolUse (Bash)

용도: gh pr merge 성공 감지 → /sync-docs 제안

메커니즘: ^\s*gh\s+pr\s+merge\b regex 앵커 + stdout 'Merged pull request' 성공 판정

임계값: Bash 외 도구·주석·echo 오탐 차단

쿨다운: 2시간

commands-drift-check.shSessionStart

용도: personal ~/.claude/commands ↔ dotclaude/commands MD5 비교

메커니즘: md5 -q 또는 md5sum 양쪽 계산 후 비교

임계값: 5건 이상 차이 시 배너 (baseline 4건 수용, Phase 12 조정)

쿨다운: 24시간

전역 토글:QJC_DOC_SYNC_DISABLED=1로 3종 훅 일괄 비활성화 (alert fatigue 발생 시 임시 사용). 판정 로그는 ~/.claude/cache/doc-sync-metrics/*.jsonl에 누적.

Phase 10: git-confused-deputy RCE 방어

훅이 임의 git 레포 경로에서 실행될 때 악성 .git/config의 core.fsmonitor 등을 통한 RCE (CVE-2022-24765 클래스) 공격 표면을 차단한다.

적용된 방어층 (3개 훅 공통)

• export GIT_CONFIG_NOSYSTEM=1 GIT_CONFIG_GLOBAL=/dev/null — system/global config 무시
• git -c safe.directory=$CWD — 소유권 검증 엄격 모드
• -c protocol.file.allow=never -c protocol.ext.allow=never — 위험 프로토콜 차단
• git -C $CWD 명시 지정 (cd 없앰, 실행 컨텍스트 고정)
• stderr 민감 파일 마스킹: .env* / *secret* / *.pem / *.p12 → [REDACTED]

Phase 12: stale lock TTL 자동 복구

비유: 경비실 자물쇠가 밤새 눌려있다면 다음 날 경비원이 들어갈 수 없다. SIGKILL/crash/OOM으로trap EXIT이 실행되지 못하면 lock 디렉토리가 영구 잔존하여 이후 세션에서 배너가 영원히 출력되지 않는다.

복구 메커니즘

# mkdir lock 획득 직전에 10분 초과 stale lock 강제 제거
find "$STAMP_DIR" -maxdepth 1 -type d -name "*.lock.d" -mmin +10 \
  -exec rm -rf {} \; 2>/dev/null
mkdir "$LOCK_DIR" 2>/dev/null || exit 0
trap 'rmdir "$LOCK_DIR" 2>/dev/null' EXIT

✓정상 실행 시간은 <1초이므로 10분 TTL은 충분한 안전 여유

✓3개 훅 모두 동일 패턴 적용 (claudemd / commands / post-merge)

✓macOS BSD find + Linux GNU find 모두 호환 (-mmin +10)

독립 skeptic 재재감사 Round 2 PASS (score 8/10, 블로커 0건). 3계층 배포 완료: personal ~/.claude/hooks/ + dotclaude + company-claude .claude/hooks/.

시나리오별 사용 플로우

상황에 따라 어떤 순서로 기능을 사용하면 좋은지 안내합니다.

프로젝트 생성 → 기획 → 태스크 → 완료까지

/project add

/project meeting

/project prd

/task add

/task done

/project advance

사용 팁

CLI 팁

모든 스킬은 인자 없이 실행하면 대화형으로 안내합니다. 예: /project, /task

웹 팁

대시보드 주소: qjc-internal.vercel.app. 모든 변경은 실시간 반영됩니다.

자동화 팁

PRD 생성, 태스크 추가/완료 시 워크플로우가 자동으로 전진합니다. 수동 개입 최소화.