그래서 이번에는 GitHub Release만 생성하면 npm 배포까지 자동으로 완료되는 파이프라인을 구축했습니다.

예제는 오래전에 개발해서 React 전에 사용하던 오픈소스 프로젝트에서 실제 사용 중인 Workflow를 기준으로 설명합니다.

https://github.com/cable8mm/jquery-infinite-with-template

구현 자체는 어렵지 않았지만, 실제로는 몇 가지 예상하지 못한 문제를 만났습니다. 이 글에서는 최종적인 워크플로우와 함께, 실제로 겪었던 트러블슈팅을 공유합니다.

목표

최종적으로 만들고 싶었던 흐름은 아주 단순했습니다.

git push
      ↓
GitHub Release 생성
      ↓
GitHub Actions 실행
      ↓
npm publish
      ↓
배포 완료

개발자는 Release만 생성하면 되고, npm 로그인이나 수동 배포는 더 이상 하지 않는 것이 목표였습니다.

GitHub Actions 구성

Release가 생성되면 자동으로 실행되는 Workflow를 작성했습니다. 아래 action 은 최종본이며, 실제로 제가 사용하고 있습니다.

NPM_TOKEN 을 만드는 법은 글 하단에 설명하겠습니다.

name: Publish to npm
on:
  release:
    types: [created]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v6
        with:
          node-version: "24"
          registry-url: "https://registry.npmjs.org"

      - name: Update version
        run: |
          VERSION=${GITHUB_REF#refs/tags/v}
          npm version $VERSION --no-git-tag-version

      - run: npm ci
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

핵심은 release.created 이벤트입니다.

GitHub Release가 생성되는 순간 Actions가 실행되고, 필요한 의존성을 설치한 뒤 npm에 패키지를 배포합니다.

첫 번째 문제

처음 만난 오류는 바로 이것이었습니다.

npm ERR!
You cannot publish over the previously published versions.

처음에는 GitHub Actions 설정이 잘못된 줄 알았습니다.

하지만 원인은 훨씬 단순했습니다.

npm은 이미 배포된 버전을 절대 다시 업로드할 수 없습니다.

그리고, npm 은 package.json의 version 값을 사용합니다.

해결

Release Tag와 package.json의 version을 항상 동일하게 맞추도록 변경했습니다.

GitHub의 Release 값을 사용하기 위해서 아래 코드를 추가했습니다.

- name: Update version
  run: |
    VERSION=${GITHUB_REF#refs/tags/v}
    npm version $VERSION --no-git-tag-version

이 코드는 package.json의 version 값을 Github Release 값으로 바꿉니다.

두 번째 문제

npm error code EOTP

다음으로 만난 오류는 이것입니다.

npm ERR! code EOTP

로컬에서는 정상적으로 Publish가 되는데 GitHub Actions에서만 실패했습니다.

원인은 npm 계정에 2단계 인증(2FA) 이 활성화되어 있었기 때문입니다.

GitHub Actions는 당연히 OTP를 입력할 수 없습니다.

해결

npm에서 Access Token을 생성할 때 Bypass two-factor authentication (2FA) 옵션을 활성화했습니다.

이 토큰은 CI/CD 환경에서 사용할 수 있도록 만들어진 토큰이라 GitHub Actions에서도 정상적으로 Publish가 가능합니다.

생성한 토큰은 GitHub Repository의

Settings
→ Secrets and variables
→ Actions

에

NPM_TOKEN

이라는 이름으로 저장했습니다.

이후 Workflow에서는

env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

만 추가하면 인증이 완료됩니다.

구축 후 달라진 점

자동화 전에는 배포할 때마다 다음 작업을 반복했습니다.

• npm 로그인
• 버전 확인
• publish 실행
• 결과 확인

지금은 훨씬 단순합니다.

코드 작성
↓
Release 생성
↓
배포 완료

개인적으로는 Homebrew, Composer, npm 모두 GitHub Release를 시작점으로 사용하는 형태로 통일했습니다. 덕분에 어떤 언어의 패키지든 동일한 배포 경험을 유지할 수 있게 되었습니다.

Release 전에 자동으로 수행되는 작업

배포 전에는 PR로 코드가 업데이트 되는데요, 아래 기능이 모두 자동으로 작동합니다.

• 테스트 코드 실행
• lint
• changelog 자동 생성
• GitHub Release Note 자동 작성(GitHub 기본 기능)
• npm과 GitHub Release 버전 자동 동기화
• 코드의 API 명세를 GitHub Pages로 자동 배포

이렇게 구성하면 Release 버튼 하나만으로 배포가 끝나는 완전한 CI/CD 파이프라인이 됩니다.

마무리

GitHub Actions를 이용한 npm 자동 배포는 생각보다 구현이 어렵지 않습니다.

하지만 실제로 구축해 보면 대부분 다음 두 가지에서 시간을 많이 쓰게 됩니다.

• package.json 버전 관리
• npm 인증(2FA)

이 두 가지만 미리 알고 시작해도 시행착오를 크게 줄일 수 있습니다.

개인적으로는 GitHub Release를 배포의 단일 진실(Single Source of Truth)로 사용하는 방식을 선호합니다.

태그, 릴리스 노트, npm 버전이 모두 하나의 이벤트를 기준으로 관리되기 때문에 실수를 줄일 수 있었고, 여러 오픈소스 프로젝트를 운영하는 데도 큰 도움이 되었습니다.

만약 바이브 코딩이 답이라면 이미 한국에는 많은 서비스가 론칭이 되고, 이미 존재하는 스타트업 서비스를 위협해야 하는데, 그런 소식은 잘 들리지 않습니다. 그것이 영업이나 마케팅 문제일 수도 있습니다.

전 바이브 코딩을 이용해서 프로젝트를 완성할 수는 있지만, 운영할 수는 없다는 사실을 알게 되었는데요, 그것은 AI가 바보라서가 아니라 Context Memory 에 한계가 있기 때문이고, 그 메모리는 미래에 가도 해결되지 않는다는 사실도 알게 되었습니다.

따라서, 몇가지 제약을 markdown으로 만들고, 절차를 만들어서 프로젝트 제작과 운영에 사용하고 있는데요, 그것이 바로 REPL Works라고 하는 AI-Native 개발방법론입니다.

그와 비슷한 시기에 Github에서는 SDD(Spec Driven Development)를 구현할 수 있는 Spec Kit이라는 것을 오픈소스로 출시했습니다.

An open source toolkit that allows you to focus on product scenarios and predictable outcomes instead of vibe coding every piece from scratch.

바이브 코딩을 정면으로 대치하는 오픈소스 툴킷이라고 자신을 소개하고 있습니다. 그리고 현재 Github Star가 11만 6천개에 달하고 있네요.

1인 개발자 혹은 소규모 AI-Native 개발환경을 운영하는 곳이라면 이미 나만의 개발 워크플로가 있을텐데요, Spec Kit에 나만의 워크플로를 넣을 수 있는 강력한 기능인 Spec Kit Extension 에 대한 소스코드를 분석한 내용을 공유합니다.(이 내용은 아쉽게도 아직 공식 메뉴얼에는 나오지 않습니다.)

Spec Kit Extension이 내장 Command 프롬프트를 대체할 수 있는가?

1. 아키텍처 개요

이번 분석과 관련하여 Spec Kit은 서로 구분되는 세 가지 계층으로 구성되어 있다.

/speckit.specify, /speckit.plan, /speckit.tasks는 Python 객체가 아니다.

이들은 디스크에 기록되는 Markdown/TOML/YAML 파일이며, AI 에이전트는 이 파일들을 직접 읽어 자신의 프롬프트로 사용한다.

2. Command Resolution Flow

2.1 Command는 어디에서 등록되는가?

출처: src/specify_cli/agents.py

CommandRegistrar.register_commands()는 실제로 Command 파일을 디스크에 생성하는 유일한 함수이다.

동작 과정은 다음과 같다.

1. source_dir에서 .md 템플릿을 읽는다.
2. Frontmatter를 파싱한다.
3. 인자 플레이스홀더를 변환한다.
   • 예: $ARGUMENTS
   • Gemini용: ``
4. 결과를 Agent별 Command 디렉터리에 기록한다.

내장 Command는 specify init 실행 시 다음 흐름을 통해 생성된다.

specify init
  → commands/init.py: register()
    → resolved_integration.setup(...)
      → IntegrationBase.setup()
        → CommandRegistrar.register_commands()
          → .claude/skills/speckit-specify/SKILL.md 생성
          → .gemini/commands/speckit.specify.toml 생성
          → ...

템플릿은 다음 우선순위로 로드된다.

1. core_pack/commands/
2. templates/commands/

2.2 Command 이름은 어디에서 검증되는가?

extensions/__init__.py

CORE_COMMAND_NAMES = frozenset({
    'analyze',
    'checklist',
    'clarify',
    'constitution',
    'converge',
    'implement',
    'plan',
    'specify',
    'tasks',
    'taskstoissues'
})

Extension Command는 다음 정규식을 반드시 만족해야 한다.

speckit.<extension-id>.<command-name>

2.3 Command Lookup 우선순위

Python에는 런타임 Command Dispatcher가 존재하지 않는다.

AI Agent가 자신의 Command 디렉터리에서 파일을 직접 찾는다.

따라서

• Override Priority
• Dispatch Table
• Runtime Lookup

모두 존재하지 않는다.

같은 위치에 마지막으로 기록된 파일이 사용된다.

3. Extension 시스템이 할 수 있는 것과 할 수 없는 것

3.1 Extension Command Namespace 제약

Extension은 자신의 ID를 Namespace로 사용해야 한다.

예를 들어

id: replworks

이면

speckit.replworks.*

만 사용할 수 있다.

다음은 허용되지 않는다.

speckit.specify.*

왜냐하면 specify는 이미 Core Namespace이기 때문이다.

예시

3.2 Extension 간 Command 충돌

Extension 설치 시에는

• 다른 Extension Command와의 충돌

만 검사한다.

Core Command와의 충돌은 별도의 Namespace 검증 단계에서 차단된다.

3.3 Hook 시스템

Hook은

.specify/extensions.yml

에 저장된다.

예를 들어

hooks:
  before_specify:

는

templates/commands/specify.md

안에서 AI가 직접 읽는다.

즉,

Hook은

Python이 실행하는 것이 아니라

AI Prompt 안에 자연어 지시문을 삽입하는 방식이다.

지원되는 Hook

3.4 Hook는 실제로 무엇을 하는가?

예를 들어

hooks:
  before_specify:
    - extension: replworks
      command: speckit.replworks.preflight
      optional: false
      priority: 5

이면

AI Prompt에는

EXECUTE_COMMAND: speckit.replworks.preflight

와 같은 자연어 지시가 추가된다.

중요한 점은

Python이 이를 강제하지 않는다는 것이다.

AI가 이 지시를 따를지 여부는 AI Agent의 구현에 달려 있다.

4. Prompt Loading Flow

4.1 Prompt는 Markdown 파일인가?

그렇다.

모든 Core Prompt는 Markdown 파일이다.

예

templates/commands/specify.md
templates/commands/plan.md
templates/commands/tasks.md

4.2 언제 읽히는가?

specify init

실행 시 읽혀서

Agent 전용 Command 파일로 변환된다.

그 이후에는

Python CLI는 Prompt 실행 과정에 관여하지 않는다.

Agent가 자신의 Command 파일을 직접 읽는다.

4.3 Source Code 안에 Embedded 되어 있는가?

아니다.

Prompt는 모두 외부 Markdown 파일이다.

Python은 이를 읽어서 Agent별 포맷으로 변환할 뿐이다.

4.4 Extension이 Prompt를 교체할 수 있는가?

직접적으로는 불가능하다.

하지만 다음 두 방법은 가능하다.

Preset

Preset은

• replace
• prepend
• append
• wrap

전략을 지원한다.

즉

speckit.specify

Prompt 자체를 변경할 수 있다.

Project Override

PresetResolver는

.specify/templates/overrides/

를 최우선으로 읽는다.

여기에 동일한 Template가 있으면 그것이 사용된다.

5. Init Process

specify init는 다음 순서로 수행된다.

1. Agent Command 생성
2. .specify/templates 복사
3. Constitution 생성
4. 기본 Workflow 설치
5. agent-context Extension 자동 설치
6. init-options.json 생성
7. --preset 설치

Extension은 Init에 참여하는가?

아니다.

예외는

• agent-context
• –preset

뿐이다.

Extension에는

on_init

Hook가 존재하지 않는다.

Preset은 Init에 참여하는가?

그렇다.

specify init --preset replworks

를 실행하면

Preset이 Template를 수정한 후 설치된다.

6. Extension Lifecycle

Extension에는 일반적인 의미의 Lifecycle Hook가 존재하지 않는다.

예를 들어

• on_install
• on_init
• on_command_start

같은 Callback은 없다.

Lifecycle은 다음과 같다.

즉

실제 Command 실행 시에는 Python이 전혀 개입하지 않는다.

7. 실제 가능한 것들

A. /speckit.specify를 완전히 교체

Extension

❌ 불가능

Preset

✅ 가능 (strategy: replace)

B. /speckit.specify 앞에 지시문 추가

Preset

✅ 가능 (prepend)

Hook

⚠️ 가능하지만 AI가 Hook를 무시할 수도 있다.

C. /speckit.specify 뒤에 지시문 추가

Preset

✅ 가능 (append)

Hook

⚠️ 가능

D. /replworks.specify 같은 새로운 Command 제공

Extension

✅ 가능

예

speckit.replworks.specify

E. specify init 중 다른 Prompt 생성

Preset

✅ 가능

Extension

❌ 불가능

F. Init 시 설치되는 Agent Prompt 교체

Preset

✅ 가능

파일 직접 수정

✅ 가능

Extension

❌ 불가능

8. REPL Works가 현실적으로 Override 가능한 것

9. REPL Works가 Override할 수 없는 것

10. REPL Works 권장 통합 전략

소스 코드를 기준으로 판단하면

가장 안정적인 방법은

Extension이 아니라 Preset이다.

이유는 다음과 같다.

1. Core Prompt를 직접 변경할 수 있다.
2. specify init 중 설치된다.
3. 모든 AI Agent에 동일하게 적용된다.

권장 구성은 두 부분으로 나뉜다.

Part 1. REPL Works Preset

provides:
  templates:
    - type: command
      name: speckit.specify
      strategy: wrap

    - type: command
      name: speckit.plan
      strategy: prepend

    - type: command
      name: speckit.tasks
      strategy: append

Part 2. REPL Works Extension

provides:
  commands:
    - name: speckit.replworks.specify

hooks:
  before_specify:
    command: speckit.replworks.preflight
    optional: false

설치 순서는 다음과 같다.

specify init my-project --integration claude --preset replworks

specify extension install /path/to/replworks-extension

중요

Preset은 기존 Core Command Prompt의 내용을 수정한다.

Extension은 새로운 Command와 Hook를 추가한다.

두 기능은 서로 경쟁하는 것이 아니라 상호 보완적이다.

주의

Hook는 Python Runtime이 아니라 AI Agent가 Prompt를 읽어 수행한다.

AI가 Hook를 무시하면 아무 일도 일어나지 않는다.

비즈니스상 반드시 실행되어야 하는 로직은 Hook가 아니라 Preset을 통해 Prompt 자체에 포함시키는 것이 바람직하다.

Evidence Index

ChatGPT와 Gemini는 성향이 너무 달라서 둘을 같이 쓰게 됩니다. ChatGPT는 냉정한 I성향이라면 Gemini는 활발한 E 성향이죠.

ChatGPT는 비교적 정확한 정보가 필요할때, Gemini는 아이디어를 넓게 탐색하거나 조금 더 편안한 대화를 하고 싶을 때 사용합니다.

그래서, 전 종종 이런 식으로 작업을 합니다.

• ChatGPT에게 물어보고
• Gemini에게 그 내용을 전달하고
• ChatGPT에게 물어보고
• Gemini에게 그 내용을 전달하고
• …

처음엔 몇번 이런 식으로 진행이 되었을 때 재밌다라는 생각을 했는데요, 생각보다 자주 이렇게 일을 하는 저 자신을 바라보면서 이게 무슨 삽질인가… 라는 생각이 들더군요.

“아, ChatGPT 답변 복사해서 Gemini에 붙여넣고, 또 그 답변 복사해서 ChatGPT에 넣는 거… 이거 누가 자동화 안 해주나?”

소프트웨어 엔지니어로서 참을 수 없는 비효율이었습니다.

LLM이 나온 지금 누군가는 만들었겠지 라는 기대로 오픈소스와 상용서비스 모두 뒤져봤습니다. 왜인지는 모르겠지만, 모든 솔루션들이 api를 사용하고 있었습니다. api… 전 api보다 채팅창에서 대화하는 것을 좋아합니다.

그래서 두 거대 언어 모델(LLM)이 서로 릴레이식으로 대화하며 문서를 고도화하는 두 개의 모델이 서로 질문하고 답변하고 내가 중재를 할 수 있는 도구를 만들기로 결심했습니다.

조건은 단 하나였습니다.

“사용성이 우아할 것.”

사용자가 평소 사용하던 크롬 브라우저와 로그인 세션을 그대로 활용하면서 동작하는 앱을 상상했습니다.

2. 폭풍 같았던 7시간, 그리고 22개의 커밋

전 AI 와의 개발에 있어서 REPL Works 프레임워크를 사용합니다. AI의 메모리를 문서화 시키면서 step by step 으로 개발하는 방식입니다.

개발에 들어가기 전에 PRODUCT_SPEC.md, ARCHITECTURE.md, FRAMEWORK.md 그리고 TASKS.md 네 개의 문서를 몇시간에 걸쳐서 만들고, 개발을 시작하자마자 AI 코딩 어시스턴트(Codex)와 호흡을 맞추며 엄청난 속도로 코드를 작성했습니다.

#1 ~ #3

프로젝트 기초를 다지고 CLI 인터페이스와 미션 상태 관리 시스템을 만들었습니다.

#4 ~ #7

브라우저 자동화 레이어, 메시지 추출 엔진, 라우팅 시스템을 구현했습니다.

이때까지만 해도 9222 포트로 기존 크롬에 연결하면 모든 것이 해결될 것이라고 생각했습니다.

#8 ~ #14

중간에 사용자가 개입할 수 있는 시스템, 멀티 탭 바인딩, 지속 가능한 미션 러너까지 추가했습니다.

린트와 포맷 설정까지 마치고 나니 정말 완성된 제품이 탄생하는 것처럼 느껴졌습니다.

터미널에서 테스트 코드가 돌아가는 모습을 보며 생각했습니다.

“역시 AI랑 코딩하니까 생산성이 미쳤네.”

딱 5시간째가 되기 전까지는 말입니다.

3. “그거 안 되는데요?” 크롬 보안 모델에 머리가 아파지다

문제는 15번째 커밋 근처에서 터졌습니다.

코드는 완벽해 보였는데 크롬이 계속 연결을 거부했습니다.

❯ curl http://127.0.0.1:9222/json/version
curl: (7) Failed to connect to 127.0.0.1 port 9222 after 0 ms: Couldn't connect to server

원인을 파악해 보니 2025년 3월 크롬은 보안 강화를 위해 기본 사용자 프로필에 대한 원격 디버깅 사용을 제한하고 있었습니다.

이미 로그인 정보와 개인정보가 들어 있는 프로필을 외부 프로그램이 마음대로 제어하는 것을 어렵게 만든 것입니다.

우회하려면 별도의 빈 프로필을 만들어야 했습니다.

google-chrome \
--remote-debugging-port=9222 \
--user-data-dir=~/chrome-debug-profile

이렇게 하면 동작은 합니다.

하지만 치명적인 문제가 생깁니다.

• 매번 터미널을 열어야 합니다.
• 새로운 프로필에서 크롬이 실행됩니다.
• ChatGPT와 Gemini에 다시 로그인해야 합니다.

문득 이런 생각이 들었습니다.

자동화를 편하게 하려고 만드는 앱인데, 왜 사용자는 매번 터미널을 열고 구글 로그인을 다시 해야 하지?

개발자인 저부터도 사용할 의향이 없었습니다.

결국 저는 제가 잘 알지 못하는 영역, 즉 크롬 보안 모델을 충분히 이해하지 못한 상태에서 AI가 할 수 있다는 말만 믿고,

“네가 제안한대로 알아서 구현해 줘.”

라고 맡긴 셈이었습니다. AI는 저보다 똑똑할 테니까요.

그리고 기술적인 막다른 길(Dead End)에 도달했습니다.

4. 살릴 것인가, 죽일 것인가

하루 동안 만든 30-40여 개의 커밋과 20여 개의 PR이 주마등처럼 스쳐 지나갔습니다. ai-issue를 만들 떈 이런 일이 발생하지 않았습니다.

“이 프로젝트는 여기서 폐기해야 하나?”

잠시 고민했습니다. Codex는 작동은 하니 일단 써(!)라고 제안을 하더군요.

My recommendation:

- If you want something that works reliably today, use a dedicated Chrome profile for the relay tool.
- If you want, I can help you set that up in the least painful way, including a launch command and a cleaner README note so it feels straightforward.

악마의 속삭임. 하지만, 하지만 그 순간 깨달았습니다. 저부터도 절대 안 쓸 것 같았습니다. 사실 이 앱은 설치용 앱으로 패키징을 할 예정이었습니다. Codex에게 솔직하게 말했습니다.

After reviewing the UX, I have decided to completely discard the –remote-debugging-port=9222 approach. Forcing the user to manually launch Chrome via the terminal with specific flags and re-authenticate their ChatGPT/Gemini accounts is an unacceptable user experience.

What do you think about pivoting to a Chrome Extension + Node.js (MCP) Server Hybrid Architecture?

AI도 의외로 담담하게 인정했습니다.

Yes, I think that pivot is materially better for the UX you want.

그렇게 도출한 대안이

Chrome Extension + Node.js MCP Server

구조였습니다.

외부 프로그램이 크롬에 침입하려고 하니까 막히는 것이라면,

브라우저 내부에서 동작하는 익스텐션이 DOM을 읽고 제어하고,

그 익스텐션과 Node.js 프로세스를 웹소켓으로 연결하는 방식입니다.

이 구조라면 사용자가 별도의 브라우저 프로필을 관리하지 않아도 되고,

평소 사용하던 로그인 세션을 대부분 그대로 활용할 수 있습니다.

5. 에필로그: 코드를 지우기 전에 문서를 고쳤다

방향이 정해지자마자 AI는 MVP코드를 만들어 준다고 하더군요. 그 방식은 REPL Works의 방식이 아닙니다.

PRODUCT_SPEC.md와 ARCHITECTURE.md와 FRAMEWORK.md와 TASKS.md를 먼저 새 구조에 맞게 전부 개정했습니다.

9222 포트와 Playwright 중심 구조를 제거하고, 새로운 Extension 기반 구조를 문서에 반영했습니다.

그리고 마지막 커밋을 남겼습니다.

docs: pivot the entire codes to incredible app (#22)

오늘 하루 동안 저는

• 삽질했고
• 실패했고
• 아키텍처를 갈아엎었고
• 문서를 다시 썼습니다.

그리고 그 모든 일을 하루 안에 끝냈습니다.

AI는 매우 유능한 프로그래머이자 아키텍쳐이자 디자이너이자 기획자입니다.

하지만 제가 크롬의 보안 모델을 이해하지 못한 상태에서

“(넌 나보다 머리가 좋으니)알아서 구현해 줘.”

라고 맡긴 순간, 저는 결과물을 검증할 능력을 잃어버렸습니다.

결국 문제는 AI가 아니라 저였습니다.

AI는 막다른 길까지는 엄청 빠르게 데려다 줍니다.

하지만

“(너가 아무리 머리가 좋아도)이 길은 안 된다.”

라고 판단하고 방향을 바꾸는 일은 아직 사람의 몫인 것 같습니다.

AI 시대의 개발자는 더 이상 모든 것을 직접 구현할 필요는 없을지도 모릅니다.

하지만 최소한,

“이 길은 막다른 길이다.”

라고 판단할 수 있을 정도의 이해는 여전히 필요하다는 것을 배웠습니다.

그런데 어느 날 예상하지 못한 장벽을 만나게 되었습니다.

바로 다른 회사, 다른 조직(Organization)의 저장소에도 이슈를 올려야 하는 상황이 생긴 것입니다.

1. 개인 토큰(PAT)의 한계

기존 ai-issue는 개발자의 개인 액세스 토큰(PAT)을 환경 변수나 설정 파일에 저장해 사용하는 방식이었습니다.

혼자 사용하는 도구라면 크게 문제 될 것이 없었습니다. 하지만 replworks 조직과 eternops 조직을 오가며 사용하기 시작하자 불편함이 생겼습니다.

• 조직마다 다른 PAT를 관리해야 하거나
• 하나의 토큰에 여러 조직 권한을 몰아 넣어야 하거나
• 토큰을 발급하고 복사해서 붙여넣는 과정 자체가 번거로웠습니다.

물론 Fine-grained PAT를 사용하면 권한 범위를 제한할 수는 있습니다. 하지만 여러 조직을 오가며 사용하는 CLI 도구의 사용자 경험으로는 여전히 만족스럽지 않았습니다.

개발자에게 가장 큰 적은 결국 마찰(Friction) 이라고 생각합니다.

사용자에게 긴 문자열 형태의 토큰을 요구하는 대신, TV나 넷플릭스 로그인처럼 브라우저에서 한 번 승인하면 끝나는 경험이 더 자연스럽다고 생각했습니다.

그래서 인증 구조를 GitHub App 기반 인증 + Device Flow 방식으로 전환하기로 했습니다.

2. GitHub App 세팅과 생각지 못한 반전

GitHub App을 만들면서 몇 가지 흥미로운 점을 발견했습니다.

1) 설치 범위는 Any account

앱 생성 과정에서 다음 항목은 반드시 Any account 로 설정해야 했습니다.

Where can this GitHub App be installed?

그래야 replworks 뿐만 아니라 eternops 같은 다른 조직에서도 동일한 앱을 설치하여 사용할 수 있습니다.

2) Webhook은 필요하지 않았습니다

ai-issue는 서버 애플리케이션이 아니라 로컬 터미널에서 동작하는 CLI 도구입니다.

GitHub 이벤트를 수신할 일이 없으므로 Webhook 기능은 비활성화하는 편이 더 깔끔했습니다.

3) Private Key는 런타임에서는 사용하지 않았습니다

