가장 어려운 것은 코드를 작성하는 것이 아니다 ─ 의도를 '구조'로 관리하며 AI와 개발하는 Intent CLI를 OSS로 공개했습니다

AI에게 코드를 작성하게 하는 개발을 지속하면서, 제 업무의 내용이 변해왔습니다. 직접 손을 움직이는 시간보다, "무엇을, 왜 만드는가"를 생각하고 전달하는 시간이 훨씬 길어지고 있습니다.

주식회사 제이텍 재팬(J-Tech Japan) CTO인 타카오카 @tomohisa입니다. 이 기사에서는 저희가 사내에서 사용하기 시작하여 이번에 OSS로 공개한 Intent CLI(프로젝트명 intent-system)라는 개발 지원 도구에 대해, 그 배경에 있는 사고방식을 써보려 합니다. 직접 손을 움직여 사용하는 절차는 이어서 공개할 실전편에 정리해 두었습니다.

AI를 향한 지시를 둘러싼 시행착오

지금까지 저는 AI에게 적절한 지시를 내리기 위해 다양한 방법을 시도해 왔습니다. 어떻게 만들지를 태스크 파일(Task file)에 남기거나, 플랜 모드(Plan mode)를 사용하거나, 설계를 작성하여 여러 에이전트(Agent)에게 체크를 받는 등의 방식입니다.

이러한 노력에 대해서는 이전에 이런 기사에도 썼습니다.

사양 주도 개발(SDD, Specification-Driven Development)도 시도했습니다. 다만, 결과물이 태스크마다 분리되어 전체를 관통하여 관리하기가 어렵다고 느꼈습니다. TAKT도 사용해 보았지만, 컨텍스트(Context) 소비가 크다는 점과 에이전트를 호출하여 구동하는 방식이 제가 사용 중인 Claude Code의 방식과 맞지 않는 부분이 있어, 딱 맞는 형태를 계속 찾아 헤맸습니다.

이러한 노력으로 확실히 좋은 설계는 할 수 있습니다. 그리고 깨달은 점은, 그 과정에서 작성한 문서에는 사실 매우 중요한 정보가 담겨 있다는 것입니다. "이렇게 하고 싶다", "이 기법을 사용해 주길 바란다", "이 인터페이스 방침으로 가고 싶다". 프로덕트의 판단을 좌우하는 의도가 그곳에 많이 적혀 있습니다.

문제는 그 중요한 문서가 항상 읽히는 장소에 정리되어 있지 않다는 것이었습니다. 쓰자마자 묻혀버립니다. 다음에 비슷한 판단을 할 때, 다시 처음부터 다시 써야 합니다. 의도는 있는데 적절한 장소에 놓여 있지 않아서 매번 제대로 전달할 수 없습니다. 이 부분이 가장 큰 과제라고 느꼈습니다.

AI에게 맡기면 확대되는 「의도의 어긋남」

의도가 제대로 전달되지 않는 상태에서 AI에게 맡기면, 어긋남은 더욱 커집니다.

의도의 해상도가 낮으면 아무리 우수한 모델이라도 기대와는 다른 것을 만들어 버립니다. 게다가 곤란하게도 AI 에이전트는 내버려 두면 멈추지 않습니다. 한 시간 동안은 눈앞의 문제를 풀어주지만, 일주일 동안 계속 구동하면 어느샌가 다른 문제를 풀고 있기도 합니다.

비슷한 일은 인간 사이에서도 일어나고 있었습니다. 구현 전에 작성한 사양서는 첫 번째 PR(Pull Request)이 머지(Merge)되는 순간부터 실물과 어긋나기 시작합니다. 2주 정도 지나면 사양서는 이미 존재하지 않는 시스템에 대해 이야기하고 있습니다. AI 에이전트가 빠르고 대량으로 코드를 작성하게 되면서, 이 어긋남이 발생하는 속도도 단번에 빨라졌다는 감각입니다.

최대의 레버리지는 「좋은 Issue」

