규약

이 페이지는 코드 네이밍, i18n 번역 용어집, 중국어 보이스 가이드의 단일 진실 공급원입니다. 예전에 packages/views/locales/glossary.md나 여기저기 흩어진 주석에 있던 내용은 이제 모두 이곳에 모여 있습니다.

Clowld Space 코드를 작성하거나, 번역을 변경하거나, 중국어 제품 카피를 작성한다면 이 페이지를 참고하세요.

용어와 개념의 진실 공급원

• 제품 객체의 고정 명칭, 의미, 관계는 docs/知识库/开始使用/核心概念.md에서 정의하며, 공개 페이지 apps/docs/content/docs/concepts.zh.mdx도 같은 의미를 유지합니다.
• 코드 네이밍, i18n 용어집, 중국어 제품 문체는 이 페이지에서 정의합니다. 저장소의 docs/知识库/开发者/开发规范.md는 Markdown 제목 래퍼를 제외하고 중국어 페이지와 문장 단위로 동기화되어야 합니다.
• CONTEXT.md, 별도의 glossary, 병렬 도메인 용어 문서를 만들지 않습니다. 용어나 개념을 바꿀 때는 영향을 받는 모든 진실 공급원을 같은 변경에서 갱신하고 충돌을 해결한 뒤 병합합니다.

1. 코드 네이밍

라우트

워크스페이스 진입 전 라우트(사용자가 워크스페이스에 들어가기 전에 존재하는 라우트)는 반드시 단일 단어 또는 /{noun}/{verb} 패턴을 사용해야 합니다.

• ✅ /login, /inbox, /workspaces/new
• ❌ /new-workspace, /create-team, /accept-invite

