지난 2년 동안 모든 것이 시스템이 되었습니다.

OpenAI API를 호출하고 데이터베이스에 쓰는 Python 스크립트? 시스템. 양식이 제출될 때 Slack으로 알림을 보내는 Zapier 자동화? 통합(Integration). 두 개의 프롬프트를 연결한 것? 에이전트 아키텍처(Agent architecture). 위젯 세 개가 있는 대시보드? 플랫폼(Platform).

최근에 기술 관련 LinkedIn이나 기술 트위터를 읽었다면, 이런 느낌을 받았을 겁니다. 어휘력이 부풀려졌어요. 솔직히 말해서 저도 그랬습니다. 작년 어느 곳의 소개글(bio), 레포지토리 README, 또는 해커톤 제출물에서 저는 실제로는 시스템이 아닌 것을 '시스템'이라고 불렀습니다. 자세히 살펴보니, 거창한 망상에 빠진 스크립트에 지나지 않았죠.

AI 시대는 모두에게 새로운 어휘를 주었습니다. 하지만 그 어휘가 실제로 묘사하는 대상 자체는 모두에게 주지 않았습니다. 우리가 사용하는 단어와 우리가 구축한 것 사이의 간극은 기술 글쓰기를 코스튬 파티로 만들고 있습니다.

우리가 여기에 오게 된 과정

같은 방향을 가리키는 두 가지 힘이 있었습니다.

첫째, LLM(대규모 언어 모델)들이 기업 블로그 포스트처럼 글을 씁니다. 대규모 언어 모델은 인터넷의 지배적인 레지스터(register)로 학습되었고, 이 자체가 이미 부풀려져 있었습니다. 누군가 ChatGPT를 열고

그 결과: 우리 모두는 자신의 실제 복잡성 수준보다 더 높은 수준의 글을 쓰고 있습니다. 그리고 대부분의 독자는 이를 구분하지 못하며, 바로 그 점 때문에 이 방식이 통용되고 있고, 바로 그 점 때문에 우리는 이를 멈춰야 합니다.

목록

가장 심각한 다섯 가지 사례입니다. 각 사례에 대해: 그것이 무엇이 되었는지, 실제로는 무엇이었는지, 그리고 더 정직한 문장은 어떤 모습인지 살펴보겠습니다.

1. "시스템 (System)"

부풀려진 표현: "우리 플랫폼에서 사용자 행동을 추적하기 위한 시스템을 구축했습니다." 실제 내용: "PostHog를 연결하고 프론트엔드에 이벤트 호출 (event calls)을 추가했습니다."

시스템은 구성 요소 (components)를 가집니다. 아키텍처 (Architecture). 부품 간의 트레이드오프 (Tradeoffs). 만약 당신의 "시스템"이 단 하나의 스크립트이거나, 단 하나의 통합 (integration)이며, 데이터가 모이는 단 한 곳뿐이라면 그것은 시스템이 아닙니다. 그것은 단순한 연결 (hookup)입니다. 그렇게 부르십시오.

2. "통합 (Integration)"

부풀려진 표현: "원활한 결제를 위해 Stripe를 우리 플랫폼과 통합했습니다." 실제 내용: "Stripe SDK를 임포트 (import)하고 체크아웃 페이지를 연결했습니다."

통합 (Integration)은 과거에 오류 처리 (error handling), 재시도 (retries), 모니터링 (monitoring), 그리고 그 접점을 책임지는 관리자가 있는 상태에서, 두 시스템이 내구성이 있고 유지보수 가능한 방식으로 서로 통신하는 법을 배우는 것을 의미했습니다. SDK 임포트를 "통합"이라고 부르는 것은 그 단어가 과거에 담고 있던 의미를 평면화시킵니다. 정직한 버전은 대개 다음과 같습니다: "그들의 SDK를 사용했습니다."

3. "에이전트 (Agent)"

부풀려진 표현: "회의록을 요약하는 에이전트를 구축했습니다." 실제 내용: "전사된 텍스트 (transcript)를 Claude로 보내고 요약본을 반환하는 함수 (function)를 작성했습니다."

"에이전트 (Agent)"라는 단어는 이제 자율성 (autonomy), 계획 (planning), 도구 사용 (tool use), 그리고 여러 단계에 걸친 의사결정 (decision-making)을 암시합니다. for-loop 안에서 실행되는 단발성 (one-shot) LLM 호출은 에이전트가 아닙니다. 그것은 우연히 LLM을 호출하는 함수일 뿐입니다. 그것이 잘못된 것은 아닙니다; 그것은 종종 해당 작업에 정확히 적절한 복잡성 수준이기도 합니다. 하지만 그것을 에이전트라고 부르는 것은 과장된 판매가이며, 진짜 에이전트가 무엇인지에 대한 가치를 저평가하는 것입니다.

