Akan.js
Docs
문서컨벤션레퍼런스Cheatsheet
Akan.js
문서컨벤션레퍼런스Cheatsheet
Akan.js

MIT 라이선스 하에 배포되었습니다.

Akan.js 공식 컨설팅 서비스AkansoftCopyright © 2026 Akan.js 모든 권리 보유.시스템 관리자bassman
사람함께에이전트▾
사람 — 직접 정하고 책임지는 비즈니스 규칙과 흐름. 직접 읽어보세요.
함께 — 개념은 알아두고, 세부 규칙은 에이전트가 따릅니다.
에이전트 — 에이전트가 따르는 규칙과 레퍼런스. 필요할 때 찾아보세요.
CLI 레퍼런스▾
명령어WorkspaceApplicationLibraryModuleScalarPackagePagePrimitiveWorkflowQualityContextAgentGuideline
AkanJS 레퍼런스▾
akanjs/baseakanjs/commonakanjs/constantakanjs/fetchakanjs/signalakanjs/serverakanjs/clientakanjs/webkit
UI 레퍼런스▾
OverviewCoreDisplayFormsOverlaysSystemAgent커스터마이즈
사람함께에이전트▾
사람 — 직접 정하고 책임지는 비즈니스 규칙과 흐름. 직접 읽어보세요.
함께 — 개념은 알아두고, 세부 규칙은 에이전트가 따릅니다.
에이전트 — 에이전트가 따르는 규칙과 레퍼런스. 필요할 때 찾아보세요.
CLI 레퍼런스▾
명령어WorkspaceApplicationLibraryModuleScalarPackagePagePrimitiveWorkflowQualityContextAgentGuideline
AkanJS 레퍼런스▾
akanjs/baseakanjs/commonakanjs/constantakanjs/fetchakanjs/signalakanjs/serverakanjs/clientakanjs/webkit
UI 레퍼런스▾
OverviewCoreDisplayFormsOverlaysSystemAgent커스터마이즈
이전Primitive다음Quality

워크플로 CLI

모듈에 필드 하나를 더하는 일도 파일 다섯 개를 건드리고, 그 대부분은 기계적인 작업입니다. 손으로 하면 이름, 타입, 기본값처럼 정작 중요한 결정이 딕셔너리 라벨과 자동 생성 파일 사이에 묻히고, 모듈마다 모양이 조금씩 달라집니다.
워크플로는 이런 변경에 이름을 붙인 것입니다. 계획하고, 계획을 읽고, 적용하고, 결과를 검증합니다. 검증이 실패하면 akan repair가 그 실패를 해소하는 명령 하나를 실행합니다.
이 페이지에서 쓰는 말
용어설명
워크플로
필드 추가나 모듈 생성처럼 늘 같은 파일을 같은 순서로 고치는 변경에 붙인 이름입니다.
플랜 파일
plan --out이 쓰는 JSON으로, 단계와 바뀔 것으로 예상되는 파일, 돌릴 검증이 담깁니다.
실행 기록
적용, 검증, 복구가 끝날 때마다 .akan/workflows/runs/<runId>.json에 남기는 기록입니다.
runId
apply-20260921103000-a1b2c3처럼 생긴 실행 기록의 파일 이름입니다.
akan repair
<kind>로 골라 쓰는, 알려진 실패 하나를 위한 좁은 처방입니다.
직접 고치기 전에 워크플로부터 찾으세요. 워크플로나 복구로 할 수 있는 변경이라면 소스를 손으로 고치지 않습니다.

계획, 적용, 검증

네 단계는 한 줄로 이어지고, 각 단계는 다음 단계에 이름이 아니라 파일 경로를 넘깁니다. 그래서 플랜은 아무것도 쓰기 전에 검토하는 문서가 되고, 실행 기록은 무슨 일이 있었는지 보여 주는 기록이 됩니다.
워크플로 흐름
플랜 JSONrunId실패 시
계획workflow plan --out
적용workflow apply
검증workflow validate
복구akan repair
계획workflow plan --out
플랜 JSON
적용workflow apply
runId
검증workflow validate
실패 시
복구akan repair
1. 계획
akan workflow plan <workflow> … --out <path>
입력값을 확인하고 플랜 JSON을 씁니다. 단계, 바뀔 파일 예상, 이후 돌릴 검증이 담기며 소스는 읽지도 쓰지도 않습니다.
2. 적용
akan workflow apply <planPath>
워크플로 이름이 아니라 플랜 파일을 받아 소스를 고칩니다. 입력이 빠진 것처럼 오류가 있는 플랜은 아무것도 적용하지 않습니다.
3. 검증
akan workflow validate <runId | path>
플랜이 요구한 검증(sync, lint, typecheck, build)을 돌리고, 실패를 원인별로 분류합니다.
4. 복구
akan repair <kind>
그 원인에 맞는 처방입니다. generated는 다시 sync하고, format과 imports는 다시 lint하며, 보고만 하는 두 종류는 모듈을 고칠 명령을 알려 줍니다.
검증 실패의 분류
원인설명
source-change
sync, lint, typecheck가 소스 문제로 실패한 경우로, 소스를 고치거나 복구를 실행합니다.
workspace-config
Biome 설정 같은 워크스페이스 설정을 불러오지 못한 경우입니다.
environment
command not found(종료 코드 127)처럼 명령 자체를 실행하지 못한 경우입니다.
unknown
build 실패를 포함한 그 밖의 실패로, 리포트의 명령 출력을 읽어 봅니다.
  • 이미 본 실패는 표시됩니다. 이전 실행에서도 났던 설정·환경 실패는 알려진 기준선 문제(baseline blocker)로 표시되어, 이번 변경과 무관하다는 것을 알려 줍니다.
  • doctor 결과도 함께 옵니다. 리포트에는 akan doctor --strict 결과가 붙는데, 이번 변경이 건드린 것과 원래 있던 것으로 나뉩니다. CLI에서는 원래 있던 것을 코드별 개수로만 보여 줍니다.
