Claude Code와 개발할 때 용어 통일이 중요한 이유

English (N/A)
#Claude Code#AI 협업#개발 팁#용어 관리

Claude Code로 프로젝트를 진행하다 보면 어느 순간 이상한 일이 벌어진다. 분명히 "workspace 영역을 수정해줘"라고 요청했는데, Claude Code는 엉뚱한 곳을 고친다. 다시 설명하면 또 다른 곳을 건드린다. 그러다 보면 서로 대화가 안 통하는 느낌이 들면서 프로젝트가 꼬이기 시작한다.

문제의 시작: 용어의 난립

Claude Code와 개발을 하다 보면, 특히 프론트엔드처럼 UI 컴포넌트가 중첩되는 구조에서 이런 일이 자주 생긴다.

예를 들어보자. 처음에는 단순히 "작업 영역"이라는 개념 하나만 있었다. 그런데 개발하면서 요구사항이 추가되고 구조가 복잡해지면, Claude Code는 비슷한 개념들을 계속 만들어낸다.

  • workspace
  • workspace container
  • work area
  • viewport
  • pane area
  • pane container
  • canvas area

얼핏 보면 다 다른 것 같지만, 실제로는 서로 겹치거나 애매하게 구분되는 개념들이다. 문제는 Claude Code 스스로도 이 용어들을 명확히 구분하지 못한다는 것이다.

용어 혼란이 만드는 악순환

용어가 헷갈리기 시작하면 이런 일이 벌어진다.

개발자가 "workspace 컴포넌트 수정해줘"라고 하면, Claude Code는 WorkspaceContainer를 수정한다. 아니라고 하면 이번엔 WorkArea를 고친다. 그것도 아니라고 하면 Viewport를 건드린다.

사용자는 정확히 어디를 말하는 건지 Claude Code가 모르고, Claude Code 스스로도 용어가 헷갈리면서 콘텍스트가 꼬인다. 그러면 그냥 이상한 삽질을 계속하게 된다.

버그를 고치려다가 다른 버그를 만들고, 그걸 고치려다가 또 다른 문제가 생기는 악순환이 시작된다.

해결 방법: 용어 사전을 만들어라

이 문제를 해결하는 방법은 간단하다. Claude Code에게 헷갈리는 용어들을 명확하게 정리해달라고 요청하는 것이다.

지금 우리 프로젝트에서 workspace, work area, viewport, pane 같은 용어들이 섞여서 쓰이고 있어.
각 용어가 정확히 뭘 의미하는지 정리하고, 앞으로는 통일된 용어만 사용하자.
용어 사전을 만들어줘.

그러면 Claude Code는 현재 코드베이스를 분석해서 각 용어가 실제로 어떤 컴포넌트나 개념을 가리키는지 정리해준다. 그리고 중복되거나 애매한 용어들을 통합하고, 명확한 용어 사전을 만들어준다.

이 용어 사전은 복잡한 코드 파일의 주석으로 달아두면 좋다. 예를 들어 메인 레이아웃 컴포넌트 파일 상단에 이런 식으로 정리할 수 있다.

/**
 * 용어 정의
 * - Canvas: 실제 드로잉이 일어나는 HTML Canvas 요소
 * - Viewport: Canvas를 감싸는 스크롤 가능한 영역
 * - WorkspaceContainer: Viewport와 도구 모음을 포함하는 전체 작업 영역
 *
 * 주의: workspace, work area 등의 용어는 사용하지 않음
 */

프로젝트 초기부터 용어를 정리하자

물론 프로젝트 중간에 이렇게 정리할 수도 있지만, 가장 좋은 건 처음부터 용어를 명확하게 정의하는 것이다.

프로젝트를 시작할 때 Claude Code에게 이렇게 요청해보자.

이 프로젝트에서 사용할 핵심 용어들을 먼저 정의하고 시작하자.
UI 구조에서 각 영역을 어떻게 부를지, 데이터 구조에서 각 개념을 어떻게 명명할지 정리해줘.

초반에 10분 투자해서 용어를 정리하면, 나중에 몇 시간씩 삽질하는 걸 막을 수 있다.

Claude Code는 사람이 아니다

이 모든 문제의 근본 원인은 간단하다. Claude Code는 사람이 아니다.

사람끼리 대화할 때는 맥락을 보고 "아, 이 사람이 저걸 말하는 거구나" 하고 알아듣는다. 하지만 AI는 명확한 정의 없이는 추론할 수 없다. 특히 비슷한 용어들이 여러 개 있으면 확률적으로 틀린 걸 선택하게 된다.

Claude Code와 협업할 때는 "이 정도면 알아듣겠지"라는 생각을 버려야 한다. 용어를 명확하게 정의하고, 일관되게 사용하고, 문서화해야 한다.

그래야 Claude Code도 제대로 일하고, 개발자도 스트레스 받지 않는다.

정리하며

Claude Code로 개발할 때 가장 중요한 것 중 하나는 용어 통일이다.

  • 용어가 난립하면 Claude Code도, 개발자도 헷갈린다
  • 헷갈리는 용어들을 발견하면 즉시 정리하고 통일해야 한다
  • 용어 사전을 만들고 코드 주석으로 남겨두자
  • 가능하면 프로젝트 초기부터 용어를 명확하게 정의하고 시작하자

10분의 용어 정리가 몇 시간의 삽질을 막아준다.