GitHub App을 생성한 뒤 설치하려고 하니 GitHub은 Private Key(.pem)를 생성하라고 안내했습니다.

이번 프로젝트에서는 Device Flow를 통해 사용자 인증만 수행하기 때문에, 실제 CLI 실행 시점에는 Private Key를 사용하지 않습니다.

다만 GitHub App 생성 과정에서는 최소 한 번 Private Key를 생성해야 설치 기능이 활성화되므로, 키를 생성해 다운로드한 뒤 그대로 보관만 해두었습니다.

결국 CLI 내부에는 Client ID만 포함하면 충분했습니다.

사용자는 이제 다음과 같이 로그인할 수 있습니다.

❯ ai-issue login
Open this URL in your browser:
https://github.com/login/device
Enter this code: FCCC-5421
Browser opened automatically.
Login successful. Token saved locally.

❯ ai-issue diagnose
=== AI Issue Publisher Diagnostics ===
✅ Git: OK
✅ Repository validation: replworks/ai-issue
✅ Publisher validation: @replworks-bot
✅ Clipboard support: Available
✅ GitHub App token: Loaded
✅ Repository access: replworks/ai-issue

Run `ai-issue` to publish.

그러면 브라우저가 열리고 GitHub 인증을 한 번 수행한 뒤 여러 조직의 저장소에 자유롭게 이슈를 발행할 수 있게 됩니다.

