sonamu 0.8.21 → 0.8.22

package/src/skills/sonamu/cone.md

@@ -111,7 +111,7 @@ pnpm sonamu cone gen Post --locale en
 #### LLM이 참조하는 정보
 
 1. Entity JSON 구조 (props, subsets, enums, relations)
-2. 프로젝트 스킬 파일 (`.claude/skills/project/requirements.md`, `business-logic.md` 등)
+2. 도메인 규칙 파일 (`contract/**/*.contract.md`)
 3. 기존 cone 메타데이터 (보존 모드 시)
 
 ### 2. stub entity — Entity 생성 시 자동 cone 생성
@@ -302,9 +302,8 @@ relation prop에서 참조 데이터 조회 방식을 지정합니다.
 
 ### LLM cone 생성 품질 높이기
 
-1. `.claude/skills/project/requirements.md`에 프로젝트 요구사항을 상세히 기록
-2. `business-logic.md`에 비즈니스 로직을 기록
-3. `cone gen` 실행 — LLM이 이 파일들을 컨텍스트로 사용
+1. `contract/{domain}/{domain}.contract.md`에 도메인 규칙과 결정 근거를 상세히 기록
+2. `cone gen` 실행 — LLM이 `contract/**/*.contract.md`를 컨텍스트로 사용
 
 ### cone 재생성이 필요한 시점
 

package/src/skills/sonamu/fixture-cli.md

@@ -49,7 +49,7 @@ production/development master (실제 DB)
 
 faker 기반으로 새로운 테스트 데이터를 생성합니다.
 
-**CRITICAL: `--use-llm` 옵션은 실제 프로젝트에서 항상 사용해야 한다.** `--use-llm` 없이 생성하면 cone.note 기반 도메인 맥락이 반영되지 않아 faker 기본값만 사용되므로, 의미 없는 데이터가 생성될 수 있다. LLM이 `requirements.md`, `business-logic.md`를 참조해 맥락에 맞는 데이터를 생성하려면 이 옵션이 필수이다.
+**CRITICAL: `--use-llm` 옵션은 실제 프로젝트에서 항상 사용해야 한다.** `--use-llm` 없이 생성하면 cone.note 기반 도메인 맥락이 반영되지 않아 faker 기본값만 사용되므로, 의미 없는 데이터가 생성될 수 있다. LLM이 `contract/**/*.contract.md`를 참조해 맥락에 맞는 데이터를 생성하려면 이 옵션이 필수이다.
 
 **CRITICAL: fixture gen을 실행하기 전에 `cone.note`가 주요 prop에 존재하는지 확인한다.** cone.note가 없으면 LLM이 맥락을 파악할 수 없어 의미 있는 데이터 생성이 불가능하다. cone.note가 부족하면 `pnpm sonamu cone generate --use-llm`으로 cone을 재생성한다.
 

package/src/skills/sonamu/workflow.md

@@ -30,15 +30,14 @@ description: Sonamu 전체 개발 워크플로우. 프로젝트 생성부터 Fro
 2. Sonamu skills를 읽고 `pnpm create sonamu [프로젝트명] --yes`로 프로젝트 생성
 3. `pnpm install` 실행
 
-### 2. 요구사항 기록 및 비즈니스 로직 파악
+### 2. 요구사항 파악 및 도메인 식별
 
-**CRITICAL: 이 단계(Step 4~6)를 완료하기 전에 auth generate나 인프라 기동으로 넘어가지 않는다.**
+**CRITICAL: 이 단계(Step 4~5)를 완료하기 전에 auth generate나 인프라 기동으로 넘어가지 않는다.**
 
-4. 사용자가 입력한 prompt를 프로젝트 루트의 `.claude/skills/project/requirements.md`에 기록
-5. 비즈니스 로직 파악 후 **작은 단위로** 사용자에게 확인받기
+4. 요구사항을 파악하고 도메인을 식별. 도메인별로 작은 단위로 사용자에게 확인받기
    - 한 번에 전체를 확인하지 말고 도메인별로 나누어 확인
    - "이 부분이 맞나요?" 식으로 구체적으로 질문