그렇다면 AI가 구현을 담당하는 시대에 인간의 역할은 어디로 이동할까요? 저는 "의도를 명확히 하는 것"이라고 생각합니다.

그런 의미에서, 좋은 Issue를 작성하는 것이 현재 가장 레버리지(Leverage)가 높은 기술이 되었습니다. 무엇을, 왜 만드는지가 명확히 적힌 Issue가 있다면 구현은 망설임이 없고, 리뷰도 "코드의 취향"이 아니라 "의도와 어긋나지 않는가"로 판단할 수 있습니다.

문제는 그 "좋은 Issue"를 매번 제로 베이스에서 작성하는 것이 힘들다는 점입니다. 아키텍처 방침, 과거에 결정한 약속들, UI 패턴. 사실은 그러한 문맥을 전부 짊어진 Issue를 내고 싶은데, 매번 손으로 다시 쓰고 있다면 버틸 수가 없습니다.

진실의 근원으로서의 의도 (IDD)

그래서 저희는 관리의 중심을 코드에서 의도로 옮기기로 했습니다. 이것이 Intent-Driven Development (의도 주도 개발, IDD)라는 사고방식입니다.

Intent-Driven Development에서는 의도와 사양과 코드를 쌓아 올려서 생각합니다. 의도(왜·무엇을 달성하고 싶은가)를 가장 위에 두고, 그 아래에 사양, 다시 그 아래에 구현이 이어집니다. 코드나 사양은 의도로부터 몇 번이고 다시 이끌어낼 수 있는 "재생 가능한 것"으로 취급합니다. 반대로 의도만큼은 아래에서 자동으로 생성할 수 없습니다. 이 부분만큼은 인간이 키워나가야 합니다.

이렇게 하면 한 가지 장점이 더 있습니다. LLM의 비결정성(동일한 입력에도 출력이 흔들리는 성질)을 하류 레이어(Downstream layer)에만 가둘 수 있습니다. 의도라는 가장 중요한 층은 인간이 쥐고, 흔들려도 괜찮은 부분만 AI에게 맡기는 식의 분리가 가능해집니다.

착안점은 Sekiban의 「추기」

애초에 이 발상은 우리가 개발하고 있는 이벤트 소싱 (Event Sourcing) 솔루션 프레임워크인 Sekiban (sekiban.dev)에서 시작되었습니다.

이벤트 소싱에서는 중요한 데이터를 덮어쓰지 않고, 발생한 일을 추기 (Append) 방식으로 계속해서 써 내려갑니다. 저는 이 개념이 매우 마음에 듭니다. 과거를 파괴하지 않고, 변화를 사실로서 차곡차곡 쌓아 올릴 수 있기 때문입니다.

이 '추기로 키워나가는' 방식을 프로그래밍 에이전트 (Programming Agent)에게도 활용할 수 없을까? 그렇게 생각했을 때 이번 아이디어가 떠올랐습니다. 의도 (Intent) 역시 마찬가지로, 덮어쓰는 것이 아니라 추기로 키워나가면 됩니다. 추정에서 시작하여, 확인을 거듭하며 기준 (Canonical)으로 승격시킵니다. 결함이 발생해도 의도를 직접 건드리지 않고, 수정을 새로운 태스크 (Task)로 추가해 나갑니다. 이후에 설명할 승격 상태나 작업 단위의 취급은 바로 이 사고방식에서 비롯되었습니다.

선행하는 「의도 주도 개발」의 움직임

의도로 구동한다는 한 점에 초점을 맞추어 도구를 만들어가는 과정에서, 의도 주도 개발 (Intent-Driven Development)에 대한 시도가 이미 다른 사람들에 의해서도 이루어지고 있다는 것을 깨달았습니다.

