다운로드한 패키지, 이렇게 씁니다Your downloaded package, explained

1개요 — 무엇을 받았고, 왜 이런 구조인가Overview — what you got, and why

이 패키지는 단순한 코드 묶음이 아닙니다. SelfAX가 당신의 요구사항을 바탕으로 구체적으로 설계한 결과물입니다. 어떤 에이전트가 필요하고, 무엇을 통제해야 하며, 어떤 데이터와 평가가 들어가야 하는지를 먼저 정한 다음, 그 설계가 안전하게 돌아가도록 거버넌스(AXCP)와 하네스까지 깔아 둔 상태로 건넵니다.

그래서 받는 순간부터 “백지에서 시작하는 코드”가 아니라, 안전 골격이 이미 깔린 위에 도메인 로직만 얹으면 되는 형태입니다. 할 일은 크게 두 부분으로 나뉩니다.

This isn't just a bundle of code — it's the concrete design SelfAX produced from your requirements: which agents you need, what must be controlled, which data and evaluations belong in it. On top of that, SelfAX has already laid down the governance (AXCP) and harness so the design runs safely. So from day one you aren't starting from a blank file — you add domain logic on a safe skeleton. The work splits into two parts.

PART 1 · 거버넌스(AXCP)는 이미 갖춰져 있습니다PART 1 · Governance (AXCP) is already in place

AXCP는 에이전트의 모든 외부·민감한 행동을 지키는 관문입니다. 에이전트는 무언가 하기 전에 AXCP에 먼저 묻고(decide), 거부면 멈추고, 보류면 사람의 승인을 기다리며, 실행한 뒤에는 반드시 그 사실을 보고(attest)합니다. 이 한 박자 덕분에 다음이 보장됩니다.

• 승인 게이트 — 고객에게 나가거나 외부로 보내는 행동은 사람의 승인 없이는 실행되지 않습니다.
• 권한 격리 — 프로젝트·테넌트 경계를 넘는 데이터 접근이 차단됩니다.
• 감사 로그 — 감지·제안·승인·실행의 모든 순간이 추적됩니다.
• fail-closed — AXCP에 닿지 못하면 아웃바운드는 막힙니다(절대 열어 두지 않습니다).

여기에 하네스(테스트 포털·골든 케이스·평가 게이트)가 더해져, 만든 에이전트가 실제로 통제 아래에서 도는지 눈으로 확인할 수 있습니다. 이 부분이 바로 SelfAX가 보장하는 안전이며, 당신이 따로 만들 필요가 없습니다.

AXCP is the gate guarding every external/sensitive action. An agent asks AXCP first (decide), stops on deny, waits for human approval on hold, and must report afterward (attest). That single beat guarantees the approval gate (no outbound without human sign-off), permission isolation (no crossing project/tenant boundaries), an audit log (every detect / propose / approve / act is traceable), and fail-closed behavior (if AXCP is unreachable, outbound is blocked). A harness (test portal, golden cases, eval gates) lets you watch the agents run under control. This is the safety SelfAX guarantees — you don't build it.

PART 2 · SelfAX의 지시어로, Claude가 코드를 채웁니다PART 2 · Claude fills the code, guided by SelfAX

나머지 절반은 에이전트의 실제 업무 로직입니다. SelfAX는 코드를 전부 써 주는 대신, Claude가 무엇을 어떻게 만들어야 하는지를 담은 지시어 묶음을 함께 줍니다.

• CLAUDE.md — 매 작업에서 지켜야 할 개발 규약과 가드레일
• KICKOFF.md — 어디서 어떻게 시작할지 (붙여넣는 빌드 프롬프트)
• TASKS.md — 무엇을 만들지 (빌드 순서까지 잡힌 백로그)
• docs/DECISIONS.md — 빌드 전에 확정할 결정들 (등급별)

이 폴더를 Claude Code로 열고 KICKOFF.md의 프롬프트를 붙여넣으면, Claude가 이 지시어들을 읽고 각 에이전트의 로직을 끝까지 구현합니다. 개방형 에이전트는 이미 LLM으로 추론하도록 만들어져 있어서(self.reason), 당신과 Claude는 프롬프트·툴·출력 형태를 도메인에 맞게 다듬기만 하면 됩니다. 결정론으로 충분한 UC는 LLM 없이 규칙 로직으로 구현합니다.