-6. 비즈니스 로직 최종 승인 완료 시 `.claude/skills/project/business-logic.md`에 기록
+5. 식별된 도메인 목록을 사용자에게 확인받기. PHASE 1에서 도메인별 `*.contract.md`를 작성함
 
 ### 3. 설정 확인
 
@@ -77,7 +76,7 @@ description: Sonamu 전체 개발 워크플로우. 프로젝트 생성부터 Fro
 **완료 기준:**
 
 - [ ] 프로젝트 생성 완료
-- [ ] requirements.md, business-logic.md 기록 완료
+- [ ] 도메인 목록 식별 및 사용자 승인 완료
 - [ ] sonamu.config.ts, .env 설정 확인 및 사용자 승인 완료
 - [ ] Docker, dev 서버 실행 중
 - [ ] Auth 엔티티 생성 및 migration 완료
@@ -85,58 +84,46 @@ description: Sonamu 전체 개발 워크플로우. 프로젝트 생성부터 Fro
 
 ---
 
-## PHASE 0.5: Contract 및 Spec 작성
+## PHASE 1: 도메인 Logic 문서화
 
 **참조 스킬:** cdd.md
 
-**CRITICAL: 이 PHASE가 완료되기 전에 엔티티 설계(PHASE 1)를 시작하지 않는다.**
+**CRITICAL: 이 PHASE가 완료되기 전에 엔티티 설계(PHASE 2)를 시작하지 않는다.**
 
-### 7. main.contract.json 작성
+### 7. 도메인별 `*.contract.md` 작성
 
-20. `packages/api/contract/main.contract.json` 생성
-    - `requirements.md`, `business-logic.md` 기반으로 작성
-    - 전체 프로젝트 Overview, 하위 도메인 목록, Domain Glossary, User Roles, Business Rules, Edge Cases 포함
-    - `content`는 Markdown 한 줄씩 `string[]`로 작성
-21. 사용자에게 보고 후 승인 대기
-
-### 8. 도메인별 contract 작성
-
-22. `business-logic.md`에서 도메인을 식별하고 도메인 목록을 사용자에게 확인받기
-23. 도메인별로 `packages/api/contract/{domain}/main.contract.json` 작성
+20. PHASE 0에서 확인된 도메인별로 `contract/{domain}/{domain}.contract.md` 작성
     - 도메인 폴더명은 영문 소문자 (예: `auth`, `organization`, `research`)
-    - 각 도메인 contract 작성 후 사용자 확인받기 (도메인별로 하나씩)
-    - Features/Capabilities 섹션을 상세하게 작성한다 (이후 spec의 1:1 기반이 됨)
+    - 도메인 규칙, 상태 전이, 권한, Edge Cases 등 코드만으로 파악하기 어려운 결정 근거 포함
+    - 처음부터 완벽할 필요 없음 — 사용자와 대화하면서 점진적으로 정리
+21. 도메인별로 작성 후 사용자에게 확인받기 (도메인별로 하나씩)
 
-### 9. Spec 작성
+**`*.contract.md` 형식:**
 
-**CRITICAL: 1 Feature = 1 Spec 파일. 도메인 contract의 Features/Capabilities에 정의된 기능 하나당 spec 파일 하나.**
+```markdown
+# {도메인} 비즈니스 로직
 
-24. 각 도메인의 Features/Capabilities를 기반으로 spec 파일 목록 작성 후 사용자 확인
-25. 도메인별로 spec 파일 작성
-    - spec 파일은 해당 도메인 폴더에 위치
-    - 파일명은 feature key (예: `signin.spec.json`)
-    - `status: "draft"`로 시작
-26. 전체 spec 작성 완료 후 사용자에게 검토 요청
-    - 사용자 검토 및 수정 반영
-    - 모든 spec 검토 완료 후에만 다음 PHASE로 진행
+## 규칙
+- 규칙과 결정 근거
+
+## 워크플로우
+1. ...
+```
 
 **완료 기준:**
 