부르는 명칭이나 접근 방식은 다양하지만, "AI 시대에는 사양 (Specification)보다 한 단계 높은 '의도'를 다뤄야 한다"라는 문제의식은 저만의 것이 아니었습니다. 선행하는 논의가 있다는 것은 든든한 일이었습니다. 우리의 방식은 그중에서도 "의도를 트리 형태로 구조화하여 운영 루프까지 돌리는 것"에 치중하고 있습니다. 서로 겹쳐지면서 우리만의 형태를 찾아 나갈 수 있기를 바라고 있습니다.

의도의 구조 ─ intent-tree

의도는 단순히 문서로만 두면 결국 틈새로 사라져 버리고 맙니다. 그래서 Intent CLI에서는 의도를 **intent-tree (의도의 나무)**라는 계층 구조로 명시적으로 가집니다. 실체는 디스크 상의 마크다운 (Markdown) 파일들의 집합입니다.

골격은 세 가지 계통으로 나뉩니다.

• Purpose (왜 만드는가) — Mission / Vision / Value / Product Goal
• User Context (누구를 위한 것인가) — 누가, 어떤 상황에서, 어떤 템포로 사용하는가
• Means (어떻게 실현할 것인가) — 조작 경험, 시스템의 동작, 기술 전략 등

여기서 중요한 것은, Means는 구현의 상세 (Implementation Details)가 아니라는 점입니다. "React와 Vue 중 무엇을 사용할 것인가"가 아니라, "브라우저 퍼스트 (Browser-first)로 갈 것인가", "서버를 권위자로 하는 전제로 삼을 것인가"와 같이, 고민이 될 때의 판단 기준을 고정하는 장소입니다.

의도의 성숙도 (승격 상태)

또 하나, 이 트리에서 마음에 드는 메커니즘은 의도에 성숙도 (승격 상태)를 부여했다는 점입니다.

• inferred (추정) — AI나 기존 코드로부터 추정했을 뿐인 단계. 아직 가설 상태
• clarified (확인됨) — 대화를 통해 확인이 완료된 단계. 의사결정에 사용할 수 있음
• canonical (기준) — 하류의 사양이나 구현을 구속하는, 확정된 판단 기준

처음부터 완벽한 요구사항 정의 (Requirement Definition)를 작성할 필요는 없습니다. 추정에서 시작하여, 대화를 통해 조금씩 정확도를 높여갑니다. AI가 "이런 의도로 보이는데, 맞습니까?"라고 확인을 요청하고, 이에 답하면 그 의도가 한 단계 승격됩니다. 이 반복을 통해 프로덕트의 방향성이 자연스럽게 언어로 정립됩니다. 정확도는 '짐작'이 아니라 '상태'라는 점을 명확히 구분하는 것이 기분 좋은 지점입니다.

Intent CLI ─ 「AI를 내장하지 않는」 설계

Intent CLI를 만들 때 공을 들인 부분은, OpenAI나 Anthropic의 구독 서비스를 일반적인 사용 범위 내에서 사용하면서도 intent-cli를 최대한 활용할 수 있도록 한 것입니다.

Intent CLI 안에는 AI 기능이 하나도 들어있지 않습니다.

intent-cli는 의도를 정리하기 위한 프롬프트 (Prompt) 모음과 메타데이터 (의도 트리와 어떤 작업이 어디까지 진행되었는지에 대한 운영 상태 데이터)를 변경하는 기능만을 가지고 있습니다. "어떻게 생각할 것인가"는 그것을 구동하는 측의 AI (저의 경우에는 Codex나 Claude)가 생각하도록 설계되어 있습니다.

그래서 사용법도 독특합니다. 인간이 명령어를 순서대로 외워서 조작하는 방식으로 접근하지 않습니다. 처음에 AI에게 "intent-cli에게 물어보고 사용법을 이해해 줘"라고 부탁합니다. 그러면 AI가 도구에 동봉된 가이드를 읽어 들인 후, 이후에는 인간을 대신하여 의도를 정리해 나갑니다. 저 자신도 최근에는 의도가 구체적으로 어떻게 정리되고 있는지 아주 세세하게는 들여다보지 않게 되었습니다.

