Foundation 사용·운영 런북
실제로 쓰는 사람을 위한 실무 런북 — 라이브(app.aisuit.dev)

AI슈트 Foundation
사용·운영 런북

AI슈트를 실제로 쓰는 사람은 셋입니다 — 자기 도구로 일하는 직원, 그 일을 세팅하고 측정하는 리더, 플랫폼 자체를 돌리는 운영자. 이 문서는 각자가 무엇을, 어떤 순서로, 어떤 화면·명령으로 하는지를 담은 실무 런북입니다. 개념 배경은 코어 설계 명세를, 화면 설명은 콘솔 시스템을 함께 보세요.

A · 일반 직원 B · 리더 C · aisuit 운영자 대상: 실무 사용자
이 런북을 어떻게 읽나 — 자기 역할 섹션만 봐도 되고, 순서대로 봐도 됩니다. 각 섹션은 흐름 요약(단계 칩) → 단계별 카드(실제 도구·화면·명령) → 원칙·주의 순입니다. 여기 적힌 모든 도구는 지금 라이브이며, 모든 외부 행동은 예외 없이 같은 4단 게이트·권한·승인·감사를 통과합니다.
00 · 시작하기 세 역할의 지도

한 문장으로: 사람에게 AI 에이전트를 붙이고, 그 일을 통제·기록한다.

AI슈트는 직군별 AI 도구 모음이 아니라, 사람·에이전트·도구·권한·지식·기록을 잇는 공통 운영 기반입니다. 그래서 쓰는 방식도 역할에 따라 갈립니다 — 아래 세 런북이 각 역할의 하루를 다룹니다.

RUNBOOK A

일반 직원

자기 AI 도구(예: Claude Code)를 회사 AI슈트에 연결해, 배정된 task를 받아 일하고, 외부 변경은 제안·승인으로 처리한다.

RUNBOOK B

리더

관리자 콘솔에서 사람에게 에이전트를 붙이고, 업무·절차·조직 지식·측정 기준을 세팅하고, 승인을 검토한다.

RUNBOOK C

aisuit 운영자

플랫폼 자체를 배포·운영한다 — 서버·데이터베이스·비밀 금고·LLM 연결·SSO·백업·관측.

공통 규칙 어느 역할이든 시크릿(API 키·비밀번호·토큰)은 절대 대화·프롬프트·로그에 넣지 않습니다. 에이전트는 자격증명을 보지 못하고, 서버가 금고에서 꺼내 대신 처리합니다. 위험한 외부 행동은 항상 승인과 감사 로그를 남깁니다.
런북 A · 일반 직원 자기 도구로 일한다

빈 화면이 아니라 담당 에이전트 브리핑으로 하루를 시작한다.

당신은 담당 에이전트를 배정받은 실무자입니다. 자기 AI 도구를 회사 AI슈트에 한 번 연결해두면, task를 받고 · 조직의 지식과 절차를 읽고 · 외부 변경은 제안해서 승인받는 흐름으로 일합니다. 아래 도구 이름은 당신의 AI 도구가 뒤에서 부르는 것이고, 당신은 자연어로 지시하면 됩니다.

대상 — 담당 에이전트를 배정받은 실무 사용자.   준비물 — 관리자에게 받은 연결 키트(MCP 엔드포인트 주소 + 개인 토큰). 키트에는 시크릿이 들어 있지 않습니다.
1 연결 2 할 일 찾기 3 세션 시작 4 맥락 읽기 5 액션 제안 6 세션 완료
POST /mcp · initialize → tools/list

1. 자기 도구를 연결한다

연결 키트의 엔드포인트 주소와 개인 토큰을 자기 AI 도구(Claude Code 등)에 등록합니다. 표준 MCP 프로토콜이라 도구가 알아서 핸드셰이크하고 사용 가능한 기능 목록을 받습니다. capabilities.list로 내가 어떤 권한을 가졌는지 확인할 수 있습니다.

tasks.list

2. 오늘 할 일을 찾는다

나에게 열린 task 카탈로그를 봅니다. 각 task에는 리더가 미리 붙여둔 절차(skill)와 측정 기준이 딸려 있을 수 있습니다. 트래커가 없는 팀도 내부 task로 독립적으로 일할 수 있습니다.

work_session.start(task_key)

