shape

Shape

요구사항을 도메인(concept)과 흐름(flow) 수준의 설계로 구체화한다. 분해(도메인의 경계)와 조합(도메인 간 흐름)을 함께 산출한다.

shape의 How는 방향성 수준이다 — 접근 전략, 제약, 트레이드오프. 구체적 기술 선택, 파일 구조, 함수 시그니처는 shape의 범위가 아니다.

Step 0 — Triage

입력의 추상화 수준을 판단한다.

shape는 기능/시스템 단위뿐 아니라 plan 태스크 단위에서도 호출될 수 있다. 태스크의 해상도가 실행에 부족할 때, 에이전트나 사용자가 해당 태스크를 shape에 입력한다.

1. 작업 대상 프로젝트의 .loom/index.md를 읽어 도메인 전체 지도를 파악한다.
2. aeira search -s {프로젝트의 .loom 경로} "{입력 키워드}" 로 관련 문서를 식별한다.
3. 식별된 문서에서 aeira graph neighbors -s {프로젝트의 .loom 경로} "{node}" 로 연결 문서를 탐색한다 (outgoing: 연관 concept과 flow, incoming: 참조 decision).
4. 탐색된 concept, flow, decision을 읽는다.
5. 입력을 다음 기준으로 분류한다:

수준	신호	행동
이미 구체적	태스크 단위가 명확하고, 영향 범위가 한정적이며, 어떤 concept을 변경하는지 특정 가능	plan으로 라우팅 — "이 입력은 shape 없이 plan으로 진행할 수 있습니다. plan을 시작할까요?"
방향은 있으나 모호	무엇을 원하는지는 알지만, 경계나 접근법이 불명확	shape 프로세스 진행
비전 수준	한 줄의 아이디어, 넓은 목표	shape 프로세스 진행 (분해부터 시작)

plan 태스크에서 진입한 경우, "이미 구체적"은 실행으로 라우팅한다 (plan은 이미 존재하므로).

triage 결과를 사용자에게 알리고 동의를 구한다.

Step 1 — 룰 카탈로그 로드

.loom/rules/index.md를 읽어 어떤 룰과 컨벤션이 있는지 카탈로그를 인지한다.

rule은 이 프로젝트에서 항상 지켜져야 하는 강제적 합의, convention은 강하게 권장되지만 대체 가능한 형태이다. 인덱스를 통해 항목 목록과 각 항목의 호출 상황을 파악한다. 본문은 활용 시점에 필요한 항목을 골라낸 뒤 로드한다.

Step 2 — 요구사항 구체화

입력의 요구사항을 대화로 구체화한다.

• 달성하고자 하는 것은 무엇인가?
• 어떤 상호작용이 일어나는가? 누가 언제 무엇을 하는가?
• 어떤 제약이 있는가? 반드시 지켜야 할 조건은?

이 단계의 초점은 요구사항 자체의 구체화이다. concept이 자연스럽게 언급될 수 있으나, 구체적 파일 구조, 함수 시그니처, 라이브러리 선택 같은 구현 수준 질문은 삼간다. 요구사항이 충분히 구체화되면 Step 3으로 넘어간다.

plan 태스크 단위로 shape가 호출된 경우(decision 0013), 태스크의 문맥(어떤 concept에서 파생되었는지, 의존관계)이 요구사항의 맥락이 된다. 이 경우 Step 2는 태스크 해상도 부족의 원인을 식별하는 역할을 한다.

Step 3 — 흐름과 경계 수립

구체화된 요구사항에서 흐름을 도출하고, 그 흐름이 가로지르는 도메인의 경계를 함께 식별하는 과정을 반복한다. 흐름(조합)과 경계(분해)는 서로를 교정하며 함께 빚어진다.

흐름과 경계의 반복 사이클

1. 흐름 도출: 요구사항에서 "무슨 일이 어떤 순서로 일어나는가"를 트리거에서 결과까지 도메인 간 사건의 연쇄로 도출한다.

2. 경계 식별: 각 단계가 어느 도메인의 책임인지 짚으면 도메인 경계가 식별된다. 한 단계가 두 도메인에 어색하게 걸치면 경계가 잘못 그어진 신호다.

3. 괴리 조정:

   • 흐름의 어떤 단계를 맡을 도메인이 없으면 -> 빠진 concept이 있다는 신호다.
   • 한 단계가 두 도메인에 걸치거나 한 도메인이 여러 단계를 떠안으면 -> 경계를 다시 그어야 한다는 신호다.

   흐름을 도출하는 일과 경계를 식별하는 일은 서로의 빈틈을 드러낸다. 한쪽을 고치면 다른 쪽으로 돌아가 다시 맞추며, 충분해질 때까지 1과 2를 오간다.