이러한 단절에는 또 하나의 실무적인 효과가 있습니다. intent-cli 자체는 AI를 보유하지 않으며, 프롬프트 가이드와 메타데이터 관리만을 제공합니다. 그것을 호출하는 것은 우리가 평소 사용하는 Codex나 Claude의 에이전트(Agent)입니다.

AI에 발생하는 비용은 자신의 Codex나 Claude 구독(Subscription) 측에서 발생합니다. 에이전트가 AI를 보유하지 않은 intent-cli를 호출하여 최신 프롬프트 가이드를 받아오는 방식입니다. 그러한 설계입니다.

기록은 모두 수중에 있는 파일에

또 하나, 안심할 수 있는 요소를 적어둡니다. intent-cli는 모든 기록을 리포지토리(Repository) 내의 파일(Markdown 및 JSON)에 작성합니다. 의도 트리(Intent tree)도, 작업 진행 상황과 같은 운용 상태도, 수중에 있는 git 리포지토리에 남을 뿐입니다.

intent-cli 자체가 네트워크 통신을 직접 수행하는 일은 없습니다. 어딘가의 자사 서비스에 접속하여 정보를 보내는 등의 처리도 포함되어 있지 않습니다. 외부와의 상호작용은 gh (GitHub CLI)를 통한 git 조작뿐입니다. 평소 사용하는 GitHub 외에 자신도 모르는 사이에 데이터가 전송될 걱정은 하지 않아도 됩니다.

사용하며 느끼고 있는 점

사용하면서 가장 고마운 점은 개발의 인지 부하(Cognitive load)가 낮아진다는 것입니다.

의도를 확정하는 인터뷰가 끝나고 개발 단계에 들어가면, 설령 루프(Loop)가 도중에 멈추더라도 깊게 생각할 필요가 없습니다. "멈춰 있으니까, intent-cli에게 물어보고 수정해서 진행해"라고 말하기만 하면 됩니다. 세세한 판단을 매번 다시 할 필요가 없기 때문에, 저는 지금 3개 정도의 프로젝트를 동시에 돌리고 있어도 머리가 따라가고 있습니다.

감각적으로는 개발 회사의 매니저와 대화하고 있는 것에 가깝습니다. 자신이 원청이고, 설계 상호작용을 하는 상대가 구현 당사자가 아닌 매니저인 상황. "진척은 어떻습니까", "이것은 제대로 되어 있습니까"라고 묻고, 보고를 받은 뒤, "그럼 다음은 이것을 부탁합니다"라고 요청하는. 그러한 거리감입니다.

결함(Bug)이 발생했을 때도 코드를 직접 수정하러 가지 않습니다. 변경 이력이 남지 않기 때문입니다. 대신 intent-system에 "이것, 잘 안 되고 있는 것 아닌가요"라고 전달합니다. 그러면 "확실히 생각이 부족했습니다, 수정용 태스크(Task)를 내보내겠습니다"라는 답변이 돌아오고, 의도 쪽을 올바르게 유지한 채 수정 사항이 새로운 태스크로서 쌓여갑니다.

「Grill Me」와의 공통점

최근 Matt Pocock 씨가 공개하여 화제가 된 Claude Code용 스킬인 「Grill Me」가 있습니다. 살펴보니 Intent CLI가 하려는 일과 상당히 유사한 것이었습니다.

Grill Me는 기능을 만들기 시작하기 전에 Claude Code를 「인터뷰 모드(Interview mode)」로 전환하여, 설계상의 결정을 하나씩 질문해 나가는 스킬입니다. 포인트는 만들고 싶은 것을 하나의 프롬프트로서가 아니라, **결정 트리(Design tree)**로 취급하여 상류의 선택을 해결한 뒤 하류로 나아가는 것입니다. 질문할 때마다 코드베이스를 조사한 뒤 「추천 답변」도 함께 제시해 줍니다. AI 코딩의 실패 대부분은 "모델이 코드를 못 써서"가 아니라 "요건(Requirement)이 충분히 다뤄지지 않아서" 발생한다는 과제에 정면으로 맞서는 스킬입니다.