MCP에서 부르기
akan mcp는 같은 단계를 툴로 제공합니다. plan 모드는 읽고 계획만 하고, apply 모드는 쓰기까지 합니다.
명령MCP 툴 · 모드
akan workflow list
list_workflows · plan, apply 모드
akan workflow explain
explain_workflow · plan, apply 모드
akan workflow plan
plan_workflow · plan, apply 모드
akan workflow apply
apply_workflow · apply 모드
akan workflow validate
run_validation · apply 모드
akan repair generated
repair_generated · apply 모드
akan repair imports
  • plan_workflow는 플랜을 항상 파일로 남깁니다. out이 없으면 워크플로 이름과 입력값으로 지은 이름(예: add-field-koyo-icecreamorder-topping.json)으로 .akan/workflows/plans/에 씁니다. 그 경로를 apply_workflow에 넘길 planPath로 돌려줍니다.

워크플로 목록

CLI에는 워크플로 일곱 개가 들어 있습니다. akan workflow list는 각각을 언제 쓰는지 보여 주고, akan workflow explain <name>은 입력, 단계, 검증 명령까지 보여 줍니다.
--format json을 주면 예상 변경과 완료 기준까지 함께 나옵니다.
워크플로설명
create-module
constant부터 store, UI까지 갖춘, DB에 저장되는 새 도메인 모듈입니다. 필수 입력: --app --module
create-scalar
값 객체나 공용 스칼라처럼 DB를 소유하지 않는 재사용 값 모듈입니다. 필수 입력: --app --scalar
create-ui
기존 모듈에 관례에 맞는 UI 파일 하나를 더합니다. 필수 입력: --app --module --surface
add-field
constant와 dictionary에 필드를 더하고, Template 폼은 검토할 곳으로 표시합니다. 필수 입력: --app --module --field --type
add-enum-field
정해진 값만 받는 필드로, enum 클래스와 라벨·옵션, 필드 자체를 더합니다. 필수 입력: --app --module --field --values
add-mutation
service 메서드와 None 가드를 단 뮤테이션을 더하고, store 액션과 UI 컨트롤은 권장만 합니다. 필수 입력: --app --module --mutation
add-slice
service 쿼리와 None 가드를 단 init 슬라이스를 더하고, 페이지 로드와 Zone은 권장만 합니다. 필수 입력: --app --module --slice
  • create-ui는 다섯 가지를 계획하고 세 가지만 적용합니다. --surface는 view, unit, template, zone, util을 받지만, 적용은 앞의 셋만 합니다.
  • 숫자는 Int나 Float입니다. --type Number로 만든 플랜에는 오류가 붙고, 오류가 있는 플랜은 아무것도 적용하지 않습니다.
  • 기본값은 타입을 따릅니다. --default는 --type에 맞게 변환되고, enum 기본값은 --values 중 하나여야 합니다.
  • add-field 입력 두 개는 MCP에서만 넘길 수 있습니다. plan_workflow에서 surfaces: ["template"]를 주면 단순한 Template 폼에 필드를 넣고, includeInLight: true를 주면 Light 모델에도 더합니다.
검증이 실행하는 명령
워크플로마다 validate가 --app 대상으로 실행할 명령이 정해져 있습니다.
워크플로
sync
lint
typecheck
build
새로 만들기
create-module
✓
✓
create-scalar
✓
✓

workflow

워크플로를 나열, 설명, 계획, 적용, 검증하거나 지난 실행의 리포트를 다시 봅니다. plan과 explain은 소스를 쓰지 않습니다. 소스를 쓰는 것은 apply뿐이고, 그것도 플랜 파일로만 씁니다.
형식
인자
actionString필수list | explain | plan | apply | validate | report
할 일입니다. 생략하면 프롬프트에서 묻습니다.
workflowString
list를 뺀 모든 action에 필요합니다. action마다 받는 값은 아래 참고 표에 있습니다.
옵션
--format

