Note: This page is reproduced verbatim from the project's Korean-language source documentation. No English version of this document exists in the source repository yet — only the top-level README has an English translation.

Architecture & Philosophy: Design Theses

Architecture & Philosophy#

cys-terminal + CYSJavis 팩이 무엇을, 왜, 어떻게 이렇게 만들었는지를 설명하는 문서입니다. 설치·사용법은 User Manual, 첫인상은 README를 보세요. 본문 주장의 근거는 저장소 소스 경로로 표기합니다. (v0.14.x 기준)

0. 한 문장 정의#

cys-terminal은 "AI 에이전트 함대"를 하나의 회사처럼 굴리기 위한 터미널·데몬·관제탑이고, CYSJavis 팩은 그 회사의 취업규칙·운영도구·기억 골격이다. 둘은 따로 설치하는 별개 제품이 아니라, 하나의 저장소에서 함께 빌드·서명·배포되어 한 몸으로 동작한다 (cysjavis-pack/README.md: "터미널의 기계 기능과 역할별 절대지침 문서가 한 몸으로 동작한다").

이 저장소의 코드 대부분은 사람의 지휘 아래 AI 에이전트들이 작성했다. 커밋 로그의 Co-Authored-By 체인이 그 기록이며, 이 저장소 자체가 "여기서 설명하는 오케스트레이션이 실제로 동작한다"는 실증이다.

1. 문제의식 — 세 개의 벽#

기존 터미널·멀티플렉서는 "사람이 명령을 치는 곳"으로 설계됐다. 그 위에 AI CLI 에이전트를 여러 개 띄우면 곧바로 세 개의 벽에 부딪힌다.

1. 대화의 벽 — pane끼리 서로 말을 걸 수 없다. 에이전트 A가 B에게 일을 시키려면 사람이 복사·붙여넣기를 해야 하고, 결과 확인은 화면 폴링뿐이다.
2. 자원의 벽 — 에이전트가 남긴 고아 서버·프로세스가 쌓여 load가 폭주하고, 인증이 깨지고 (401), 시스템이 hang 된다. 누구도 정리 책임을 지지 않는다.
3. 관측의 벽 — 누가 얼마나 쓰는지(토큰·비용·컨텍스트), 지금 무엇을 하는지 보이지 않는다.

cys-terminal은 이 세 가지를 1급 기능으로 해결하기 위해 처음부터 새로 작성한 독자 구현이다. 그리고 네 번째 벽 — "에이전트를 어떻게 조직으로 묶을 것인가" — 를 CYSJavis 팩(역할별 절대지침 + 결정론 운영 도구)으로 해결한다.

2. 3층 구조 — 코어 / 팩 / 개인 층#

시스템 전체는 세 층으로 분리된다 (cysjavis-pack/README.md §3층 구조).

세 번째 층이 핵심 설계 결정이다. 배포되는 soul.md와 memory/는 의도적으로 비어 있는 골격이다.

"이 파일은 의도적으로 비어 있는 골격이다. 시스템을 사용하면서 당신의 우선순위·취향· 금지선을 직접 채워라. 절대지침(directives/)이 '어떻게 일하는가'라면, soul은 '누구를 위해 왜 일하는가'다." — cysjavis-pack/soul.md

"장기기억은 빌리는 것이 아니라 사용하며 축적하는 것이다." — cysjavis-pack/memory/MEMORY.md

작동 방식(디렉티브)과 능력(도구·스킬)은 완비해서 배포하되, 가치관과 기억은 소유자의 것으로 남긴다. 팩 설치기는 이 원칙을 코드로 강제한다 — soul.md·디렉티브·CLAUDE.md·schedule.json은 사용자 수정 시 영구 보존되고, 업데이트가 이를 덮어쓰지 않는다 (src/pack.rs의 is_user_owned / 사용자-수정 불가침 설치 로직).

3. 설계 철학 — 10개 명제#

문서·디렉티브·코드를 관통하는 원칙들이다. 각 명제는 배포되는 팩 원문에서 인용했다.