3. 로컬 테스트 하려다 만난 Go 1.24 의존성 지옥

인증 구조를 바꾸고 로컬에서 테스트를 진행하던 중 또 다른 문제가 나타났습니다.

golangci-lint를 설치하지 않고 go run 방식으로 실행했더니, 깔끔하던 go.mod 파일에 수백 줄의 // indirect 의존성이 추가된 것입니다.

린트 도구 하나 실행했을 뿐인데 프로젝트의 가독성이 무너지는 모습은 보고 싶지 않았습니다.

그래서 선택한건 homebrew 였습니다.

# 더러워진 go.mod 복구
go mod tidy

# homebrew 로 설치
brew install golangci-lint

Makefile은 다음처럼 구성했습니다.

lint: ## runs golangci-lint via go run
 golangci-lint run ./...

덕분에 프로젝트 의존성과 개발 도구 의존성을 깔끔하게 분리할 수 있었습니다.

마치며

이번 작업을 하면서 느낀 것은, 잘 동작하던 도구도 사용 범위가 넓어지는 순간 기존 아키텍처의 한계가 드러난다는 점이었습니다.

PAT 기반 인증은 단순하고 익숙하지만, 여러 조직을 오가며 사용하는 CLI 도구에서는 Device Flow가 훨씬 자연스러운 사용자 경험을 제공해 주었습니다.