repair

좁은 범위의 복구 하나를 실행하고 구조화된 리포트를 출력합니다. kind마다 알려진 문제에 대한 정해진 처방이 있습니다. dictionary와 module-shape는 아무것도 고치지 않습니다. akan doctor --strict 결과에서 해당 모듈 항목만 골라, 고칠 명령을 알려 줍니다.
형식
인자
kindString필수generated | format | imports | dictionary | module-shape
실행할 복구 종류입니다. 각각 하는 일은 아래 참고 표에 있습니다.
옵션
--formatString기본값 markdownmarkdown | json · -o
출력 형식입니다. json은 MCP 클라이언트가 받는 형식입니다.

이 페이지

워크플로 CLI
계획, 적용, 검증
워크플로 목록
workflow
repair
관련 페이지
Primitive 명령→
워크플로가 적용할 때 쓰는 명령입니다. 직접 실행할 수도 있습니다.
akan mcp→
워크플로와 복구를 MCP 툴로 에이전트에게 제공합니다.
String
기본값 markdown
markdown | json · -o
markdown은 사람이 읽는 형식이고, json은 MCP 클라이언트가 받는 것과 같은 리포트입니다.
--outString-w
plan 전용입니다. 플랜 JSON을 이 경로에 씁니다. 없으면 화면에 출력만 되어 적용할 수 없습니다.
--dry-runBoolean기본값 false-r
apply 전용입니다. 소스를 쓰지 않고 예상 결과만 보고하며, 실행 기록은 남습니다.
--appString-a
플랜 입력: 대상 앱이나 라이브러리입니다. 모든 워크플로에 필요합니다.
--moduleString-m
플랜 입력: 대상 도메인, 서비스, 스칼라 모듈입니다. create-scalar를 뺀 모든 워크플로에 필요합니다.
--fieldString-f
add-field, add-enum-field의 입력: 필드 이름입니다.
--typeString-t
add-field의 입력: 필드 타입이나 스칼라 이름입니다. Number 대신 Int나 Float를 씁니다.
--valuesString-l
add-enum-field, 또는 --type enum인 add-field의 입력: 쉼표로 구분한 enum 값입니다.
--defaultString-d
플랜 입력: 필드 기본값입니다. 타입에 맞게 변환되고, enum 기본값은 --values 중 하나여야 합니다.
--scalarString-c
create-scalar의 입력: 스칼라 이름입니다.
--surfaceStringview | unit | template | zone | util · -u
create-ui의 입력: 만들 UI 파일입니다. zone과 util은 계획만 되고 적용되지 않습니다.
--mutationString-n
add-mutation의 입력: 뮤테이션(액션) 이름입니다.
--sliceString-i
add-slice의 입력: 슬라이스(쿼리) 이름입니다.
참고
이름설명
explain · plan
workflow 인자에 akan workflow list에 나오는 이름을 넣습니다.
apply
workflow 인자에 이름이 아니라 --out으로 쓴 경로를 넣고, 실행 기록은 .akan/workflows/runs/<runId>.json에 남습니다.
validate
workflow 인자에 플랜 경로, 실행 기록 경로, runId 중 하나를 넣으며, 검증도 실행 기록을 남깁니다.
report
workflow 인자에 runId를 넣으면 적용, dry run, 검증, 복구 어느 것이든 그 리포트를 다시 보여 줍니다.
예시
--appString-a
대상 앱이나 라이브러리입니다. generated, dictionary, module-shape에 필요합니다.
--moduleString-m
대상 모듈입니다. dictionary, module-shape에 필요합니다.
--targetString-t
대상 앱, 라이브러리, 패키지입니다. format, imports에 필요합니다.
참고
이름설명
generated
akan sync <app>을 실행합니다.
format · imports
둘 다 akan lint <target>을 실행하며, kind는 리포트가 무엇에 관한 것인지 표시할 뿐입니다.
dictionary
고치지 않고 보고만 하며, 빠진 딕셔너리 라벨을 찾아 akan add-field를 알려 줍니다.
module-shape
고치지 않고 보고만 하며, 모양이 어긋난 모듈이나 빠진 abstract를 찾아 akan create-module을 알려 줍니다.
그다음
모든 복구는 실행 기록을 남기고, 다음 단계로 akan doctor --strict --format json을 권합니다.
MCP에서
apply 모드가 repair_generated, repair_imports, repair_module_shape를 제공하고, 나머지는 CLI 전용입니다.
예시
repair_imports · apply 모드
akan repair module-shape
repair_module_shape · apply 모드
akan workflow reportakan repair formatakan repair dictionary
CLI 전용
create-ui
✓
✓
모듈에 더하기
add-field
✓
✓
✓
add-enum-field
✓
✓
✓
add-mutation
✓
✓
✓
add-slice
✓
✓
✓
✓validate가 실행실행 안 함