결정을 트리로 취급하고, 선택지에 권장 사항을 곁들여 하나씩 확인해 나가는 방식. 이 진행 방식은 Intent CLI의 인터뷰나 intent-tree와 상당히 유사한 발상입니다.

Grill Me에 대해서는 무잘 채널(Muzal Channel) 회차에서도 자세히 논의되어 있어 참고가 되었습니다.

그 점을 바탕으로, Intent CLI는 한 발짝 더 나아갑니다. Grill Me가 「하나의 기능을 만들기 전의 요건 정의」에 초점을 맞추고 있다면, Intent CLI는 확정된 의도를 프로젝트 전체의 메타데이터(Metadata)로서 계속 남겨두며, 어떤 태스크가 끝났고 지금 어떤 태스크를 다루고 있는지까지 관리합니다. 전처리뿐만 아니라 그 이후의 운용 루프까지 돌리는 것입니다. 다만, 근본적인 방침은 매우 가깝습니다. 먼저 인간이 어떻게 하고 싶은지를 확실히 듣고 정리하며, 그것을 구조화한다는 점은 같습니다.

이러한 방침은 이치에 맞다고 생각합니다. 앞서 "개발 회사의 매니저와 대화하는 감각"이라고 썼지만, 이는 우연이 아닙니다. 신뢰하는 개발자나 개발 회사에는 세세하게 간섭하기보다 "무엇을 하고 싶은지"를 브리핑하곤 합니다. AI의 기술이 올라갈수록 똑같은 말을 할 수 있다고 생각합니다. 하나하나의 구현을 마이크로매니지먼트(Micromanagement)하는 것보다, 확실히 전달되는 의도를 정리해서 전달하는 편이 더 좋은 결과를 가져옵니다. Intent CLI는 그 "의도를 전달하는 것"을 구조적으로 하기 쉽게 만들기 위한 도구입니다.

Intent CLI는 인간과 AI 사이의 공통 언어가 되어줍니다.

설계·구현·리뷰가 돌아가는 루프 기구

Intent CLI의 가장 큰 강점은 의도 주도 개발(Intent-Driven Development)을 **설계·구현·리뷰의 루프 기구(Loop Mechanism)**로서 돌아가도록 설계했다는 점입니다. 단순히 의도를 정리하는 것만으로 끝나지 않습니다.

구체적으로는 다음과 같습니다. 의도 트리(Intent Tree)로부터 태스크(Task)를 만들고, 그 태스크를 GitHub의 이슈(Issue)로 분리합니다. 구현 스레드(Implementation Thread)가 그것을 구현하여 PR(Pull Request)을 올리면, 리뷰 스레드(Review Thread)가 "의도 트리대로 만들어졌는가"를 대조하며 리뷰합니다. 만약 어긋나 있다면 변경 요청을 내고, 구현 스레드가 이를 수정합니다. 괜찮다면 머지(Merge)하고, 다음 태스크가 있다면 그것을 다시 다음 이슈(Issue)로 분리합니다.

이 **의도 → 태스크 → 이슈(Issue) → 구현 → 리뷰 → 수정 → 머지(Merge) → 다음 이슈(Issue)**라는 개발 루프가, 상태를 확실히 관리할 수 있는 CLI(메타데이터 관리)에 의해 계속해서 돌아갑니다. 의도를 정리하는 입구뿐만 아니라, 의도로부터 구현·리뷰·머지까지를 잇는 "개발 프로세스" 그 자체로서 만들어져 있습니다. 여기서 Intent CLI는 단순한 "의도를 정리하는 도구"가 아니라, 개발 프로세스를 돌리기 위한 도구가 됩니다.