아직 완성된 것은 아니지만, 적어도 이제는 토큰을 발급하고 복사해서 붙여넣는 과정 없이 브라우저 인증 한 번으로 여러 조직의 저장소를 다룰 수 있게 되었습니다.

혹시 비슷한 문제를 겪고 계신다면 GitHub App과 Device Flow 조합을 한 번 검토해 보시는 것도 괜찮을 것 같습니다.

p.s.

1인 개발 프로젝트지만, 저는 결정, 승인 및 테스트를 하고, Discussion AI는 제안을, Execution AI는 코딩을 담당하는데요, 그것을 전통적인 개발팀이 개발하는 Git 개발 프로세스 그대로 운영하고 있습니다.

어떻게 운영되는지는 replworks/ai-issue 의 이슈메뉴에서 보실 수 있습니다.

같은 요구사항을 줘도 결과 코드의 방향이 계속 달라진다.

이 문제는 단순한 “프롬프트 문제”라기보다는, 조금 더 구조적인 문제일 가능성이 있습니다.

1. 현재 LLM 기반 개발 흐름의 구조

대부분의 AI 기반 개발 흐름은 대략 다음과 같이 구성됩니다.

IDEAS.md
→ PRODUCT_SPEC.md
→ ARCHITECTURE.md
→ FRAMEWORK.md
→ TASKS.md
→ AI Code Generation

이 구조는 충분히 잘 작동합니다. 하지만 실제로 TASK 단위로 AI를 실행해보면 문제가 발생합니다.

2. 문제: 매번 “전체 문서를 다시 해석”합니다

AI는 TASK 하나를 수행할 때마다 다음 과정을 반복합니다.

• PRODUCT_SPEC 전체를 다시 읽고
• ARCHITECTURE를 다시 해석하고
• FRAMEWORK 제약을 다시 적용하고
• TASK 정의를 다시 매핑합니다

이 과정은 명시적으로 보이지 않지만 항상 발생합니다.

그리고 여기서 다음과 같은 문제가 생깁니다:

• 문서 간 중요도 충돌
• 모델마다 다른 해석
• TASK마다 일관성 흔들림
• 불필요한 컨텍스트 노이즈

결과적으로 “같은 시스템인데 코드 스타일이 계속 달라지는 문제”가 발생합니다.

3. 아이디어: WORKING_SPEC이라는 “컴파일 결과물”

여기서 나온 아이디어가 하나 있습니다.

전체 설계를 매번 해석하지 말고,
TASK 단위로 “압축된 실행 명세”를 만들자

그 결과물이 WORKING_SPEC입니다.

4. WORKING_SPEC의 개념

WORKING_SPEC은 다음과 같은 역할을 합니다.

• PRODUCT_SPEC + ARCHITECTURE + FRAMEWORK + TASKS를 입력으로 받습니다
• 현재 TASK 기준으로 중요한 것만 남깁니다
• 나머지 정보는 제거하거나 비우선화합니다
• 실행에 필요한 정보만 남깁니다

즉:

PRODUCT_SPEC
ARCHITECTURE
FRAMEWORK
TASKS
↓
WORKING_SPEC (compressed execution IR)
↓
AI Code Generation

5. WORKING_SPEC은 “현재 작업용 사양서”입니다

WORKING_SPEC은 전체 시스템의 정의가 아닙니다.

오히려 반대에 가깝습니다.

“이번 TASK를 수행하기 위한 최소한의 실행 명세”

예를 들면 다음과 같습니다.

Task: VoiceSession cancellation

• Functional goal: interruption 시 TTS 즉시 중단
• Non-negotiable: state machine consistency 유지
• Constraint: Swift Concurrency only
• Constraint: Combine 사용 금지
• Requirement: cancellation latency < 100ms
• Requirement: OSLog event 반드시 기록