① 산문 계약을 코드 불변식으로 격상한다#

자연어 지침("서버를 정리해라", "완료 전에 검증해라")은 언젠가 무시된다. 그래서 반복되는 운영 의무는 결정론 도구·스키마·게이트로 내려앉힌다.

"결정론으로 환원 가능한 작업은 LLM 자연어 추론으로 다시 풀지 마라. … 도구 출력과 너의 기억이 충돌하면 항상 도구 출력이 이긴다." — directives/MASTER_DIRECTIVE.md

부트 검증은 javis_preflight.py의 exit code가 사실이고, 진행률은 javis_report.py의 체크박스 산술이 사실이며, 이벤트는 javis_event.py의 닫힌 enum만 통과한다.

② producer ≠ evaluator — 자기채점 금지#

산출물을 만든 주체가 그 품질을 채점하지 않는다.

"후보 생산자가 자기 점수 산출 금지. 채점 = locked-eval launcher." — directives/RSI_LEARNING_DIRECTIVE.md

리뷰어 판정 스키마(schemas/verdict_schema.json)에는 score/grade/rating 필드 자체가 없다 — 점수를 매길 수 없게 스키마 층에서 구조적으로 금지했다(다수결·평균·reward-hack 차단). 판정은 ACCEPT | REVISE | BLOCK | ESCALATE 닫힌 enum + evidence(file:line) 필수다.

③ 환각 0 — 검색 우선, garbage-in 차단#

"토대가 오염되면 아무리 다듬어도 거짓만 정교해진다." — directives/MASTER_DIRECTIVE.md "할루시네이션 자료로 학습하면 시스템 전체가 붕괴한다. … 부분 통과 = 전체 중단." — directives/RSI_LEARNING_DIRECTIVE.md

학습 루프(javis_learn.py)는 citation 없는 입력을 hard fail 시키고, 자기개선 봉쇄 게이트(bin/rsi-gate.sh)는 fail-closed로 동작한다(의심스러우면 차단).

④ 적대적 검증이 합의(다수결)에 우선한다#

"칭찬만 하는 리뷰는 리뷰가 아니다 — 결함을 찾는 것이 너의 직무다." — directives/REVIEWER_DIRECTIVE.md

리뷰어끼리 판정이 갈리면 다수결이 아니라 독립 재유도로 결착한다. 리뷰어를 서로 다른 모델 계열로 두는 이유도 명문화되어 있다 — 같은 모델이면 "사각지대(blind spot)가 상관되어 같은 실수를 함께 놓칠 수 있다"(REVIEWER_DIRECTIVE.md).

⑤ 롤백 우선 — baseline을 못 이기면 되돌린다#

모든 자기개선·팩 변경은 되돌릴 수 있어야 한다. RSI 라운드는 checkpoint를 먼저 만들고 (javis_rsi.py checkpoint), baseline을 못 이기면 rollback 한다 — 이때도 콘텐츠 삭제로 점수를 올리는 reward-hack을 막기 위해 retention 게이트(비가역 삭제 차단)가 걸린다. 팩 설치는 저널 트랜잭션이라 중단되면 부팅 시 자동 롤백된다 (src/pack.rs).

⑥ fail-closed와 fail-open의 의도적 비대칭#

모든 게이트가 같은 방향으로 실패하지 않는다. 보안·서명·능력 게이트는 fail-closed (팩 서명 검증 src/packsig.rs, capability 게이트, RSI 봉쇄), 관측·텔레메트리 훅은 fail-open(항상 exit 0 — 관측이 에이전트를 깨뜨리면 안 된다, hooks/cys-hook.sh), 통신 정책(ACL) 부재는 fail-open(설정 파일이 없다고 함대가 벙어리가 되면 안 된다). 어느 쪽으로 실패할지는 각 게이트의 목적에 따라 선택된 설계 결정이며 코드 주석에 명시된다.

⑦ 로컬 우선 — 데이터는 머신을 떠나지 않는다#