4. 반복 종료: 사용자가 구현 수준 이야기(파일 구조, API 시그니처, 구체적 라이브러리 등)를 시작하면 반복이 충분한 신호이다. Step 4로 넘어간다.

흐름을 도출하는 일은 경계를 비추는 렌즈다 — 흐름을 그려봄으로써 한 단계가 두 도메인에 걸치거나 맡을 도메인 없는 빈 단계가 드러나면, 경계가 잘못 그어진 것이다. 그러나 흐름을 그렸다고 모두 flow 문서가 되지는 않는다. 두 관문으로 판별한다 — 단계 사이를 흐르는 것이 상태를 전이시키는 사건인가(사건성), 경로가 도메인 경계를 가로지르는가(경계 횡단성). 여러 입력을 받아 한 결과로 닫히는 계산과 한 도메인 내부의 동작은 concept의 몫이다. 조정에 이름을 붙일 수 있는지는 판별 근거가 아니다 — 자기 상태나 규칙(보상, 재시도, 진행 추적)을 지닌 조정만 조정자 concept이 되어 flow의 한 노드로 등장하고, 순서의 배열뿐인 조정은 flow 그 자체다. 단계는 도메인 경계를 넘는 수준에 머물고, 한 도메인 내부의 구현으로 내려가지 않는다.

감지 관점 (반복 전 과정에 상시)

흐름과 경계 판단을 하면서 다음 극단에 대한 감지를 유지한다:

• 분화 부족: 분화해야 하는데 기존 concept에 덧붙이거나(비대화), 예외나 단서로 감싸거나(의미 흐려짐), 삭제해야 하는데 방치(데드 concept)
• 과잉 분화: 분화가 불필요한데 쪼갬. 이 분화가 지금 실제로 필요한 쓰임을 가지는지 묻는다 — 옵션 가치가 충분하지 않으면 미루는 편이 낫다

전제·제약 재평가

흐름과 경계 판단을 하면서 기존 concept이나 flow나 decision의 전제 또는 제약에 무효화 정황이 드러났는지 수시로 감지한다.

• 무효화가 드러나면 사용자에게 재설계 또는 유지 판단을 요청한다
• 유지 판단은 사용자의 영역이다 — 에이전트는 감지하고 근거를 수집한다
• 유지 선택 시 Step 4에서 "유지 decision"을 생산한다
• 재설계 선택 시 이 Step 안에서 방향을 다시 수립한다

룰 카탈로그 활용

흐름과 경계 판단 시, 인지한 룰 카탈로그를 도구 선택 절차로 활용한다:

1. 지금 수행하려는 행동을 의식적으로 명시한다
2. 카탈로그에서 그 행동에 적용될 가능성 있는 항목을 골라낸다
3. 골라낸 항목의 본문 파일을 로드해 적용 방식을 파악한다
4. 본문에 따라 설계를 진행한다

적용된 rule을 만족하지 못하는 설계 방향이 발견되면 사용자에게 보고한다.

결정 기록

대화 중 결정이 발생하면 즉시 .loom/decisions/에 기록한다. 결정의 신호: 대안이 제시되었고, 사용자가 하나를 선택했으며, 그 선택에 근거가 있을 때. 발견 즉시 기록하여 맥락 유실을 방지한다.

Step 4 — 산출물 작성

Concept 생성/수정

새로운 도메인이 식별되면 .loom/concepts/에 파일을 생성한다. 기존 concept이 변경되면 해당 파일을 수정한다.

concept에는 목적·책임·정책·경계를 기술한다 — 도메인이 무엇을 위해 존재하고(목적), 무엇을 달성하며(책임), 어떤 규칙을 지키고(정책), 무엇을 하지 않는지(경계). 도메인 간 흐름과 시점 종속 항목은 다음으로 라우팅한다:

• 도메인 간 협력의 경로 (사건이 도메인 경계를 가로지르는 흐름) -> flow에 기록
• concept의 형태에 영향을 준 보류 -> decision에 기록 (보류 결정)
• 나중에 해야 할 작업 -> plan의 태스크로 이동

템플릿: ../../templates/concept.md를 읽어 사용한다.

Flow 생성/수정