-- [ ] `packages/api/contract/main.contract.json` 작성 및 사용자 승인
-- [ ] 모든 도메인 contract 작성 및 사용자 승인
-- [ ] 모든 domain spec 파일 작성 완료
-- [ ] 사용자 spec 검토 완료
-- [ ] `pnpm cdd test` 실행 시 MISSING 0, NO_MATCH 0 확인
+- [ ] 모든 도메인의 `contract/{domain}/{domain}.contract.md` 작성 완료
+- [ ] 사용자 도메인별 확인 완료
 
 ---
 
-## PHASE 1: 엔티티 설계
+## PHASE 2: 엔티티 설계
 
 **참조 스킬:** entity-basic.md, entity-relations.md
 
-**전제 조건:** PHASE 0.5 완료 (모든 spec 사용자 검토 완료)
+**전제 조건:** PHASE 1 완료 (모든 도메인 `*.contract.md` 사용자 확인 완료)
 
-### 10. 엔티티 설계
+### 8. 엔티티 설계
 
 20. 사용자 요구사항에 맞는 엔티티 설계
     - 설계하면서 사용자에게 비즈니스 로직에 맞는지 **지속적으로 디테일하게** 확인받을 것
@@ -156,22 +143,22 @@ description: Sonamu 전체 개발 워크플로우. 프로젝트 생성부터 Fro
 
 ---
 
-## PHASE 2: 엔티티 생성 및 마이그레이션
+## PHASE 3: 엔티티 생성 및 마이그레이션
 
 **참조 스킬:** entity-basic.md, entity-validation-checklist.md, migration.md
 
-### 8. 엔티티 생성
+### 9. 엔티티 생성
 
 22. 설계에 따라 **batch로** entity.json 생성
 23. biome check, type check
 24. 문제 없이 빌드되는지 확인
 
-### 9. 마이그레이션
+### 10. 마이그레이션
 
 25. 사용자에게 Sonamu UI와 CLI 중 어떤 방식으로 migration을 진행할지 확인 후 실행
 26. 실제 테이블이 생성되었는지 확인
 
-### 10. Cone 및 Scaffolding
+### 11. Cone 및 Scaffolding
 
 **참조 스킬:** cone.md
 
@@ -205,44 +192,47 @@ description: Sonamu 전체 개발 워크플로우. 프로젝트 생성부터 Fro
 
 ---
 
-## PHASE 3: 테스트 및 API 구현
+## PHASE 4: 테스트 및 API 구현
+
+**참조 스킬:** testing.md, testing-devrunner.md, naite.md, cdd.md
 
-**참조 스킬:** testing.md, testing-devrunner.md, naite.md
+### 12. AC 구체화 및 Claim 구성
 
-### 11. 테스트 계획
+**AC(수락 기준)는 테스트 파일의 describe/test 이름이다.** 별도 문서로 관리하지 않는다.
 
-33. 테스트 계획을 batch로 세우기 — **항상 User 관련 테스트가 우선**
-34. `.claude/skills/project/test-plan.md`에 기록
-35. `architecture.md`에 test-plan.md 링크 추가
+33. `contract/**/*.contract.md`와 실제 코드를 참고하여 도메인별 AC 목록 초안 작성
+    - **항상 User 관련 테스트가 우선**
+34. 사용자와 논의하며 `pnpm cdd ac add`로 테스트 스켈레톤 생성
+35. `pnpm cdd ac list`로 확정된 AC 목록 확인
+36. Claim을 `tmp/claims/`에 YAML로 작성 (`surface` → `implement` 순)
+    - 상세 Claim 형식은 cdd.md 참조
 
-### 12. Batch별 테스트 및 API 구현 (반복)
+### 13. Claim 실행 (반복)
 
-각 batch마다 다음을 반복:
+각 Claim마다:
 