3. 세션을 시작하면 브리핑을 받는다

task를 시작하면 빈 화면 대신 브리핑이 옵니다 — 내 페르소나(정체성), 이 일의 절차(skill playbook), 관련 조직 지식, 쓸 수 있는 capability 핸들(시크릿이 아니라 도구 이름), 그리고 보고 규약. 여기서부터 일을 시작합니다.

context.search · context.ask · context.get_skill

4. 일하면서 조직의 맥락을 읽는다

context.search로 조직 지식을 검색하고(관련 페이지·낡음 표시 포함), context.ask로 “우리는 이걸 어떻게 하나?”를 물어 답을 받고, context.get_skill로 이 task의 절차 런북을 가져옵니다. 모두 redaction 경계 뒤라 시크릿·개인정보는 보이지 않습니다.

action.propose → approval.execute

5. 외부 변경은 실행이 아니라 제안한다

이슈 코멘트·상태 변경 같은 외부 행동은 직접 실행하지 않고 제안합니다. 권한 엔진이 판정합니다 — 바로 허용/거부이거나, 승인이 필요하면 pending으로 남습니다. 승인되면 approval.execute로 실행되는데, 실제 호출은 서버가 Adapter와 금고로 대신합니다. 당신은 시크릿을 보지 않습니다. approval.status로 진행을 확인합니다.

work_session.complete

6. 세션을 닫으며 기록을 남긴다

일을 마치면 세션을 완료하면서 WorkLog를 남깁니다 — 무엇을 했고, 왜 그렇게 판단했고, 다음 액션은 무엇인지. 이 기록이 조직의 기억이 되고, 담당자가 바뀌어도 인수인계 자산으로 남습니다.

원칙 · 프롬프트가 곧 산출물 에이전트에게 준 지시와 맥락은 그대로 기록으로 남아 재사용됩니다. “대충 시켜서 대충 나온” 결과가 아니라, 지시 자체가 조직의 절차가 됩니다.
주의 · 시크릿 API 키·비밀번호·토큰을 프롬프트나 대화에 절대 넣지 마세요. 필요한 외부 접근은 서버가 capability 핸들로 대신 처리합니다. 시크릿을 붙여넣어야 할 것 같으면, 그건 리더/운영자가 금고에 등록할 일입니다.
런북 B · 리더 일을 세팅하고 측정한다

리더는 에이전트가 아니라 업무 운영 상태를 본다.

당신은 팀 리더/관리자입니다. 관리자 콘솔에서 사람에게 에이전트를 붙이고, 업무와 절차와 조직 지식과 측정 기준을 세팅하고, 위험한 행동의 승인을 검토합니다. 한 번 잘 세팅하면 모든 세션이 같은 절차·지식·기준을 물려받습니다.

대상 — 팀 리더·조직 관리자.   접속 — app.aisuit.dev 콘솔에 SSO로 로그인. 각 항목은 콘솔의 실제 화면에 대응합니다.
1 사람·권한 2 업무·절차 3 조직 지식 4 승인 검토 5 측정·평가 6 오프보딩
콘솔 · 멤버 / 초대

1. 사람에게 에이전트를 붙인다

담당자에게 전담 에이전트를 배정하고 Role Pack(직군 기본 권한)을 선택합니다. 권한 천장(ceiling)으로 그 에이전트가 넘볼 수 없는 위험 상한을 겁니다. 새 사람은 초대 링크로 온보딩합니다.

콘솔 · 저작(업무·절차)

2. 업무 카탈로그와 절차(skill)를 만든다

task type을 정의하고 task pack을 적용하면 실무자가 tasks.list로 보게 될 목록이 됩니다. 각 task에 “어떻게 할지” skill을 작성하고 버전·신선도를 관리합니다. skill은 조언일 뿐, 행동은 여전히 게이트를 통과합니다.

콘솔 · 조직 지식

3. “조직이 아는 것”을 적어둔다

선언적 지식 페이지를 씁니다 — 검색어(retrieval terms), 엔티티 그래프(같은 대상을 공유하는 페이지끼리 연결), 낡음 표시. 저장 시 하드 게이트가 붙어 붙여넣은 시크릿이나 위장된 권위 헤더는 거부됩니다. 미리보기로 저장 전에 검증하고, 질의응답으로 확인합니다.