핵심은 이것입니다:

“AI가 지금 무엇을 중요하게 봐야 하는지”를 명시적으로 정의하는 것입니다.

6. 왜 이 구조가 의미가 있을 수 있는가

이 구조의 핵심 가설은 단순합니다.

기존 방식

AI는 매번 전체 문서를 해석합니다.

• 해석 비용이 매번 발생합니다
• 중요도 판단이 매번 달라질 수 있습니다
• 결과 코드도 흔들릴 수 있습니다

WORKING_SPEC 방식

해석을 구조적으로 줄이고, 실행에 집중합니다.

• TASK에 맞는 압축된 컨텍스트 제공
• 중요도 이미 정렬됨
• 모델은 “구현”에 집중

7. 사실 이것은 새로운 개념은 아닙니다

이 아이디어는 완전히 새로운 것은 아닙니다.

이미 유사한 개념들이 존재합니다:

• Compiler IR
• LLVM pass 구조
• Prompt chaining
• DSPy optimization
• Eval-driven prompt tuning

하지만 차이점이 하나 있습니다.

LLM 개발 전체를 “컴파일 파이프라인”으로 보는 관점입니다

8. Backend LLM 분기 가능성

이 구조가 흥미로운 이유는 여기서 확장됩니다.

WORKING_SPEC는 모델별로 변형될 수 있습니다.

WORKING_SPEC.gpt.md
WORKING_SPEC.claude.md
WORKING_SPEC.gemini.md

각 모델은 선호하는 입력 구조가 다르기 때문에:

• GPT: 간결한 constraint 중심
• Claude: 철학 + 구조 중심
• Gemini: 예시 중심

같은 WORKING_SPEC이라도 backend pass를 통해 변형할 수 있습니다.

9. 결과적으로 생기는 구조

이 관점에서 보면 전체 시스템은 다음과 같이 정리할 수 있습니다.

IDEAS.md

→ Design Layer
PRODUCT_SPEC.md
ARCHITECTURE.md
FRAMEWORK.md

→ Planning Layer
TASKS.md

→ Compilation Layer
WORKING_SPEC.md

→ Execution Layer
LLM Backend

10. 결론

이 아이디어의 핵심은 단순합니다.

LLM에게 “문서 전체를 이해하라”고 요구하는 것이 아니라
“지금 이 작업을 위한 최소 실행 사양만 보게 만드는 것”입니다

WORKING_SPEC는 모델을 더 똑똑하게 만드는 것이 아닙니다.

대신 다음을 목표로 합니다:

• 해석 비용을 줄이고
• 중요도를 미리 정렬하고
• 실행 단위를 명확하게 만드는 것

결과적으로 우리는 LLM을 단순한 코드 생성기가 아니라

“컴파일 타겟으로 취급할 수 있는 실행 엔진”

으로 바라보게 됩니다.

p.s.

이 개념에 대한 후속 논의는
https://github.com/replworks/replworks.github.io/issues/63
에서 이어갈 예정입니다.

AI와 함께 서비스를 개발하고 운영하면서 깨달은 것이 하나 있습니다.

창업자에게 가장 중요한 문서는 과연 무엇일까요?

많은 창업 관련 서적이나 투자자들은 스타트업을 시작할 때 다양한 문서를 준비하라고 이야기합니다.

• PRD
• BUSINESS.md
• METRICS.md
• EXECUTIVE_SUMMARY.md
• ROADMAP.md

저 역시 처음에는 그렇게 믿었습니다.

문서를 촘촘하게 만들고 체계적으로 관리할수록 사업이 더 명확해지고, 불확실성도 줄어들 것이라고 생각했습니다.

하지만 실제로 AI를 팀원처럼 활용하여 서비스를 처음부터 개발하기 시작하면서, 예상과는 다른 현상을 경험하게 되었습니다.

문서가 많아질수록 오히려 개발 속도가 느려지고, 시스템 전체에는 작은 균열들이 생기기 시작했던 것입니다.

가장 위험했던 문제는 Conflict of Sources, 즉 서로 다른 문서들이 서로 다른 진실을 말하는 상황이었습니다.

AI는 행간을 읽지 않습니다

예를 들어 BUSINESS.md에는 마진율이 30%라고 적혀 있고, METRICS.md에는 40%, EXECUTIVE_SUMMARY.md에는 35%라고 적혀 있다고 가정해 보겠습니다.

사람은 이런 상황을 보면 대체로 쉽게 이해합니다.

“아, 문서를 수정하는 과정에서 숫자가 일치하지 않게 남아 있었구나.”

하지만 AI는 그렇게 생각하지 않습니다.

AI는 어떤 문서가 가장 최근에 수정되었는지 알지 못합니다.

어떤 문서가 더 중요하게 관리되고 있는지도 판단하지 못합니다.

AI에게는 세 개의 문서가 모두 동일한 무게를 가진 사실입니다.

그리고 어느 순간 존재하지 않는 숫자를 만들어내기 시작합니다.

30%

40%

35%

↓

32.5%

AI는 사실 관계를 스스로 판단하지 않습니다.

인간이 제공한 문서를 사실로 받아들일 뿐입니다.

그래서 AI와 함께 일하는 시대에는 문서의 양보다,

오염되지 않은 단 하나의 Source of Truth를 정의하는 것

이 훨씬 중요해진다고 생각하게 되었습니다.

그런데 흥미로운 점은, 그 Source of Truth가 사람마다 완전히 다를 수 있다는 사실입니다.

저는 왜 PITCHING_SCRIPT.md만 계속 읽게 되었을까요?

처음에는 저도 다른 사람들처럼 다양한 문서를 만들었습니다.

PRD를 작성했고, BUSINESS.md도 만들었으며, METRICS.md와 EXECUTIVE_SUMMARY.md도 준비했습니다.

문서 자체는 모두 잘 작성되어 있었습니다.

그런데 몇 주가 지나자 이상한 일이 생겼습니다.

분명 많은 시간을 들여 만들었던 문서들인데, 정작 저는 거의 읽지 않게 되었습니다.

반대로 PITCHING_SCRIPT.md는 계속 읽고 있었습니다. 심지어 가장 먼저 만든 IDEAS.md 조차 몇일 몇주가 지나고 나서는 이해하기가 쉽지 않았습니다.

투자자, 파트너 혹은 사업 제안 당사자에게 보여주기 위해 만든 발표 대본이었는데도, 새로운 기능을 추가하려고 할 때, 사업 방향이 흔들릴 때, 우선순위를 다시 정해야 할 때, 저는 항상 이 문서를 다시 열어보게 되었습니다.

왜 그럴까요?

돌이켜보니 저는 사업을 문서가 아니라 하나의 이야기로 이해하는 사람이었습니다.

제 머릿속에서 사업은 항상 다음과 같은 순서로 정리됩니다.

왜 이 문제가 존재하는가?
↓
왜 지금 해결할 수 있는가?
↓
왜 내가 잘할 수 있는가?
↓
어떻게 돈을 버는가?
↓
어디까지 확장할 수 있는가?

저는 사업을 기능 목록으로 기억하지 않았습니다.

숫자로 기억하지도 않았습니다.

하나의 이야기로 기억하고 있었습니다.

그래서 저에게는 PITCHING_SCRIPT.md가 가장 좋은 Source of Truth였던 것입니다.

그런데 다른 창업자는 완전히 다를 수도 있습니다

어떤 사람들은 사업을 사용자 경험의 흐름으로 이해합니다.

User
↓
Pain Point
↓
Feature
↓
Metric
↓
Experiment

이런 분들에게는 PRD가 최고의 Source of Truth가 될 수 있습니다.

어떤 사람들은 사업을 시스템으로 이해합니다.

Input
↓
Process
↓
Output
↓
Failure Mode

이런 분들에게는 ARCHITECTURE.md가 더 중요할 수도 있습니다.

또 어떤 사람들은 숫자로 사업을 이해합니다.

Traffic
↓
Conversion
↓
Revenue
↓
Margin

이런 분들에게는 METRICS.md가 사업의 중심 문서가 될 가능성이 높습니다.

중요한 것은 문서의 종류가 아닙니다

저는 이제 Source of Truth는 문서의 이름이 아니라,

창업자의 인지 구조(Cognitive Style)에 의해 결정된다

고 생각하게 되었습니다.