-36. **하나의 batch 비즈니스 로직에 맞는 테스트 코드 작성**
-37. biome check, type check
-38. **model의 API 구현**
+37. **AC 작성 + 구현 교차 반복** (AC 하나 → 구현 → 다음 AC → 구현)
+38. biome check, type check
 39. **`pnpm sonamu test`로 테스트 돌려보기**
     - dev 서버가 올라가있지 않으면 올린 뒤 실행
 
-### 13. 전체 검증
+### 14. 전체 검증
 
-40. 모든 batch 완료 후 전체 biome check, type check 및 빌드 확인
+40. 모든 Claim 완료 후 전체 biome check, type check 및 빌드 확인
 41. **`pnpm sonamu test`로 전체 테스트 실행**
 
 **완료 기준:**
 
-- [ ] test-plan.md 기록 완료
-- [ ] 모든 batch의 테스트 통과
-- [ ] 모든 batch의 API 구현 완료
+- [ ] 모든 도메인 AC 정의 완료 (테스트 파일에 스켈레톤으로 존재)
+- [ ] 모든 Claim 실행 완료
+- [ ] 모든 테스트 통과
 - [ ] 전체 biome check, type check, build 통과
-- [ ] 전체 테스트 통과
 
 ---
 
-## PHASE 4: Fixture 생성
+## PHASE 5: Fixture 생성
 
-### 14. Fixture 생성
+### 15. Fixture 생성
 
 42. 사용자에게 fixture 생성할지 확인
 43. 모든 엔티티의 prop에 `cone.note`가 존재하는지 체크
@@ -254,7 +244,7 @@ description: Sonamu 전체 개발 워크플로우. 프로젝트 생성부터 Fro
     - `pnpm sonamu fixture gen --include User,Account,Session --count 10 --use-llm`
     - **CRITICAL**: User.id string PK를 위한 `users_id_seq`가 생성되어 있어야 함 (PHASE 0 Step 18-19에서 설정)
     - 상세 내용은 `auth-migration.md` "Better-auth 엔티티 Fixture 생성" 섹션 참조
-46. 승인하면 테스트에서 batch로 나눈 대로 fixture 생성 (LLM 사용 필수)
+46. 승인하면 Claim 단위로 fixture 생성 (LLM 사용 필수)
     - `--use-llm` 옵션은 반드시 사용 (cone.note 기반 도메인 맥락 반영 필수)
 47. 실제 DB에 생성되었는지 사용자에게 확인 요청
 48. **`pnpm sonamu test`로 전체 테스트 재실행**
@@ -271,21 +261,19 @@ description: Sonamu 전체 개발 워크플로우. 프로젝트 생성부터 Fro
 
 ---
 
-## PHASE 5: Frontend 개발
+## PHASE 6: Frontend 개발
 
 **참조 스킬:** frontend.md
 
-### 15. Frontend 계획
+### 16. Frontend 계획
 
 49. Frontend 개발 진행할지 사용자에게 확인
-50. 승인 후 테스트에서 나눈 batch로 Frontend 개발 계획 세우기
-51. `.claude/skills/project/frontend-plan.md`에 기록
-52. `architecture.md`에 frontend-plan.md 링크 추가
+50. 승인 후 도메인별 Frontend 개발 계획을 `contract/{domain}/{domain}.contract.md`에 추가하거나 사용자와 구두로 확인
 
-### 16. Batch별 Frontend 개발 (반복)
+### 17. Batch별 Frontend 개발 (반복)
 
-53. batch 대로 조금씩 진행하며 **사용자에게 확인 요청**
-54. 사용자가 브라우저에서 확인 후 Claude Code에게 피드백
+51. batch 대로 조금씩 진행하며 **사용자에게 확인 요청**
+52. 사용자가 브라우저에서 확인 후 Claude Code에게 피드백
     - "확인했다"
     - "로직대로 된다"
     - "이 부분이 잘 안 된다"
@@ -293,7 +281,6 @@ description: Sonamu 전체 개발 워크플로우. 프로젝트 생성부터 Fro
 
 **완료 기준:**
 
-- [ ] frontend-plan.md 기록 완료
 - [ ] 모든 batch의 Frontend 구현 완료
 - [ ] 사용자 확인 및 피드백 반영 완료
 