4. "파이프라인 (Pipeline)"

부풀려진 표현: "다양한 소스에서 고객 신호를 수집하는 데이터 파이프라인을 구축했습니다." 실제 내용: "크론 (cron) 작업으로 세 개의 API에서 데이터를 가져와 Google Sheet에 넣는 스크립트를 작성했습니다."

파이프라인 (Pipeline)은 단계 (stages), 변환 (transformations), 에러 경계 (error boundaries), 재시도 (retries), 배압 처리 (backpressure handling), 그리고 관찰 가능성 (observability)을 갖추고 있습니다. 스프레드시트로 이어지는 순차적인 API 호출은 그런 것이 아닙니다. 그것은 단순한 페치 작업 (fetch job)입니다.

1. "프로덕션 레디 (Production-ready)"

부풀려진 표현: "이 시스템은 프로덕션 레디 (production-ready)이며 엔터프라이즈급 (enterprise-grade)입니다." 실제 내용: "내 컴퓨터에서 돌아가고 있으며 지난 한 시간 동안 다운되지 않았습니다."

프로덕션 레디 (Production-ready)는 구체적인 의미를 담고 있습니다: 에러 처리 (error handling), 구조화된 로깅 (structured logging), 관찰 가능성 (observability), 부하 테스트 완료 (tested under load), 배포 가능성 (deployable), 보안 (secure), 그리고 시스템이 고장 났을 때 대응할 온콜 (on-call) 인력이 있어야 함을 의미합니다. 엔터프라이즈급 (Enterprise-grade)은 이러한 요소들에 서비스 수준 협약 (SLA), 컴플라이언스 (compliance), 그리고 멀티 테넌트 안전성 (multi-tenant safety)이 더해진 것을 의미합니다. 만약 당신의 작업물이 이 중 어느 것도 갖추지 못했다면, 그것 또한 프로덕션 레디도 엔터프라이즈급도 아닙니다. 그것은 작동하는 프로토타입 (prototype)일 뿐이며, 다시 말하지만 프로토타입을 갖는 것 자체는 아주 좋은 일입니다.

이것이 왜 중요한가 (미학적인 측면을 넘어)

"짜증 난다"는 수준을 넘어선 두 가지 이유가 있습니다.

첫째: 숙련된 독자는 즉시 알아차릴 수 있습니다. 당신의 부풀려진 포스트를 읽는 모든 시니어 엔지니어 (senior engineer), 모든 경험 많은 데브렐 (DevRel) 담당자, 모든 기술 창업자 (technical founder)는 당신이 실제로 무엇을 만들었는지 파악하기 위해 어휘들을 훑으며 동일한 정신적 뺄셈을 수행합니다. 그들이 글의 끝에 도달하여 그것이 단순한 스크립트였다는 것을 깨닫는 순간, 당신이 사용한 어휘들은 그들의 신뢰를 앗아갔을 것입니다. 당신이 가장 도달하고 싶었던 바로 그 독자들에게 신뢰를 잃은 것입니다. 당신을 똑똑하게 보이게 만들려 했던 단어들이 오히려 그 반대로 보이게 만들었습니다.

둘째: AI 어시스턴트(AI assistants)는 모호한 글에서 구체적인 주장(claims)을 추출할 수 없습니다. 이전 포스트에서 저는 William Imoh가 정의한 AEO(Answer Engine Optimization)에 대해 썼습니다. 즉, 이제 콘텐츠는 단순히 Google에서 순위를 높이는 것뿐만 아니라, AI 어시스턴트(ChatGPT, Perplexity, Claude)가 인용할 수 있어야 한다는 내용이었습니다. 과장된 글쓰기는 바로 이 지점에서 실패합니다. Perplexity가 "Stripe를 Next.js 앱에 어떻게 연결하나요?"라는 질문에 대한 답변을 생성할 때, 시스템은 구체적인 지침, 실제 예시, 명명된 라이브러리, 작동하는 패턴을 가져와야 합니다. "우리는 프로덕션급 플랫폼에 Stripe를 원활하게 통합했습니다"라고 말하는 블로그 포스트는 건너뛰어집니다. 반면 "클라이언트에 @stripe/stripe-js를 추가하고 환경 변수(env var)에 시크릿 키를 넣어 /api/checkout 핸들러를 설정했습니다"라고 말하는 블로그 포스트는 인용됩니다.

구체성(Specificity)이 새로운 SEO입니다. 어휘의 인플레이션(Vocabulary inflation)은 구체성의 반대입니다. 그것이 바로 DevRel(Developer Relations)의 비용입니다.

