align

name	align
description	구현 전에 의도 정렬을 절차로 강제한다. 코드베이스를 먼저 탐색하고 모든 모호함을 끄집어내 사용자와 합의할 때까지 반복한 뒤, 정렬된 의도를 handoff 문서(의도 + 확정 범위 + 검증 가능한 완료 조건)로 남긴다. 산출물은 코드가 아니다. 다단계 구현 전, 요청이 모호할 때, 또는 사용자가 "align", "정렬", "의도 맞춰", "문맥 파악해", "명확히 해줘"라고 할 때 사용한다. 스스로 트리거로 쓸 수도 있다 — 요청이 모호해 보이면 찍어서 물어보지 말고 align에 들어간다.

align ⟷

원칙: 모호함은 정확한 실행의 적이다. 짐작한 의도로 코드를 내보내는 에이전트는 "자신감 있게 틀린" 결과물을 생산한다. align의 일은 모호함을 제로로 끌어내리는 것 — 먼저 탐색, 그 다음 정조준된 질문 — 이고, 정렬된 의도를 대화보다 오래 살아남는 문서로 포착하는 것이다.

0. 번들 파일

• ~/.agents/skills/align/packs/handoff-template.md — 끝에 채우는 handoff 템플릿.

1. 먼저 탐색하고, 그 다음에 물어라 (필수, 건너뛰지 말 것)

코드베이스가 대답할 수 있는 질문을 사용자에게 하지 마라. "로그인 코드가 어디 있죠?"는 사용자가 아니라 Grep에 할 질문이다. 어떤 명확화 질문을 하기 전에, 이미 관련 영역을 탐색해 스스로 알 수 있는 만큼은 알아둬야 한다. 질문은 탐색으로도 메울 수 없는 빈칸 — 의도, 우선순위, 말하지 않은 제약, 취향 — 을 위해서만 쓴다.

1-A. 탐색 절차

사용자 요청에서 출발해 fan-out으로 읽되, 둘 중 하나가 될 때까지:

1. 맥락이 충분하다 — (a) 이 작업이 닿는 영역(실제 경로 포함), (b) 그 영역의 구조·규칙, (c) 완료가 관측 가능한 형태로 어떻게 보이는지를 내 말로 설명할 수 있다. 그러면 탐색을 멈추고 §2로.
2. 탐색으로는 넘을 수 없는 벽 — 관련 코드는 찾았는데 요청이 여전히 모호하다. 그러면 탐색을 멈추고 발견한 모호함과 함께 §2로.

넓은 훑기에는 탐색 서브에이전트(Agent 툴, subagent_type: "Explore")가 낫다 — 파일이 많거나 이름 규칙을 모를 때. 경로를 이미 알면 직접 읽는다.

Agent tool call (subagent_type: "Explore")
prompt:
  "이 작업의 맥락을 모아라: [요청을 바꿔 쓴 것].
   1) 관련 파일/모듈의 실제 경로와 역할
   2) 그 영역의 구조 — 규칙, 의존성, 진입점
   3) 이 코드베이스에서 비슷한 작업이 이미 어떻게 구현됐는지
   4) '완료'를 정의하는 관측 가능한 것(테스트, CLI, 엔드포인트, 로그)
   파일 내용을 쏟지 말고 결론만 반환하라."

1-B. 탐색이 대답하는 것 (사용자에게 물어볼 필요 없는 것)

• 관련 코드의 위치.
• 현재 구조와 지키는 규칙.
• 비슷한 것이 이미 있는지.
• "완료"가 관측 가능한 형태로 어떻게 보이는지.

1-C. 탐색이 대답 못 하는 것 (이게 질문이 된다)

• 여러 해석 중 어느 것을 사용자가 뜻하는지.
• 우선순위 — 반드시 vs 있으면 좋고 vs 범위 밖.
• 말하지 않은 제약 — 하위 호환, 성능 예산, 스타일 취향.
• 왜 이걸 원하는지 (근본 목표가 방식을 바꿀 수 있다).

2. 모호함 → 제로 루프

§1 뒤에 모호함 목록을 적는다: 요청이 합리적으로 두 갈래 이상이 될 수 있는 모든 지점. 솔직해져라 — 확신이 없으면 그것도 모호함이다. 실행엔 기본값이 괜찮지만 정렬엔 기본값이 괜찮지 않다.

2-A. 질문을 묶어서

하나씩 묻지 마라. 열린 모호함을 모아 한 묶음으로 제시한다. 사용자가 한 번에 여러 개에 답할 수 있어 빠르고, 첫 디테일만 파고 드는 대신 전체 그림을 생각하게 만든다.

모호함이 깔끔한 선택지로 떨어지면 AskUserQuestion 툴을 쓴다. 열린 의도 질문("근본 목표가 뭔가요?")은 산문으로 묻는다.

좋은 묶음 질문:

• 영향력이 가장 큰 모호함(이게 풀리면 다른 것들이 가장 많이 녹는 것)을 먼저.
• 추천값이 있으면 첫 옵션으로 — 사용자가 그냥 확인만 하면 된다.
• 옵션은 상호배타적이고 구체적으로, 추상적이지 않게.