사건이 도메인 경계를 가로지르는 협력의 경로가 실재할 때 .loom/flows/에 flow 파일을 생성한다. 여러 입력을 받아 한 결과로 닫히는 계산이거나 한 도메인 내부의 동작이면 concept의 몫이므로 flow를 만들지 않는다. 조정의 명명 가능성은 판별 근거가 아니다 — 조정이 자기 상태나 규칙을 지닐 때만 조정자 concept이 되고, 그 경우에도 경로는 flow에 남는다. 기존 흐름이 변경되면 해당 파일을 수정한다.

flow에는 목적과 단계를 기술한다. 단계 사이를 흐르는 것은 상태를 전이시키는 사건이며, 데이터가 변환되어 넘어갈 뿐인 계산의 연쇄는 담지 않는다. 각 단계는 도메인 경계를 넘는 수준이며, 한 도메인 내부의 구현은 담지 않는다. 변이는 별도 항목이 아니라 하위 흐름으로 표현한다.

템플릿: ../../templates/flow.md를 읽어 사용한다.

Decision 기록

설계 과정에서 concept이나 flow나 구현의 형태에 영향을 준 결정을 .loom/decisions/에 기록한다.

기록할 것:

• concept이나 flow의 구조적 방향을 결정하는 선택 (아키텍처, 접근 전략, 기술 선택)
• 구현(스킬 등)의 동작 범위를 결정하는 선택
• 대안이 존재했고, 선택이 concept이나 flow나 구현의 형태에 영향을 준 것
• concept이나 flow의 범위를 한정하는 보류 결정 (예: "비동기 모델을 지금 결정하지 않는다")
• 유지 decision — 전제 또는 제약에 무효화 정황이 드러났는데도 기존 concept이나 결정을 유지한 경우. 무효화된 전제·제약, 유지 근거, 유지 결정의 유효 기한을 기록한다. 변화 정황이 없으면 기록하지 않는다

기록하지 않을 것:

• 버그 픽스 — 의도된 동작으로의 복원이므로 설계 결정이 아니다
• plan의 스코프 조정 (예: "이 작업을 후속으로 미룬다")
• 작업 순서나 우선순위
• 자명한 선택 (예: 네이밍)

decision 간 참조 규칙:

• 대체·폐기 참조는 두지 않는다 — 각 decision은 자기완결적이다
• 갱신·계승 참조는 허용한다 (유지 decision이 기존 decision의 전제·제약 변화를 기록하는 경우 등). 참조된 decision을 읽지 않아도 현재 decision의 맥락을 이해할 수 있어야 한다

템플릿: ../../templates/decision.md를 읽어 사용한다.

Index 갱신

concept이나 flow를 생성/수정한 경우, .loom/index.md의 갱신이 필요한지 판단한다. 갱신이 필요한 경우: 새 도메인이나 흐름 추가, 항목 간 관계 변경, 기존 항목의 책임 변경. index는 프로젝트 탐색의 지도 역할을 하므로, 항목 목록과 관계도를 최신 상태로 유지한다.

파일 이름 규칙

• concept: {도메인-이름}.md (예: user-authentication.md)
• flow: {흐름-이름}.md (예: checkout-flow.md)
• decision: {NNNN}-{결정-제목}.md (예: 0001-session-based-auth.md)

decision은 순번을 부여하여 시간순을 보존한다.

그래프 갱신

.loom/ 내 문서를 생성하거나 수정한 후 aeira sync -s {프로젝트의 .loom 경로} 를 실행한다.

Summary

shape 완료 시 다음 형식으로 정리한다:

## Shape Summary
- 입력: [원래 요구사항 한 줄 요약]
- Concepts: [생성/수정된 concept 파일 목록]
- Flows: [생성/수정된 flow 파일 목록]
- Decisions: [기록된 decision 파일 목록]
- 다음 단계: [plan 진행 여부와 범위]

완료 후 라우팅

shape 완료 시 다음 단계를 판단한다.

산출물 상태	신호	행동
태스크 분해가 필요	영향 범위가 넓고, 구현 순서에 의존관계가 있으며, 복수의 독립적 작업 단위가 존재	plan으로 진행
즉시 실행 가능	shape의 산출물이 단일 작업 또는 기계적 변환이며, 분해할 태스크가 없음	직접 실행 — "이 설계는 plan 없이 실행 가능합니다. 진행할까요?"
추가 설계 필요	shape 과정에서 새로운 모호함이 발견됨	shape 재진입

라우팅 결과를 사용자에게 알리고 동의를 구한다.