관제 데이터(사용량·비용·세션·전사)는 전부 로컬 SQLite(analytics.db·transcripts.db)에 쌓이고, 데몬은 네트워크 리스너가 없다(사용자 소유 Unix 소켓 / DACL 봉인 named pipe만). 외부 대시보드·클라우드 의존 0. PII는 CYS_CONTROL_REDACT=1로 가린 채 집계만 보존할 수 있다.

⑧ 판단과 구현의 분리 — 빠른 사고 / 느린 사고#

master는 판단(분해·브리프·검증·승인)에 집중하고 구현 노동은 워커에게 위임한다. 간단한 것은 직접(빠른 사고), 대부분은 위임 + 철저한 관리감독(느린 사고). 그리고 경계:

"Worker의 완료 보고를 그대로 믿지 마라 — diff와 테스트로 직접 확인한 뒤 승인한다." — directives/MASTER_DIRECTIVE.md

⑨ 실측만 완료로 인정한다 — started ≠ completed#

"도구가 completed를 반환하지 않은 작업을 완료라고 보고하지 않는다. started는 완료가 아니다." — directives/WORKER_DIRECTIVE.md "'될 것이다'가 아니라 '확인했다'로 보고한다." — 같은 문서

도구 반환어휘도 닫힌 8종 집합(round/TOOL_RESULT_VOCAB.md)으로 계약되어 있다.

⑩ 자율은 넓게, 정지는 denylist로 — 그리고 kill-switch#

승인된 로드맵 안에서는 멈추지 않고 달린다. 멈추는 곳은 금지선(denylist)뿐이다: 로드맵 이탈 새 범위·헌장(soul/디렉티브) 변경·외부 발행(git push 등 비가역)·비가역 삭제· 오너 명시 보유 결정권.

"로드맵 안·가역이면 달리고, 로드맵 밖·비가역이면 주차한다." — directives/MASTER_DIRECTIVE.md "오너의 어떤 입력이든 자율주행을 즉시 일시정지시킨다 — 오너가 항상 우선이다." — soul.md

이 자율주행 권한은 오너가 soul.md에 명시적으로 부여할 때만 발생하며("이 절이 없으면 master는 자율주행하지 않는다"), 자율화되는 것은 '전환을 누가 누르냐'뿐 — 품질 게이트의 엄격성은 불변이다. 집행은 산문이 아니라 PreToolUse 훅(hooks/guard.sh, deny-by-default allowlist·fail-closed)과 데몬 kill-switch(cys pause — 큐 배달·스케줄 발화 동결)가 맡는다.

4. 역할 체계 — 에이전트를 회사로 묶는 법#

CYSJavis 팩은 에이전트를 다섯 역할로 조직한다. 각 역할은 기동 시 절대지침 (directives/*.md)을 자동 주입받아 "각성"한다 — 지침 없는 노드는 단순 단말로 수렴한다는 것이 반복 관찰된 실패 양식이기 때문이다.

라운드 루프 — 중요 산출물은 "작업 → 리뷰어 [문제·논쟁·조언] → 반박(vindication) → 재반박 → 수용·수정"의 라운드를 목표 품질 도달 또는 상한(10라운드)까지 반복한다. 상한 도달 시 무한 루프 대신 오너에게 격차를 보고한다(escalation).

역할은 이름뿐이 아니라 기계로 강제된다:

• 데몬은 커널 peer pid로 발신자를 검증하고(자기신고 role 불신), acl.json의 role→role 정책으로 stdin 주입을 게이트한다 — 예: 리뷰어는 워커를 직접 조향할 수 없다 (중재는 master 경유).
• 능력 모델(src/bin/cysd/caps.rs)은 deny-by-default — reviewer/planner는 읽기·검색만. 에이전트 내부 도구는 PreToolUse 훅(hooks/role-capability-gate.sh)이 실 집행자다 (리뷰어가 검토 대상을 직접 고쳐버리는 reward-hack 차단).
• master 특권 탈취(라이브 master role claim), 워커 무한 증식(active-limit), 승인 자기결재 (feed.push한 노드가 스스로 feed.reply)는 데몬이 거부한다.

Continue: System Architecture & Security → · Back to Overview