The other half is the agent's real work. Instead of writing all the code, SelfAX ships instructions that tell Claude what to build and how: CLAUDE.md (rules & guardrails), KICKOFF.md (how to start — the paste-in prompt), TASKS.md (what to build, in order), docs/DECISIONS.md (decisions to confirm first). Open this folder in Claude Code, paste the KICKOFF.md prompt, and Claude reads these and implements each agent end to end. Open agents already reason with the LLM (self.reason), so you and Claude just refine the prompt, tools, and output shape; deterministic UCs are implemented as rule logic without the LLM.

2패키지 구성Package structure

# 루트 디렉터리project root
docs/            PRD_SDS.md · DECISIONS.md · FOUNDATION_GUIDE.md (무엇을·왜 / 결정대장 / 신뢰표면 설명)(what & why / decision ledger / trust surface)
CLAUDE.md        개발 규약 — Claude Code가 먼저 읽음dev rules — Claude Code reads this first
KICKOFF.md       착수 가이드kickoff guide  ·  TASKS.md  개발 백로그(빌드 순서)backlog (build order)
FOUNDATION.md    정직한 상태 대시 · honest status dash · trace.json · consistency_report.md · profile.json
architecture.json 에이전트 토폴로지(클러스터·협응)agent topology (clusters, coordination)
agents/         base.py(거버넌스 루프 + LLM 추론 reason()governance loop + reason()) · agent_01.py …
llm.py           LLM 클라이언트(도구 중립·OpenAI 호환·무의존)LLM client (tool-neutral, OpenAI-compatible, no deps)
prompts/        에이전트별 시스템 프롬프트(reason()이 로드)per-agent system prompts (loaded by reason())  ·  tools/tools.schema.json
router.py        매니저 라우터(협응이 single이 아닐 때만)manager router (only if coordination ≠ single)
workflow/       workflow.json(도구 중립 워크플로tool-neutral flow) · n8n.workflow.json(핀 시if pinned)
rag/            retriever.py · memory.py(지식·메모리)retriever.py · memory.py  ·  integrations/ 연동 어댑터 스텁connector adapters
axcp_client.py   AXCP 거버넌스 클라이언트(무의존)AXCP client (no deps)  ·  publish_to_axcp.py · axcp/design.sections.json
runtime.py · config.py · agents.json   로드·설정·매니페스트load · config · manifest
demo.py · portal.html · test_portal.py 데모·테스트 포털(3탭)demo & test portal (3 tabs)
acceptance/ · tests/ · evals/   골든 인수·테스트·평가golden acceptance · tests · evals
Dockerfile · docker-compose.yml · .devcontainer/ · Makefile · .env.example · requirements.txt · README.md

꼭 알아야 할 파일Files you must know

3빠른 시작 (한 줄)Quick start (one command)

필요한 것: Docker만. 압축을 풀고 그 폴더에서:

All you need: Docker. Unzip, then in that folder:

docker compose up --build

그러면 차례대로 AXCP(거버넌스 런타임)가 뜨고, 동봉된 설계를 자동으로 발행·등록한 뒤, 에이전트와 테스트 포털이 올라옵니다. SelfAX 없이 이 한 줄이면 끝납니다.

In order: AXCP (governance runtime) starts → the bundled design is auto-published & registered → the agents & test portal come up. Self-contained — no SelfAX needed.

4빌드·실행 방법 (3가지)Build & run (3 ways)

A. Docker 권장 · recommended

docker compose up --build      # AXCP + 발행 + 에이전트 + 포털# AXCP + publish + agents + portal
docker compose logs -f          # 로그 보기# watch logs
docker compose down             # 정지# stop

B. 로컬 파이썬Local Python

python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate# Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env            # AXCP_URL · LLM_* 값 채우기# fill AXCP_URL and LLM_*
python publish_to_axcp.py       # AXCP가 떠 있어야 함# AXCP must be running
python demo.py                  # 또는: make portal# or: make portal

C. Dev Container

VS Code에서 폴더를 열고 “Reopen in Container” — 파이썬 환경이 자동 구성됩니다. 이후 make portal.