콘솔 · 승인

4. 위험한 행동을 검토·승인한다

실무자가 제안한 외부 변경 중 승인이 필요한 것이 pending으로 모입니다. 검토 후 승인/거부하고, 멈춰버린(stranded) 승인은 회수합니다. 위험도를 올리는 예외 권한은 항상 감사 로그를 남깁니다.

콘솔 · 평가

5. 일을 측정하고 평가한다

업무별 측정 루브릭(어떻게 잘했다고 판단할지)을 정의합니다. 실무 신호(사람이 얼마나 고쳤나·거부했나)를 보고 버전으로 다듬고, AI가 신호 기반 초안을 제안하면 사람이 소유·활성화합니다. 세션별 판정으로 실제 결과를 봅니다.

콘솔 · 연동 / 알림 / 보안

6. 도구·알림·인증을 연결한다

연동 화면에서 Linear 같은 어댑터의 키를 금고에 넣고, 알림 화면에서 Slack 웹훅을 연결해 승인 대기를 통보받고, 보안 화면에서 SSO·세션 정책·세션 일괄 폐기를 관리합니다.

콘솔 · 오프보딩 / 인수인계 / 소유권

7. 사람이 떠날 때를 대비한다

오프보딩 킬스위치로 즉시 비활성화하고, 진행 중이던 일을 정리하고, 인수인계로 에이전트를 다음 담당자에게 넘깁니다. 소유권 이전으로 오프보딩 데드락도 빠져나옵니다.

콘솔 · 조직 연결(federation)

8. 다른 조직과 합의하에 연결한다

필요하면 다른 조직과 연결합니다 — 양쪽 소유자가 합의해야만 성립하고, 거버넌스만 롤업되며 테넌트 벽은 그대로입니다. 연결은 언제든 취소할 수 있습니다.

원칙 · write-once 절차·지식·측정 기준을 한 번 세팅하면 이후 모든 세션이 그것을 물려받습니다. 매번 다시 지시할 필요가 없습니다.
원칙 · 실무자의 언어로 실무자에게는 내부 시스템 용어를 강요하지 않습니다. task·지식·절차는 현장 언어로 쓰고, 게이트·상태머신 같은 기계 용어는 뒤에 둡니다.
런북 C · aisuit 운영자 플랫폼을 돌린다

플랫폼을 안전하게 배포하고, 시크릿을 격리하고, 상시 관측한다.

당신은 AI슈트 자체를 배포·운영하는 사람입니다. 서버·데이터베이스·비밀 금고·LLM 연결·SSO·백업·관측을 책임집니다. 라이브 구성은 nginx → systemd(uvicorn, 다중 워커) → PostgreSQL이며, 아래는 실제 유닛·스크립트·환경변수입니다.

대상 — 인프라·플랫폼 운영자.   범위 — 배포 · DB/백업 · 비밀 금고 · LLM egress · SSO · 신뢰성/관측. 설정은 EnvironmentFile /etc/ai-suit-foundation.env에 모입니다.
1 배포 2 DB·백업 3 비밀 금고 4 LLM 연결 5 SSO 6 신뢰성·관측
systemctl · nginx

1. 배포하고 갱신한다

서비스는 systemd 유닛 ai-suit-foundation(uvicorn, 다중 워커, proxy-headers)로 돌고, 앞단은 nginx 가상호스트 + Let’s Encrypt입니다. 코드 갱신 후 sudo systemctl restart ai-suit-foundation로 재시작합니다. 랜딩·/spec·/console·/runbook 같은 페이지는 요청마다 파일을 다시 읽으므로 재시작 없이 즉시 반영됩니다.

AISUIT_DATABASE_URL · scripts/backup_db.py

2. 데이터베이스와 백업

PostgreSQL을 AISUIT_DATABASE_URL=postgresql+psycopg://…로 가리킵니다. 연결 풀은 pre-ping과 recycle로 끊긴 연결을 방지합니다. 백업은 scripts/backup_db.py가 pg_dump로 뜨고 복원 목록으로 검증하며 보존 개수를 관리합니다 — 상시 자동으로 돕니다.

scripts/provision_secret.py · rotate_vault_key.py

3. 비밀 금고를 관리한다