그렇다고 해서 이것으로 버그가 발생하지 않는 것은 아닙니다. 꿈처럼 오류가 없는 것이 만들어진다는 이야기가 아닙니다. 정기적으로 인간이 코드의 방침을 리뷰하고 동작을 확인합니다. AI 에이전트(AI Agent)에게도 동작 확인을 시킵니다. 의도대로 구현되지 않았다면, 의도를 보강하여 수정하거나 "의도가 구현되지 않았다"는 버그로 보고합니다. 그러한 조정을 거듭하며 진행해 나갑니다. 가능한 한 문제가 발생하지 않는 이슈(Issue)가 되도록 최선을 다하지만, 완전히 문제가 발생하지 않는 것은 아니라는 것이 솔직한 체감입니다. 그럼에도 불구하고, 개발 프로세스로서 좋은 아웃풋(Output)을 내는 데 도움이 되고 있다고 느끼고 있습니다.

본番 운용의 현황

이것은 구상 단계의 이야기가 아닙니다. 사내에서는 이미 여러 프로젝트에서 본番 운용(Production Operation)을 하고 있으며, AI에 의한 구현과 리뷰의 루프를 지속적으로 돌리고 있습니다. 어떤 프로젝트에서는 이슈(Issue)와 PR을 합쳐 1,000개 가까이 쌓아 올리기도 했습니다.

솔직히 말씀드리면, 꿈처럼 오류가 없는 것이 만들어지는 것은 아닙니다. 버그는 발생합니다. 그래서 정기적으로 인간이 코드의 방침을 리뷰하고 동작을 확인하며, AI 에이전트에게도 동작 확인을 시키고 있습니다. 의도대로 구현되지 않았다면 의도를 보강하여 수정하거나, "의도가 구현되지 않았다"는 버그로 보고합니다. 그러한 조정을 거쳐 나아갑니다. 가능한 한 문제가 발생하지 않는 이슈(Issue)가 되도록 최선을 다하지만, 완전히 문제가 없는 것은 아니라는 것이 체감입니다.

그럼에도 개발 프로세스로서 좋은 아웃풋(Output)을 내는 데 도움이 되고 있다고 느낍니다. "생각한 대로 만들어지고 있는가"를 언제든 의도로 거슬러 올라가 확인할 수 있다는 것── 이 상태에는 지금까지 없었던 안심감이 있습니다.

맞지 않는 케이스

만능이라고 생각하지는 않습니다. 일회성 스크립트나 혼자 만드는 작은 프로토타입(Prototype)에는 Intent CLI가 오버킬(Overkill)입니다. 의도를 구조화하는 수고가 더 커지게 됩니다.

이것이 효과를 발휘하는 것은 어느 정도 기간 동안 여러 사람이나 AI가 관여하여, 의도가 흔들리면 곤란한 개발입니다. 우리가 매일 하고 있는 일이 바로 그러한 업무였습니다.

오픈 소스 공개

이번에 Intent CLI를 OSS (Apache-2.0)로 공개했습니다.

공개 리포지토리(Repository)는 여기입니다.

바로 사용해 보실 수 있도록, NuGet을 통한 .NET 글로벌 도구(dotnet tool install -g JTechJapan.IntentSystem.Cli)로 배포하고 있습니다. 구체적인 절차는 실전편에 정리해 두었습니다.

향후에는 의도(Intent)의 트리(Tree)를 프로젝트를 넘어 재사용할 수 있는 작은 생태계(Ecosystem)로 만들고 싶습니다. npm 패키지나 Helm 차트처럼, 어떤 프로젝트에서 키워낸 의도를 다른 프로젝트에서 참조할 수 있는 방식입니다. 의도가 '해당 프로젝트에 국한된 문서'가 아니라 '재사용 가능한 지식의 단위'가 되는 세상입니다.

우선 직접 사용해 보세요. 다음 실전편에서는 설치부터 '3개의 AI를 병행시켜 자율 개발을 수행하는' 단계까지, 실제 절차를 따라가며 설명하겠습니다.

질문이나 상담은 J-Tech JAPAN OSS Discord에서도 받고 있습니다. 의도 주도 개발(Intent-Driven Development)이나 Intent CLI에 대해 언제든 편하게 말씀해 주세요.

Discussion