실제로 구축한 것처럼 쓰는 법

제가 스스로 지키려고 노력하는 몇 가지 작동 원칙입니다. 규칙이 아니라 습관입니다.

가장 작고 정확한 단어를 사용하세요. 스크립트(script)라면 스크립트라고 하세요. 함수(function)라면 함수라고 하세요. SDK 호출(SDK call)이라면 그대로 쓰세요. 더 작은 단어가 정확성을 잃을 때만 더 큰 단어를 찾으세요.

명사보다 동사를 선호하세요. "X와 Y 사이의 통합(integration)을 구축했습니다"보다 "X를 Y에 연결했습니다"가 더 강력하게 전달됩니다. 동사는 동작을 설명합니다. 명사는 추상화(abstractions)를 설명합니다. 동작이 실제로 일어난 일입니다.

구체적인 구성 요소를 명시하세요. "시스템 프롬프트(system prompt)와 도구 정의(tool definition)를 사용한 Claude Sonnet 4.5 기반의 LLM 호출"은 "AI 기반 에이전트 워크플로우(AI-powered agent workflow)"보다 매번 더 낫고, 심지어 더 짧습니다.

분류하지 말고 보여주세요. 당신의 프로젝트가 어떤 카테고리에 속하는지 설명하는 대신("확장 가능하고 프로덕션 준비가 된 AI 관측성(observability) 플랫폼"), 독자가 검증할 수 있는 단 하나의 구체적인 문장으로 무엇을 하는지 설명하세요. 독자가 검증할 수 없다면, 주장하지 마세요.

가장 위험한 두 형용사인 'robust(강건한)'와 'seamless(매끄러운)'를 삭제하세요. 두 단어 모두 아무런 의미가 없습니다. 두 단어 모두 당신이 무언가를 구축하기보다 설명하고 있다는 신호입니다. 만약 당신의 작업물이 robust하다면, 그것이 무엇을 처리하는지에 대한 설명만으로도 그 사실은 명백해질 것입니다. 그 단어는 필요하지 않습니다.

회의적인 시니어 엔지니어의 관점에서 초안을 다시 읽어보세요. 모든 주장마다 스스로에게 물으세요. '내가 화이트보드 앞에서 이 말을 한다면, 이를 방어할 수 있는가?' 만약 그렇지 않다면, 삭제하거나 수위를 낮추세요. 과장된 글의 대부분은 소리 내어 읽는 순간 생명력을 잃습니다.

메타 포인트 (The meta point)

DevRel (Developer Relations)은 본질적으로 번역 행위입니다. 실제적이고 복잡한 무언가를 가져와서 독자가 실제로 이해할 수 있도록 표현하는 것입니다. 명확하게 만드는 대신 부풀리기만 하는 모든 단어는 직무에 반하는 단계입니다.

누구나 3초 만에 자신감 있어 보이는 기술 문서를 생성할 수 있는 시대에, 차별점은 정밀함 (precision)입니다. 어휘력이 아닙니다. 톤 (tone)도 아닙니다. 표 (tables)도 아닙니다. 바로 정밀함입니다.

제가 현재 읽고 있는 최고의 기술 작가들은 AI가 부풀려 놓은 일반적인 흐름과는 반대 방향으로 움직이고 있습니다. 더 짧은 단어. 더 구체적인 동사. 더 적은 형용사. 자신이 무엇을 만들었는지 실제로 알고 있다는 데서 오는 조용한 자신감 말입니다.

그러니, 당신의 GitHub에 있는 그 프로젝트 말인가요? README를 읽어보세요. 만약 첫 번째 문단이 기업용 발표 자료 (corporate deck)에서 나온 것처럼 읽힌다면, 아마 실제로 그렇게 작성되었을 것입니다. 마치 술집에서 시니어 엔지니어에게 당신이 실제로 무엇을 만들었는지 이야기하듯 다시 작성하세요. 사람들이 신뢰할 버전은 바로 그 버전입니다. AI 어시스턴트가 인용할 버전도 바로 그 버전입니다. 그리고 재미있게도, 그 버전이 당신을 더 똑똑하게 들리게 할 것입니다. 왜냐하면 당신을 실제로 그것을 만든 사람처럼 들리게 할 것이기 때문입니다.

이 글은 정직한 기술 글쓰기에 관한 시리즈의 세 번째 글입니다. 첫 번째 글은 DevRel이 실제로 무엇인지 다루었고, 두 번째 글은 정직한 "X vs Y" 콘텐츠를 위한 비교 테스트 (Comparison Test)를 다루었습니다. 공통된 맥락은 이것입니다: 구체성 (specificity)은 언제나 퍼포먼스 (performance)를 이깁니다. 🥑