@@ -301,17 +288,21 @@ description: Sonamu 전체 개발 워크플로우. 프로젝트 생성부터 Fro
 
 ## 프로젝트 문서 구조
 
-워크플로우 진행 중 다음 문서들이 프로젝트 루트의 `.claude/skills/project/`에 생성된다:
+워크플로우 진행 중 다음 문서들이 생성된다:
 
 ```
+contract/
+└── {domain}/
+    └── {domain}.contract.md  # PHASE 1: 도메인 규칙 + 결정 근거 (영구 문서)
+
 .claude/skills/project/
-├── requirements.md      # PHASE 0: 사용자 요구사항 원문
-├── business-logic.md    # PHASE 0: 파악한 비즈니스 로직 (사용자 승인)
-├── architecture.md      # PHASE 1: 엔티티 설계안 + test-plan, frontend-plan 링크
-├── test-plan.md         # PHASE 3: batch별 테스트 계획
-└── frontend-plan.md     # PHASE 5: batch별 Frontend 개발 계획
+└── architecture.md           # PHASE 2: 엔티티 설계안
+
+tmp/claims/                   # PHASE 4: 실행 중 Claim YAML (완료 후 폐기)
 ```
 
+**Ground truth는 코드다.** `*.contract.md`는 코드 결정의 근거를 기록하는 문서이지 선행 정의서가 아니다. 코드와 `*.contract.md`가 충돌하면 코드를 우선한다.
+
 ---
 
 ## 핵심 원칙
@@ -320,6 +311,7 @@ description: Sonamu 전체 개발 워크플로우. 프로젝트 생성부터 Fro
 2. **테스트는 `pnpm sonamu test`** — `pnpm test`는 CI용
 3. **순서를 지킬 것** — 단계를 건너뛰지 않음
 4. **사용자에게 자주 확인** — 추측하지 말고 질문
-5. **batch 단위로 작업** — 한 번에 모든 것을 하지 않음
+5. **Claim 단위로 작업** — 한 번에 모든 것을 하지 않음
 6. **User 관련이 항상 우선** — 테스트, API, Frontend 모두
-7. **문서를 기록** — requirements, business-logic, architecture, test-plan, frontend-plan
+7. **Ground truth는 코드** — `*.contract.md`는 근거 기록, 코드와 충돌 시 코드 우선
+8. **신규는 contract→Claim→AC→implement, 변경은 code→Claim→contract 갱신**

package/src/syncer/syncer.ts

