@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/ko-KR/workspace.md

@@ -0,0 +1,323 @@
+---
+title: "작업공간"
+description: "Claude-사용자별 코드 수준 사용자 정의 — skills, 메모리, 지침, 사용자 정의 에이전트, 예약된 작업, MCP 서버 — 파일 시스템이 아닌 SQL가 지원합니다."
+---
+
+# 작업 공간
+
+> **어떤 작업공간 문서입니까?** 이 페이지에서는 **사용자 정의 레이어**, 즉 작업공간이*무엇인지* 다룹니다. 배포 형태(하나의 단일 저장소, 많은 앱)는 [Multi-App Workspaces](/docs/multi-app-workspace)를 참조하세요. 거버넌스(누가 무엇을 검토하고, 승인하고, 소유하는지)에 대해서는 [Workspace Governance](/docs/workspace-management)를 참조하세요.
+
+모든 에이전트 기반 앱에는 **작업 공간**, 즉 에이전트를 나만의 것으로 만드는 사용자 정의 레이어가 함께 제공됩니다. 여기에는 팀 지침(`AGENTS.md`), 공유 학습(`LEARNINGS.md`), 개인 구조적 메모리(`memory/MEMORY.md`), 에이전트가 요청 시 가져오는 skills, 사용자 정의 하위 에이전트, 예약된 작업 및 연결된 MCP 서버 등 Claude 코드/Codex 설정에서 기대할 수 있는 모든 것이 포함되어 있습니다.
+
+비틀림: **파일 시스템 파일이 아니라 SQL 행입니다.** 각 사용자는 데이터베이스에 저장된 자신의 작업 공간을 얻습니다. 가동할 개발 상자도 없고, 사용자당 컨테이너도 없고, 마운트할 파일도 없습니다. 멀티 테넌트 SaaS는 개인 메모리, 개인 MCP 서버, 개인 skills, 개인 하위 에이전트 등 모든 행이 행으로 구성되어 있고 공유 코드베이스가 이 모든 것을 한 번에 호스팅하기 때문에 모든 사용자에게 본질적으로 무료로 완전히 사용자 정의 가능한 에이전트를 제공할 수 있습니다.
+
+```an-diagram title="A Claude-Code workspace, but stored in SQL" summary="The same customization layer — instructions, skills, memory, agents, jobs, MCP — except every file is a row in a shared multi-tenant database."
+{
+  "html": "<div class=\"ws-map\"><div class=\"diagram-card cc\"><span class=\"diagram-pill warn\">Claude Code / Codex</span><small class=\"diagram-muted\">~/.claude/ on a local disk</small><div class=\"ws-files\"><span class=\"diagram-box\">CLAUDE.md</span><span class=\"diagram-box\">skills/</span><span class=\"diagram-box\">memory</span><span class=\"diagram-box\">mcp.json</span></div><small class=\"diagram-muted\">one codebase per developer</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card an\"><span class=\"diagram-pill accent\">Agent-native workspace</span><small class=\"diagram-muted\">rows in one SQL database</small><div class=\"ws-rows\"><span class=\"diagram-pill\">AGENTS.md</span><span class=\"diagram-pill\">skills/&hellip;</span><span class=\"diagram-pill\">memory/&hellip;</span><span class=\"diagram-pill\">mcp-servers/&hellip;</span></div><small class=\"diagram-muted\">one codebase, many users, scoped <code>u:&lt;email&gt;:&hellip;</code></small></div></div>",
+  "css": ".ws-map{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.ws-map .diagram-card{display:flex;flex-direction:column;gap:8px;padding:16px 18px;flex:1;min-width:220px}.ws-map .ws-files,.ws-map .ws-rows{display:flex;flex-wrap:wrap;gap:6px;margin:4px 0}.ws-map .diagram-arrow{font-size:24px}"
+}
+```
+
+| Claude 코드 / Codex                  | 에이전트 기반 작업공간                         |
+| ------------------------------------ | ---------------------------------------------- |
+| 로컬 디스크의 파일                   | 공유 SQL 데이터베이스의 행                     |
+| 개발자당 하나의 코드베이스           | 하나의 코드베이스, 많은 사용자                 |
+| 개발 상자 또는 컨테이너가 필요합니다 | 모든 서버리스/에지 호스트에서 실행             |
+| `~/.claude/`의 사용자 정의           | 사용자별 맞춤설정, 범위가 지정된 `u:<email>:…` |
+| 프로젝트별 `CLAUDE.md` / skills      | 앱별 `AGENTS.md` + 작업 공간 메모리 리소스     |
+| JSON 파일의 MCP 구성                 | JSON의 MCP 구성 _또는_ 범위당 UI 설정          |
+
+동일한 기능. 다른 경제학. 이것이 SaaS에 중요한 이유는 [Templates](/docs/cloneable-saas)를 참조하세요.
+
+## 개요 {#overview}
+
+리소스에는 세 가지 런타임 범위가 있습니다.
+
+- **개인** — 단일 사용자(이메일)로 범위가 지정됩니다. 기본 설정, 메모 및 사용자별 컨텍스트에 적합합니다.
+- **공유/조직** — 앱 또는 조직의 모든 사용자에게 표시됩니다. 앱/팀 지침, skills 및 공유 구성에 적합합니다.
+- **작업 공간** — 디스패치 리소스에서 관리되는 상속된 전역 기본값입니다. 회사 정보, 포지셔닝, 브랜드 지침, 글로벌 가드레일, 작업 공간 전체 skills 및 공유 MCP 서버에 적합합니다. 앱은 런타임에 이를 읽습니다. 각 앱에 복사되지는 않습니다.
+
+인앱 작업 공간 패널에는 세 가지 범위가 모두 표시됩니다. 개인 및 공유/조직 리소스를 편집할 수 있습니다. Workspace 범위 리소스는 앱 패널에서 읽기 전용이고 Dispatch에서 중앙에서 편집되므로 모든 앱은 동기화 단계 없이 동일한 표준 파일을 볼 수 있습니다.
+
+에이전트가 각 리소스를 사용하는 방법을 제어하는 표준 경로:
+
+| 런타임 리소스          | 경로                                      | 상담원이 사용하는 방법                          |
+| ---------------------- | ----------------------------------------- | ----------------------------------------------- |
+| 가드레일 지침          | `AGENTS.md` 또는 `instructions/<slug>.md` | 수신하는 모든 앱에서 매 턴마다 로드됨           |
+| 글로벌 skills          | `skills/<slug>/SKILL.md`                  | 작업 공간 skills로 나열되고 요청 시 읽기        |
+| 브랜드/회사 리소스     | `context/<slug>.md`                       | 매 턴마다 색인이 생성되며 관련이 있는 경우 읽기 |
+| 맞춤형 에이전트 프로필 | `agents/<slug>.md`                        | 재사용 가능한 로컬 에이전트 프로필로 사용 가능  |
+| 공유 HTTP MCP 서버     | `mcp-servers/<slug>.json`                 | 부여된 앱의 MCP 도구 레지스트리에 로드됨        |
+
+이러한 경로는 작업 영역, 조직/앱, 개인의 세 가지 범위 모두에 적용됩니다. 동일한 경로가 여러 수준에 존재하는 경우 나중 범위가 우선합니다.
+
+```an-diagram title="Three scopes, one effective file" summary="The runtime resolves the same path across workspace, app, and personal scopes on read — the most specific scope wins."
+{
+  "html": "<div class=\"ws-stack\"><div class=\"diagram-card\"><span class=\"diagram-pill\">Workspace</span><small class=\"diagram-muted\">company-wide defaults from Dispatch</small><code>context/brand.md</code></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">Organization / app</span><small class=\"diagram-muted\">team override for one app</small><code>context/brand.md</code></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Personal</span><small class=\"diagram-muted\">per-user override &mdash; wins</small><code>context/brand.md</code></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box ok\">Effective <code>context/brand.md</code></div></div>",
+  "css": ".ws-stack{display:flex;flex-direction:column;align-items:flex-start;gap:8px}.ws-stack .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px;min-width:280px}.ws-stack .diagram-arrow{font-size:20px;align-self:center}.ws-stack code{font-size:.85em}.ws-stack .diagram-box{align-self:center;margin-top:4px}"
+}
+```
+
+## 시작하기: 1분 둘러보기 {#getting-started}
+
+60초 안에 상담원의 행동 방식을 변경하세요.
+
+1. **작업 공간** 탭 → **공유** → `AGENTS.md`를 엽니다(누락된 경우 `+` → **파일**으로 생성).
+2. 규칙 하나를 추가하세요. 예:
+
+   ```마크다운
+   ## 톤
+
+   간결하게 작성하세요. 답을 제시하세요.
+   ```
+
+3. 저장하고 **채팅**으로 전환하고 무엇이든 물어보세요. 상담원은 즉시 새 규칙을 따릅니다.
+
+```an-callout
+{ "tone": "info", "body": "No restart, no redeploy. `AGENTS.md` is read at the start of every turn, so an edit you save now changes the agent's behavior on the very next message." }
+```
+
+**원할 때 다음 단계:**
+
+- **Skills** (`+` → **스킬**) — `/skill-name`와의 채팅에서 호출되는 집중 방법 파일입니다.
+- **에이전트** (`+` → **에이전트**) — `@agent-name`로 호출되는 재사용 가능한 하위 에이전트 페르소나.
+- **예약된 작업** (`+` → **예약된 작업**) — cron에서 실행되는 프롬프트입니다. 일정 및 트리거는 [Recurring Jobs](/docs/recurring-jobs)를 참조하세요.
+- **메모리** — 공유 `LEARNINGS.md` 및 개인 `memory/MEMORY.md`는 대화 전반에 걸쳐 지속적인 컨텍스트를 제공합니다.
+
+## 전역 리소스 및 표준 경로 {#global-resources}
+
+작업 공간 범위 리소스는 Dispatch의 **리소스** 페이지에서 관리되며 런타임 시 앱에 의해 상속됩니다. 복사 또는 동기화 단계가 없습니다. Dispatch는 두 가지 부여 범위를 지원합니다:
+
+- **모든 앱** — 작업 공간의 모든 앱이 상속하는 전역 리소스입니다. 대부분의 회사, 브랜드, 페르소나, 포지셔닝, 메시징 및 가드레일 컨텍스트는 **모든 앱**이어야 합니다.
+- **선택한 앱** — 앱별 컨텍스트 또는 도구를 위해 특정 앱에 부여된 리소스입니다. 이러한 정보는 아껴서 사용하세요.
+
+경로는 에이전트가 리소스를 사용하는 방법을 결정합니다(위의 [Overview](#overview) 표 참조). 이곳은 많은 앱이 활용할 수 있는 핵심 페르소나, 포지셔닝, 메시징, 회사 정보, 브랜드 지침, 지원 정책, 공유 skills 또는 공유 HTTP MCP 도구를 위한 최적의 공간입니다.
+
+새로운 작업 공간을 위한 유용한 스타터 팩:
+
+```text
+context/company.md              # what the company does, ICP, products, links
+context/brand.md                # voice, visual identity, spelling, forbidden usage
+context/messaging.md            # positioning, value props, proof points, objections
+instructions/guardrails.md      # compliance, escalation, and approval rules
+skills/company-voice/SKILL.md   # on-demand guidance for customer-facing writing
+agents/<slug>.md                # reusable custom agent profiles
+```
+
+`context/` 파일을 사실대로 유지하고 쉽게 훑어볼 수 있습니다. `instructions/guardrails.md`에 매 턴마다 적용해야 하는 규칙을 입력하세요. 상담원이 회사의 목소리에 맞춰 의도적으로 사본을 변형하거나 검토해야 하는 경우 `skills/company-voice/SKILL.md`를 사용하세요.
+
+하나의 앱이나 팀에 대한 전역 기본값을 재정의하려면 해당 앱에 동일한 경로를 사용하여 공유/조직 리소스를 만듭니다. 한 사람에 대해 이를 재정의하려면 동일한 경로를 사용하여 개인 리소스를 만듭니다. 작업 영역 파일을 모든 앱에 복사하지 마세요. 런타임은 읽기 시 스택을 확인합니다.
+
+```text
+workspace context/brand.md
+-> shared/app context/brand.md
+-> personal context/brand.md
+```
+
+`context/` 파일을 짧고 사실대로 유지하세요. 상담원이 훑어볼 수 있는 몇 가지 글머리 기호는 다음과 같습니다.
+
+```text
+<!-- context/brand.md -->
+
+# Brand
+
+- Voice: direct, warm, concrete
+- Use: "workspace", "agent", "team"
+- Avoid: unsupported superlatives and vague AI claims
+```
+
+## 작업공간 패널 {#workspace-panel}
+
+상담사 패널에는 Chat 및 CLI와 함께 **작업 공간** 탭이 포함되어 있습니다. 여기에는 모든 리소스의 폴더 구성 트리, 텍스트 파일용 인라인 편집기(Markdown, JSON, YAML, 일반 텍스트) 및 `+` 메뉴의 입력된 생성 흐름(파일, Skills, 에이전트, 예약된 작업)이 표시됩니다. 사용자는 상속된 작업 공간 기본값을 찾아보고 개인 또는 조직 리소스를 생성/편집/삭제할 수 있습니다.
+
+리소스를 열면 편집기에 `workspace default -> organization/app override -> personal override` 스택이 포함된 **유효 컨텍스트** 스트립이 표시되므로 상속된 내용과 재정의가 활성화된 이유를 확인할 수 있습니다. Dispatch는 제어 영역 측에서 동일한 모델을 보여줍니다. **리소스** 페이지에서 **Effective in app**을 사용하거나 앱 카드의 **컨텍스트** 대화 상자에서 리소스 행의 **스택**을 확장합니다.
+
+디스패치 승인 정책이 활성화되면 **모든 앱** 리소스를 생성, 업데이트 또는 삭제하면 승인 요청이 즉시 적용되지 않고 대기열에 추가됩니다. 생성/편집/삭제 대화 상자에는 저장 전 영향 미리보기가 표시됩니다.
+
+언제든지 이 문서로 돌아가려면 작업공간 도구 모음에서 `?` 아이콘을 클릭하세요.
+
+## 에이전트가 리소스를 사용하는 방법 {#how-the-agent-uses-resources}
+
+내장 앱 에이전트는 통합 `resources` 도구를 사용하여 리소스를 관리합니다. `action: "list"`, `"read"`, `"effective"`, `"write"`, `"promote"` 또는 `"delete"`를 사용합니다. 외부 CLI/코드 에이전트는 동등한 `pnpm action resource-*` 명령을 사용할 수 있습니다.
+
+모든 대화가 시작될 때 상담원은 자동으로 다음 내용을 읽습니다.
+
+### AGENTS.md 및 지침 {#agents-md}
+
+`AGENTS.md`는 기본적으로 시드되고 작업 공간, 공유/조직 및 개인 범위에서 순서대로 로드됩니다. 즉, 회사 전체 기본값을 위한 작업 공간, 팀 규칙을 위한 공유/앱, 사용자별 기본 설정을 위한 개인입니다. `instructions/` 아래의 파일은 모든 차례(규정 준수 규칙, 에스컬레이션 정책, 브랜드 목소리)를 적용하고 동일한 우선 순위를 따르는 별도의 가드레일 문서입니다. 일반 채팅과 통합 트리거 실행 모두 응답하기 전에 이를 로드합니다.
+
+```text
+AGENTS.md
+instructions/customer-support-guardrails.md
+instructions/legal-review-policy.md
+```
+
+### 참조 자료 {#reference-resources}
+
+재사용 가능한 회사 컨텍스트는 `context/`(페르소나, 포지셔닝, 제품 정보, 브랜드 지침, 경쟁 제품 정보)에 따릅니다. 에이전트는 이들의 색인을 확인하고 작업이 이에 의존할 수 있는 경우 `resources` 도구(`action: "read"`)를 사용하여 관련 파일을 읽습니다. 앱이나 사용자에 대해 작업공간 기본값이 재정의되었는지 확인하려면 `action: "effective"`를 사용하세요.
+
+### 메모리 {#memory}
+
+작업 공간에는 현재 두 개의 메모리 표면이 있습니다:
+
+- 프로젝트 전반의 규칙, 수정 및 지속적인 팀 지식을 위한 **공유** 범위의 `LEARNINGS.md`.
+- 현재 사용자에 대한 구조화된 메모리에 대한 **개인** 범위의 `memory/MEMORY.md`.
+
+리소스 시스템은 이전 작업 공간과의 호환성을 위해 개인 `LEARNINGS.md`도 시드하지만 채팅 사전 로드 경로는 공유 `LEARNINGS.md`와 개인 `memory/MEMORY.md`입니다.
+
+**저장되는 내용.** 에이전트를 수정("항상 Y 대신 X 사용"), 선호도 공유("간결한 답변을 선호합니다") 또는 컨텍스트 공개("우리 팀에서는 이를 '디스패치 레이어'라고 함")할 때 에이전트는 해당 학습 내용을 캡처하여 실수를 반복하거나 다시 요청하지 않습니다. 프로젝트 전반의 학습은 공유된 `LEARNINGS.md`로 진행됩니다. 사용자별 메모리는 `memory/` 아래에 있습니다. `capture-learnings` 스킬은 시기와 방법을 설명합니다.
+
+**적합한 위치**
+
+| 표면               | 범위          | 작성자                                | 읽을 때                                              |
+| ------------------ | ------------- | ------------------------------------- | ---------------------------------------------------- |
+| `AGENTS.md`        | 공유          | 요청 시 인간/에이전트                 | 매 턴                                                |
+| `LEARNINGS.md`     | 공유          | 요청 시 인간/에이전트                 | 매 턴(공유 사본만 해당)                              |
+| `memory/MEMORY.md` | 개인          | 에이전트/인간                         | 매 턴                                                |
+| `instructions/…`   | 공유          | 요청 시 인간/에이전트                 | 매 턴                                                |
+| `skills/…`         | 공유          | 요청 시 인간/에이전트                 | 요청 시(`/slash` 명령)                               |
+| `context/…`        | 공유          | 요청 시 인간/에이전트                 | 매 턴마다 색인이 생성되며 관련이 있는 경우 읽습니다. |
+| `mcp-servers/…`    | 작업공간/공유 | Dispatch 또는 앱 작업공간을 통한 인간 | MCP 구성 새로 고침                                   |
+
+사용자는 작업 공간 탭에서 직접 이러한 메모리 파일을 편집할 수 있습니다. 이는 일반 리소스입니다. 상담원이 잘못 입력한 줄을 삭제하고, `memory/MEMORY.md`에서 개인 기본 설정을 유지하거나, 팀 전체 규칙을 `AGENTS.md`로 승격하세요.
+
+`AGENTS.md`, skills, 메모리, 사용자 지정 에이전트, MCP 서버 등 이러한 표면은 모두 동일한 기본 리소스 형태(`path` + `scope` + `content`)이며 동일한 방식으로 처리되고 해결됩니다.
+
+```an-schema title="The workspace resource model" summary="One resource shape backs every workspace file. The runtime keys it by path and scope and resolves the effective value on read."
+{
+  "entities": [
+    {
+      "id": "resource",
+      "name": "workspace resource",
+      "note": "A single file in a user's workspace — instructions, skill, memory, agent, MCP config, or job.",
+      "fields": [
+        { "name": "path", "type": "string", "note": "Canonical path, e.g. AGENTS.md, skills/<slug>/SKILL.md" },
+        { "name": "scope", "type": "workspace | shared | personal", "note": "Which level this row lives at" },
+        { "name": "owner", "type": "string", "nullable": true, "note": "u:<email> for personal scope" },
+        { "name": "content", "type": "text", "note": "Markdown / JSON / YAML body" }
+      ]
+    }
+  ]
+}
+```
+
+## Skills {#skills}
+
+Skills는 `/skill-name`와의 채팅에서 호출되는 에이전트 주문형 도메인 지식을 제공하는 `skills/` 경로(바람직하게는 `skills/<name>/SKILL.md`) 아래의 Markdown 리소스 파일입니다. 작업공간 탭에서 추가하거나 코드 모드의 `.agents/skills/`에서 추가하세요.
+
+기술 형식, 범위, 검색 및 작성을 위한 단일 소스인 [Skills Guide](/docs/skills-guide)를 참조하세요.
+
+## 맞춤 에이전트 {#custom-agents}
+
+사용자 지정 에이전트는 `agents/*.md` 아래에 Markdown 리소스로 저장된 재사용 가능한 로컬 하위 에이전트 프로필입니다. 이는 맞춤형 에이전트 형식의 표준 홈입니다.
+
+고유한 이름, 설명, 모델 기본 설정 및 지침 세트를 갖춘 집중된 대표자를 원할 때 사용하십시오. skills와 달리 사용자 지정 에이전트는 수동적 지침이 아닙니다. 기본 에이전트가 `@` 멘션을 통해 호출하거나 하위 에이전트 생성 중에 선택하여 호출할 수 있는 운영 페르소나입니다.
+
+### 에이전트 형식 {#agent-format}
+
+사용자 지정 에이전트는 YAML 머리말과 Markdown 지침을 사용합니다.
+
+```an-annotated-code title="A custom agent profile"
+{
+  "filename": "agents/design.md",
+  "language": "markdown",
+  "code": "---\nname: Design\ndescription: >-\n  Reviews layouts, interaction patterns, and product UX decisions.\nmodel: inherit\ntools: inherit\ndelegate-default: false\n---\n\n# Role\n\nYou are a focused design agent.\n\n## Responsibilities\n\n- Review layouts and interaction flows\n- Suggest stronger visual direction\n- Be concise and opinionated",
+  "annotations": [
+    { "lines": "2", "label": "@mention handle", "note": "`name` is what appears in the `@`-dropdown and what the main agent delegates to." },
+    { "lines": "3-4", "label": "When to delegate", "note": "The `description` is what the orchestrator reads to decide this profile fits a task." },
+    { "lines": "5", "label": "Model", "note": "`inherit` reuses the main agent's model. Override only when the profile clearly needs a different one." },
+    { "lines": "6", "note": "`tools: inherit` for now — the field is reserved for future per-agent tool policies." }
+  ]
+}
+```
+
+권장 규칙:
+
+- `agents/<slug>.md`에 맞춤형 에이전트 저장
+- 프로필에 분명히 다른 모델이 필요한 경우가 아니면 `model: inherit`를 사용하세요
+- 지금은 `tools: inherit`를 유지하세요. 이 필드는 향후 도구 정책을 위해 예약되어 있습니다.
+
+### 원격 에이전트와 맞춤형 에이전트 {#remote-vs-custom-agents}
+
+Workspace에는 두 가지 에이전트 유형이 있습니다.
+
+- **사용자 지정 에이전트** — 현재 앱/런타임 내에서 실행되는 `agents/*.md`의 로컬 프로필
+- **연결된 에이전트** — `remote-agents/*.json`의 매니페스트로 설명되는 원격 A2A 피어(레거시 `agents/*.json` 매니페스트는 계속 인식됨)
+
+하나의 앱 내에서 위임을 위해 사용자 정의 에이전트를 사용합니다. A2A를 통해 다른 앱에 전화해야 할 때 연결된 에이전트를 사용하세요.
+
+## @태깅 {#at-tagging}
+
+작업 영역 항목을 참조하려면 채팅 입력에 `@`를 입력하세요. 일치하는 에이전트와 파일을 보여주는 드롭다운이 커서에 나타납니다. 탐색하려면 화살표 키를 사용하고 선택하려면 Enter를 사용하세요. 선택한 항목이 입력에 인라인 칩으로 나타납니다.
+
+메시지를 보내면 **파일/리소스**는 에이전트가 읽을 수 있는 참조로 전달되고, **사용자 지정 에이전트**는 프로필 지침에 따라 로컬로 실행되며, **연결된 에이전트**는 A2A를 통해 호출됩니다.
+
+## / 슬래시 명령 {#slash-commands}
+
+스킬을 호출하려면 줄 시작 부분에 `/`를 입력하세요. 드롭다운에는 사용 가능한 skills가 이름 및 설명과 함께 표시됩니다. 하나를 선택하면 인라인 칩이 추가되고 메시지가 전송될 때 해당 내용이 컨텍스트로 포함됩니다. skills가 구성되지 않은 경우 드롭다운이 이 문서로 연결됩니다.
+
+## 코드 대 앱 모드 {#dev-vs-prod}
+
+자원 시스템은 두 모드에서 동일하게 작동합니다. 차이점은 `@` 태깅 및 `/` 명령에 사용할 수 있는 추가 소스입니다.
+
+| 기능                 | 코드 모드                                                                  | 앱 모드                                                   |
+| -------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------- |
+| @태그                | 코드베이스 파일 + 작업공간 리소스 + 사용자 정의 에이전트 + 연결된 에이전트 | 작업 공간 리소스 + 사용자 정의 에이전트 + 연결된 에이전트 |
+| / 슬래시 명령        | .agents/skills/ + 리소스 skills                                            | 리소스 skills만                                           |
+| 에이전트 파일 액세스 | 파일 시스템 + 리소스                                                       | 리소스만                                                  |
+| 작업공간 패널        | 전체 액세스                                                                | 전체 액세스                                               |
+| AGENTS.md / 메모리   | 사용 가능                                                                  | 사용 가능                                                 |
+
+## 작업공간 연결 {#workspace-connections}
+
+작업 공간 연결을 사용하면 앱이 자격 증명을 복제하지 않고도 동일한 공급자 계정(Slack, GitHub, HubSpot 등)을 공유할 수 있습니다. 연결은 공급자 ID, 계정 레이블, 상태, 범위, 앱 부여 및 자격 증명 참조를 SQL에 기록합니다. 비밀은 자격 증명 저장소에 보관됩니다. 연결은 `SLACK_BOT_TOKEN`와 같은 자격 증명 키 이름만 가리킵니다.
+
+빠른 시작, 연결/부여/자격 증명 참조 API 및 구체적인 Slack, HubSpot 및 GitHub 예는 [Workspace Connections](/docs/workspace-connections)를 참조하세요.
+
+---
+
+# 참고자료
+
+## 자원 API {#resource-api}
+
+리소스는 서버 코드 actions 또는 REST API에서 관리할 수 있습니다.
+
+### 서버 API {#server-api}
+
+REST 엔드포인트가 자동으로 마운트됨:
+
+| 방법     | 엔드포인트                                    | 설명                        |
+| -------- | --------------------------------------------- | --------------------------- |
+| `GET`    | `/_agent-native/resources?scope=all`          | 자원 나열                   |
+| `GET`    | `/_agent-native/resources?scope=workspace`    | 상속된 작업공간 리소스 나열 |
+| `GET`    | `/_agent-native/resources/tree?scope=all`     | 폴더 트리 가져오기          |
+| `GET`    | `/_agent-native/resources/effective?path=...` | 유효한 상속 스택 표시       |
+| `POST`   | `/_agent-native/resources`                    | 리소스 생성                 |
+| `GET`    | `/_agent-native/resources/:id`                | 콘텐츠와 함께 리소스 얻기   |
+| `PUT`    | `/_agent-native/resources/:id`                | 리소스 업데이트             |
+| `DELETE` | `/_agent-native/resources/:id`                | 리소스 삭제                 |
+| `POST`   | `/_agent-native/resources/upload`             | 파일을 리소스로 업로드      |
+
+### 액션 API {#script-api}
+
+에이전트는 이러한 기본 제공 actions를 사용합니다. 자신의 actions에서 호출할 수도 있습니다:
+
+```bash
+# List all resources
+pnpm action resource-list --scope all
+
+# Read a resource
+pnpm action resource-read --path "skills/my-skill/SKILL.md"
+
+# Read inherited workspace context managed by Dispatch
+pnpm action resource-read --scope workspace --path "context/brand.md"
+
+# Show workspace -> organization/app -> personal precedence for a path
+pnpm action resource-effective --path "context/brand.md"
+
+# Write a resource
+pnpm action resource-write --path "notes/meeting.md" --content "# Meeting Notes..."
+
+# Delete a resource
+pnpm action resource-delete --path "notes/old.md"
+```

package/docs/content/locales/ko-KR/writing-agent-instructions.md

@@ -0,0 +1,173 @@
+---
+title: "작성 대리인 지침 및 Skills"
+description: "에이전트 기본 앱 또는 템플릿에 대한 훌륭한 에이전트 지침을 작성하는 방법: AGENTS.md, skills 및 도구 설명"
+---
+
+# 작성 에이전트 지침 및 Skills
+
+에이전트 기본 앱에서 에이전트의 행동은 사용자가 제공한 지침만큼만 좋습니다. 해당 지침은 `AGENTS.md`(지도), skills(심층 분석), 작업/도구 설명(에이전트가 올바른 도구를 선택하는 방법) 등 세 가지 표면에 전달됩니다. 산문이 아닌 빠른 검색을 위해 각각 작성하세요.
+
+```an-diagram title="Three authored surfaces + one runtime surface" summary="AGENTS.md and tool descriptions load every turn; skills load on demand; application_state is written live by your UI."
+{
+  "html": "<div class=\"diagram-surfaces\"><div class=\"diagram-card always\" data-rough><span class=\"diagram-pill accent\">Every turn</span><strong>AGENTS.md</strong><small class=\"diagram-muted\">the map: purpose, core rules, state keys, action + skills index</small></div><div class=\"diagram-card always\" data-rough><span class=\"diagram-pill accent\">Every turn</span><strong>Tool descriptions</strong><small class=\"diagram-muted\">drive tool selection — one precise sentence each</small></div><div class=\"diagram-card ondemand\" data-rough><span class=\"diagram-pill\">On demand</span><strong>Skills</strong><small class=\"diagram-muted\">deep how-to, loaded when the description fires</small></div><div class=\"diagram-card runtime\" data-rough><span class=\"diagram-pill ok\">Live</span><strong>application_state</strong><small class=\"diagram-muted\">written by your UI: navigation, selection, focus</small></div></div>",
+  "css": ".diagram-surfaces{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:12px}.diagram-surfaces .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px}"
+}
+```
+
+## AGENTS.md를 작고 훑어볼 수 있도록 유지 {#small-agents-md}
+
+`AGENTS.md`가 방향으로 로드됩니다. 모든 것이 skills에 깊숙이 들어가 에이전트가 올바르게 작동할 수 있도록 하는 가장 작은 것이어야 합니다. 다음 섹션을 목표로 하세요:
+
+- **목적 라인** — 앱이 무엇인지와 기본 워크플로에 대한 한 문장입니다.
+- **핵심 규칙** — 항상 유지해야 하는 몇 가지 불변 사항(SQL의 데이터, 작업은 actions를 거치고, AI는 에이전트 채팅을 거치고, 스키마 변경 사항은 추가됨). 짧고 필수적인 글머리 기호.
+- **애플리케이션 상태 키** — 에이전트가 사용자가 보고 있는 내용과 모양을 알기 위해 읽는 `navigation`/선택/초점 키입니다.
+- **작업 테이블** — 목적에 맞는 작업 이름을 간략하게 정리한 테이블입니다.
+- **Skills 인덱스** — 존재하는 skills 목록과 각각을 읽는 시기.
+
+섹션이 화면을 넘어서 커지면 스킬에 속합니다. `AGENTS.md`는 "어려운 일을 정확히 어떻게 하는가"가 아니라 "이 앱이 무엇이고 무엇을 할 수 있는가"에 대해 답합니다.
+
+```markdown
+# Projects App
+
+One workspace for projects, tasks, and notes. Agent and UI share the same SQL
+data and the same actions.
+
+## Core Rules
+
+- Data lives in SQL via Drizzle. Use actions for all writes.
+- All AI work goes through the agent chat; never call an LLM inline.
+- Schema changes are additive only.
+
+## Application State
+
+- `navigation.view`: `home` | `project`
+- `navigation.projectId`: selected project on a project page
+
+## Actions
+
+| Action           | Purpose                     |
+| ---------------- | --------------------------- |
+| `list-projects`  | List accessible projects    |
+| `create-project` | Create a project            |
+| `update-project` | Rename or archive a project |
+
+## Skills
+
+- `project-imports` — read before importing legacy CSV exports.
+- `sharing` — read before exposing a project to other users.
+```
+
+## 단일 소스 AGENTS.md {#single-source}
+
+하나의 정식 지침 파일인 `AGENTS.md`를 보관하세요. 클라이언트가 `CLAUDE.md`를 기대하는 경우 두 번째 복사본이 아닌 `AGENTS.md`에 대한 심볼릭 링크로 만듭니다. 손으로 관리하는 두 개의 파일이 표류하고 에이전트는 결국 모순되는 규칙에 직면하게 됩니다. 필요한 곳에 연결되는 단일 정보 소스
+
+## SKILL.md 머리말은 언제 AND가 무엇인지 말해야 합니다 {#skill-frontmatter}
+
+`description`는 에이전트가 스킬 읽기 여부를 결정할 때 보는 유일한 것입니다. 기술이 다루는 내용과 발동 시기라는 두 가지 질문에 답해야 합니다. 주제만을 설명하는 설명은 실행되지 않습니다.
+
+```markdown
+---
+name: project-imports
+description: >-
+  How to import projects from the legacy CSV export. Use when the user uploads
+  a project CSV or asks to migrate projects from the old system.
+---
+```
+
+- 기능을 설명하고 명시적인 **"사용 시기..."** 절을 추가하세요.
+- 약간 강압적으로 행동하세요. 과도하게 트리거하면 절대 로드되지 않는 스킬을 능가합니다.
+- 최대 40단어 미만으로 유지하세요. 모든 대화의 맥락에 로드됩니다.
+
+## 점진적 공개 {#progressive-disclosure}
+
+`SKILL.md`를 간결하고 꼭 알아야 할 레이어(규칙, 수행 방법, 해야 할 일/하지 말아야 할 일 및 포인터)로 작성하세요. 긴 예제, 철저한 필드 참조, API 특이 사항 및 특수 사례 테이블을 에이전트가 필요할 때만 읽는 `references/` 파일에 푸시합니다.
+
+```text
+.agents/skills/project-imports/
+├── SKILL.md            # rule + happy path + do/don't
+└── references/
+    └── csv-format.md   # full column spec, encodings, edge cases
+```
+
+이것은 항상 로드되는 표면을 작게 유지하고 컨텍스트를 부풀리지 않고 깊이 확장을 가능하게 합니다. 전체 스킬 형식은 [Skills Guide](/docs/skills-guide)를 참조하세요.
+
+## 행동 중심 테이블 작성 {#action-tables}
+
+에이전트는 산문보다 빠르게 테이블을 스캔합니다. 각 작업을 설명하는 단락보다 목적에 맞는 이름 표를 선호합니다. 상태 키, 필드 유형 및 열거 가능한 집합에도 동일하게 적용됩니다. 테이블은 훑어보고 비교할 수 있으며 작업을 추가할 때 동기화를 쉽게 유지할 수 있습니다.
+
+## 명확한 도구 설명 작성 {#tool-descriptions}
+
+작업 설명은 도구 설명입니다. 즉, 도구 선택을 유도합니다. 각각의 문장을 정확하고 단일 목적의 문장으로 만드세요.
+
+- 구현 방법이 아니라 무엇을 하고 무엇을 반환하는지 말하세요.
+- 에이전트가 올바르게 채울 수 있도록 `.describe()`의 각 매개변수를 설명하세요.
+- 행동 당 하나의 책임. 설명에 "및…"이 필요한 경우 분할하세요.
+- 상담원이 자유롭게 통화해도 안전하다는 것을 알 수 있도록 읽기 전용 actions(`readOnly: true` 또는 `http: { method: "GET" }`)를 표시하세요.
+
+```ts
+defineAction({
+  description: "Create a project. Returns the new project id and title.",
+  schema: z.object({
+    title: z.string().min(1).describe("Project title shown in the sidebar"),
+  }),
+  // ...
+});
+```
+
+## Skills 대 actions {#skills-vs-actions}
+
+Skills 및 actions는 상호보완적입니다. 스킬은 에이전트가 읽는 지침입니다. 와
+액션은 에이전트가 실행할 수 있는 코드입니다.
+
+| 필요                                                              | 사용               |
+| ----------------------------------------------------------------- | ------------------ |
+| 상담사는 워크플로, 정책, 체크리스트 또는 기준표를 따라야 합니다.  | **스킬**           |
+| 에이전트에는 예시, 참조 자료 또는 도메인별 규칙이 필요합니다.     | **스킬**           |
+| 에이전트는 앱 데이터를 읽거나 써야 합니다                         | **액션**           |
+| 에이전트는 외부 API를 호출하거나 승인을 수행해야 합니다.          | **액션**           |
+| 에이전트가 올바른 작업을 호출했지만 잘못된 방식으로 호출했습니다. | **스킬** 향상      |
+| 에이전트가 작업을 안정적으로 호출할 수 없습니다.                  | **액션** 개선      |
+| 상담원이 잘못된 도구를 선택했습니다                               | **작업 설명** 개선 |
+
+대부분의 실제 기능은 두 가지를 모두 사용합니다. 기술은 작업에 접근하는 방법을 설명하고
+작업은 입력된 작업을 제공합니다. 예를 들어 `invoice-review` 스킬
+검토 정책 및 에스컬레이션 규칙을 설명할 수 있고, `list-invoices`,
+`flag-invoice` 및 `approve-invoice` actions는 실제 읽기 및 쓰기를 수행합니다.
+
+## 가공 방지 베이킹 및 완료 전 검증 {#anti-fabrication}
+
+앱 지침은 정직과 검증을 기본 행동으로 만들어야 합니다.
+
+- **조작하지 마세요.** 데이터를 찾을 수 없거나 작업이 실패하면 그렇다고 말하고 복구하세요. 결과를 만들어내거나 성공했다고 주장하지 마세요. 보고하기 전에 작업이나 쿼리를 통해 실제 가치를 읽어보세요.
+- **완료를 선언하기 전에 확인하세요.** 변경 후에는 쓰기가 작동했다고 가정하는 대신 다시 읽기(행을 다시 쿼리하고 `view-screen`를 통해 화면을 다시 읽음)로 확인하세요.
+- **복구하세요. 포기하지 마세요.** 복구 가능한 오류(실패한 쿼리, 일시적인 가져오기)가 발생하면 작업을 포기하는 대신 입력을 다시 시도하거나 수정하세요. 이를 조작 방지 규칙과 별도로 유지하십시오. "만들지 마세요"와 "첫 번째 오류에서 중지"를 혼동하지 마십시오.
+
+이를 `AGENTS.md`의 핵심 규칙으로 설정하여 모든 턴에 적용하세요.
+
+## 에이전트가 보는 네 가지 표면 {#four-surfaces}
+
+당신이 작성한 모든 지침은 네 가지 표면 중 하나에 속합니다. 어떤 표면을 사용할지 알면 중복과 잘못된 세부 정보를 방지할 수 있습니다.
+
+| 표면                         | 작성자             | 로드된 경우                                        | 거기에 속한 것                                         |
+| ---------------------------- | ------------------ | -------------------------------------------------- | ------------------------------------------------------ |
+| `AGENTS.md` 지침             | 당신(개발자)       | 매 턴마다 방향으로                                 | 목적, 핵심 규칙, 상태 키, 작업 인덱스, skills 인덱스   |
+| Skills (`SKILL.md`)          | 귀하(개발자)       | 상담원이 해당 기술이 관련성이 있다고 판단하는 경우 | 특정 패턴에 대한 단계별 방법, 나열하거나 나열하지 않음 |
+| 작업 설명(도구)              | 귀하(개발자)       | 매 턴마다 도구 목록으로                            | 작업이 수행하는 작업, 반환하는 작업, 매개변수 의미     |
+| `application_state` 컨텍스트 | UI 코드(런타임 시) | 매 턴마다 라이브 앱 상태로                         | 현재 탐색, 선택, 초점 개체, URL                        |
+
+**빠른 진단:**
+
+- "기록이 열려 있어도 어떤 기록을 처리해야 하는지 에이전트가 계속 묻습니다." → 수정: 현재 항목 ID를 UI에서 `application_state`(`navigation` 키)에 씁니다. 그것은 기술 격차가 아니라 `application_state` 격차입니다.
+- "에이전트가 잘못된 액션을 호출하거나 매개변수를 오용합니다" → 수정: 매개변수에 대한 액션의 `description` 및 `.describe()`를 개선합니다. 그건 기술이 아니라 도구 설명 수정입니다.
+
+## 무엇이 어디로 가는가 {#what-goes-where}
+
+- **AGENTS.md** — 목적, 핵심 규칙, 상태 키, 작업 인덱스, skills 인덱스 등 모든 단계에서 전체 앱에 적용됩니다.
+- **Skills** — 요청 시 로드되는 특정 패턴에 대한 재사용 가능한 방법입니다. 앱에서 작업하는 모든 사람에게 적용됩니다.
+- **메모리(`memory/MEMORY.md`)** — 작성된 지침이 아닌 사용자별 기본 설정 및 수정 사항입니다.
+
+## 다음 단계 {#whats-next}
+
+- [Skills Guide](/docs/skills-guide) — 스킬 파일 형식, 프레임워크 skills 및 앱 지원 skills.
+- [Creating Templates](/docs/creating-templates) — `AGENTS.md` 및 skills가 배송 가능한 템플릿에 어떻게 적용되는지.
+- [The four-area checklist](/docs/key-concepts#four-area-checklist) — 모든 기능이 충족해야 하는 4개 영역 모델