2-B. 풀고, 필요하면 다시 탐색

사용자가 답하면 둘 중 하나:

1. 모호함 제로 도달. 한 문단에 "어쩌면" 없이 작업을 설명할 수 있다. §3으로.
2. 답이 탐색 안 한 새 영역을 연다. 그 영역만 §1로 돌아가고 다시 온다. 스스로 읽을 수 있는 걸 사용자에게 묻지 마라.

이건 루프지 한 패스가 아니다. 진짜 모호한 작업엔 1~3 라운드가 흔하다. 명확한 단일 작업("foo를 bar로 바꿔")은 0라운드 — §1만으로 충분.

2-C. 사용자도 모를 때

사용자가 "잘 모르겠는데, 어떻게 생각해?"라고 할 수 있다. 정당한 답이다. 그러면:

• 탐색에서 읽은 것에 근거해 이유와 함께 추천을 준다.
• 그것을 이의 없으면 진행할 추천으로 명시 — 합의된 결정이 아니라. 그래야 handoff가 사실이 아니라 가정으로 기록된다.

사용자 불확실을 더 많은 질문의 구실로 쓰지 마라. 모호함이 당신에게 옮겨질 뿐 풀리진 않는다. 추천하고 나아가라.

3. Handoff 문서 (실제 산출물)

align의 결과물은 코드가 아니다. 정렬된 의도를 담은 handoff 문서 — 다음 단계(forge의 인수조건 변환, prometheus 분해, 새 구현 세션, 사람 검토)가 공통 출발점에서 시작하게 하는.

~/.agents/skills/align/packs/handoff-template.md를 채운다. 핵심 필드:

• 한 문장 작업 — 정렬된 재진술, 헤징 없이.
• "완료"가 어떻게 보이는지 — 관측·검증 가능 조건(명령 + 예상 결과, 렌더된 상태, 테스트 결과). 모르는 사람도 검사할 수 있을 만큼 구체적으로.
• 범위 안 / 범위 밖 — 명시적으로, 특히 사용자가 안 했는데 하고 싶어질 것들까지.
• 가정 — 확인된 결정이 아니라 추천 기본값(§2-C)으로 진행한 것들. 나중에 다시 볼 수 있게 표시.
• 관련 맥락 — §1에서 찾은 경로, 규칙, 선행사례. 다음 에이전트가 처음부터 다시 탐색하지 않을 정도로.
• 열린 위험 — 의도는 정렬됐지만 현실이 다를 수 있는 지점 (예상과 다를 수 있는 의존성, 성능 가정 등).

완성된 문서를 사용자에게 보여주고 정렬 완료로 처리하기 전 최종 확인을 받는다. 사용자가 수정하면 반영하고 재확인.

4. 다른 스킬과의 관계

align  →  forge   →  prometheus
의도       인수조건     실행 + 검증

• align은 무엇과 왜를 확정한다. 산출물: handoff.
• forge는 handoff의 "완료" 조건을 /goal이 판정 가능한 인수조건(명령 + 예상 결과)으로 변환한다.
• prometheus는 인수조건을 받아 /goal 문장으로 옮기고 끝까지 실행·검증한다.

다단계 작업의 의도된 흐름: align을 먼저 돌려 handoff를 만들고, forge로 인수조건을 벼린 뒤, prometheus에 넘긴다. 명확한 단일 작업은 align을 건너뛰고 곧장 forge/prometheus로 갈 수 있다.

5. 역량 한계 (에스컬레이션)

align은 두 가지 이유로 실패할 수 있고, 대응이 다르다:

1. 모호함이 환원 불가능하다 — 사용자가 진짜로 뭘 원하는지 아직 모른다. 정렬 실패가 아니라 발견/설계 역량의 한계다. 그러면: (a) thinking-effort를 Max로 올리길 권한다 (Z.ai는 코딩/설계 작업에 Max를 권장), 더 깊은 추론이 방향을 드러낼 수 있다; (b) 그래도 막히면, 모호함 목록을 증거 패키지로 삼아 새 세션에서 더 강한 모델에 넘긴다; (c) 그 외엔, 의도가 아직 결정 가능하지 않음을 솔직히 알리고 생각이 정리되면 돌아오라고 한다.

2. 충분히 탐색했는데 계속 새 모호함이 나온다 — 보통 작업이 보기보다 큰 신호다. 전체를 한 번에 정렬하려 멈추고, 첫 하위 작업을 잘라내 그것만 제로로 정렬하고 넘긴다. 나머지는 그게 끝난 뒤 다시 온다. 여러 주짜리 프로젝트를 한 자리에서 정렬하려 하지 마라.

두 경우 모두, 추측으로 가득 찬 handoff를 조용히 만들지 말고 상황을 사용자에게 드러내라. 미해결 모호함 위에 세운 handoff는 handoff가 없는 것보다 나쁘다 — 그냥 모호함을 자신감 있어 보이는 문서로 세탁했을 뿐이다.