@@ -283,7 +283,7 @@ export class Syncer {
 
   async autoloadWorkflows() {
     this.workflows = await loadWorkflows();
-    await Sonamu.workflows?.synchronize(this.workflows);
+    await Sonamu.workflows.synchronize(this.workflows);
   }
 
   async autoloadSSRRoutes(): Promise<void> {

package/src/testing/global-setup.ts

@@ -31,10 +31,6 @@ export function createGlobalSetup() {
       };
     }
 
-    if (!config.database) {
-      throw new Error("database 설정이 필요합니다 (병렬 테스팅)");
-    }
-
     const maxWorkers = config.test.maxWorkers ?? 4;
     const templateDb = `${config.database.name}_test`;
 

package/src/ui/api.ts

@@ -1087,12 +1087,15 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
 
       // Tasks API
       server.get("/api/tasks/status", async () => {
-        return { active: Sonamu.workflows !== null };
+        try {
+          Sonamu.workflows;
+          return { active: true };
+        } catch {
+          return { active: false };
+        }
       });
 
       server.get("/api/tasks/workflowDefinitions", async () => {
-        if (!Sonamu.workflows)
-          throw new Error("Workflows not initialized (database not configured)");
         const definitions = Sonamu.workflows.workflowDefinitions;
         return { definitions };
       });
@@ -1109,8 +1112,6 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
           createdBefore?: string;
         };
       }>("/api/tasks/workflowRuns", async (request) => {
-        if (!Sonamu.workflows)
-          throw new Error("Workflows not initialized (database not configured)");
         const backend = Sonamu.workflows.backend;
         const { limit, after, before, order, status, workflowName, createdAfter, createdBefore } =
           request.query;
@@ -1129,8 +1130,6 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
       server.get<{
         Params: { id: string };
       }>("/api/tasks/workflowRuns/:id", async (request) => {
-        if (!Sonamu.workflows)
-          throw new Error("Workflows not initialized (database not configured)");
         const backend = Sonamu.workflows.backend;
         const workflowRun = await backend.getWorkflowRun({
           workflowRunId: request.params.id,
@@ -1144,8 +1143,6 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
       server.post<{
         Params: { id: string };
       }>("/api/tasks/workflowRuns/:id/cancel", async (request) => {
-        if (!Sonamu.workflows)
-          throw new Error("Workflows not initialized (database not configured)");
         const backend = Sonamu.workflows.backend;
         return backend.cancelWorkflowRun({
           workflowRunId: request.params.id,
@@ -1155,8 +1152,6 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
       server.post<{
         Params: { id: string };
       }>("/api/tasks/workflowRuns/:id/pause", async (request) => {
-        if (!Sonamu.workflows)
-          throw new Error("Workflows not initialized (database not configured)");
         const backend = Sonamu.workflows.backend;
         return backend.pauseWorkflowRun({
           workflowRunId: request.params.id,
@@ -1166,8 +1161,6 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
       server.post<{
         Params: { id: string };
       }>("/api/tasks/workflowRuns/:id/resume", async (request) => {
-        if (!Sonamu.workflows)
-          throw new Error("Workflows not initialized (database not configured)");
         const backend = Sonamu.workflows.backend;
         return backend.resumeWorkflowRun({
           workflowRunId: request.params.id,
@@ -1182,8 +1175,6 @@ export async function sonamuUIApiPlugin(fastify: FastifyInstance) {
           before?: string;
         };
       }>("/api/tasks/workflowRuns/:id/steps", async (request) => {
-        if (!Sonamu.workflows)
-          throw new Error("Workflows not initialized (database not configured)");
         const backend = Sonamu.workflows.backend;
         const { limit, after, before } = request.query;
         return backend.listStepAttempts({

package/src/skills/project/business-logic.md

@@ -1,270 +0,0 @@
-# 비즈니스 로직 상세
-
-> 이 문서는 개발 과정에서 정리되는 비즈니스 규칙과 로직을 기록합니다.
-> 대화를 통해 명확해진 내용들을 추가하여 일관된 구현을 유지합니다.
-
-## 엔티티별 비즈니스 규칙
-
-### [Entity명]
-
-#### 상태 전이
-
-<!--
-예시:
-- draft → published: 관리자만 가능, 필수 필드 검증
-- published → closed: 마감일 이후 자동 전환
-- closed → archived: 90일 후 자동 전환
--->
-
-#### 검증 규칙
-
-<!--
-예시:
-- 제목: 3-100자, 필수
-- 시작일 < 종료일
-- 예산: 0 이상
-- 첨부파일: 최대 10MB, 5개까지
--->
-
-#### 계산 로직
-
-<!--
-예시:
-- 총점 = sum(평가항목별 점수 × 가중치)
-- 진행률 = (완료된 마일스톤 / 전체 마일스톤) × 100
--->
-
-#### 권한 규칙
-
-<!--
-예시:
-- 생성: 로그인한 모든 사용자
-- 수정: 작성자 본인 또는 관리자
-- 삭제: 관리자만
-- 조회: 공개 상태면 모두, 비공개면 작성자/관리자만
--->
-
----
-
-## 워크플로우
-
-### [프로세스명]
-
-<!--
-예시: 연구과제 평가 프로세스
-
-1. 공고 발행 (관리자)
-2. 과제 지원 (신청자)
-3. 평가위원 배정 (관리자)
-4. 평가표 작성 (평가위원)
-   - 각 항목별 점수 입력
-   - 총점 자동 계산
-   - 의견 작성
-5. 평가 완료 처리
-   - 모든 평가위원 제출 완료 시
-   - 평균 점수 계산
-6. 선정 결과 발표 (관리자)
-
-예시: 의료 실험 데이터 수집 프로세스
-
-1. 프로토콜 승인 (IRB)
-2. 피험자 모집 및 동의서 획득 (연구원)
-3. 베이스라인 데이터 수집 (연구원)
-4. 데이터 검증 (모니터)
-5. 주기적 follow-up 데이터 수집
-   - 스케줄 알림 자동 발송
-   - 데이터 입력
-   - 이상치 자동 플래그
-6. 최종 분석 (연구책임자)
-
-예시: 커머스 주문 처리 프로세스
-
-1. 장바구니 담기 (고객)
-2. 주문 생성 및 재고 예약 (시스템)
-3. 결제 처리 (PG사 연동)
-4. 결제 확인 및 주문 확정 (시스템)
-5. 상품 준비 (판매자)
-6. 배송 시작 (배송사 연동)
-7. 배송 완료 (배송사 웹훅)
-8. 구매 확정 (고객 또는 자동)
-
-예시: AI Agent 대화 세션 프로세스
-
-1. 세션 생성 (사용자)
-2. 프롬프트 템플릿 선택 (사용자 또는 자동)
-3. 사용자 메시지 입력
-4. 모델 선택 및 파라미터 설정 (자동)
-5. AI 응답 생성 (외부 API 호출)
-6. 응답 저장 및 표시
-7. 사용량 기록 (토큰 수 계산)
-8. 세션 종료 또는 계속
-
-예시: 의사 소통 도구 메시지 전달 프로세스
-
-1. 메시지 작성 (의사)
-2. 메시지 타입 감지 (텍스트/이미지/파일/음성)
-3. 의료정보 포함 여부 자동 감지
-4. 민감 정보 암호화 (필요시)
-5. 채널 멤버에게 전송
-6. 실시간 알림 발송 (푸시/이메일)
-7. 읽음 상태 업데이트
-8. 검색 인덱싱
--->
-
----
-
-## 상태 전이 다이어그램
-
-<!--
-Mermaid 다이어그램이나 텍스트로 표현
-
-예시:
-```
-[초안] --발행--> [발행됨] --마감--> [마감됨] --보관--> [보관됨]
-  |                |
-  +----삭제--------+
-```
--->
-
----
-
-## 비즈니스 제약사항
-
-<!--
-예시 (연구과제):
-- 한 사용자는 동일 공고에 한 번만 지원 가능
-- 평가위원은 자신의 소속 기관 과제는 평가 불가
-- 평가 시작 후에는 평가 기준 변경 불가
-- 마감일 이후 지원서 수정 불가
-
-예시 (의료 실험):
-- IRB 승인 없이는 데이터 수집 불가
-- 피험자는 언제든 참여 철회 가능
-- 프로토콜 일탈은 24시간 내 보고 필수
-- 데이터 삭제 요청시 익명화 처리 (완전 삭제 불가)
-
-예시 (커머스):
-- 동일 상품 중복 재고 예약 방지
-- 결제 실패시 재고 예약 자동 해제
-- 판매자는 본인 상품만 수정 가능
-- 리뷰는 구매 확정 후에만 작성 가능
-
-예시 (AI Agent):
-- 동시 세션 수 제한 (플랜별)
-- API 호출 실패시 3회 재시도 후 에러
-- 프롬프트 템플릿은 버전 관리 (삭제 불가)
-- 과거 대화는 수정 불가 (읽기 전용)
-
-예시 (의사 소통 도구):
-- 채널 멤버만 메시지 접근 가능
-- 삭제된 메시지는 7일간 복구 가능
-- 민감 정보 포함 채널은 외부 초대 불가
-- 파일은 바이러스 검사 후 업로드
--->
-
----
-
-## 알림 규칙
-
-<!--
-예시 (연구과제):
-- 공고 발행 시: 전체 사용자에게 이메일 발송
-- 평가 배정 시: 해당 평가위원에게 알림
-- 평가 마감 3일 전: 미제출 평가위원에게 알림
-- 선정 결과 발표 시: 지원자에게 개별 알림
-
-예시 (의료 실험):
-- 방문 예정일 3일 전: 피험자에게 SMS 알림
-- 데이터 이상치 감지: 연구원에게 즉시 알림
-- 프로토콜 일탈 발생: 연구책임자에게 즉시 알림
-- 동의서 만료 30일 전: 연구원에게 갱신 알림
-
-예시 (커머스):
-- 주문 확정: 판매자에게 즉시 알림
-- 배송 시작: 고객에게 추적번호 포함 알림
-- 재고 부족 (임계값 이하): 판매자에게 알림
-- 구매 확정: 판매자에게 정산 예정 알림
-
-예시 (AI Agent):
-- 사용량 80% 도달: 사용자에게 경고
-- API 오류 발생: 관리자에게 즉시 알림
-- 세션 타임아웃 5분 전: 사용자에게 연장 여부 확인
-- 새 모델 추가: 전체 사용자에게 공지
-
-예시 (의사 소통 도구):
-- 새 메시지: 채널 멤버에게 실시간 푸시
-- 멘션 시: 해당 사용자에게 강조 알림
-- 파일 업로드 완료: 업로더에게 알림
-- 읽지 않은 메시지 100개 이상: 일일 요약 이메일
--->
-
----
-
-## 예외 처리
-
-<!--
-예시:
-- 중복 지원 시도: "이미 지원한 공고입니다" 에러
-- 권한 없는 수정: "권한이 없습니다" 에러
-- 마감 후 지원: "마감된 공고입니다" 에러
-- 필수 필드 누락: 구체적인 필드명 포함 에러
--->
-
----
-
-## 데이터 일관성
-
-<!--
-예시 (연구과제):
-- 과제 삭제 시: 관련 평가 데이터도 함께 삭제 (CASCADE)
-- 사용자 삭제 시: 작성한 콘텐츠는 유지하되 "탈퇴한 사용자"로 표시
-- 평가표 제출 후: 평가 항목 변경 불가 (버전 관리)
-
-예시 (의료 실험):
-- 피험자 탈퇴 시: 데이터는 익명화하여 보존
-- 프로토콜 변경 시: 기존 버전도 보관 (감사 추적)
-- 동의서 철회 시: 향후 데이터 수집 중단, 기존 데이터는 익명화
-
-예시 (커머스):
-- 상품 삭제 시: 주문 히스토리는 유지 (스냅샷)
-- 주문 취소 시: 재고 복원, 결제 환불 처리
-- 판매자 탈퇴 시: 진행 중인 주문 완료 후 계정 비활성화
-
-예시 (AI Agent):
-- 프롬프트 템플릿 삭제 시: 기존 세션은 유지 (soft delete)
-- 사용자 삭제 시: 대화 히스토리 익명화
-- 모델 변경 시: 기존 세션은 기존 모델 설정 유지
-
-예시 (의사 소통 도구):
-- 채널 삭제 시: 메시지 30일간 보관 후 영구 삭제
-- 사용자 탈퇴 시: 메시지는 유지하되 "탈퇴한 사용자"로 표시
-- 파일 삭제 시: 참조하는 메시지가 있으면 soft delete
--->
-
----
-
-## 성능 고려사항
-
-<!--
-예시:
-- 대시보드 통계: 캐시 적용 (5분 TTL)
-- 검색: 인덱스 적용 필요 필드 명시
-- 파일 업로드: 비동기 처리
-- 대량 데이터: 페이지네이션 필수
--->
-
----
-
-## 개발 중 논의 내역
-
-<!--
-날짜별로 대화 중 정리된 내용 기록
-
-### 2024-01-15
-- 평가 점수 계산 방식 확정: 가중치 평균 사용
-- 동점자 처리: 특정 항목 우선순위로 결정
-
-### 2024-01-20
-- 첨부파일 저장 방식: S3 사용 결정
-- 파일명 중복 처리: UUID 접두사 추가
--->