Open the folder in VS Code and “Reopen in Container” — the Python env is set up automatically. Then make portal.

5LLM 두뇌 & 비용LLM brain & cost

이 패키지는 AI 에이전트입니다. 개방형 에이전트는 기본적으로 LLM으로 추론합니다. SelfAX는 특정 모델을 강제하지 않으므로(도구 중립), .env에서 원하는 모델을 연결하면 됩니다.

This is an AI agent — open agents reason with an LLM by default. SelfAX does not pick a model (tool-neutral); connect your own via .env.

# .env — OpenAI 호환 엔드포인트면 무엇이든(상용 API · 온프렘 vLLM · 게이트웨이)# .env — any OpenAI-compatible endpoint (commercial API, on-prem vLLM, gateway)
LLM_BASE_URL=https://api.openai.com/v1   # or http://vllm:8000/v1
LLM_API_KEY=발급키your-key
LLM_MODEL=gpt-4o-mini

6테스트 포털 (3탭)Test portal (3 tabs)

make portal을 실행하면 http://localhost:7000에 SelfAX 디자인의 통합 포털이 뜹니다. 사이드바에서 AXCP 연결 상태를 한눈에 볼 수 있습니다.

make portal → http://localhost:7000. A unified portal in the SelfAX design, with AXCP connection status in the sidebar.

7신뢰 표면 — FOUNDATION · trace · 결정 등급Trust surface — FOUNDATION · trace · decision grades

신뢰는 겉모습이 아니라 계보·정직함·일관성에서 나옵니다. 그래서 이 패키지는 자기 상태를 숨기지 않고 그대로 보여줍니다.

Trust comes from provenance, honesty, consistency — not polish. The package surfaces its state instead of hiding it.

결정 등급 (DECISIONS.md)Decision grades (DECISIONS.md)

8AXCP 자동 등록 — 어떻게 도나AXCP auto-register — how it works

예전엔 에이전트를 AXCP에 손으로 등록해야 했지만, 이 패키지는 스스로 합니다.

You used to register agents into AXCP by hand. This package does it itself.

수동으로도 가능: python publish_to_axcp.py (환경변수 AXCP_URL·AXCP_PUBLISH_ACTOR).

Manual run too: python publish_to_axcp.py (env AXCP_URL · AXCP_PUBLISH_ACTOR).

9Git 연결 & 서버 배포Git setup & deploy

방법 1 — SelfAX에서 바로 GitHub로 푸시Option 1 — push to GitHub from SelfAX

SelfAX 화면의 GitHub 푸시 버튼으로, 리포를 미리 만들 필요 없이 한 번에 올릴 수 있습니다(리포명만 입력 — 없으면 자동 생성).

Use the Push to GitHub button in SelfAX — no need to pre-create the repo (just type a name; it's auto-created if missing).

방법 2 — 로컬에서 직접Option 2 — do it locally

# 패키지 폴더에서# inside the package folder
git init && git add -A && git commit -m "init: SelfAX build package"
git branch -M main
git remote add origin https://github.com/<you>/<repo>.git
git push -u origin main

서버에 배포 — clone 후 빌드Deploy on a server — clone & build

# private 리포면 fine-grained PAT(Contents: Read) 또는 SSH deploy key# private repo: fine-grained PAT (Contents: Read) or SSH deploy key
git clone https://github.com/<you>/<repo>.git && cd <repo>
cp .env.example .env            # 값 채우기(AXCP_URL · LLM_*)# fill values (AXCP_URL, LLM_*)
docker compose up --build -d

10로직 채우기 — 다듬는 일Fill the logic — it's refinement

개방형 에이전트는 이미 LLM으로 추론합니다. 그래서 할 일은 코드를 처음부터 짜는 게 아니라 다듬는 것입니다.

Open agents already reason with the LLM. Your job is refinement, not writing from scratch.

def _analyze(self, ctx):     # 개방형: 기본 = LLM 추론# open agent: default = LLM reasoning
    from llm import LLMNotConfigured
    try:
        return self.reason(ctx)   # prompts/ 로드 → 모델 → 거버넌스 툴 루프# load prompt → model → governed tool loop
    except LLMNotConfigured as _e:
        raise NotImplementedError(str(_e))

다듬는 포인트What to refine

① 프롬프트 — prompts/<agent>.md(역할·규칙·출력 형식)를 도메인에 맞게 손봅니다. ② 툴 — tool_registry()에 실제 도구를 등록하면, 추론 루프가 거버넌스를 거쳐 그 도구를 호출합니다. ③ 출력 형태 — 골든 케이스(acceptance/cases)의 기대값에 맞춥니다. ④ 워크플로형 UC — LLM 대신 규칙 로직으로 직접 구현합니다.

1) Prompt — tailor prompts/<agent>.md (role, rules, output format). 2) Tools — register real tools in tool_registry(); the reasoning loop calls them through governance. 3) Output shape — match the golden cases (acceptance/cases). 4) Workflow UCs — rule logic instead of the LLM.

