작동하는 빌드를 재사용 자산으로 포장하기

액셀러레이터는 한 번 만든 솔루션을 다음에도 그대로 쓸 수 있게 포장해 둔 것입니다. 덕분에 다음 프로젝트는 빈 저장소에서 출발하는 대신, 이미 작동하는 토대 위에서 곧장 이어 갑니다.

포장은 두 가지를 나누는 데서 시작합니다. 특정 고객에게만 해당하는 코드와, 어디서든 다시 쓸 수 있는 핵심을 갈라내고, 나머지는 설정값으로 빼냅니다. 작동하는 빌드를 하나 놓고, 고객마다 달라지는 부분을 찾아 파라미터로 노출하되 기본값을 함께 문서로 적어 둡니다. 그러면 다음 팀은 자산을 통째로 다시 쓰는 대신, 설정만 바꿔서 씁니다.

이 작업은 빌드가 아직 신선할 때 해 두는 편이 좋습니다. 몇 달이 지나면 어떤 값을 왜 고정해 두었는지 알던 사람이 이미 자리를 옮겼을 수 있고, 그때 의도를 되짚어 복원하는 비용이 훨씬 큽니다.

재사용할 수 있는 작업은 대부분 세 가지 유형 중 하나에 들어갑니다. 이 모듈 전체에서 쓰는 분류인데, 유형마다 담는 내용이 다르고 포장하는 방법도 다릅니다.

유형을 잘못 고르면 겉보기에는 재사용할 수 있어 보여도, 막상 적용하기는 어려운 자산이 되기 쉽습니다.

THREE ASSET TYPES — 유형별로 담는 것과 포장법

가장 흔한 실수는 에이전트를 템플릿이 아니라 흩어진 스크립트 묶음으로 내보내는 것입니다. 스크립트가 작동하니 재사용할 수 있어 보이지만, 고객마다 다른 값이 파일마다 흩어져 있어서 다음 팀은 자산 하나를 설정해 쓰는 대신 복사한 뒤 조금씩 갈라 나가게 됩니다.

코드는 자산이 무엇을 하는지를 보여 줍니다. 하지만 코드만 읽어서는 다음 사람이 확실히 알아내기 어려운 것들이 있습니다.

자산이 자기 환경에 대해 전제하는 가정, 기대하는 입력, 이미 처리해 둔 실패 상황, 그리고 자산이 여전히 제대로 동작하는지 판단하는 평가 — 이런 것은 소스만 봐서는 짚어 내기 어렵습니다. 문서가 없으면 다음 팀은 자산을 속을 알 수 없는 상자처럼 다루게 되고, 결국 다시 만드는 쪽을 택합니다.

여기에 하나가 더 붙습니다. 규제를 받는 고객이라면 검토자가 이런 것을 묻습니다. 이 자산이 어떤 데이터를 건드리는지, 어떤 자격으로 동작하는지, 어떤 기록을 남기는지. 이 세 가지가 준비돼 있지 않으면 자산은 데모까지는 통과해도 첫 보안 검토에서 멈춰 섭니다. 그래서 감사 로그도 패키지의 일부로 함께 담아 둡니다.

포장하는 동안 이 표를 빌드 옆에 두고 봅니다. 각 칸은 자산 하나에 대해 한 번씩 내리는 결정입니다.

PACKAGING CHECKLIST — 유형별로 한 번씩 정하는 결정

포장을 언제 하고 언제 건너뛰면 좋을지는 상황에 따라 갈립니다.

HANDLES WELL · ADDS COST · USE A DIFFERENT APPROACH

하드코딩하면 더 빨리 낼 수 있고, 마침 마감이 있었습니다. 그래서 데모를 작동하게 만든 값들을 코드에 그대로 적어 넣었습니다. 템플릿은 잘 작동했죠. 바로 그래서, 다음 팀이 재사용하려 들기 전까지는 아무도 그 템플릿을 다시 들여다보지 않았습니다.

아래는 재사용 시도가 실패한 뒤 팀이 정리하는 방식 그대로 옮긴 사후 기록입니다. 누군가 이것을 '실수'라고 부르기 전에, 실패가 어떤 모양으로 나타나는지 먼저 볼 수 있게요.

무슨 일이 있었나. 한 팀이 고객 프로젝트를 위해 에이전트 템플릿을 만들어 기한에 맞춰 냈습니다. 마감을 지키려고 고객마다 달라지는 값들을 코드에 곧장 적어 넣었습니다 — 저장소 경로, 모델 이름, 검토 임계값, 그리고 그 고객 도메인에만 해당하는 프롬프트 조각 몇 개였죠. 템플릿은 잘 작동했고, 프로젝트는 마무리됐고, 빌드는 '재사용 가능'이라는 이름표를 달고 공용 저장소로 들어갔습니다.

몇 달 뒤, 두 번째 팀이 비슷한 프로젝트를 맡으며 그 템플릿을 꺼냈습니다. 그런데 설정을 할 수가 없었습니다. 설정할 것이 아예 없었기 때문입니다. 바꿔야 할 값은 전부 루프 안에 적혀 있었고, 파일 전체를 읽지 않고서는 그 값들이 어디 있는지조차 보이지 않았습니다. 어떤 값이 고객 특정 값이고 어떤 값이 함부로 건드리면 안 되는 값인지 알려 주는 문서도 없었습니다. 번들로 담긴 평가도 없어서, 값을 짐작으로 고쳐 본 뒤에도 템플릿이 새 환경에서 여전히 동작하는지 확인할 길이 없었습니다. 결국 처음부터 다시 만들어야 했습니다.

왜 그렇게 됐나. 빌드를 작동하는 순간 끝났다고 본 것이 원인입니다. 재사용할 수 있는 순간이 아니라요. 마감 앞에서 하드코딩은 합리적인 선택이었습니다. 다만 그 뒤로 다시 손보지 않았습니다. 겉으로 작동하는 템플릿만 봐서는 그것이 재사용될 수 없다는 걸 알아채기 어렵습니다. 그래서 비용은 두 번째 팀이 그 템플릿을 다시 만들 때가 되어서야 드러났습니다. 포장이 막아 줬어야 할 재작업 비용에, 템플릿이 막다른 길이었음을 알아채기까지 잃은 시간까지 더해서요.

원문의 점검 과제는 직접 코드를 고쳐 보는 서술형입니다. 아래는 다른 팀이 재사용해야 하는 에이전트 템플릿인데, 결함이 하나 있습니다 — 파라미터가 들어갈 자리에 고객 특정 값이 하드코딩돼 있습니다. 하드코딩된 값이 무엇인지 먼저 짚어 보고, 고친 함수 시그니처와 그 값을 대체할 파라미터화한 줄을 직접 써 보세요.

THE TEMPLATE AS SHIPPED — 결함이 하나 있는 재사용 템플릿

# agent_template.py : "reusable" code-review agent
def build_review_agent():
    return Agent(
        model="claude-opus-4-8",
        system_prompt=SYSTEM_PROMPT,
        tools=[read_file, run_linter],
        repo_path="/home/acme/checkout-service",  # customer repo
    )

모델 ID claude-opus-4-8은 빌드 시점에 최신 값을 확인하세요 — platform.claude.com/docs/en/about-claude/models

def build_review_agent(repo_path):
    return Agent(
        model="claude-opus-4-8",
        system_prompt=SYSTEM_PROMPT,
        tools=[read_file, run_linter],
        repo_path=repo_path,  # set per engagement
    )

이어서 객관식으로 점검합니다. 정답을 먼저 떠올려 본 뒤 골라 보세요. 맞히면 설명이 나옵니다.