사람함께에이전트▾

사람 — 직접 정하고 책임지는 비즈니스 규칙과 흐름. 직접 읽어보세요.

함께 — 개념은 알아두고, 세부 규칙은 에이전트가 따릅니다.

에이전트 — 에이전트가 따르는 규칙과 레퍼런스. 필요할 때 찾아보세요.

CLI 레퍼런스▾

명령어 Workspace Application Library Module Scalar Package Page Primitive Workflow Quality Context Agent Guideline

AkanJS 레퍼런스▾

akanjs/base akanjs/common akanjs/constant akanjs/fetch akanjs/signal akanjs/server akanjs/client akanjs/webkit

UI 레퍼런스▾

Overview Core Display Forms Overlays System Agent 커스터마이즈

이전Page 다음Workflow

사람함께에이전트▾

사람 — 직접 정하고 책임지는 비즈니스 규칙과 흐름. 직접 읽어보세요.

함께 — 개념은 알아두고, 세부 규칙은 에이전트가 따릅니다.

에이전트 — 에이전트가 따르는 규칙과 레퍼런스. 필요할 때 찾아보세요.

CLI 레퍼런스▾

명령어 Workspace Application Library Module Scalar Package Page Primitive Workflow Quality Context Agent Guideline

AkanJS 레퍼런스▾

akanjs/base akanjs/common akanjs/constant akanjs/fetch akanjs/signal akanjs/server akanjs/client akanjs/webkit

UI 레퍼런스▾

Overview Core Display Forms Overlays System Agent 커스터마이즈

Primitive 명령

이미 있는 모듈에 필드 하나나 UI 파일 하나를 더하는 명령 세 가지입니다. 딕셔너리 라벨 누락, 빠뜨린 import, 엉뚱한 파일에 놓인 컴포넌트처럼 손으로 하다 틀리기 쉬운 기계적인 부분을 대신 씁니다.

create-ui, add-field, add-enum-field 워크플로가 적용하는 바로 그 단계입니다. 무엇을 바꿀지 이미 알고 있다면 직접 실행합니다.

이 페이지에서 쓰는 말

용어설명

primitive

이미 정한 수정 하나를 플랜 없이 바로 소스에 쓰는 명령입니다.

surface

모듈 UI 파일 하나의 역할로, --surface에서 view, unit, template 중 하나를 고릅니다.

리포트

명령이 끝나면 출력하는 결과로, 바뀐 파일과 진단, 다음에 실행할 명령이 담깁니다.

워크플로

같은 수정에 먼저 읽는 플랜과 뒤따르는 검증을 더한 절차로, 페이지 끝에서 비교합니다.

명령별로 쓰는 파일

명령

constant

.constant.ts

dictionary

.dictionary.ts

.tsx

UI 파일 만들기

create-ui

✓

View, Unit, Template 파일 하나만 쓰고 다른 파일은 건드리지 않습니다.

필드 더하기

add-field

✓

Input 클래스에 필드를, 딕셔너리에 그 라벨을 더합니다.

add-enum-field

✓

enum 클래스를 먼저 선언하고, 그 클래스를 타입으로 하는 필드를 더합니다.

✓씀건드리지 않음

세 명령의 공통 규칙

빠진 옵션을 되묻지 않습니다. --app이나 --module을 빼면 프롬프트 대신 리포트에 오류가 나옵니다.
오류가 있으면 아무것도 쓰지 않습니다. 앱을 찾지 못하거나 입력이 빠졌거나 값이 틀리면 파일은 그대로이고, 리포트가 원인을 알려 줍니다.
sync와 lint는 직접 실행합니다. 명령은 소스만 씁니다. 다음에 할 일로 akan sync <app>와 akan lint <app>가 리포트에 적혀 있습니다.
--format json은 스크립트와 에이전트용입니다. 같은 리포트를 JSON 객체 하나로 출력합니다.

create-ui

기존 모듈의 lib/<module>/에 UI 파일 하나를 씁니다. View, Unit, Template 중 하나입니다. akan create-module이 모듈을 만들 때 쓰는 것과 같은 템플릿을 쓰고, 다른 파일은 건드리지 않습니다. akan create-view, create-unit, create-template을 옵션으로 고르는 형태입니다.

형식

옵션

--appString필수-a

대상 앱이나 라이브러리 이름입니다.

--moduleString필수-m

icecreamOrder 같은 대상 모듈 이름입니다.

--surfaceString기본값 templateview | unit | template · -u

만들 파일이며, Zone과 Util은 이 명령으로 만들지 않습니다.

--formatString기본값 markdownmarkdown | json · -o

markdown은 사람이 읽는 형식이고, json은 같은 리포트를 객체 하나로 출력합니다.

참고

이름설명

view

General을 내보내는 <Module>.View.tsx로, 상세 화면을 그리는 서버 컴포넌트입니다.

unit

Card를 내보내는 <Module>.Unit.tsx로, 목록이나 카드 한 칸을 그리는 서버 컴포넌트입니다.

template

폼 General을 내보내는 <Module>.Template.tsx로, 첫 줄이 "use client"입니다.

name 필드

스캐폴드는 모듈의 name 필드만 그리므로, 필요한 필드로 바꿔 씁니다.

기존 파일

같은 경로에 파일이 있으면 스캐폴드로 덮어쓰므로, 실행 전에 커밋해 둡니다.

그다음

akan sync <app>, akan lint <app>를 차례로 실행합니다.

예시

add-field