11Claude Code로 이어 개발 — 효과적인 진행법Build it with Claude Code — the effective workflow

이 폴더는 Claude Code가 CLAUDE.md(규약)·KICKOFF.md(착수)·TASKS.md(백로그)를 따라 스스로 끝까지 완성하도록 설계돼 있습니다. 아래 순서대로 하면 결과가 가장 좋습니다.

This folder is designed so Claude Code finishes it by following CLAUDE.md + KICKOFF.md + TASKS.md. The steps below give the best result.

1단계 · 결정부터 확정Step 1 · Confirm the decisions first

손으로 파일을 편집할 필요는 없습니다. DECISIONS.md의 Part A "결정 프롬프트"를 Claude에 붙여넣으면, 항목마다 제안·트레이드오프·추천을 보여주고 묻습니다 — 채팅으로 답만 하면 확정값을 파일에 기록합니다. 또는 직접 ____ 빈칸을 채워도 됩니다.

No hand-editing needed. Paste the Part A "decision prompt" from DECISIONS.md into Claude; for each item it shows the proposal, tradeoffs and a recommendation and asks you — answer in chat and it records the value. Or fill the ____ blanks yourself.

2단계 · 골격이 도는지 확인Step 2 · Verify the skeleton runs

# .env의 AXCP_URL · LLM_* 설정 후# after setting AXCP_URL and LLM_* in .env
make verify     # 거버넌스 테스트 초록# governance tests green
make portal     # 모든 에이전트가 AXCP 판정을 받는지# every agent gets an AXCP verdict

3단계 · (권장) 실제 샘플 데이터를 넣는다Step 3 · (Recommended) put in real sample data