그리고 좋은 Source of Truth는 세 가지 조건을 만족해야 합니다.

1. 창업자가 가장 자주 읽는 문서인가?

읽지 않는 문서는 존재하지 않는 것과 크게 다르지 않습니다.

2. AI가 읽었을 때 모순이 없는가?

AI는 인간처럼 행간을 읽지 못합니다.

문서를 믿습니다.

따라서 모순된 문서는 결국 AI를 혼란스럽게 만들게 됩니다.

3. 6개월 후의 내가 읽어도 즉시 이해할 수 있는가?

좋은 문서는 남을 설득하기 위한 문서가 아니라, 기억을 잃어버린 미래의 나를 설득하기 위한 문서라고 생각합니다.

AI 시대에 우리가 던져야 할 질문은,

“남들은 어떤 문서를 사용하는가?”

가 아니라,

“나는 어떤 방식으로 세상을 이해하는 사람인가?”

일지도 모릅니다.

그리고 그 질문에 대한 답이, 미래의 나와 AI가 같은 방향을 바라보게 만드는 진짜 Source of Truth를 결정한다고 생각합니다.

새로운 기능을 추가하려고 할 때, 여러분은 가장 먼저 어떤 문서를 열어보시나요?

• Pitching Script
• PRD
• Architecture
• Metrics Dashboard

아마 그 문서가, 여러분의 진짜 Source of Truth일 가능성이 높습니다.

돌이켜보면, 좋은 문서는 많이 만들어 둔 문서가 아니라, 시간이 지나도 계속 다시 열어보게 되는 문서였던 것 같습니다.

AI와 개발을 시작한 지 세 달 반 정도 되었습니다. 그리고, 몇개의 오픈소스를 공개하고, 활용하고 있습니다.

처음에는 저도 멀티 에이전트 프레임워크가 미래라고 생각했습니다. 직접 CrewAI를 사용해 보았고, LangGraph와 AutoGen도 공부했습니다.

“PM Agent”, “Architect Agent”, “Developer Agent”, “QA Agent”가 서로 협업하면서 서비스를 만들어 주는 모습을 상상하면 꽤 그럴듯해 보입니다.

하지만 결론부터 이야기하면, 저는 개발 프로젝트에서는 아직 사용할 이유를 찾지 못했습니다.

물론 제가 틀릴 수도 있습니다.

하지만 적어도 인하우스 서비스 개발과 운영 관점에서는 그렇습니다.

운영되는 서비스는 끝나지 않습니다

제가 20년 넘게 IT 업계에 있으면서 얻은 결론은 단순합니다.

운영되지 않는 코드는 자산이 아닙니다.

서비스는 출시하면 끝나는 것이 아닙니다.

사용자 피드백이 들어오고,

기능이 추가되고,

아키텍처가 수정되고,

때로는 기존 기능을 삭제해야 합니다.

이 과정은 몇 달이 아니라 몇 년 동안 반복됩니다.

그래서 중요한 것은 누가 무엇을 하는지가 아니라, 무엇이 바뀌었는가 입니다.

실제 애자일 팀은 역할이 계속 바뀝니다

인하우스 서비스를 운영하는 팀에서는 역할이 고정되어 있지 않습니다.

• PM이 직접 코드를 읽습니다.
• 개발자가 기획을 수정합니다.
• QA가 아키텍처 변경을 제안합니다.
• CTO가 지표를 보고 기능 삭제를 결정합니다.

하지만 대부분의 Agent Framework는 다음과 같은 구조를 전제로 합니다.

PM Agent
-> Architect Agent
-> Developer Agent
-> QA Agent

인간 조직을 모델링하는 방식입니다.

하지만 운영 중인 서비스는 조직도를 따라 진화하지 않습니다.

운영 중인 서비스는 문제를 발견하고,

명세를 수정하고,

아키텍처를 변경하고,

다시 배포하는 피드백 루프로 진화합니다.

저는 결국 문서 몇 개만 남겼습니다

2주 정도 Agent Framework를 공부한 뒤, 저는 오히려 더 단순한 구조로 돌아왔습니다.

PRODUCT_SPEC.md
↓
ARCHITECTURE.md
↓
FRAMEWORK.md
↓
TASKS.md
↓
AGENTS.md
↓
AI
↓
Code

아키텍처가 바뀌면 ARCHITECTURE.md를 수정합니다.

기능이 추가되면 TASKS.md를 수정합니다.

AI가 지켜야 할 규칙은 AGENTS.md에 정의합니다.

문서의 변경 이력은 Git이 관리합니다.

서비스를 운영하다가 문제가 발생하면 문서를 수정하는 것이 아니라 GitHub Issue를 생성합니다.

그리고 사람이 판단해서 다음 작업을 TASKS.md에 반영합니다.

현재까지는 이 방식이 제가 찾은 가장 단순하고 관리 가능한 AI 개발 방식입니다.

Agent Framework가 실패한다고 생각하지는 않습니다

저는 CrewAI, LangGraph, AutoGen이 실패할 것이라고 주장하지 않습니다.

다만 아직까지는 개발 프로젝트를 운영하면서 계속 진화시키는 문제를 해결하기에는 너무 조직 중심적이라고 느꼈습니다.

그리고 AI와 개발을 막 시작한 사람이라면, CrewAI를 공부하는데 2주를 쓰기 전에, 먼저 PRODUCT_SPEC.md 하나를 만들고 서비스를 세상에 배포해 보는 것을 추천합니다.

서비스는 운영되기 시작하는 순간부터 배움을 줍니다.

운영되는 제품은 자산이 될 수 있습니다.

하지만 아직 운영되지 않는 Agent Graph는 적어도 제게는 자산처럼 느껴지지 않았습니다.

2주를 쓰고 얻은 개인적인 결론입니다.

혹시 저처럼 AI 개발을 시작하며 Agent Framework를 공부하고 계신다면, 잠시 멈추고 스스로에게 질문해 보시기 바랍니다.

내가 만들고 싶은 것은 AI 조직인가?

아니면 운영되는 제품인가?

p.s. 혹시 Agent Framework 를 사용해서 개발 프로젝트 온보딩과 운영을 성공적으로 하신 분이 있다면 공유해 주세요.

Cursor, Claude Code, Lovable 같은 도구를 이용하면 몇 줄의 자연어만으로 웹 서비스와 모바일 앱을 만들 수 있습니다. 유튜브와 커뮤니티에는 “개발을 몰라도 앱 만드는 법”, “10분 만에 SaaS 출시하기” 같은 콘텐츠가 넘쳐나고, AI 코딩을 가르치는 강사들도 빠르게 늘어나고 있습니다.

기술의 발전 자체는 분명 놀랍습니다.

하지만 20년 넘게 IT 업계에서 여러 회사의 성장과 실패, 그리고 청산 과정을 지켜본 사람으로서 한 가지 우려가 있습니다.

AI를 이용해 개발하는 사람들이 많아졌지만, 아직까지 AI를 이용해 만든 서비스가 독립적인 산업을 만들거나 거대한 부가가치를 창출했다는 사례는 많지 않습니다.

오히려 가장 먼저 눈에 띄는 수익 모델은 AI 코딩 교육 시장인 것처럼 보입니다.

물론 이것이 AI 코딩이 실패했다는 뜻은 아닙니다.

저는 오히려 AI가 개발자와 창업자에게 주어진 가장 강력한 생산성 도구라고 생각합니다.

다만 많은 사람들이 한 가지 사실을 오해하고 있는 것 같습니다.

코드는 자산이 아닙니다.

정확히 말하면,

운영되고 있는 시스템만이 자산입니다.

개발자들이 잘 모르는 회계와 세법의 현실

많은 개발자들은 자신이 만든 코드가 회사의 자산이라고 생각합니다.

하지만 회계와 세법은 생각보다 훨씬 냉정합니다.

회사가 직접 개발한 ERP, 그룹웨어, 플랫폼 같은 인하우스(In-house) 시스템은 자동으로 자산이 되지 않습니다.

회계기준(K-IFRS)은 다음 조건을 모두 만족하는 경우에만 개발비를 무형자산으로 인식하도록 허용합니다.

• 기술적으로 완성 가능할 것
• 완성 후 사용할 의도가 있을 것
• 사용할 능력이 있을 것
• 미래 경제적 효익이 예상될 것
• 개발 완료에 필요한 자원을 확보할 수 있을 것
• 개발 비용을 신뢰성 있게 측정할 수 있을 것

