Automation Flow (이 프로젝트의 작업 방식 자체)

memory feedback_automation_flow 정합 + 워크스페이스 skill 종합.

Overview

LinkMusic 은 1인 개발자 + Claude Code 협업으로 정식 출시급 SaaS 를 만든다. 메모리 / skill / hook 으로 자동화 흐름을 정형화 — 이 흐름 자체를 문서화한다.

권장 워크플로우

/spec  →  /tdd (선택)  →  구현  →  /verify  →  /sync-api (BE 변경 시)  →  /review  →  /commit  →  /pr

단계	도구	책임
1. SPEC 작성	`/spec` skill	인터뷰 → 명세 → 사용자 확정
2. TDD (선택)	`/tdd` skill	실패 테스트 먼저
3. 구현	메인 또는 `frontend-engineer` / `backend-engineer` 서브에이전트	코드
4. 검증	`/verify` skill	lint · typecheck · test · build (BE: ktlintCheck/build/test, FE: pnpm -r …)
5. API 동기화	`/sync-api` skill	OpenAPI fetch → orval → barrel → typecheck
6. 리뷰	`/review` skill	code-reviewer · security-auditor 서브에이전트
7. 커밋	`/commit` skill	conventional commits, 변경 레포 분류
8. PR	`/pr` skill	gh pr create + Copilot review

메모리 정합 (`~/.claude/projects/.../MEMORY.md`)

메모	행동 강제
`feedback_capacity`	Capacity 우려 빼고 정식 출시급 스코프 그대로
`feedback_no_assignee`	Claude 가 만드는 commit/PR 에 assignee 금지
`feedback_no_coauthor_trailer`	커밋에 `Co-Authored-By: Claude` trailer 금지
`feedback_git_flow`	feature → develop squash / develop → main merge commit / default=develop / review 1
`feedback_no_spec_numbering`	커밋·PR 에 SPEC 번호 박지 않음 (의미 기반 history)
`feedback_release_on_main_merge`	develop → main 후 무조건 `gh release create`. SemVer + 포함 SPEC
`feedback_local_verify_before_push`	환경 의존 변경은 로컬 통과 후에만 push
`feedback_copilot_review_before_merge`	merge 전 Copilot 코멘트 모두 평가·해결
`feedback_announce_new_env_vars`	main 머지 전 새 env var 사용자 안내 의무
`feedback_jira_task_md`	SPEC 완료 후 `docs/jira/{repo}/{category-slug}.md` 에 task 목록
`feedback_backend_engineer_delegation`	SPEC 확정 후 backend-engineer 일괄 위임
`feedback_frontend_no_direct_db`	프론트엔드는 DB 직접 접근 금지 — 모든 데이터 backend API 경유
`feedback_design_only_from_handoff`	디자인은 claude design handoff 에서만

서브에이전트 분담 (격리 컨텍스트)

에이전트	역할
`planner`	변경 전 탐색 · 영향분석 · SPEC 초안
`frontend-engineer`	Next.js · TS 구현 전담 (linkmusic-frontend-space)
`backend-engineer`	Kotlin · Spring 구현 전담 (linkmusic-msa-space-was)
`debugger`	에러 · 근본원인 추적
`test-writer`	테스트 설계 · 작성 (`/tdd` 짝)
`code-reviewer`	일반 코드 리뷰
`security-auditor`	보안 깊이 감사
`devops`	CI/CD · GitHub Actions · 배포

복잡한 작업은 격리 컨텍스트 서브에이전트에 위임 — 메인 대화의 토큰 보호.

Copilot review 사이클 자동화

PR 생성 후:

GitHub Copilot review trigger
코멘트 모두 평가 — 해결 / 불필요 분류
해결할 항목 수정 commit
모두 resolved 되면 merge
main 머지 시 release create

.claude/rules/frontend.md 의 Copilot 패턴 17 가지를 코드 작성 단계에서 적용 → review round 6+ → 1~2.

자동화 흐름 의무 (이 프로젝트 작업 방식 자체)

코드 변경 시:

타입 시그니처 / API 변경 → 모든 호출부 grep 후 함께 수정 (LSP find-references)
OpenAPI 변경 → /sync-api → typecheck → drift 0 확인
새 env var → main 머지 전 사용자 안내
동작 / 관례 변경 → 관련 docs · .claude/rules/ 함께 갱신 (이 페이지가 그 docs)
새 패턴 / helper 도입 → 같은 의미 호출 grep 후 동일 적용 (cross-cutting)
타입 변경 (필드 이름 등) → 접근처 grep 후 검증

주기 점검 — `/factcheck-docs`

문서와 코드 drift 정기 점검:

코드 path 가 실제 존재하는지
enum 값 / API endpoint 가 OpenAPI 와 일치하는지
handoff brief 의 ① 항목이 코드에 반영됐는지

각 레포는 주간 docs-factcheck 워크플로우 자동 수행 (GitHub Actions schedule).

Constraints

자동화는 작성 단계에서. CI 강제 검증 X (false positive 위험).
새 SPEC 작업 시 docs 동기화는 같은 PR 안에서 (이 문서의 SPEC #014 §2-5).

HqDispatchScheduler (#078 — 본사 송출 예약 디스패처)

본사 송출 예약(SPEC #078)이 도입한 BE 백그라운드 컴포넌트. 다른 자동화 자원과 한 곳에서 추적할 수 있게 본 페이지에 정리.

위치: application/hq/HqDispatchScheduler.kt (linkmusic-msa-space-was).
트리거: @Scheduled(cron = "0 * * * * *") — 1분마다 1 tick. 환경별 enable/disable: @ConditionalOnProperty(name = "scheduler.dispatch.enabled", matchIfMissing = true).
동작: 한 tick 당 한 번의 원자 UPDATE 로 SCHEDULED → PENDING 전이.
```
UPDATE announcement_dispatch
SET status = 'PENDING'
WHERE status = 'SCHEDULED' AND scheduled_at <= :now
LIMIT 1000
```
affected rows 가 그 tick 에서 디스패치된 건수. LIMIT 1000 으로 한 tick 폭주를 가드(드물지만 1000 초과 시 다음 tick 에서 자연 처리).
멱등 보장: 같은 cron tick 이 중복 fire 해도 이미 PENDING 으로 전이된 row 는 WHERE status='SCHEDULED' 매치에서 제외 → 0 row affected. 동시 노드 race(현재는 단일 노드지만 후속 다중 노드 대비)도 같은 보장.
새 fan-out 훅 불요: 점장 player polling 이 이미 WHERE status='PENDING' 만 가져가므로, 디스패처는 status 만 바꾸면 자연 픽업. 별도 push/SSE 0.
audit 미생성: 자동 전이는 시스템 액션이라 audit 0. 예약 등록 시점에 이미 HQ_ANNOUNCEMENT_DISPATCHED audit 1건이 기록돼 있다(actor·시각·detail 에 scheduled_at 포함).
partial index: V29 의 idx_announcement_dispatch_scheduled(status, scheduled_at) WHERE status='SCHEDULED' 가 cron 쿼리를 가속. 전체 row 가 아니라 SCHEDULED 만 인덱스 적재 → 디스패처 종료 후 PENDING 된 row 는 인덱스에서 빠짐(VACUUM).
테스트 환경: scheduler.dispatch.enabled=false 로 통합 테스트가 cron 간섭 없이 명시 호출만 검증.

Roadmap

docs 사이트 publish 시 자동 deploy (Vercel)
OpenAPI diff → 자동 changelog generation
Copilot review 자동 응답 (해결 가능한 nit 자동 fix)
다중 노드 leader election (현재는 단일 노드 가정 — 다중 노드 도입 시 race 가드는 원자 UPDATE 가 이미 보장하지만, 불필요한 중복 쿼리 줄이려면 leader 만 cron 실행)

References

워크스페이스 CLAUDE.md
.claude/skills/ (/spec · /verify · /sync-api · /commit · /pr · /factcheck-docs · /tdd · /review)
.claude/agents/ (subagent 정의)
.claude/rules/ (frontend.md · backend.md)
memory feedback_*

Design System (OKLCH v2)Login