๐จ [๊ธด๊ธยท1์์] ๋ฉํฐ์์ด์ ํธ ํตํฉ ์ํคํ ์ฒ โ ์ธ๋ถ ์์ (cmdboard ์์ ์ฐธ์กฐ)
2026-05-29 KST ยท SARA(vscode_sara) ๋ฉํฐ์์ด์ ํธ ํตํฉ ์ค๊ณ ์ธ๋ถ ์์. ์ฑํฐโ์ฌ์ฉ์ ๋ํ ์ ์ฒด ๊ธฐ๋ก. ๊ธด๊ธยท1์์. ์ ๋ํ๋ฐฉ์ ์ด ํ์ด์ง + ์ธ์์ธ๊ณ์ ์ต์ ์ค๋ ์ท์ ์ฝ๊ณ ์ด์ด๋ฐ๋๋ค.
0. ํ ์ค ์์ง
vscode_sara๋ cmdboard ํ์๋ฌผ์ด๊ณ , cmdboard์๋ ์ด๋ฏธ PLANNER/CODI/EVALUATOR/ROUTER ํ๋ค์ค + ์ ์ฅ ๋ชจ๋ธ(chat_messagesยทactivity_logsยทHandoffArtifactยทcontinuation_state) + Phase ๋ก๋๋งต์ด ์ค๊ณยท์ผ๋ถ ๊ตฌํ๋ผ ์๋ค. ๋ฐ๋ผ์ SARA ๋ฉํฐ์์ด์ ํธํ๋ ๋ฐฑ์ง ์ค๊ณ๊ฐ ์๋๋ผ cmdboard ์์์ ์ด์ยท์ฌ์ฌ์ฉ์ผ๋ก ์ ๊ทผํ๋ค. ๋ ๋ชฉํ(๋ฌดํ ๋ฃจ์๋ค์ด์ ์ ํ์ฑ + ๋น ๋ฅธ ๋ก๋/์ ์ฅ)์ ํต์ฌ ๋ ๋ฒ๋ ์ ์ฅ์ ์ข ๋ฅ๊ฐ ์๋๋ผ (A) ์ง์๋ฒ ์ด์ค ๊ฒ์์ ๋ต + (B) ์์ ๊ทธ๋ํ + ๊ฒ์ฆ์ฆ๊ฑฐ ๊ธฐ๋ฐ ๊ฒฐ๊ณผ๊ณ์ฝ์ด๋ค.
1. ๋ ผ์ ํ๋ฆ (์๊ฐ์)
- Obsidian ๊ฒํ โ ๋
ธํธ์ฑ Obsidian(๋ก์ปฌ .md + git + AI ํ๋ฌ๊ทธ์ธ) vs ํ์ฌ Notion ์ํคํ
์ฒ ๋น๊ต. ๊ฒฐ๋ก : Obsidian์
.md+git ์ํฌํ๋ก์ ๋ง์ง๋ง SARA ์ ํ์ฑยท์๋์ ๋ ๋ฒ๊ฐ ์๋. ํธ๋์ปค DBยท๋งํฌ ๊ณต์ ๋ Notion ์ฐ์ธ. ํ์ด๋ธ๋ฆฌ๋ ๊ฐ๋ฅํ๋ ํ์ ์๋. - Notion+RDS ์บ์ ํ๊ฐ โ ์๋๋ ์ด๋ฏธ RDS-first๋ก ํด๊ฒฐ๋จ. ์ ํ์ฑ ์ํ์ ์ ์ฅ์๊ฐ ์๋๋ผ ์บ์ ์ ๋ต: ํ์ฌ truncate(์๋ผ๋ด๊ธฐ) + ๋จ์ผ ํ์ด์ง ํฌ๋กค์ด 1์์ ํ ๋ฃจ์๋ค์ด์ ์์ธ.
- ์ ํ์ฑโ์๋ ์คํํธ๋ผ โ truncate-dump(ํ์ฌ, ์ํ) โ full-dump(ํ ๊ท๋ชจ ์ต์ ) โ ์๋ฒ ๋ฉ RAG(๊ท๋ชจ ํ์ฅ ์ ์ ๋ต, ๊ทผ๊ฑฐ ์ธ์ฉ ๊ฐ๋ฅ).
- ๋ฉํฐ์์ด์ ํธ ์ง์ ์๋๋ฆฌ์ค โ ๋ณ๋ชฉยทํ ๋ฃจ์๋ค์ด์ ๋ฌด๊ฒ์ค์ฌ์ด "์ฝ๊ธฐ"์์ "์ง์ยท์ทจํฉ"์ผ๋ก ์ด๋ โ ๋ ๋ ์ด์ด ๋ถ๋ฆฌ ํ์.
2. ํต์ฌ ๊ฒฐ๋ก โ ๋ ๋ ์ด์ด ๋ถ๋ฆฌ
- A. ์ง์๋ฒ ์ด์ค(ํ์ ์ฉ): ์ธ๊ณ์ยท์ํคํ ์ฒยท๊ฒฐ์ ยท์ฝ๋. ์ฝ๊ธฐ ์์ฃผ, RAG. RDS ๋ฒกํฐ + Notion(์์ฑ/ํฌ์).
- B. ์์ ๊ทธ๋ํ(์กฐ์จ์ฉ): ํ๋ยทํ์คํฌ ์ํยท์ญํ ๋ถ๋ดยท๊ฒฐ๊ณผ. ์ฝ๊ธฐยท์ฐ๊ธฐ hot, ๋์์ฑ. RDS ํธ๋์ญ์ . (Notion=rate limitยท๋ธ๋ก / Obsidian=git ์ถฉ๋ โ hot ์กฐ์จ ๋ฃจํ ๋ถ์ ํฉ)
3. ํ ๋ฃจ์๋ค์ด์ ๋ฐฉ์ด
- ์ง์ 3๊ฐ: โ SARAโ์ง์(๋งฅ๋ฝ ๋๋ฝ) โก ์์ด์ ํธโ์์ (์ปจํ ์คํธ ๋ถ์กฑ) โข ์์ด์ ํธโ๊ฒฐ๊ณผ๋ณด๊ณ (๊ฒ์ฆ ์๋ '์๋ฃ').
- ์ต์ = โข์ ์ฐ์ ํ ๋ฃจ์๋ค์ด์ (SARA๊ฐ ๊ฐ์ง ์๋ฃ๋ฅผ ์ทจํฉ โ ์ ํ).
- ์ฐจ๋จ๋ฒ: ๊ฒฐ๊ณผ๋ฅผ ์์ ์์ ์ด ์๋๋ผ ๊ฒ์ฆ์ฆ๊ฑฐ(ํ ์คํธยท์ปค๋ฐ ํด์ยทdiffยทpy_compile) ๊ธฐ๋ฐ ๊ตฌ์กฐํ ๊ณ์ฝ์ผ๋ก ํ์ + ๋ ๋ฆฝ ๊ฒ์ฆ์ธต.
4. โ cmdboard ์์ ์ฐธ์กฐ (ํต์ฌ โ ์ฌ์ฌ์ฉ ๋์)
cmdboard V2(2026-05-25 ํ์ ) ํ๋ธยทํ๋ค์ค ๋ฌธ์ ๊ธฐ์ค, ๋ค์์ด ์ด๋ฏธ ์ค๊ณ๋จ:
- ์ญํ ํ๋ค์ค: SARA(user-facing coordinator: ์์ฒญ ์์ ยท์ํ ์์ฝยท์ง๋ฌธ/์น์ธยท๊ฒฐ๊ณผ ๋ณด๊ณ ) / PLANNER(=๊ธฐ์กด ์ฑํฐ: ์์
๊ณ์ฝ์ยท์๋ฃ๊ธฐ์คยท๊ฒ์ฆ๊ธฐ์คยทCODI ์ง์๋ฌธ ์์ฑ) / CODI(์ฝ๋ ์์ ยทํ
์คํธยท์ปค๋ฐยท๋ณด๊ณ ) / EVALUATOR(๋
๋ฆฝ ๊ฒ์ฆ์ธต: task_contract ๊ธฐ์ค PASS/FAIL/์์ ์๊ตฌ, ์ง์ ์์ ๊ธ์ง) / ROUTER(๋ค์ ํ๋ ๊ฒฐ์ ยทsilent block ์ฌ์ ๊ธฐ๋กยทhandoff ํ๋จ).
- ์ ์ฅ/ํ์คํ ๋ฆฌ ๋ชจ๋ธ: ์ฌ์ฉ์โSARA=chat_messages / ๋ด๋ถ์งํ=activity_logs / ์ฅ๋ฌธ ์ฐ์ถ๋ฌผ=HandoffArtifact / ์ ์ธ์
์ด์ด๋ฐ๊ธฐ=continuation_state. ์นด๋ ๋ณธ๋ฌธ์ ์ต์ ์์ฝ + artifact pointer๋ง(์ฅ๋ฌธ ๋์ ๊ธ์ง).
- B ๋ ์ด์ด๋ฅผ ์ ํ
์ด๋ธ ์์ด: HandoffArtifact enum ํ์ฅ 1ํ๋ก task_contract/evaluator_report/routing_decision/continuation_state ์์ฉ ๊ฐ๋ฅ(Phase 2 ํ๋ณด).
- EVALUATOR ๋
๋ฆฝ์ฑ = ์ต์
A ํ์ : ์๊ฐ๊ฒ์ฆ(์ ๋น์ฉ)์ baseline์ผ๋ก โ ๋
๋ฆฝ EVALUATOR๋ ์ํ ๋์ ์์
์๋ง ์ ์ง ๋์
(์ต์
B ๊ธฐ๊ฐ).
- Phase ๋ก๋๋งต: P1 ๋ผ๋ฒจ SARAํ โ P2 PLANNER+task_contract โ P3 EVALUATOR ๋
๋ฆฝ โ P4 ROUTER decision โ P5 continuation_state โ P6 3-zone UI. (ํ
์คํธ ์๋ฒ :8003, ์ด์ master push ์๋๋ฐฐํฌ)
- ์ฐธ์กฐ ๋งํฌ: cmdboard ํ๋ธ /3689512d9469810faa6dc5f90c0d0c38, V2 ํ๋ค์ค /36a9512d94698138aac4d6c3d5c306a2.
5. ๋งคํ โ ์ด๋ฒ ๋ ผ์ โ cmdboard ๊ธฐ์กด ์์
| ์ด๋ฒ ๋ ผ์ ๊ฐ๋ | cmdboard ๊ธฐ์กด ์์ |
|---|---|
| ์ค์ผ์คํธ๋ ์ดํฐ SARA | SARA (user-facing coordinator) |
| "์ฑํฐ vs SARA ์ฃผ์ฒด" ๊ฒฐ์ ํฌ์ธํธ | ์ด๋ฏธ ๊ฒฐ์ ๋จ: ์ฑํฐ=PLANNER(๋ด๋ถ), SARA=coordinator |
| ๊ฒ์ฆ์ฆ๊ฑฐ ๊ธฐ๋ฐ ๊ฒฐ๊ณผ๊ณ์ฝ | task_contract + EVALUATOR ๋ ๋ฆฝ๊ฒ์ฆ |
| ํ๋=1๊ธ ๊ตฌ์กฐ ๊ฐ์ฒด(B ๋ ์ด์ด) | HandoffArtifact enum ํ์ฅ(task_contract ๋ฑ) |
| ์กฐ์จ ํ๋ฆ ์ ์ด | ROUTER (next actionยทsilent block) |
| continuation ์ต์ ๋ณต์(g15) | continuation_state |
| A ์ง์๋ฒ ์ด์ค RAG | (์ ๊ท) โ cmdboard 'ํ๋ก์ ํธ ๋ฉ๋ชจ๋ฆฌ ๋ ํผ๋ฐ์ค'๊ฐ ์ ์ฌ ์ ๋ก |
| ## 6. ๊ฒฐ์ / ๋ฏธ๊ฒฐ | |
| ๊ฒฐ์ (cmdboard ๊ธฐ๋ฐ, ์ฌํ์ธ) | |
| - ์ฌ์ฉ์-facing = SARA ๋จ์ผ. ๋ด๋ถ = PLANNER/CODI/EVALUATOR/ROUTER ๋ถ๋ด. | |
| - ์ฑํฐ = PLANNER. B ๋ ์ด์ด๋ HandoffArtifact ์ฌ์ฌ์ฉ. EVALUATOR ์ต์ A(์ ์ง ๋์ ). | |
| ๋ฏธ๊ฒฐ (์ ๋ฐฉ ๊ฒฐ์ ๋๊ธฐ) | |
| 1. vscode_sara(SARA ํจ๋)์ cmdboard ํ๋ค์ค๋ฅผ ์ด๋๊น์ง ์ด์ํ ์ง โ ํจ๋์ ํ์ฌ ๋จ์ผ SARA(์ฝ๊ธฐ์ ์ฉ)ยทclaude-code MCP ๋ฏธ๋ฑ๋ก. PLANNER/CODI ๊ฒฝ๋ก(์ฑํฐโ์ฝ๋ ๋๋ SARAโ์ฝ๋ bridge)๋ฅผ ํจ๋์ ์ด๋ป๊ฒ ๋ค์ผ์ง. | |
| 2. A ์ง์๋ฒ ์ด์ค: full-dump ์ ์ง vs RDS ์๋ฒ ๋ฉ RAG ๋์ ์์ . | |
| 3. ์บ์ truncate ์ ๊ฑฐ + ์์ ํฌ๋กค(B-2)์ ๋ฉํฐ์์ด์ ํธ ์ ์ ๋จผ์ ์ฒ๋ฆฌํ ์ง. | |
| 4. cmdboard โ vscode_sara ์ฝ๋/์คํค๋ง ๊ณต์ ๋ฒ์(๊ณตํต ๋ผ์ด๋ธ๋ฌ๋ฆฌํ vs ๊ฐ์ ์ด์). | |
| ## 7. ๋ค์ ์์์ (์ ๋ํ๋ฐฉ) | |
| - ์ด ํ์ด์ง + ์ธ์์ธ๊ณ์ ์ต์ ์ค๋ ์ท์ ์๋๋ก ์ฝ๋๋ค. | |
| - ์ฒซ ๊ฒฐ์ : ยง6 ๋ฏธ๊ฒฐ 1ยท4(์ด์ ๋ฒ์ยท์ฝ๋ ๊ณต์ ) โ ๊ทธ๋ค์ B ๋ ์ด์ด ์คํค๋ง(HandoffArtifact ํ์ฅ vs sara_* ํ ์ด๋ธ) ์ค๊ณ. | |
| - ์์น: ๋ฐฑ์ง ์ค๊ณ ๊ธ์ง, cmdboard ๊ฒ์ฆ ์์ ์ฌ์ฌ์ฉ ์ฐ์ . ์ํ์์ (์ญ์ ยท์ด์๋ฐฐํฌยทforce)์ ๋ณ๋ ์น์ธ. | |
| --- | |
| ## 8. ์๋ธ์์ด์ ํธ ๊ธฐ๋ฐ ์คํ ๋ชจ๋ธ ์ถ๊ฐ (2026-05-29 KST ยท ์ฑํฐโ์ฌ์ฉ์ ํ์ ์์) | |
| > ์ง์ ยง1~7์ "์ญํ ํ๋ค์ค"๋ฅผ claude-agent-sdk ์๋ธ์์ด์ ํธ(Agent/Task ๋๊ตฌ) ๋ก ๊ตฌํํ๋ ๋ฐฉ์์ผ๋ก ๊ตฌ์ฒดํ. cmdboard ๊ณํ์ ๋์ฒด๊ฐ ์๋๋ผ ํฉ์นจ: ์๋ธ์์ด์ ํธ=์คํ ๊ฒฉ๋ฆฌ, cmdboard RDS ๋ชจ๋ธ=์ํยท๊ฒ์ฆยท์์. | |
| ### 8.1 SDK ์ฌ์ค ํ์ธ (๋ฆฌ์์น ๊ทผ๊ฑฐ) | |
| - ์๋ธ์์ด์ ํธ๋ ๊ฐ์ ์(fresh) ์ปจํ ์คํธ์์ ์คํ, ์ค๊ฐ ๋๊ตฌํธ์ถยท๊ฒฐ๊ณผ๋ ๋ด๋ถ์ ๋จ๊ณ ๋ถ๋ชจ์ ์ต์ข ๋ฉ์์ง๋ง ๋ฐํ. | |
| - ์๋ก์ ์์ ์ ์ ๊ทผ ๋ถ๊ฐ(๋ช ์์ ์ ๋ฌ๋ง), ์๋ธ์์ด์ ํธ๋ ์๊ธฐ ์๋ธ์์ด์ ํธ ๋ชป ๋์(1-depth). | |
- ๊ธฐ๋ณธ stateless(resume ์๋ ํธ์ถ=๊ธฐ์ต ์์). resume(agent_id)๋ก stateful ์ด์ด๊ฐ๊ธฐ ๊ฐ๋ฅ(v2.0.28+). |
|
- outputFormat(v0.1.45+, {type:'json_schema', schema:{...}})๋ก ์ต์ข
๊ฒฐ๊ณผ JSON ์คํค๋ง ๊ฐ์ โ ํ๋กฌํํธ๋ก JSON ๋ถํ๋ณด๋ค ํ์ฑ ์์ . |
|
| - ์๋ธ์์ด์ ํธ๋ณ ์์ฒด systemPromptยท๋๊ตฌ ์ ํ ๋ถ์ฌ ๊ฐ๋ฅ โ ํ๋ค์ค ๊ทธ๋๋ก ์ด์. | |
| ### 8.2 ์ญํ โ์๋ธ์์ด์ ํธ ๋งคํ | |
- PLANNER / CODI / EVALUATOR = .claude/agents/ ์๋ธ์์ด์ ํธ(ํ๋กฌํํธ=cmdboard ํ๋ค์ค ์ด์, ๋๊ตฌ ์ ํ ๊ฐ์). |
|
| - ROUTER = ๋ถ๋ชจ SARA ๋ก์ง(์๋ธ์์ด์ ํธ ์๋). ์๋ธ์์ด์ ํธ ๊ฐ ํธ์ถ ๋ถ๊ฐํ๋ฏ๋ก ๋ค์ํ๋ยท์ฌํธ์ถยท์๋ฃยท์์ค์ปฌ๋ ์ด์ ํ๋จ์ ์ ๋ถ ๋ถ๋ชจ ๋ฃจํ์ ๋ชจ์. | |
- ๊ฒฐ๊ณผ ํ์: ์ฝ๋๊ฐ โ ์์ธ๋ .md(Write ๋๊ตฌ, ์ฌ๋์ฉ) โก ์ต์ข
์ outputFormat JSON(๋ณ๊ฒฝํ์ผ/์ปค๋ฐํด์/ํ
์คํธ์ถ๋ ฅ/py_compile/md_artifact_path)์ผ๋ก ํ์ โ RDS HandoffArtifact. |
|
| ### 8.3 ์ฝ๋ ์ง์ (ํํ ์๋) vs ์๋ธ์์ด์ ํธ ์ฝ๋ โ ์ฐจ์ด | |
- ์คํ ํธ๋ฆฌ๊ฑฐ: ์ฌ๋์ด VS Code ๋์คํจ์น(ํํ) vs SARA๊ฐ Task๋ก ์๋ ํธ์ถ. |
|
| - ๊ถํ ์ํ: ํํ์ ์ฝ๋๊ฐ broker(:7777) ๊ฒฝ์ โ ์ํ์์ ํ ๋ ๊ทธ๋จ ๊ฒ์ดํธ. ์๋ธ์์ด์ ํธ ์ฝ๋๋ Bash๋ฅผ broker ๊ฒฝ์ ๋ก ๊ฐ์ ์ ํ๋ฉด ๊ฒ์ดํธ ์ฐํ(= ์ธ๊ณ์ "์ฑํฐโclaude-code broker ๋ฏธ๊ฐ๋ ๊ฐญ"). โ ์ฝ๋ ์๋ธ์์ด์ ํธ ๋๊ตฌ์ broker ๊ฒฝ์ ๊ฐ์ ๊ฐ P1 ํ์ ์กฐ๊ฑด. | |
| - ์ฌ๋ ๊ฐ์ ์ง์ ์๋ฉธ โ ยง3 โข ์ฐ์ ํ ๋ฃจ์๋ค์ด์ ์ํโ โ task_contract+EVALUATOR๊ฐ ์ฌ๋๊ฒ์ฆ ๋์ฒดํด์ผ ํจ. | |
| ### 8.4 ์ ์ด ๋ฃจํ (์ฌ์งํยท์๋ฃ ํ๋จ์ ์์ฌ) |
SARA(๋ถ๋ชจ ๋ฃจํ)
โโ PLANNER โ task_contract(JSON) โ RDS
โโก CODI(๊ณ์ฝ ์ ๋ฌ) โ ๊ฒฐ๊ณผ(JSON+.md) โ RDS
โโข EVALUATOR(๊ณ์ฝ+๊ฒฐ๊ณผ ์ ๋ฌ) โ evaluator_report(PASS/FAIL/์์ ์๊ตฌ + ์ฌ์ + ์ฌํ์ฆ๊ฑฐ)
โโฃ ROUTER(๋ถ๋ชจ) ๋ถ๊ธฐ:
PASS โ ์๋ฃ ์ฒ๋ฆฌ / FAILยท์์ โ โก๋ก ์ฌํธ์ถ(๊ณ์ฝ+required_fixes ์ฃผ์
) / ํ๊ณ์ด๊ณผ โ ์ฌ๋ ์์ค์ปฌ๋ ์ด์
- EVALUATOR = ํ์ ๋ง(PASS/FAIL/์์ ์๊ตฌ), ์ง์ ์์ ยท์ฌํธ์ถ ๊ธ์ง(๋ ธ์ ยง4 ์์น ์ ์ง). CODI๋ ๋ชป ๋ถ๋ฆ.
- ์ฌ์งํ ์ง์ = SARA(ROUTER ๋ก์ง): evaluator_report.required_fixes๋ฅผ ์ ๊ณ์ฝ๊ณผ ํฉ์ณ CODI ์ ํธ์ถ ํ๋กฌํํธ๋ก ์ฃผ์ . ์ฌํธ์ถ์ ์ ๊ท ์ธ์ (๊ธฐ๋ณธยท์์ ) ๋๋ resume(ํจ์จยท์ค์ผ์ํ) ์ ํ.
- ์๋ฃ ํ๋จ = ROUTERโSARA: EVALUATOR PASS + ์ข ๋ฃ์กฐ๊ฑด ์ถฉ์กฑ ์.
- ๊ฒ์ฆ ํ๊ณ:
outputFormat์ JSON ๋ชจ์๋ง ๋ณด์ฅ, ์ง์ ์๋ โ EVALUATOR๊ฐ ์ฆ๊ฑฐ(์ปค๋ฐยทpy_compileยทํ ์คํธ)๋ฅผ ์ฌ์คํ ๊ฒ์ฆํด์ผ โข ์ฐจ๋จ. - ํ์ง ์ํ = PLANNER ๊ณ์ฝ์ ๊ฒ์ฆ๊ธฐ์ค ๊ตฌ์ฒด์ฑ("๋์ํ๊ฒ" X โ "์๋ชป๋ ์ ๋ ฅ ํ ์คํธ ํต๊ณผ" O).
8.5 ๋ฌดํ๋ฃจํยท๊ณต๋ชจ ๋ฐฉ์ด
- ์ฌ์๋ ์ํ(์: 2~3ํ) FAIL โ ์๋์ค๋จ+์ฌ๋ ์์ค์ปฌ๋ ์ด์ .
- EVALUATOR ๋ ๋ฆฝ์ฑ = ์ต์ A(์ ์ํ ์๊ฐ๊ฒ์ฆ, ๊ณ ์ํ๋ง ๋ ๋ฆฝ). CODIโEVALUATOR ์ฆ๊ฑฐ ๊ณต์ ํ๋ ํ์ ๋ถ๋ฆฌ.
- ROUTER๊ฐ ์ฐจ๋จยท๋๋๋ฆผ ์ฌ์ ๋ฅผ
activity_logs/routing_decision์ silent block ๊ธฐ๋ก.
8.6 P1 ๊ถ์ฅ (๋จ๊ณ ๊ฒ์ดํ )
- P1 = ๊ณํยท๊ฒ์ฆ ๋ฃจํ ์๋ํ ๋จผ์ : PLANNER/EVALUATOR ์๋ธ์์ด์ ํธ ์ ์ + task_contract/evaluator_report JSON ์คํค๋ง + RDS ํ์. CODI๋ ๋น๋ถ๊ฐ ์๋ ์ ์ง(์ฌ๋ ๋์คํจ์น=์์ ํ).
- CODI ์๋ธ์์ด์ ํธ ์๋ํ = ๋ณ๋ ๋จ๊ณ: โ broker ๊ฒฝ์ ๊ฐ์ + โ EVALUATOR ํต๊ณผ ์กฐ๊ฑด์ด ๊ฐ์ถฐ์ง ๋ค ์ผฌ(์ธ๊ณ์ ๋ฏธ๊ฒฐ โ bridge ๋ฐฉํฅ๊ณผ ์ผ์น).
- ๋ฏธ๊ฒฐ โ ๊ฐฑ์ : ์ญํ 4๊ฐ๋ฅผ ์๋ธ์์ด์ ํธ๋ก ์ด์ํ๋ ๊ฒฐ๊ณผํ์๋ RDS task_contract๋ก ๊ตฌ์กฐํ ๊ฐ์ , ROUTER๋ ๋ถ๋ชจ ๋ก์ง.
- ๋ฏธ๊ฒฐ โฃ ๊ฐฑ์ : ์คํค๋ง(HandoffArtifact enum ํ์ฅ)๋ cmdboard์ ๊ณต์ , ์๋ธ์์ด์ ํธ ์ ์ ํ์ผ์ SARA ๋ฆฌํฌ
.claude/agents/์์ฒด ๋ณด์ .
8.7 ๋ค์ ์ฐ์ถ๋ฌผ ํ๋ณด
- P1 ์์ ๊ณ์ฝ์(.md): ์๋ธ์์ด์ ํธ ์ ์ ๋ฒ์ + ์คํค๋ง + RDS ํ์ + ์ฝ๋ ๊ฒ์ดํ ์กฐ๊ฑด.
- task_contract / evaluator_report / routing_decision JSON ์คํค๋ง ์ด์.
- ์ฝ๋ ์๋ธ์์ด์ ํธ ํ๋ค์ค ํ๋กฌํํธ + outputFormat ์คํค๋ง ์ํ 1๊ฐ.
8.8 ๋ณํ ์์ : RDS ๋ฉ๋ชจ๋ฆฌ MCP (์ด ๋ํ๋ฐฉ์ฉ)
- ๋ชฉํ: cmdboard RDS์ ์์ธ SARA ๋ฉ๋ชจ๋ฆฌ/ํธ๋์คํ๋ฅผ ๋ํ๋ฐฉ ์ฑํฐ๊ฐ MCP ๋๊ตฌ๋ก ์กฐํ(์ฝ๊ธฐ ์ฐ์ ).
- ์งํ: ๋ณ๋ ๊ฒํ ์ค(์ฝ๊ธฐ์ ์ฉ MCP ์๋ฒ ์ ๊ท vs ๊ธฐ์กด notion-anchor๋ฅ ํจํด ์ฌ์ฌ์ฉ). ๊ฒฐ์ ์ ๋ณธ ์น์ ์ ์ถ๊ฐ.
9. โ ์๋ฃ โ ์ฑํฐโGPT ์๋ ์ํต SW (agent-dialogue-hub ๊ตฌ์ถ ์๋ฃ, 2026-05-30)
์ฌ์ฉ์ ์ง์๋ก ์ 1์์ = ์ฑํฐ(Claude)โGPT ์๋ ํ์ SW. ๊ธฐ์กด ๋ฉํฐ์์ด์ ํธ ํตํฉ(ยง1~8)์ 2์์๋ก ๋ด๋ฆผ. ์ ๋ํ๋ฐฉ์ ์ด ยง9 + ์ธ์์ธ๊ณ์ ์ต์ ์ค๋ ์ท์ ์๋๋ก ์ฝ๋๋ค.
9.1 ๋ชฉํ
์ฑํฐ์ GPT๊ฐ ์ฌ์ฉ์ ๊ท์น ๊ธฐ์ค์ผ๋ก ์๋(์ฌ๋์ด ๋งค ํด ๊ฐ์ ํ์ง ์๊ณ ) ํ์. ์ฌ์ฉ์๋ ์์ ๊ด์ + ์ ํ์ ๊ฐ์ (์ฃผ์ ยท์ผ์์ ์งยท์น์ธ). ํต์ ๊ธฐ๋ก์ RDS. ์๋ ์ฐ์ .
9.2 ํต์ฌ ์ ์ฝ (๋ฆฌ์์น ํ์ )
- ChatGPT ๋ฐ์คํฌํฑ ์ฑ์ ๋ก์ปฌ(localhost/http) ์ปค๋ฅํฐ ๊ฑฐ๋ถ("Unsafe URL"), ์๊ฒฉ HTTPS๋ง. ๊ฒ๋ค๊ฐ ์ฌ๋์ด ์ ๋ ฅํ ํด์๋ง ๋ฐ์(์์จ ํด๋ง ๋ถ๊ฐ) โ ์ฑ์ผ๋ก๋ ์๋ํ ๋ถ๊ฐ๋ฅ.
- ๋ฐ๋ผ์ GPT ์ชฝ์ OpenAI API ์ง์ ๊ตฌ๋์ด ์ ์ผํ ์๋ํ ๊ฒฝ๋ก. Plus ๊ตฌ๋ (์ฑ)๊ณผ ๋ณ๊ฐ.
- Plus ์ฑ ๋ถ๊ฐ๊ธฐ๋ฅ(๋์ ๋ฉ๋ชจ๋ฆฌยท์ปค์คํ ์ธ์คํธ๋ญ์ )์ ์๋ํ ๋งฅ๋ฝ์์ RDS(๊ธฐ๋ก)+์์คํ ํ๋กฌํํธ(๊ท์น)+ํ๋ธ ๋งฅ๋ฝ์ฃผ์ ์ผ๋ก ๋์ฒด. ๋ชจ๋ธ ์ง๋ฅ ์์ฒด๋ API๋ก ๋์ผ.
9.3 ํ์ ๊ฒฐ์
- GPT ๋ชจ๋ธ = GPT-5.5 API ($5/M in, $30/M out, ์บ์ $1.25). ์ธ์ ๋น ๋๋ต ์์ผํธ~$0.5, ์ ์๋ฌ๋ฌ~์์ญ๋ฌ๋ฌ ์ถ์ . ๋น์ฉ ํฐ ๋ ๋ฒ=๋ชจ๋ธ ์ ํ(ํ์์ 5.4๋ก ํํฅ).
- ์ฑํฐ ์ ์ = ๋ก์ปฌ stdio MCP(์ต์). GPT ์ ์ = OpenAI API.
- ๋ ๋ค ๋์ผ ๋ก์ปฌ ๋ํ ํ๋ธ์ ๋ถ์. ํฐ๋ ๋ถํ์(์ฑ ์ ์) โ ์์ ๋ก์ปฌ.
9.4 ์ํคํ ์ฒ
๋ก์ปฌ ๋ํ ํ๋ธ (FastAPI, ์ค์ผ์คํธ๋ ์ดํฐ=ROUTER)
- ์๋ ํํ ๋ฃจํ: ํด ์งํยท์ข
๋ฃ์กฐ๊ฑด(ํฉ์)ยท์ฌ์๋ ์ํ Nํ
- ๊ท์น ๊ฐ์ : room/topic/role(chati|gpt)/kind(report|feedback) ์คํค๋ง
- ์ ํด cmdboard RDS ๊ธฐ๋ก (source of truth)
- WebSocket ํธ์
โ stdio MCP โ ์ฑํฐ(Claude)
โ OpenAI API โ GPT-5.5 ์ฐธ์ฌ์
โ WebSocket โ ์น๋ทฐ์ด(๊ด์ + ์ ํ์ ๊ฐ์
: ์ฃผ์
/์ผ์์ ์ง/์น์ธ)
- ์ฌ์ฉ์ ๊ด์ฌ = ์์ ๊ฐ๋ฅยท์ ํ์ (๋งค ํด ๊ฐ์ ์๋). ์ด๊ฒ "์๋ํ" ์๊ฑด.
- ๋ฉํฐ์์ด์ ํธ ์ค๊ณ์ ํธํ: ํ๋ธ=ROUTER, ์ ํด=RDS ๊ณ์ฝ/๊ธฐ๋ก.
9.5 ์ฌ์ฌ์ฉ ์์ฐ
cody-mcp-gateway(C:devtoolscody-mcp-gateway): ๋ฐ์คํฌํฑโClaude Code ๋ก์ปฌ MCP ๋ธ๋ฆฌ์ง + ์ํ๋ ๋ถ๋ฅ + broker ํ ๋ ๊ทธ๋จ ๊ฒ์ดํธ. ํ๋ธ ๊ณจ๊ฒฉยท๊ฒ์ดํธ ๋ก์ง ์ฐธ๊ณ .sara-memory(2026-05-29 ๊ตฌํ): RDS ์ฝ๊ธฐ์ ์ฉ ์กฐํ ์ฝ์ด. ํ๋ธ์ RDS ๊ธฐ๋ก/์กฐํ ๋ ์ด์ด ๊ธฐ๋ฐ.- SARA ์น๋ทฐ์ด ์์ฐ: ๊ด์ UI ์ฌ์ฌ์ฉ.
9.6 ๋ฏธ๊ฒฐ (์ ๋ฐฉ ๊ฒฐ์ )
- ์ฑํฐ๋ ์๋ ๋ฃจํ์ ๋ฃ์์ง: โ์ฑํฐ๋ Claude API/agent-sdk๋ก ์๋ ๊ตฌ๋(์์ชฝ ๋์นญยท์ง์ง ์๋) vs โGPT๋ง ์๋, Claude๋ SARA ํจ๋ ๋ด๋น. (์ด ๋ฐฉ ์ฑํฐ ์ฑ์ GPT ์ฑ๊ณผ ๋์ผ ํ๊ณ๋ก ์๋ ๋ฃจํ ๋ถ์ ํฉ)
- ํ๋ธ๋ฅผ ์ ๊ท๋ก ๋ง๋ค์ง vs cody-mcp-gateway ํ์ฅ.
- ์ข ๋ฃ์กฐ๊ฑดยท์ฌ์๋ ์ํยท์ญํ ํ๋กฌํํธ(์ฌ์ฉ์ ๊ท์น ์ฃผ์ ) ๊ตฌ์ฒด๊ฐ.
- RDS ์คํค๋ง: ์ ๊ท conversation ํ ์ด๋ธ vs ๊ธฐ์กด chat_messages ํ์ฅ.
- OpenAI API ํค ๋ฐ๊ธยท๊ฒฐ์ ์ ์ .
9.7 ๋ค์ ์ฐ์ถ๋ฌผ ํ๋ณด
- PoC ์ค๊ณ์(.md): ํ๋ธ ์คํค๋ง + ๋ฉ์์ง ๋ฒ์ค + ์๋ ๋ฃจํ + ์น๋ทฐ์ด + ๊ท์น ๊ฐ์ .
- RDS ๋ํ ์คํค๋ง ์ด์.
- ํ๋ธ โ ์ฑํฐ(stdio) / ํ๋ธ โ GPT(API) ์ด๋ํฐ PoC.
10. โ ํฉ์ โ 4๋ฏธ๊ฒฐ ํ์ (2026-05-30 KST, hub session #19)
ยง6 ๋ฏธ๊ฒฐ 1~4 ์ ๋ถ ํด์. ์ฑํฐ(PLANNER)โGPT ์๋ ํ์๋ก ๊ฒฐ๋ก . (#19 ์๋ฌธ ํ์ ๊ฒฐ๊ณผ ํ์ด์ง๋ ์ญ์ ๋จ โ ๊ฒฐ๋ก ์ ์๋ ๋ณด์กด.) (๋ค) CLI ๋ฌ๋ ์ค๊ณ ํ์ = ํ์ ๊ฒฐ๊ณผ โ (๋ค) CLI ๋ฌ๋ ์ค๊ณ ํ์ (hub #28). ๋ฐํ ์ ์ ๊ฒฐ ํ์ธ 5๊ฑด = ยง12(์๋). ์ด ยง10์ด ยง1~9 ์ค๊ณ์ ์คํ ํ์ ๋ณธ์ด๋ค.
๊ฒฐ๋ก
- โ ํ๋ค์ค ์ด์(๋ฏธ๊ฒฐ1 ํด์): ROUTER(
chat/task/verify_required3๋ถ๋ฅ) + EVALUATOR(task์ฑ ๊ฒฐ๊ณผ๋ง ๋ ๋ฆฝ๊ฒ์ฆ). ์ธ๋ถ/chat์๋ต ๋ถ๋ณ, ๊ฒฐ๊ณผ๊ณ์ฝ์activity_logs/HandoffArtifact๋ด๋ถ ๊ธฐ๋ก๋ง(G11 ํ๊ท ์ฐจ๋จ). PLANNER/CODI = disabled adapter. ROUTER๊ฐ evidence ํ์ ๋์ ํ์ (task|verify_required๋ง EVALUATOR ๊ฒ์ดํธ, chat ์ฐํ). - โก ์ง์๋ฒ ์ด์ค(๋ฏธ๊ฒฐ2 ํด์): full-dump ์ ์ง. RAG ์ ํ = ์ ์ ์จ(usage_ratioโฅ0.5 ๋๋ ์ฒซํดโฅ0.65 ๋น๋ฐ) AND ์ฌํ์จ(ํ์๋ฌธ์ ๋๋ฝ 0๊ฑด) ๋์ ์ถฉ์กฑ ์๋ง. ๊ณ์ธก
cache_bytes/estimated_tokens/load_ms/usage_ratio. - โข ๋ ธ์ ์บ์(๋ฏธ๊ฒฐ3 ํด์) โ ์ต์ฐ์ : truncate ์ ๊ฑฐ + ์์ ์ ๋ RDS ์บ์(G2 ํ ๊ฒฝ์ ). ์ ์ฅโ ์ฃผ์ (์ฃผ์ ๊ธฐ๋ณธ summary). ์์ ์ถ์ = page_id ์งํฉ diff + tombstone.
- โฃ ๊ณต์ ๋ฒ์(๋ฏธ๊ฒฐ4 ํด์): ์คํค๋ง cmdboard ๋จ์ผ์์ (SARA DDL 0). contract ๋ฒ์ ๊ณ ์ vendoring. ํ๋ค์ค vendored copy + upstream commit hash, ์ง์ import ๊ธ์ง.
์คํ์์ (ํ์ )
โข(์ ์ฅ ์ ๋ฌธํ+์์ํฌ๋กค, G2 ํ) โ โก๊ณ์ธก ์ถ๊ฐ โ [์ฐจ๋จํด์ : cmdboard ํ๋ค์ค ์คํ์ผ ๋์กฐ] โ โ ROUTER+EVALUATOR ์ต์์ด์(task์ฑ๋ง) โ โก๊ฒ์ดํธ ํ์ ์ผ๋ก RAG. โฃ๋ ์ ๊ตฌ๊ฐ ๊ณต์ ์ ์ฑ .
์ ํ ์ฐจ๋จ์กฐ๊ฑด (์ฝ๋ ๋ฌด๋ณ๊ฒฝ, โ ์ ์ )
cmdboard ROUTER/EVALUATOR/PLANNER/CODI ์คํ์ผ ์ธํฐํ์ด์คยทํธ์ถ๊ท์ฝ์ ์ค์ ๋์กฐ(claude-agent-sdk ๋ฐํ์ ์ ํฉ์ฑ). ๋ฏธํ์ธ ์ํ๋ก โ ์ฝ๋ ์ฐฉ์ ๊ธ์ง.
๋๊ตฌ ์ํ
ยง9์ ์ฑํฐโGPT ์๋ ํ์ SW = agent-dialogue-hub๋ก ๊ตฌ์ถ ์๋ฃ(:8780, PoC H1~H6 + A + B, ์ปค๋ฐ hub a49682dยทSARA 82670c1). ๋ณธ ํฉ์๋ ๊ทธ hub๋ก ๋์ถ.
11. โ ์์ ์คํ โ ๋ผ์ด๋ธ ๊ฒ์ฆ ๊ฒฐ๊ณผ (2026-06-01, #23~#25)
ยง8(์๋ธ์์ด์ ํธ ์คํ ๋ชจ๋ธ)์ ์ค์ ๊ตฌํยท๊ฒ์ฆ ๋จ๊ณ. SARAโ์ฝ๋(claude-code) ์์์
_bridge_e2e๋ธ๋์น์ ๊ตฌํํ๊ณ ๋ผ์ด๋ธ ๊ฒ์ฆํ ๊ฒฐ๊ณผ. ์ธ์์ธ๊ณ์ ์ต์ ์ค๋ ์ท #4์ ๋์ผ ๋ด์ฉ์ ์ค๊ณ์ธก ๊ธฐ๋ก.
11.1 ๊ตฌํ (์ปค๋ฐ f470578, _bridge_e2e, master ๋ฏธ๋จธ์ง)
์ง์๋ฌธ C:\dev\SARA\codi_bridge_delegation_fix_2026-06-01.md(GPTยท์ฑํฐ #23ยท#24 ํ์ ๋ฐ์). 5์์
:
1. .claude/agents/codi.md โ codi ์๋ธ์์ด์ ํธ ๋ฑ๋ก(ยง8.2 ๋งคํ ๊ตฌํ). tools = Read/Glob/Grep/Edit/MultiEdit/Write/Bash, Agent/Task ๋ฏธ๋ณด์ (leaf ์คํ์=ยง8.1 1-depth ์ค์).
2. .claude/settings.json โ ์ ์ญ broker ํ
(PreToolUseโ:7777) verbatim ๋ณต์ (deny 27+hooks 3์ข
). ยง8.3์์ ์๊ฒฌํ "์ฝ๋ ์๋ธ์์ด์ ํธ Bash์ broker ๊ฒฝ์ ๊ฐ์ = P1 ํ์"์ ๊ตฌํ ์๋.
3. subagent_type=codi ๊ฐ์ 2์ธต โ ๊ณ์ฝ ํ
์คํธ(render_contract_text) + ๊ฒฐํฉ์ธต(broker_gate Agent ๋ถ๊ธฐ deny-on-mismatch).
4. diag ํฌ๋์ fix โ extract_test_cmd ๋น๊ฐ ๊ฐ๋ + ๊ฒ์ฆ๋ธ๋ก try/except + verify_error.
5. ๋จ์ 5์ผ์ด์ค. pytest 115 passed(baseline 107+8), router_evaluator.py diff=0.
11.2 ๋ผ์ด๋ธ ๊ฒ์ฆ (์ฑํฐ ์ค์ผ์คํธ๋ ์ด์ : ๋๋ ์ธโํ ์คํธ๊ธฐ๋ WS=C:devSARAยทBRIDGE=1ยทloopbackโPROBEโ์๋ณต)
- โ
ยง3 ๊ฐ์ ์ธต PASS โ
general-purpose์์ ์broker_gate๊ฐ ์ ํํ deny โ SDK๊ฐ ์ฌ์ ๋ฐํ โ ๋ชจ๋ธ์ดcodi๋ก ์ฌํธ์ถ(ยง8.4 ROUTER ๋ถ๊ธฐ์ denyโ์ฌ์๋ ํ๋ฆ์ด ์๋๋๋ก ์๋). - โ
ยง4 diag PASS โ ํฌ๋์ 0,
verify_error:nullํฌํจ ์์ ํ diag 1ํ ๋ฐํ. - โ PROBE-0 (codi ์ธ์) FAIL โ
codi๋ก ์ฌํธ์ถํ์ผ๋ "Agent type 'codi' not found". codi.md๋ ์์นยทํ์ ์ ํํ๋claude mcp serve์๋ธํ๋ก์ธ์ค๊ฐ cwd์.claude/agents/๋ฅผ ์ ์ฌํ์ง ์์. - โธ PROBE-A/BยทT2 = codi ์ธ์ ์คํจ๋ก ๊ฒ์ดํธ ์ฐจ๋จ(์ค๊ณ๋๋ก ๋ฏธ์คํ).
11.3 โ ๊ทผ๋ณธ ์์ธ + #25 ์ฌ์ค๊ณ ๊ณผ์
claude mcp serve๋ ๋๊ตฌ ๋
ธ์ถ ์๋ฒ๋ผ ํ๋ก์ ํธ .claude/agents/(์๋ธ์์ด์ ํธ)๋ฅผ ์ ์ฌ ์ ํจ. ยง6 ๋ฏธ๊ฒฐ1("ํจ๋์ PLANNER/CODI ๊ฒฝ๋ก๋ฅผ ์ด๋ป๊ฒ ๋ค์ผ์ง")์ ํต์ฌ ๊ธฐ์ ์ ์ฝ์ด ์ฌ๊ธฐ์ ๊ตฌ์ฒดํ๋๋ค. ยง8.3์์ "broker ๊ฒฝ์ ๊ฐ์ "๋ ์ง์์ผ๋, ๊ทธ ์ ์ ์ธ "์์ ๋์ ์๋ธ์์ด์ ํธ๊ฐ ์ ์ด์ ๋ก๋๋๋๊ฐ"๊ฐ ๋ผ์ด๋ธ์์ NO๋ก ํ๋ช
.
- #25 ์์์ : (a) claude mcp serve --help๋ก --agents/--setting-sources/--mcp-config ๋ฑ .claude ์ ์ฌ ์ธ์ ์ค์ธก โ (b) ์์ผ๋ฉด SDK ์์ ํธ์ถ์ agents ์ต์
์ง์ ์ฃผ์
(ClaudeAgentOptions.agents) ๊ฒํ โ (c) ๊ทธ๋๋ ์ ๋๋ฉด mcp serve ๋์ SDK ์ธํ๋ก์ธ์ค ์๋ธ์์ด์ ํธ๋ก ์ ํ.
- fail-safe: SARA_CODI_BRIDGE ๊ธฐ๋ณธ OFF ์ ์ง(ํํ ๋จ์ผ ์ฝ๋๋ค์ดํฐ์ ๋์ผ). codi ์ธ์ PASS ์ ๊น์ง ์๋ ์์ ๋นํ์ฑ.
- ๊ฒ์ฆ ์ฌ๊ฐ = PROBE-0 PASS โ PROBE-A(broker ์์ฒญ ์ค์ธก, 0๊ฑด์ด๋ฉด ๋ฏธ๊ฒ์ดํธโ์๋์ฐ๊ธฐ ๊ธ์งยท์์ค์ปฌ๋ ์ดํธ) โ PROBE-B(force-push ๋๋ฏธ ๊ฒ์ดํธ, ์ค push 0) โ T2(์ค์ปค๋ฐยทdiagยทverdict=pass) โ master ๋จธ์ง(๋ณ๋ ์น์ธ).
- [page] ํ์ ๊ฒฐ๊ณผ โ (๋ค) CLI ๋ฌ๋ ์ค๊ณ ํ์ (hub #28, 2026-06-01)
12. โ (๋ค) ๋ฐํ ์ ์ ๊ฒฐ ํ์ธ ๊ฒฐ๊ณผ โ cmdboard ์ด์ ์ ๊นจ์ง๋ ์ง์ 5๊ฑด (2026-06-02)
hub #28 ํฉ์ ยง5("๋ฏธํ์ธ ์ํ๋ก ๋ฐํ ๊ธ์ง")๊ฐ ์๊ตฌํ ์ ๊ฒฐ ํ์ธ์, ์ฑํฐ๊ฐ ์ค์น CLI ์ค์ธก(
claude --version=2.1.154) + ๊ณต์ ํค๋๋ฆฌ์ค ๋ฌธ์ + cmdboard ์ค์ฝ๋ ๋์กฐ๋ก ํด์ํ ๊ฒฐ๊ณผ. (๋ค) ์ฝ๋ ์ง์๋ฌธ(C:\dev\SARA\codi_cli_runner_2026-06-02.md)์ "๋ฐํ ์ ํ์ธ ๊ฒฐ๊ณผ" ํ๊ฐ ์ด ๋ด์ฉ์ ๋ฐ์ ๊ฒ. ์ถํ (๋ค) ๊ตฌํ์ด ์ฌ์ฉ์ ์๋์ ์ด๊ธ๋๊ฑฐ๋ ํ๋ก์ธ์ค ์๋์ ๋ฌธ์ ๊ฐ ์๊ธฐ๋ฉด ์ด ์ ์ ๋จผ์ ์ฐธ์กฐํ๋ค. ํต์ฌ ๊ฒฐ๋ก : cmdboardcodi_runner_cliํจํด์ ๊ทธ๋๋ก ์ด์ํ๋ฉด ๊นจ์ง๋ค. argvยท๊ถํยทํ๋๋ช 5๊ฐ ์ง์ ์์ ์ ์ ์ด ํ์ํ๊ณ , ๊ทธ ๊ทผ๊ฑฐยท์กฐ์น๋ฅผ ์๋์ ๋ณด์กดํ๋ค.
12.0 ๊ฒ์ฆ ๋ฐฉ๋ฒ (์ฌํ ๊ฐ๋ฅ)
- CLI ์ค์ธก:
claude --versionโ 2.1.154 (Claude Code).claude --help์ ๋ฌธ ํ์ฑ(ํ๋๊ทธยทpermission-modeยทsetting-sources). - ๊ณต์ ๋ฌธ์: code.claude.com/docs/en/headless (
--bare์ hook/MCP/CLAUDE.md ๋ก๋ฉ ๊ด๊ณ). - cmdboard ์ค์ฝ๋:
bridge/app/services/codi_runner_cli.py(argv ์์ฑยท_classify_failure),app/services/codi.py:671(apply_codi_result),app/api/tasks.py:9608(/codi/result-reportpayload ๊ณ์ฝ).
12.1 ๋ค์ฏ ์ ์ (๊ทผ๊ฑฐ โ ์กฐ์น)
A. --max-turns ํ๋๊ทธ๊ฐ v2.1.154์ ์๋ค (์ด์ ์ ์ฆ์ CLI ์๋ฌ).
- ๊ทผ๊ฑฐ: claude --help์ max ๊ณ์ด์ --max-budget-usd ํ๋๋ฟ. --max-turns๋ ๋ชฉ๋ก์ ์์. ๊ทธ๋ฌ๋ cmdboard codi_runner_cli.py:1192๋ "--max-turns", str(max_turns)๋ฅผ argv์ ๊ทธ๋๋ก ๋ฃ์(+_classify_failure์ claude_cli_max_turns ๋ถ๊ธฐ ์กด์ฌ).
- ์กฐ์น: SARA argv์์ --max-turns ์ ๊ฑฐ. ํด/๋น์ฉ ํญ์ฃผ ์ฐจ๋จ์ timeout_s(hard timeout) + ์ ํ์ --max-budget-usd๋ก ๋์ฒด. claude_cli_max_turns ๋ถ๋ฅ๋ ์ฃฝ์ ๋ถ๊ธฐ๋ก ๋๋ ์ ์ฌ ํธํ ์ํด ์ญ์ ํ์ง ์์.
- ์ํฅ: ์ด์ ์งํ ๋ชจ๋ claude -p ์คํ์ด unknown-option์ผ๋ก ์คํจํ๋ 1์์ ์ฌ๊ณ ์ง์ .
B. claude -p์ broker ํ
๋ก๋ฉ = --bare๋ง ์์ผ๋ฉด ์๋ (๋ณ๋ ์ธ์ ๋ถํ์).
- ๊ทผ๊ฑฐ(๊ณต์ ๋ฌธ์): --bare๊ฐ ์์ผ๋ฉด claude -p๋ ์ธํฐ๋ํฐ๋ธ ์ธ์
๊ณผ ๋์ผํ ์ปจํ
์คํธ(์์
๋๋ ํฐ๋ฆฌยท~/.claude์ hooksยทMCPยทCLAUDE.md)๋ฅผ ๋ก๋ํ๋ค. --bare๋ฅผ ๋ถ์ด๋ฉด hooks/skills/plugins/MCP/auto-memory/CLAUDE.md ์๋ํ์์ ์ ๋ถ ์คํตํ๊ณ ๋ช
์ ์ธ์๋ง ์ ์ฉ.
- ์๋ฏธ: ยง11(#25)์์ FAIL๋ ๊ฒ์ claude mcp serve๊ฐ .claude/agents/๋ฅผ ์ ์ฝ์ ๊ฒ์ด๊ณ , claude -p๋ ๊ทธ๊ฒ๊ณผ ๋ค๋ฅธ ๊ฒฝ๋ก๋ผ .claude/settings.json์ broker PreToolUse ํ
์ด ๊ธฐ๋ณธ ๋ฐํํ๋ค. (๋ค) ์ฑํ์ ํต์ฌ ๊ทผ๊ฑฐ(โฃ๋ฒ ์ด์ )๊ฐ ์ด ์ฌ์ค๋ก ํ์ธ๋จ.
- ์กฐ์น: argv์ --bare ์ ๋ ๊ธ์ง. ํ
๋ก๋ฉ์ ๋ช
์์ ์ผ๋ก ๋ชป๋ฐ๊ธฐ ์ํด --setting-sources user,project,local ์ถ๊ฐ(์ ํจ ์ธ์ ํ์ธ๋จ).
- ๋จ, ์ค๋ฐํ๋ PROBE P-1ยทP-2 ์ค์ธก์ผ๋ก๋ง ํ์ (broker ์์ฒญ 0๊ฑด์ด๋ฉด ํ๋ฆฝ ์๊ตฌ ์ฐจ๋จ). ๋ฌธ์ยท์ฝ๋ ๊ทผ๊ฑฐ๊ฐ ์์ด๋ ๋ฐํ์ ์ค์ธก ์ ๊น์ง ์๋์ฐ๊ธฐ ๋นํ์ฑ.
C. ์ํ permission-mode = bypassPermissions์ธ๋ฐ cmdboard ์์ ๊ฒ์ฌ๊ฐ ๋ชป ์ก๋๋ค.
- ๊ทผ๊ฑฐ: --permission-mode ์ ํจ๊ฐ = acceptEdits, auto, bypassPermissions, default, dontAsk, plan. ์ค์ํ๊ฐ์ bypassPermissions. ๊ทธ๋ฌ๋ cmdboard ์์ ๊ฒ์ฌ(codi.py/codi_runner_cli.py:1165)๋ if "dangerously" in permission_mode.lower()๋ก๋ง ๋ง์ bypassPermissions ๋ฌธ์์ด์ ํต๊ณผ์ํจ๋ค.
- ์กฐ์น: SARA allowlist์์ bypassPermissions๋ ์ฐจ๋จ(๋ค์ด์ค๋ฉด acceptEdits๋ก ๊ฐ์ ์นํ). --dangerously-skip-permissionsยท--allow-dangerously-skip-permissions ํ๋๊ทธ๋ ์ฐจ๋จ. ๋จ์ํ
์คํธ assert "bypassPermissions" not in argv_safe.
D. cmdboard activity_logs.payload ์ ๊ท ํค โ commit_sha๊ฐ ์๋๋ผ commit.
- ๊ทผ๊ฑฐ: apply_codi_result(codi.py:671)์ /codi/result-report(tasks.py:9608) ๋ entrypoint์ payload ์ ๊ท ํค = result(completed/partial/failed), summary, commit(๋ฌธ์์ด), branch, tests(list[str]), changed_files(list[str]), notes, source(codi_stub/codi_runner/codi_user), error_code, chati_run_id, details_full/details_preview. (์คํค๋ง โฃ = cmdboard ๋จ์ผ์์ .)
- ์กฐ์น: SARA๊ฐ ๊ณต์ RDS activity_logs์ ์ง์ ์ธ ๋ ์ด ํค ์ดํ๋ฅผ ๊ทธ๋๋ก ์ฌ์ฌ์ฉ(ํ๋๋ช
๋๋ฆฌํํธ = โฃ ์๋ฐ). SARA ํ์ฅ ResultContract ์ ์ฒด๋ sara_codi_cli_result ๋จ์ผ ํค 1๊ฐ์ ์ค์ฒฉ. source๋ ์ ๊ท๊ฐ sara_codi_cli(๊ธฐ์กด๊ฐ ์ถฉ๋ ๊ธ์ง). action๋ช
codi_cli_result/sara_bridge_route/sara_bridge_task_verdict(cmdboard codi_done/codi_error/codi_result_reported์ ๋น์ถฉ๋). statusโresult ๋งคํ: passโcompleted, partialโpartial, fail/timeout/stall/crash/blockedโfailed.
- ๊ธ์ง: apply_codi_result ๋ฑ cmdboard ํจ์ ์ง์ ํธ์ถ ๊ธ์ง(Q1). SARA๋ ์ง์ SQLAlchemy๋ก๋ง ๊ธฐ๋ก.
E. --effort/--fallback-model ์ ํ ํ๊ธฐ ํ์ .
- ๊ทผ๊ฑฐ: --effort <level> ์ ํจ๊ฐ = low, medium, high, xhigh, max(--reasoning-effort ์๋). --fallback-model <model>์ ์ ํ ํ๊ธฐ์ด๋ฉฐ --print ์ ์ฉ(=-p์๋ง ๋์). --model์ alias(sonnet/opus) ๋๋ full name(claude-opus-4-8) ํ์ฉ.
- ์กฐ์น: argv ํ์ฅ ์ธ์ = --model / --effort(enum์ max ํฌํจ) / --fallback-model. (์ธ์์ธ๊ณ์ ๋ฏธ์ปค๋ฐ ๋๋ฆฌํํธ config/settings.json effort highโxhigh์๋ ์ ํฉ โ ๋จ ๊ทธ ํ์ผ์ ๋ณธ ์์
๊ณผ ๋ฌด๊ดํ๋ฏ๋ก ๊ฑด๋๋ฆฌ์ง ์์.)
12.2 ์ ์ฉ ๊ฒฐ๊ณผ / ๋ฏธํ์ธ
- ์ A~CยทE๋ ์ด ๋จธ์ ์ ์ค์น CLI(v2.1.154) ๊ธฐ์ค ์ค์ธก์ด๊ณ , D๋ cmdboard ์ค์ฝ๋ ๊ธฐ์ค. SARA๋ ์ด ๋จธ์ ์์ ์คํ๋๋ฏ๋ก v2.1.154๊ฐ ์ ์ฉ ๋ฒ์ .
- ๋ฏธํ์ธ: cmdboard๊ฐ ๋ค๋ฅธ ๋จธ์ /CLI ๋ฒ์ ์์ ๊ตฌ๋๋๋ ๊ฒฝ์ฐ์ ํธํ(SARA ์์ ๋ฒ์ ๋ฐ). CLI๊ฐ ์ ๊ทธ๋ ์ด๋๋์ด ํ๋๊ทธ ์ ์ด ๋ฐ๋๋ฉด AยทCยทE๋ฅผ ์ฌํ์ธํด์ผ ํจ.
- ํ์: P-1ยทP-2ยทP-3 broker ์ค๋ฐํ๋ ๋ฐํ์ PROBE๋ก๋ง ํ์ (๋ฌธ์ยท์ฝ๋ ๊ทผ๊ฑฐ๋ก ์๋ ํ์ฑํ ๊ธ์ง).