이 조건을 만족하지 못하면 개발자의 인건비는 그해 비용으로 처리되고 손익계산서에서 사라집니다.

설령 무형자산으로 인식되더라도 끝이 아닙니다.

소프트웨어가 오픈되면 일반적으로 수년간 감가상각되며, 기대했던 경제적 효익을 창출하지 못하면 손상차손(Impairment Loss)을 인식해야 합니다.

즉, 장부상 수십억 원으로 기록되어 있던 개발비가 몇 년 뒤 거의 가치가 없는 자산으로 정리되는 일은 생각보다 흔합니다.

저는 20년 넘게 IT 업계에 있으면서 여러 시스템의 탄생과 죽음을 보았습니다.

수십억 원을 들여 만든 ERP와 플랫폼,

몇 년 동안 수십 명의 개발자가 투입된 서비스,

대형 SI 프로젝트의 결과물들.

하지만 회사가 청산되는 순간 그 코드를 사겠다는 사람은 거의 없었습니다.

인수자가 사는 것은 코드가 아니라,

• 고객
• 계약
• 데이터
• 운영 프로세스
• 현금 흐름

이었습니다.

개발자들이 흔히 외치는

“코드는 자산이다”

라는 말은 비즈니스 관점뿐 아니라 회계 장부 위에서도 상당 부분 성립하지 않습니다.

AI 시대의 성공 사례들은 무엇을 말하고 있을까?

AI를 적극 활용해 빠르게 성장한 서비스들은 이미 등장하고 있습니다.

Base44

이스라엘 개발자 Maor Shlomo는 AI를 적극 활용해 Base44를 개발했습니다.

서비스 출시 후 약 6개월 만에 약 25만 명의 사용자를 확보했고, 2025년 6월에는 Wix가 Base44를 8천만 달러 현금으로 인수했습니다.

흥미로운 점은 Wix가 산 것이 소스코드 파일이 아니라는 것입니다.

Base44는 이미 운영되고 있었고, 사용자가 존재했고, 매출이 발생하고 있었으며, 제품-시장 적합성(Product-Market Fit)을 검증한 상태였습니다.

Lovable

AI 기반 앱 빌더인 Lovable 역시 매우 작은 조직으로 빠르게 성장하고 있습니다.

Lovable의 경쟁력은 코드 생성 기술 자체가 아니라,

사용자들이 서비스를 만들고,

배포하고,

실패하고,

다시 시도하는 과정에서 축적되는 운영 데이터와 고객 경험입니다.

AI 코딩의 진짜 가치

AI는 코드를 대신 작성해 줄 수 있습니다.

하지만 사용자의 불만을 해결해주지는 않습니다.

AI는 결제 시스템을 붙여줄 수는 있어도 고객이 왜 돈을 내는지는 알려주지 않습니다.

AI는 로그인 화면을 만들어줄 수는 있어도 시장이 원하는 제품이 무엇인지는 대신 찾아주지 않습니다.

AI 코딩의 진짜 가치는 코드를 더 많이 생산하는 데 있는 것이 아닙니다.

AI 코딩의 진짜 가치는

시장 검증까지 걸리는 시간을 극단적으로 줄여주는 것

에 있습니다.

예전에는 아이디어 하나를 검증하기 위해 몇 달이 필요했다면, 지금은 며칠 안에도 운영 가능한 수준까지 도달할 수 있습니다.

AI 시대 개발자들의 목표는 달라져야 한다

서비스를 만들었다면 가능한 한 빨리 공개하십시오.

사용자가 한 명이라도 들어오게 하십시오.

누군가 실제로 돈을 내는지 확인하십시오.

반응이 없다면 미련 없이 버리고 다음 아이디어를 시도하십시오.

AI 시대의 경쟁력은 얼마나 많은 코드를 작성했는지가 아니라,

얼마나 많은 운영 사이클을 돌렸는가

에 달려 있다고 생각합니다.

AI를 배우는 사람들이 많아지는 것은 좋은 일입니다.

하지만 1년 뒤에도 대부분의 사람들이 여전히

“만들어 본 프로젝트”

만 이야기하고 있고,

실제로 운영하며 수익을 내는 사람은 거의 없다면 우리는 AI를 잘못 사용하고 있는 것인지도 모릅니다.

AI는 우리를 부자로 만들어주는 마법 지팡이가 아닙니다.

AI는 단지 더 빨리 만들고,

더 빨리 실패하고,

더 빨리 운영 단계에 도달하게 해주는 도구입니다.

그리고 결국 살아남는 것은 가장 많은 코드를 만든 사람이 아니라,

가장 빨리 세상에 서비스를 던지고,

가장 오래 운영한 사람일 것입니다.

개발자들은 코드를 자산이라고 믿지만, 회계 장부는 대부분의 코드를 비용으로 처리합니다.

AI 시대에 희소한 것은 코드가 아니라 운영입니다.

중국 정부의 강력한 인터넷 차단 시스템인 만리방화벽(Great Firewall, GFW) 때문인데요. 현지에서도 평소처럼 막힘없이 키보드를 두드리기 위해 출국 전 반드시 설정해야 할 필수 개발 환경과 네트워크 설정을 정리했습니다.

0. 로밍 회선 하나는 반드시 준비하기

VPN이 모두 막히거나 설정이 꼬였을 때를 대비해, 한국 통신사의 데이터 로밍이나 중국 외 지역 경유형 eSIM을 준비해 두는 것이 좋습니다.

많은 경우 로밍 회선은 만리방화벽의 영향을 덜 받기 때문에 긴급 상황에서 GitHub, Slack, Google Workspace 등에 접속할 수 있는 최후의 백업 수단이 됩니다.

1. 네트워크의 핵심: 중국 대응 VPN 설정

중국에서 일반적인 OpenVPN, WireGuard 연결은 DPI에 의해 불안정하거나 차단될 수 있습니다. 따라서 일반 유료 VPN을 그냥 켜는 것만으로는 부족합니다.

• 출국 전 결제 및 설치 필수: 중국에 도착하면 VPN 공식 홈페이지와 앱스토어 다운로드 주소 자체가 차단됩니다. 반드시 한국에서 메인과 백업용(최소 2개 추천) VPN을 설치하고 로그인까지 끝내두세요.
• 난독화(Obfuscation) 기능 활성화: VPN 서비스가 제공하는 난독화 서버나 중국 전용 서버를 사용합니다. ExpressVPN, Astrill 등 일부 서비스는 자체 우회 기술을 제공하며 중국에서 상대적으로 안정적인 편입니다.
• 라우팅 분할(Split Tunneling) 활용: 모든 트래픽을 VPN으로 보내면 속도가 느려집니다. GitHub나 개발 관련 툴만 VPN을 타게 하고, 중국 현지 인프라나 바이두 등은 바이패스하도록 설정하면 쾌적합니다.

2. 패키지 매니저 및 도커(Docker) 미러 서버 변경

VPN이 가끔 불안정하거나 끊길 때를 대비해, 패키지 다운로드 속도가 기어가지 않도록 환경 설정 파일(rc 파일 등)에 미리 글로벌/중국 로컬 미러 서버를 등록해 두는 것이 좋습니다.

NPM / Yarn (Node.js)

중국 내에서 가장 빠른 타오바오(Taobao) 미러 서버로 임시 변경해 둡니다.

# NPM 미러 변경
npm config set registry https://registry.npmmirror.com

# Yarn 미러 변경(Yarn 버전에 따라 설정 방식이 다를 수 있음)
yarn config set registry https://registry.npmmirror.com

Docker Hub

공용 Docker Hub 미러 대부분이 중단되었기 때문에, VPN/프록시를 통한 직접 접근이나 사설 레지스트리 사용을 준비하는 것이 더 현실적입니다.

3. IDE 및 깃(Git) 프록시(Proxy) 강제 지정

IDE(IntelliJ, VS Code 등) 내부에서 플러그인을 업데이트하거나, 터미널에서 git clone을 받을 때 VPN이 켜져 있어도 split tunnel 설정, TUN 모드 여부, 로컬 프록시 방식 등에 따라 달라집니다. 로컬 프록시 방식 VPN을 사용하는 경우에는 Git이나 IDE가 프록시를 사용하지 않아 우회가 되지 않을 수 있습니다.