자격증명은 Fernet로 암호화돼 금고에만 삽니다. scripts/provision_secret.py로 키를 주입하고, scripts/rotate_vault_key.py로 키를 교체(전체 재암호화)합니다. 시크릿 원값은 이 경계를 절대 벗어나지 않습니다 — 에이전트·콘솔·LLM 어디에도.

AISUIT_KNOWLEDGE_SYNTH · _EGRESS_ACKNOWLEDGED · OPENAI_API_KEY

4. LLM을 연결한다(egress 게이트)

LLM은 세 조건이 모두 맞을 때만 켜집니다 — AISUIT_KNOWLEDGE_SYNTH=llm(및 AISUIT_RUBRIC_DRAFTER=llm) + AISUIT_LLM_EGRESS_ACKNOWLEDGED=1 + OPENAI_API_KEY. 모델은 AISUIT_LLM_MODEL(기본 gpt-5.5). 하나라도 빠지거나 API가 실패하면 결정적 요약으로 폴백합니다. 나가는 텍스트는 redaction된 것뿐이고, 키는 요청 헤더에만 실립니다.

AISUIT_SSO_CLIENT_SECRET · 콘솔 보안

5. SSO를 연결한다

AISUIT_SSO_CLIENT_SECRET를 환경에 두고, 콘솔 보안 화면에서 Google Workspace OIDC(client_id·리다이렉트 URI)를 연결합니다. require_sso를 강제하면 비밀번호 로그인이 차단되고 SSO만 허용됩니다.

scripts/reap_stuck.py · /health · /metrics

6. 신뢰성과 관측

멈춘 승인은 reaper가 회수합니다 — scripts/reap_stuck.py, AISUIT_REAP_STUCK_AFTER_SECONDS, 콘솔의 회수 엔드포인트, 부팅 시 sweep. 폭주 방지는 조직별 rate limit(AISUIT_ORG_RATE_LIMIT/_WINDOW). 관측은 /health, /metrics(AISUIT_METRICS_TOKEN으로 보호), AISUIT_SENTRY_DSN, AISUIT_LOG_LEVEL.

ENV핵심 환경변수 한눈에

환경변수용도
AISUIT_DATABASE_URLDB 연결(라이브: postgresql+psycopg://…). 없으면 SQLite로 폴백.
AISUIT_KNOWLEDGE_SYNTH / AISUIT_RUBRIC_DRAFTERllm이면 해당 기능에 LLM 합성/초안을 켬(게이트 1/3).
AISUIT_LLM_EGRESS_ACKNOWLEDGED1이어야 외부 LLM 호출 허용(게이트 2/3, 명시적 승인).
OPENAI_API_KEY / AISUIT_LLM_MODELLLM 키(헤더에만) / 모델명(기본 gpt-5.5). 키 없으면 결정적 폴백(게이트 3/3).
AISUIT_SSO_CLIENT_SECRETGoogle Workspace OIDC 클라이언트 시크릿.
AISUIT_REAP_STUCK_AFTER_SECONDS이 시간 이상 멈춘 승인을 reaper가 회수.
AISUIT_ORG_RATE_LIMIT / AISUIT_ORG_RATE_WINDOW조직별 요청 폭주 방지(요청 수 / 창 크기).
AISUIT_METRICS_TOKEN/metrics 보호 토큰(관측).
AISUIT_SENTRY_DSN / AISUIT_LOG_LEVEL에러 추적 / 로그 상세도.
AISUIT_ENV / AISUIT_BASE_URL환경 구분(쿠키 보안 등) / 외부 접근 기준 URL.
주의 · 시크릿 취급 시크릿은 로그·프롬프트·이슈·터미널 어디에도 남기지 않습니다. 키는 파일 → 환경변수 → 소비하는 명령으로만 흘려보내고, 화면에 echo하지 않습니다.
주의 · 라이브 안전 운영 서버가 돌고 있을 때 광범위한 pkill은 금지입니다. 검증은 격리된 포트에서 하고, 배포는 반드시 systemctl restart로 — kill + nohup으로 띄우지 않습니다.
원칙 · 기본은 안전 DB 접근은 readonly로 설계되고 파괴적 SQL은 기본 차단, 외부 쓰기는 승인 후 실행이 기본입니다. 정의되지 않은 행동은 default-deny — 모르면 막습니다.