모듈의 constant와 dictionary에 필드 하나를 더합니다. 필드는 <module>.constant.ts의 <Module>Input에, 라벨과 설명은 <module>.dictionary.ts의 .model<Module>에 들어갑니다. 타입이 Int나 Float이면 akanjs/base import도 더합니다.

형식

옵션

--appString필수-a

대상 앱이나 라이브러리 이름입니다.

--moduleString필수-m

대상 모듈로, constant와 dictionary 파일이 둘 다 이미 있어야 합니다.

--fieldString필수-f

필드 이름이며, Input 클래스에 이미 있는 이름이면 거절합니다.

--typeString필수-t

필드 타입이나 스칼라 이름으로, int 같은 소문자 별칭은 아래 참고 표대로 바로잡습니다.

--defaultString-d

선택 사항인 기본값으로 타입에 맞게 변환되며, 타입에 맞지 않는 값이면 아무것도 쓰지 않습니다.

--formatString기본값 markdownmarkdown | json · -o

markdown은 사람이 읽는 형식이고, json은 같은 리포트를 객체 하나로 출력합니다.

참고

이름설명

숫자 별칭

int, integer는 Int로, float, double, decimal은 Float로 바뀝니다.

그 밖의 별칭

string, boolean, date는 첫 글자를 대문자로 바꾸고, 나머지 이름은 그대로 씁니다.

Int · Float

number와 numeric은 거절하므로, 정수는 Int, 소수는 Float를 씁니다.

그 밖의 import

import를 더해 주는 것은 Int와 Float뿐이라, ID나 스칼라 타입은 직접 import합니다.

파일 필드

Upload는 파일 업로드 요청 본문에만 쓰는 타입이라 거절하므로, File 모델과의 관계로 선언합니다.

--default

Int/Float는 숫자, Boolean은 true/false, Date는 now나 날짜를 받고, 나머지는 문자열입니다.

--default now

() => dayjs()를 쓰므로 레코드마다 자기 시각을 받습니다. 날짜를 주어도 함수 형태로 씁니다.

라벨

한국어 라벨은 status 같은 흔한 단어만 채워지고, 나머지는 영어를 그대로 쓰니 직접 고칩니다.

컴포넌트

컴포넌트는 고치지 않으므로, Template 폼에는 필드를 직접 더합니다.

그다음

akan sync <app>, akan lint <app>를 차례로 실행합니다.

예시

add-enum-field

정해진 값 중 하나만 받는 필드를 더합니다. 먼저 enum을 선언합니다. constant에 <Module><Field> 이름의 enumOf 클래스를 만들고 enumOf import를 더한 뒤, dictionary의 .enum 단계에 선택지를 등록합니다. 그다음 그 클래스를 타입으로 하는 필드를 add-field와 똑같이 더합니다.

형식

옵션

--appString필수-a

대상 앱이나 라이브러리 이름입니다.

--moduleString필수-m

대상 모듈로, constant와 dictionary 파일이 둘 다 이미 있어야 합니다.

--fieldString필수-f

필드 이름이자 enum 이름으로, order 모듈의 status 필드는 OrderStatus를 선언합니다.

--valuesString필수-l

pending,serving,served처럼 쉼표로 구분한 enum 값입니다.

--defaultString-d

선택 사항인 기본값으로, --values 중 하나여야 합니다.

--formatString기본값 markdownmarkdown | json · -o

markdown은 사람이 읽는 형식이고, json은 같은 리포트를 객체 하나로 출력합니다.

참고

이름설명

--type 없음

타입은 항상 새로 만드는 enum 클래스라서, 이 명령은 --type 대신 --values를 받습니다.

add-field --type enum

오류로 끝나고 아무것도 쓰지 않으므로, 새 enum은 항상 add-enum-field로 만듭니다.

이미 있는 enum

enum 클래스가 이미 있으면 대신 add-field --type <Class>를 실행합니다.

선택지 라벨

값마다 영어 Title Case 라벨이 두 언어 모두에 들어가므로, 한국어 라벨은 직접 번역합니다.

그다음

akan sync <app>, akan lint <app>를 차례로 실행합니다.

예시

Primitive와 워크플로 중 무엇을 쓸까

primitive는 이미 정한 수정 하나입니다. 워크플로는 같은 수정에 먼저 읽는 플랜, 함께 고칠 수 있는 UI, 뒤이은 검증 단계를 더한 것입니다.

얻는 것

primitive

akan add-field

workflow

akan workflow plan

둘 다

소스 수정

✓

워크플로도 안에서 이 명령을 부르므로, 같은 코드가 같은 필드나 UI 파일을 씁니다.

워크플로에만 있는 것

검토할 플랜

✓

무엇이 바뀔지 먼저 읽고, 그다음 akan workflow apply로 씁니다.

surfaces: ["template"]

✓

단순한 Template 폼에 필드를 넣으며, MCP plan_workflow로만 넘깁니다.

includeInLight: true

✓

Light 모델에도 필드를 더하며, 이것도 MCP로만 넘깁니다.

akan workflow validate

✓

sync와 lint를, 필드를 바꿨다면 typecheck까지 한 번에 실행하고 실패를 원인별로 나눕니다.

✓포함없음

언제 무엇을 쓰나

Primitive

akan add-field --field topping …

모듈 안에서 작업하다가 필드를 더할 때 씁니다. 파일 둘, 명령 하나, 플랜 없음이고 sync와 lint는 직접 실행합니다.

워크플로

akan workflow plan add-field … --out <path>

쓰기 전에 변경을 검토하고 싶을 때 씁니다. 에이전트에게는 이 방식을 쓰라고 안내합니다.