Git 글로벌 프록시 설정 (로컬 VPN 포트 기준)

유료 VPN들이 로컬에 열어두는 프록시 포트(보통 고유 설정에서 확인 가능, 예: 1080 또는 7890 등)를 Git에 강제로 지정합니다.

# HTTP/HTTPS 프록시 적용
git config --global http.proxy http://127.0.0.1:포트번호
git config --global https.proxy http://127.0.0.1:포트번호

# 출장 복귀 후 해제할 때
git config --global --unset http.proxy
git config --global --unset https.proxy

IDE 내부 Proxy 설정

• IntelliJ / WebStorm: Settings -> Appearance & Behavior -> System Settings -> HTTP Proxy 이동 후 Manual proxy configuration에서 로컬 VPN 호스트와 포트를 입력해 둡니다.
• VS Code: 설정에서 Http: Proxy 항목에 로컬 프록시 주소(예: http://127.0.0.1:7890)를 지정하면 Copilot 등의 확장 프로그램이 보다 안정적으로 동작합니다.

4. 2차 인증(MFA) 수단 오프라인 백업

의외로 많은 개발자가 놓쳐서 멘붕이 오는 지점입니다. GitHub나 사내 시스템 로그인 시 2중 인증 등을 사용하실 텐데요.

• 중국에서 유심을 갈아끼우거나 로밍 처리를 하다가 기기 인증이 풀리는 경우가 있습니다.
• 만약 SMS 인증으로만 2차 인증을 해두었다면, 중국 현지에서 한국 문자가 제때 수신되지 않아 아예 계정이 잠길 수 있습니다.
• 대책: 출국 전, GitHub, AWS, Google Workspace, 사내 SSO 등의 MFA 복구 코드를 미리 백업해 두세요.

🚀 출장 출발 전 최종 체크리스트

• 노트북 및 스마트폰에 유료 VPN 2개 이상 설치 완료 (난독화 서버 구동 확인)
• 해외 로밍 또는 중국 외 지역(홍콩·대만 등) 경유형 데이터 eSIM 준비 완료
• GitHub, AWS, 사내 인프라 계정의 ‘오프라인 복구 코드’ 백업 완료
• 프로젝트 의존성 설치 및 초기 빌드가 정상 동작하는지 한국에서 미리 검증
• GitHub Copilot, Claude Code, Cursor 등의 AI 개발 도구가 VPN 환경에서 정상 동작하는지 사전 확인

만리방화벽은 생각보다 촘촘하지만, 사전 준비를 잘 해두면 대부분의 개발 업무를 큰 문제 없이 이어갈 수 있습니다. 미리 설정하셔서 현지에서 당황하는 일 없으시길 바랍니다!

“중국 구글 주소가 따로 있나요? google.cn으로 들어가면 되나요?”

중국에서 막히는 서비스는 무엇일까?

중국 본토에서는 다음과 같은 해외 서비스가 제한되는 경우가 많습니다.

• Google
• Gmail
• YouTube
• Google Maps
• Facebook
• Instagram
• X(Twitter)
• WhatsApp

결론부터 말씀드리면, 단순히 주소(URL)만 입력해서 들어갈 수 있는 ‘우회용 중국 구글 주소’는 존재하지 않습니다. 과거 구글의 흔적이 남은 주소는 있지만, 실제 검색을 하려면 주소가 아니라 접속하는 망(IP)을 바꿔야 합니다.

오늘은 중국 구글 주소에 얽힌 흥미로운 진실과 함께, 현지에서 구글 및 필수 서비스(유튜브, 카톡 등)를 이용할 수 있는 현실적인 가이드를 정리해 드립니다.

1. 중국 구글 주소 google.cn의 진실

많은 분들이 궁금해하시는 google.cn은 실제로 구글이 소유한 중국 공식 도메인이 맞습니다. 하지만 지금 이 주소로 접속하면 다음과 같은 현상이 일어납니다.

• 홍콩 구글로 자동 전환: 과거에는 google.cn을 입력하면 검색 기능이 살아있는 홍콩 구글 주소(google.com.hk)로 리다이렉트되었습니다.(과거 2010년 구글이 중국 정부의 검열 정책에 반대하며 본토 검색 서비스를 철수했기 때문입니다.)
• 결국은 차단: 우회 프로그램을 쓰지 않은 중국 본토 안에서는 이 홍콩 구글 주소마저 만리방화벽(Great Firewall)에 막혀 “사이트에 연결할 수 없음” 메시지만 뜨게 됩니다.
• 현재의 용도: 지금은 리다이렉트는 중단되고 링크만 살아있는 랜딩페이지가 노출되고 있습니다.

2. 중국에서 구글을 뚫는 가장 확실한 방법 3가지

주소 입력만으로는 해결할 수 없기 때문에, 우리는 만리방화벽을 우회하는 기술을 써야 합니다. 실무 환경과 체류 기간에 따라 가장 알맞은 방법을 선택하세요.

방법 A. 해외 eSIM(이심) 사용 (단기 출장/여행 강추)

인터넷에서 ‘중국 전용 데이터 eSIM’을 구매해 스마트폰에 등록하는 방법입니다.

• 원리: 중국 현지 통신망이 아닌, 홍콩·대만·한국 등 해외 망을 경유하여 로밍 형태로 데이터를 처리합니다. 만리방화벽의 검열 대상에서 아예 제외되기 때문에 별도의 VPN 앱을 켤 필요 없이 기존 구글 주소(google.com)로 즉시 접속됩니다.
• 장점: 속도가 가장 안정적이고 배터리 소모가 적습니다.
• 주의: VPN이나 기업 전용 회선 혹은 일부 국제 회선이 아닌 일반적인 상황에서 호텔이나 카페의 현지 와이파이(Wi-Fi)에 연결하는 순간 다시 구글이 막히므로, 현지에서는 와이파이를 끄고 모바일 데이터만 사용해야 합니다.

방법 B. 난독화 기능이 포함된 유료 VPN (장기 체류 필수)

노트북 작업을 해야 하거나 현지 와이파이를 무제한으로 써야 한다면 중국 대응 기능(Obfuscation, Stealth Protocol 등)을 제공하는 유료 VPN이 필수입니다.

• 핵심 팁: 중국의 인터넷 검열 시스템은 일반적인 VPN 트래픽도 탐지하여 차단하는 경우가 많습니다. 따라서 단순 연결이 아닌, 앱 설정에서 ‘난독화(Obfuscation) 프로토콜’ 옵션을 반드시 활성화해야 검열 시스템을 속이고 구글에 접속할 수 있습니다.
• ⚠️ 출국 전 필수 사항: 반드시 한국에서 미리 앱을 다운로드하고 결제까지 완료해야 합니다. 중국 공항에 내리는 순간 VPN 공급업체의 홈페이지 자체가 차단되어 앱 설치가 불가능해집니다.

방법 C. 국내 통신사 로밍 요금제

기존에 사용하던 스마트폰 통신사(SKT, KT, LGU+)의 로밍 서비스를 신청하는 방법입니다.

• 원리: eSIM과 마찬가지로 국내 통신망을 거쳐 나가므로 구글, 유튜브, 카카오톡 모두 아무런 제약 없이 작동합니다.
• 장점: 한국에서 오는 전화나 문자(본인 인증 등)를 그대로 수신해야 하는 비즈니스 업무 시 가장 안전합니다.

🚀 요약 가이드

중국에서 구글을 사용하려면 특별한 URL을 찾는 것이 아니라, 중국 검열 시스템(만리방화벽)의 영향을 받지 않는 인터넷 경로를 확보해야 합니다. 실제로 여행자와 출장자들은 국제 로밍, 해외 eSIM, 또는 중국 대응 기능이 포함된 VPN을 이용하는 경우가 많습니다.

1. “비밀 주소는 없다”: google.cn이든 뭐든 주소만으로는 안 됩니다. 일반 google.com 주소를 쓰되 망을 우회해야 합니다.
2. 3박 4일 내외 가벼운 일정: 복잡한 설정 없이 뇌 비우고 쓸 수 있는 해외 데이터 eSIM이 가성비와 정신 건강에 가장 좋습니다.
3. 노트북 작업이 많은 개발자/스타트업: 출국 전 성능 좋은 유료 VPN을 미리 세팅하고 현지 와이파이와 조합하여 사용하세요.