acceptance/cases/*.json의 입력을 실제 회의록·티켓 등으로 바꾸고 기대값(must_contain·fields)을 엄격하게 만드세요. 그래야 골든이 진짜 기준이 됩니다. RAG를 쓰면 rag/corpus/에 실제 문서를 넣습니다.

Replace the input in acceptance/cases/*.json with real meeting notes, tickets, and make the checks (must_contain, fields) strict so the goldens become a real bar. For RAG, drop real docs into rag/corpus/.

4단계 · KICKOFF 붙여넣고, 빌드 방식을 고른다Step 4 · Paste KICKOFF, pick a build mode

KICKOFF.md의 프롬프트를 붙여넣으면 Claude가 먼저 빌드 방식을 묻습니다 — (A) UC-1 파일럿으로 골격 검증 후 확장(권장) / (B) 전체를 한 번에. 9개 UC가 모두 생성돼 있으니 한 번에 가도 됩니다. 막히는 도메인 결정은 답하며 진행하세요.

Paste the prompt from KICKOFF.md; Claude first asks your build mode — (A) pilot UC-1 to validate the skeleton, then expand (recommended), or (B) all at once. All UCs are generated, so all-at-once is fine. Answer blocking domain choices as they come.

5단계 · UC 하나씩 + 눈으로 확인Step 5 · One UC at a time + eyeball it

구현 → make acceptance 초록 → make portal의 인수 탭에서 입력·기대·실제 출력 확인 → 다음 UC.

Implement → make acceptance green → check input/expected/actual in the Acceptance tab of make portal → next UC.

make acceptance # 비즈니스 로직 골든(빨강→초록) + blocking 평가# business-logic golden (red→green) + blocking evals

6단계 · 완료 기준 = 체크박스 전부 + 초록Step 6 · Done = all boxes + green

TASKS.md의 모든 체크박스(로직 + 연동 어댑터(integrations/) + 평가기)가 체크되고, make acceptance·make verify가 초록이며, AXCP 가드레일이 유지되면 완료입니다. "테스트 초록"만으로는 완료가 아닙니다.

Done when every checkbox in TASKS.md is checked (logic + connector adapters under integrations/ + evaluators), make acceptance and make verify are green, and the AXCP guardrails hold. "Tests green" alone is not done.

복붙용 프롬프트 — 순서대로Copy-paste prompts — in order

① 오리엔테이션 (코드 X)

1) Orient (no code yet)

이 폴더는 SelfAX가 만든 거버넌스 AI 에이전트 패키지다. CLAUDE.md, docs/PRD_SDS.md, docs/DECISIONS.md, FOUNDATION.md, TASKS.md, KICKOFF.md를 먼저 읽고, 구조·무엇을 만들지·남은 ASK_USER 결정을 5줄로 요약해줘. 아직 코드는 만들지 마.This is a governed AI-agent package from SelfAX. First read CLAUDE.md, docs/PRD_SDS.md, docs/DECISIONS.md, FOUNDATION.md, TASKS.md and KICKOFF.md, then summarize the structure, what to build, and open ASK_USER decisions in 5 lines. No code yet.

② 결정 확정 (대화로, Claude가 기록)

2) Confirm decisions (in chat; Claude records)

docs/DECISIONS.md의 결정을 한 항목씩 확정하자. 항목마다 (a) SelfAX 제안 (b) 트레이드오프 (c) 추천+근거 (d) 내 결정 질문을 보여줘. 🔴ASK_USER와 '구현 솔루션 선택'(RAG·LLM 서빙·워크플로 엔진)부터 시작하고, 내가 답하면 그 값을 DECISIONS.md에 기록해줘.Let's confirm docs/DECISIONS.md one item at a time. For each, show (a) the proposal, (b) tradeoffs, (c) a recommendation + rationale, (d) ask me. Start with the 🔴ASK_USER items and the "Implementation solution choices" (RAG, LLM serving, workflow engine); when I answer, record the value into DECISIONS.md.

③ LLM 연결 + 골격 확인

3) Wire the LLM + verify the skeleton

.env의 AXCP_URL과 LLM_BASE_URL/LLM_MODEL/LLM_API_KEY가 채워졌는지 확인하고, make verify와 make portal을 실행해 모든 에이전트가 AXCP 판정을 받는지 보여줘.Check AXCP_URL and LLM_BASE_URL/LLM_MODEL/LLM_API_KEY in .env, then run make verify and make portal and show that every agent gets an AXCP verdict.

④ UC 하나씩 구현 (초록까지)

4) Implement one UC (to green)

KICKOFF.md대로 시작하되 한 번에 다 하지 말고 UC-1만 끝까지 하자. 개방형이면 prompts/와 출력 형태를 다듬고(추론은 self.reason 기본), 워크플로형이면 규칙 로직을 구현해. make acceptance에서 그 UC의 골든이 초록이 될 때까지 반복하고, 막히는 결정은 물어봐.Follow KICKOFF.md but do only UC-1 end to end. If it's an open agent, refine prompts/ and the output shape (reasoning defaults to self.reason); if workflow, implement rule logic. Repeat until that UC's golden is green in make acceptance; ask me on blocking choices.

⑤ 연동 어댑터 (건너뛰지 마) → ⑥ 완료 점검

5) Connectors (don't skip) → 6) Done check

TASKS.md '연동·제약'의 미체크 항목, 특히 integrations/ 어댑터를 구현하자(외부 API 세부 모르면 인터페이스만 만들고 호출부는 TODO). 그다음 미체크 항목을 전부 나열하고 make acceptance·make verify가 초록인지 확인해줘.Implement the unchecked items in TASKS.md "integrations & constraints", especially the integrations/ adapters (if API details are unknown, build the interface and TODO the call). Then list every unchecked item and confirm make acceptance and make verify are green.

12거버넌스 모델 (AXCP)Governance model (AXCP)

모든 외부·민감 행동(툴 사용 포함)은 3박자를 따릅니다:

Every external/sensitive action (including tool use) follows three beats:

13문제 해결Troubleshooting