루트에 하이픈으로 연결된 단어 묶음은 사용자가 직접 고른 워크스페이스 slug와 충돌하며, 끝없는 예약어 slug 점검을 강요합니다. 명사(workspaces)를 예약해 두면 /workspaces/* 하위 트리 전체가 자동으로 보호됩니다.

워크스페이스 범위 라우트

항상 /{slug}/{section} 아래에 둡니다 — /{slug}/issues, /{slug}/agents, /{slug}/settings. 워크스페이스 라우팅 로직을 절대 중복하지 말고, 공유 코드에서는 프레임워크별 link API 대신 useNavigation().push()를 사용하세요.

패키지와 모듈

모노레포는 엄격한 패키지 경계를 강제합니다:

두 앱 모두에 동일한 로직이 나타난다면 반드시 공유 패키지로 추출해야 합니다. "사소한" 중복이라는 예외는 없습니다. Mobile은 독립된 UI, 데이터 계층, 출시 절차를 가지며 유형과 순수 함수만 공유합니다.

파일과 컴포넌트

• 파일: kebab-case.tsx / kebab-case.ts (예: agent-row-actions.tsx)
• 컴포넌트: PascalCase (예: AgentRowActions)
• Hook: useCamelCase (예: useWorkspaceId)
• 테스트: <file>.test.ts(x)로 같은 위치에 배치
• Store (Zustand): <feature>-store.ts, use<Feature>Store로 export

데이터베이스 (Go + sqlc)

• 테이블: snake_case 단수 (user, workspace, agent_runtime)
• 컬럼: snake_case (workspace_id, created_at, last_seen_at)
• 외래 키: <table>_id
• 불리언: is_<state> 또는 <state>_at (상태 변경에는 타임스탬프 형태 선호)
• 마이그레이션 파일: NNN_descriptive_name.up.sql + .down.sql — 항상 양방향을 모두 제공
• 데이터베이스 foreign key, cascade delete, cascade update를 만들지 않고 관계 검사와 정리는 애플리케이션 계층에서 수행
• 모든 index는 CREATE INDEX CONCURRENTLY 또는 CREATE UNIQUE INDEX CONCURRENTLY를 사용하고 각 concurrent index를 단일 문장 migration 파일에 분리

Go

• 표준 gofmt + go vet. 예외 없음.
• Handler 파일은 도메인을 반영: agent.go, auth.go, runtime.go
• 테스트: <file>_test.go로 같은 위치에 배치
• handler에서의 UUID 파싱은 루트 AGENTS.md의 규칙을 따릅니다 — 경계 입력에는 parseUUIDOrBadRequest, 신뢰할 수 있는 왕복에는 parseUUID(panic 버전), 절대 error를 확인하지 않고 util.ParseUUID를 직접 사용하지 마세요.

TypeScript

• 네트워크상의 API 응답은 snake_case이며, api client가 경계에서 camelCase로 변환합니다. TS 코드 내부에서는 항상 camelCase.
• 타입: PascalCase (Issue, AgentRuntime); IPrefix 금지, _t 접미사 금지.
• 열거형: string literal union을 선호하고, 런타임 순회가 필요한 경우에만 enum을 사용.
• TanStack Query 키: <feature>/queries.ts 안의 팩토리 함수, 예: issueKeys.detail(id).

API 경계

• 네트워크 응답은 packages/core/api/schema.ts의 parseWithFallback과 zod schema로 parsing하며 as T로 직접 강제 변환하지 않음
• endpoint를 추가하거나 변경할 때 schema도 업데이트하고 필드 누락 또는 잘못된 형식을 테스트로 포함
• 하위 UI는 선택 필드에 기본값을 제공하고 서버 enum의 switch에는 반드시 default 분기를 포함
• 설치된 Desktop이 더 새로운 backend에 연결될 수 있으므로 프런트엔드와 backend가 항상 같은 버전이라고 가정하지 않음

태스크 키

모든 태스크에는 CS-123 같은 사람이 읽을 수 있는 키가 있습니다: 워크스페이스 issue_prefix(대문자와 숫자, 보통 3자, 최대 10자) + 일련번호. 워크스페이스 admin은 Settings → General에서 접두사를 변경할 수 있는데, 변경하면 기존의 모든 태스크가 다시 번호 매겨지므로 옛 접두사가 박혀 있는 외부 참조(PR 제목, 브랜치 이름, 문서와 채팅 속 링크)는 더 이상 연결되지 않습니다.

코드 내 주석

영어만 사용합니다. 레포는 Go와 TypeScript 모두에 이를 강제합니다. 코드에서 중국어 주석을 발견하면 그것은 버그이니 교체하세요.

커밋 메시지

Conventional 형식: feat(scope), fix(scope), refactor(scope), docs, test(scope), chore(scope). 의도별로 묶인 원자적 커밋.

2. i18n 번역 용어집

이것은 모든 번역 PR이 반드시 지켜야 하는 용어집입니다. 예전에는 packages/views/locales/glossary.md에 있었는데, 그 파일은 삭제되었고 이 페이지가 대체합니다.

핵심 구분: 일상어 vs Clowld Space 고유 용어

Clowld Space의 제품 명사는 두 가지 범주로 나뉩니다.

• 일상어 — 사용자가 그대로 말하는 단어입니다. 데이터베이스 엔티티인지와 무관하게 중국어로 완전히 번역합니다. 예: issue → 任务, workspace → 工作区, topic → 主题.
• Clowld Space 고유 용어 — 중국어에 대응어가 없는 개념(skill)이나 사용자가 입력·대조할 schema 식별자(todo, in_progress, task_id)입니다. 식별자 자체를 보여 줄 때만 소문자 영문을 유지하고 UI 표시명은 현지화합니다.

중국어 페이지 apps/docs/content/docs/*.zh.mdx가 나머지 중국어 문체의 기준입니다. 본문은 제품 엔티티를 “任务”라고 부르며 원시 issue는 명령, 필드, URL, 코드, 명시적 용어 설명에만 남깁니다. 또한 *.ja.mdx와 *.ko.mdx의 본문도 이제 아래 표를 따릅니다.

issue는 제품의 “할 일” — 반드시 번역

issue는 사용자가 등록하고智能体가 처리하는 대상의 영문 제품명입니다. 영어 이외의 언어에서는 일상적인 “할 일” 단어를 사용합니다.

두 단어는 모두 사용자에게 보이지만 같은 것이 아닙니다. 하나의任务에서 여러 번의执行이 생길 수 있습니다.

바뀌지 않는 항목:

• API / DB 필드는 항상 issue / task / skill을 유지합니다.
• 코드 참조와 리터럴 명령은 영문을 유지합니다.
• 원시 실행 식별자는 API, CLI 인자, 로그, 코드 예시에서 task / task_id를 유지하고 중국어 사용자 표시명만 “执行”으로 번역합니다.
• **skill**은 중국어 본문에서도 소문자 영문을 유지하며 제목에서는 Skills를 사용할 수 있습니다.
• **plugin**은 중국어 UI와 본문에서 “插件”으로 번역하고 기술 식별자만 plugin을 유지합니다.
• 문제나 이상을 뜻하는 일반 명사 issue는 제품 엔티티가 아닙니다. 머신 카드의 {{count}} issues는 {{count}} 个异常 / 問題 {{count}} 件 / 문제 {{count}}개이며, 엔티티 단어를 쓰지 않습니다.

다른 제품 명사도 정착된 일상어가 있는지에 따라 판단합니다.

• topic → "主题": 관련 작업과 컨텍스트를 묶는 공통 방향입니다.
• autopilot → "自动化": 일정이나 외부 이벤트에 따라 실행을 시작하는 기능입니다.
• Promotion → "晋级": 검증된 dev 스냅샷을 고정해 main에 병합하는 Clowld 전달 작업입니다. Release(版本发布/发行), Deployment(部署)와 구분하며 기술 식별자는 영문을 유지합니다.

번역하지 않음 — 브랜드와 약어

완전히 번역 — 개념

완전히 번역 — 일반 UI 단어

역할과 상태: 표시명은 번역하고 식별자는 유지

다음 schema 식별자는 API, DB, CLI, 로그, 코드 예시에서 소문자 영문을 유지합니다.

• 역할: owner / admin / member
• 태스크 상태: backlog / todo / in_progress / in_review / done / blocked / cancelled
• 태스크 상태 카테고리: unstarted / started / done / closed

중국어 UI와 자연어 문장에서는 내장 표시명을 현지화합니다. 사용자가 식별자를 입력·복사·대조할 때만 원시 영문을 표시합니다.

• "你需要所有者权限"
• "已切换到进行中"

단어 조합 규칙

영문 단어(엔티티 / 브랜드 / 약어)와 주변 중국어 사이에는 항상 단일 공백을 둡니다:

• "Create new issue" → "新建任务"
• "Assign to agent" → "分配给智能体"
• "Configure runtime" → "配置运行时"
• "Stop daemon" → "停止守护进程"

복수형과 개수

i18next는 _one / _other를 사용합니다; 중국어에는 문법적 수가 없으므로 _other만 채웁니다.

// en/issues.json
{
  "issue_count_one": "{{count}} issue",
  "issue_count_other": "{{count}} issues"
}

// zh-Hans/issues.json
{
  "issue_count_other": "{{count}} 个任务"
}

일반적인 개수 형식:

• {{count}} issues → {{count}} 个任务
• {{count}} agents → {{count}} 个智能体
• {{count}} workspaces → {{count}} 个工作区
• {{count}} comments → {{count}} 条评论
• {{count}} members → {{count}} 位成员
• {{count}} skills → {{count}} 个 skill

보간

{{var}}를 사용합니다. 중국어 번역은 자연스러운 문장 흐름을 위해 순서를 재배치할 수 있습니다.

// en
{ "welcome_message": "Welcome back, {{name}}!" }

// zh-Hans
{ "welcome_message": "欢迎回来，{{name}}！" }

번역 키 네이밍

3단계 중첩: feature.component.action.

{
  "feature_or_component": {
    "subcomponent_or_section": {
      "action_or_label": "..."
    }
  }
}

예시:

• issues.toolbar.batch_update_success
• issues.detail.comment_form.placeholder
• inbox.empty.title
• settings.preferences.language.title

Web 전용 / Desktop 전용 카피

• 공유 카피: namespace JSON의 최상위
• Web 전용: web 섹션
• Desktop 전용: desktop 섹션

정식 예시는 auth.json을 참고하세요(web 섹션에 prefer_desktop / desktop_handoff.*가 포함됨).

3. 중국어 보이스와 스타일

구두점

• 중국어에서는 전각 구두점 사용: ，。：；！？
• 따옴표: 영어 원문과 맞추기 위해 곧은 큰따옴표 "..."를 사용. 「」나 둥근 따옴표는 사용하지 마세요.
• 줄임표: 단일 문자 …가 아닌 세 개의 점 .... 영어 원문과 일치시키세요.
• 중국어-영어 혼용: 영문 단어 양옆에 각각 단일 공백(단어 조합 규칙 참고).

스타일 원칙

• 간결하고 직접적으로. 번역투 회피: "对于 X 来说"、"作为 X"、"我们的".
• 오류 메시지: 부드럽지만 명확하게. "无法保存修改"가 "保存修改失败了！"보다 낫습니다.
• 버튼: 동사를 먼저, 2~4자. "取消"、"保存修改"、"立即同步".
• 툴팁: 완결된 짧은 문장. "复制链接到剪贴板".
• 플레이스홀더: 예시 형태. "输入任务标题...".

막힐 때 참고할 곳

용어집이 특정 용어를 다루지 않을 때는 다음을 참고하세요:

1. apps/docs/content/docs/*.zh.mdx — 사실상의 중국어 보이스 표준, 일관된 번역 20개 이상 페이지
2. packages/views/locales/zh-Hans/auth.json과 editor.json — JSON 구조 + selector API 패턴
3. packages/views/auth/login-page.tsx — 컴포넌트 수준 selector API 호출 지점
4. packages/views/settings/components/preferences-tab.tsx — 언어 전환기 참고

이 페이지를 업데이트할 때

이곳의 규칙을 변경하면 다음도 함께 수행하세요:

1. 관련 locale JSON / AGENTS.md / 문서 페이지에 적용
2. PR 설명에 변경 사항을 기록하여 리뷰어가 다운스트림 정리를 살펴보도록 알리기

이 페이지가 계약입니다; 다른 어떤 것도 이를 무시할 수 없습니다.