컨텍스트 CLI
코딩 에이전트, CI, IDE 도구에 워크스페이스를 건네는 명령입니다. 모두 워크스페이스 루트에서 실행합니다.
명령설명
모듈 단위까지 내려간 워크스페이스 구조를 에이전트가 읽을 수 있는 형태로 출력합니다.
워크스페이스가 Akan 컨벤션을 어긴 곳을 찾아, 문제마다 고칠 명령과 함께 보고합니다.
Akan MCP 서버를 띄웁니다. 에디터 속 에이전트가 같은 정보를 직접 물어볼 수 있습니다.
그 서버를 Cursor, Claude Code, Codex의 프로젝트 설정에 등록합니다.
MCP 툴 하나를 터미널에서 호출해, 에이전트가 받을 결과를 그대로 보여 줍니다.
이 페이지에서 쓰는 말
용어설명
*.abstract.md
모듈마다 옆에 두는 짧은 문서입니다. 모듈이 맡는 일과, 코드로는 드러나지 않는 규칙을 적습니다.
MCP
Model Context Protocol입니다. 코딩 에이전트가 바깥의 툴을 부르는 표준 방식입니다.
stdio
표준 입력과 출력입니다. 에디터가 서버를 자식 프로세스로 띄우므로 포트를 열지 않습니다.
mode
MCP 서버가 어디까지 할 수 있는지입니다.
readonly는 읽기, plan은 플랜 파일 쓰기, apply는 소스 수정까지입니다.workflow plan
.akan/workflows/plans/ 아래에 두는 JSON 파일로, 무엇을 바꿀지 수정 전에 적어 둡니다.어떤 명령을 쓸까
context는 워크스페이스를 한 번에 건네고, mcp는 에이전트가 계속 물어보게 합니다. 에이전트가 무엇까지 바꿀 수 있는지는 mcp의 --mode가 정합니다.| 하려는 일 | 실행할 명령 |
|---|---|
| 작업을 시작할 때 에이전트에게 워크스페이스 전체를 건넵니다. | akan context --format json |
| 모듈 하나를 abstract와 함께 건넵니다. | akan context --module user |
| 에이전트가 바꾸기 전과 후에 컨벤션을 점검합니다. | akan doctor --strict --format json |
| 에디터 속 에이전트가 필요할 때마다 직접 묻게 합니다. | akan mcp-install |
| MCP 툴 하나가 무엇을 돌려주는지 직접 확인합니다. | akan mcp-call list_apps |
context
워크스페이스 구조를 에이전트가 읽을 수 있는 형태로 출력합니다.
외부 코딩 에이전트, CI job, IDE 확장이 워크스페이스 요약을 필요로 할 때 씁니다.
형식
옵션
--formatString기본값 markdownmarkdown | json
출력 형식입니다. 도구에는
json을, 사람이나 채팅 프롬프트에는 markdown을 씁니다.--appStringnullable
이 앱만 나열합니다. 라이브러리와 패키지는 그대로 모두 나옵니다.
--moduleStringnullable
이 이름의 모듈만 나열하고, 모듈마다
*.abstract.md 본문을 파일 목록보다 먼저 넣습니다.참고
이름설명
출력 내용
앱·라이브러리·패키지, 모듈별 파일 목록, 생성 파일 패턴, 검증 명령입니다.
abstract 범위
--module이 없으면 abstract는 경로와 제목만 나오고, --module을 주면 본문까지 나옵니다.민감 정보
.env 값이나 secret은 출력하지 않습니다.예시
doctor
워크스페이스가 Akan 컨벤션에서 벗어난 곳을 보고합니다. 허용되지 않은 파일, 빠진 모듈 abstract 같은 것들입니다.
에이전트가 바꾸기 전과 후에 실행하고, 기계가 읽을 결과가 필요하면
--format json을 씁니다.형식
옵션
--formatString기본값 texttext | json
출력 형식입니다. 에이전트 검증 루프와 CI에는
json을 씁니다.--strictBoolean기본값 false
권장 사항인 컨벤션도 오류로 올립니다. 지금은 빠진 모듈 abstract가 여기에 해당합니다.
--iosBoolean기본값 false
컨벤션 대신 native 설정만 점검합니다. Apple이 이미 가져갔을 법한 자리 표시자 bundle id를 찾습니다.
참고
이름설명
상태
진단 중 하나라도 오류면
failed, 아니면 passed입니다.함께 출력
생성 파일이 최신인지, 문제별 복구 명령, 검증 명령을 함께 출력합니다.
불리언 옵션
--strict처럼 이름만 쓰면 --strict true와 같습니다.예시
doctor가 보는 항목
진단마다 코드, 수준, 가리키는 파일이 붙습니다. 대부분은
akan repair module-shape처럼 고칠 때 쓸 명령도 함께 알려 줍니다.| 진단 코드 | 수준 |
|---|---|
| ↳ 뜻 | |
| app-root-unknown-entry | 오류 |
| 앱 루트에 허용되지 않은 파일이나 폴더가 있습니다. | |
| lib-root-unknown-entry | 오류 |
| 라이브러리 루트에 대한 같은 점검입니다. | |
| module-shape-invalid | 오류 |
모듈에 *.signal.ts 같은 필수 파일이 빠졌습니다. | |
| module-abstract-missing | 경고 (--strict면 오류) |
모듈에 *.abstract.md가 없습니다. | |
| dictionary-label-missing | 경고 |
*.constant.ts의 필드에 대한 라벨이 모듈 딕셔너리에 없습니다. | |
| agent-guide-stale | 경고 |
AGENTS.md가 설치된 프레임워크보다 오래된 릴리스로 쓰였습니다. | |
| agent-guide-unstamped | 경고 |
AGENTS.md에 버전 표시가 없어 언제 쓰였는지 알 수 없습니다. | |
| recipe-index-stale | 오류 |
AGENTS.md의 레시피 목록에 빠진 레시피가 있거나 없어진 레시피가 남아 있습니다. | |
| recipe-inline-duplicate | 경고 |
인라인 className이 레시피를 쓰지 않고 같은 모양을 다시 적었습니다. | |
| mobile-appid-placeholder | 경고 (--ios에서만) |
| 네이티브 타깃이 아직 자리 표시자 bundle id를 씁니다. | |
doctor는 프로세스를 실패로 끝내지 않습니다. 상태가
failed여도 종료 코드는 0이므로, CI에서 막으려면 --format json 결과의 status를 읽어야 합니다.mcp
Akan MCP 서버를 stdio로 띄웁니다.
MCP를 지원하는 코딩 에이전트가 이 서버에 워크스페이스·모듈 컨텍스트, 가이드라인, 명령 설명, 진단을 묻습니다.
에이전트가 어디까지 할 수 있는지는
--mode가 정하고, 기본값이 가장 좁은 범위입니다.형식
옵션
--modeString기본값 readonlyreadonly | plan | apply
readonly는 읽기만 하고, plan은 플랜 파일도 쓰며, apply는 소스까지 고칩니다.참고
이름설명
plan 모드
list_workflows, explain_workflow, plan_workflow가 더해집니다. 쓰는 것은 플랜 파일뿐입니다.apply 모드
apply_workflow, run_validation과 복구 툴이 더해지므로 소스를 고칩니다.워크플로 정책
AGENTS.md는 에이전트에게 --mode plan으로 계획하고 --mode apply로 적용하며, 워크플로를 먼저 쓰라고 안내합니다.모듈 컨텍스트
get_module_context는 모듈 abstract를 먼저, 이어서 모듈의 파일 목록을 돌려줍니다.실행 위치
워크스페이스 루트에서 띄웁니다. 서버는 현재 폴더를 워크스페이스로 읽습니다.
예시
mcp-install
Akan MCP 서버를 Cursor, Claude Code, Codex의 프로젝트 설정에 등록합니다.
설정 파일에 있던 다른 서버는 그대로 두고
akan 항목만 씁니다.형식
인자
targetString기본값 allcursor | claude | codex | all
등록할 도구입니다. 생략하면 셋 모두 등록합니다.
옵션
--forceBoolean기본값 false
내용이 다른
akan 항목이 이미 있으면 덮어씁니다. 없으면 오류를 내고 멈춥니다.--modeString기본값 applyreadonly | plan | apply
에디터가
akan mcp를 띄울 때 쓸 모드입니다. 여기서는 기본값이 readonly가 아니라 apply입니다.참고
이름설명
Cursor
.cursor/mcp.json에 씁니다. 항목이 먼저 열린 워크스페이스 폴더로 이동한 뒤 실행합니다.Claude Code
.mcp.json에 씁니다. 항목이 먼저 $CLAUDE_PROJECT_DIR로 이동한 뒤 실행합니다.Codex
.codex/config.toml에 씁니다. 항목이 폴더를 옮기지 않으므로 Codex를 워크스페이스 루트에서 실행합니다.새 워크스페이스
akan create-workspace가 셋 모두에 --force로 실행하므로 새 워크스페이스는 apply 모드로 시작합니다.예시
mcp-call
Akan MCP 툴 하나를 터미널에서 호출하고 JSON 결과를 출력합니다.
stdio 프로토콜 없이 서버와 같은 코드를 실행하므로, 에이전트가 받을 결과를 그대로 볼 수 있습니다.
형식
인자
toolString필수
list_apps, plan_workflow 같은 툴 이름입니다.옵션
--modeString기본값 readonlyreadonly | plan | apply
호출할 모드입니다. 그 모드에 없는 툴을 부르면 실패합니다.
--argsStringnullable
툴 인자를 JSON 객체 하나로 넘깁니다. 셸에서는 작은따옴표로 감쌉니다.
--formatString기본값 jsonjson
출력 형식입니다.
json 하나뿐입니다.참고
이름설명
실제 호출
흉내가 아니라 실제로 실행합니다.
plan_workflow는 플랜 파일을 쓰고 apply_workflow는 소스를 고칩니다.예시
MCP 툴과 리소스
akan mcp가 내놓는 툴은 --mode에 따라 늘어납니다. 넓은 모드는 좁은 모드의 툴을 모두 포함합니다.툴
readonly
plan
apply
워크스페이스 읽기
inspect_akan_context
✓
✓
✓
타입이 있는 읽기 전용 컨텍스트 조회입니다. 에이전트는 이 툴부터 쓰도록 안내받습니다.
get_workspace_summary
✓
✓
✓
akan context --format json이 출력하는 것과 같은 요약입니다.list_apps
✓
✓
✓
앱 목록과 앱별 모듈입니다.
list_modules
✓
✓
✓
앱과 라이브러리에 걸친 모든 모듈입니다.
get_module_context
✓
✓
✓
abstract 본문을 포함한 모듈 하나입니다. 두 앱에 같은 이름의 모듈이 있으면
app을 넘깁니다.get_guideline
✓
✓
✓
이름으로 고른 Akan 가이드라인 하나입니다.
akan guideline show와 같은 내용입니다.explain_command
✓
✓
✓
akan 명령 하나에 대한 짧은 설명입니다.doctor_workspace
✓
✓
✓
akan doctor 결과입니다. 플랜이나 바뀐 파일을 주면 원래 있던 문제와 새 문제를 나눕니다.get_validation_contract
✓
✓
✓
검증 명령, 리포트 형식, 모드별 툴 목록입니다.
변경 계획
list_workflows
✓
✓
사용할 수 있는 워크플로 목록입니다.
explain_workflow
✓
✓
워크플로 하나의 입력, 예상 변경, 검증 항목입니다.
plan_workflow
✓
✓
플랜 파일을 쓰고,
apply_workflow에 넘길 planPath를 돌려줍니다.적용과 복구
apply_workflow
✓
저장된 플랜을 실행하고, 다음에 검증할 대상을 알려 줍니다.
run_validation
✓
플랜이나 적용 리포트에 대한 검증 명령을 실행합니다.
repair_generated
✓
akan repair generated처럼 생성 파일을 새로 만듭니다.repair_imports
✓
akan repair imports처럼 import를 정리합니다.repair_module_shape
✓
akan repair module-shape처럼 모듈에 빠진 것을 보고합니다.✓이 모드에서 제공제공 안 함
리소스
툴과 별도로, 에이전트가 URI로 여는 읽기 전용 문서도 모든 모드에서 제공합니다.
URI설명
akan://docs/framework
Akan 프레임워크 가이드입니다.
akan://workspace/summary
워크스페이스 요약(JSON)입니다.
akan://workspace/apps
앱 목록(JSON)입니다.
akan://workspace/modules
모든 모듈(JSON)입니다.
akan://guidelines/<name>
가이드라인 하나입니다. 가이드라인마다 항목이 하나씩 있습니다.
akan://workspace/modules/<module>/abstract
모듈 하나의 abstract 본문입니다. URI로 읽을 수는 있지만 목록에는 나오지 않습니다.
관련 페이지