AI 코딩 또는 운영 어시스턴트를 도입하는 대부분의 팀은 결국 동일한 결론에 도달합니다:

모델이 병목 현상(bottleneck)인 경우는 드뭅니다. 병목 현상은 컨텍스트(context)입니다.

잘못된 컨텍스트를 가진 유능한 모델은 자신감 넘치고 일반적인 답변을 내놓습니다. 반면, 올바른 컨텍스트를 가진 동일한 모델은 엔지니어가 실제로 사용할 수 있는 결과물을 만들어낼 수 있습니다.

따라서 실질적인 질문은 다음과 같습니다:

어떤 모델을 사용해야 하는가?

뿐만 아니라 다음과 같은 질문도 던져야 합니다:

컨텍스트에는 무엇이 포함되어야 하며, 이를 어떻게 구축해야 하는가?

유용한 컨텍스트에는 단순히 긴 프롬프트(prompt)나 문서로 가득 찬 폴더 그 이상의 것이 필요합니다. 여기에는 세 가지 뚜렷한 구성 요소가 필요합니다:

1. 규칙 (Rules)
2. 지식 (Knowledge)
3. 검색 (Retrieval)

각 구성 요소는 서로 다른 문제를 해결합니다.

1. 규칙 (Rules): AI가 수행해야 할 작업

규칙에는 업무가 수행되어야 하는 방식에 대한 팀의 구체적인 기대 사항이 포함됩니다.

예시는 다음과 같습니다:

• 다음 코딩 및 리뷰 표준을 준수할 것.
• 포화 상태이지만 상태가 양호한 기본(primary) 시스템에서는 절대 페일오버(fail over)하지 말 것.
• 이 클래스의 오류는 인프라 팀으로 에스컬레이션(escalate)할 것.
• 생성된 출력에 고객 데이터를 절대 포함하지 말 것.
• 공개 대안보다 이 내부 라이브러리를 우선적으로 사용할 것.
• 운영 환경(production) 변경을 수행하기 전에 반드시 사람의 승인을 받을 것.

규칙은 일반적인 참조 자료와는 다르게 작동합니다.

지식(Knowledge)은 AI에게 무엇이 사실인지를 알려줍니다. 규칙은 AI에게 무엇을 할 수 있고 무엇을 해야 하는지를 알려줍니다.

범용 모델은 귀하의 팀의 경계, 에스컬레이션 경로, 안전 요구 사항 또는 아키텍처 컨벤션(architectural conventions)을 자동으로 알 수 없습니다. 이러한 제약 조건은 명시적으로 제공되어야 합니다.

규칙은 단순히 모델이 사용할 수 있는 정보를 바꾸는 것이 아니라 모델의 행동(behavior)을 바꾸기 때문에, 잘 작성된 몇 가지 규칙이 수 페이지 분량의 배경 자료보다 답변을 더 효과적으로 개선할 수 있습니다.

이것은 종종 컨텍스트에서 가장 레버리지가 높은 부분이며, 동시에 누락되기 가장 쉬운 부분이기도 합니다.

2. 지식 (Knowledge): 시스템이 실제로 작동하는 방식

지식은 시스템과 운영 관행을 설명하는 상시 자료입니다.

일반적으로 다음과 같은 범주를 포함합니다.

문제 해결 가이드 (Troubleshooting guides)

문제 해결 가이드 (Troubleshooting guides)는 숙련된 엔지니어들이 머릿속에 담고 있는 서비스 특화 진단 지식을 포착합니다:

• 어떤 신호(signals)들이 함께 중요하게 작용하는지
• 어떤 알림(alerts)이 보통 노이즈(noisy)인지
• 특정 장애 모드(failure mode)가 귀하의 환경에서 어떻게 나타나는지
• 어떤 겉보기 증상들이 서로 관련이 없는지
• 에스컬레이션(escalating)하기 전에 무엇을 확인해야 하는지

런북 및 절차 (Runbooks and procedures)

런북 (Runbooks)은 시스템을 운영하는 데 필요한 조치들을 설명합니다:

• 서비스를 롤백(roll back)하는 방법
• 큐(queue)를 드레인(drain)하는 방법
• 자격 증명(credentials)을 로테이션(rotate)하는 방법
• 배포 파이프라인(deployment pipeline)이 기대하는 사항
• 어떤 단계들이 특정 순서로 수행되어야 하는지

아키텍처 및 도메인 노트 (Architecture and domain notes)

이 문서들은 귀하의 팀에게는 당연할 수 있지만 일반적인 모델에게는 보이지 않는 정보들을 설명합니다:

• 서비스 경계 (Service boundaries)
• 소유권 (Ownership)
• 데이터 흐름 (Data flows)
• 의존성 (Dependencies)
• 명명 규칙 (Naming conventions)
• 비즈니스 제약 사항 (Business constraints)
• 중요한 역사적 결정 사항들

이러한 지식은 귀하의 조직에 특화되어 있으며, 시간이 지남에 따라 변합니다.

런북 (Runbook)은 사후 분석 (postmortem) 후에 다시 작성될 수 있습니다. 문제 해결 가이드 (Troubleshooting guide)는 마이그레이션 (migration) 이후에 부정확해질 수 있습니다. 아키텍처 문서 (Architecture document)는 현재의 서비스 토폴로지 (topology)를 반영하지 못하게 될 수도 있습니다.

따라서 좋은 컨텍스트 (context)는 지식을 모델에 영구적으로 임베딩(embedded)되어 잊혀지는 것이 아니라, **살아있고 버전이 관리되는 소스 (living, versioned source)**로 취급합니다.

3. 검색 (Retrieval): 지금 무엇이 사실인가

규칙과 상시 지식만으로는 많은 실제 엔지니어링 작업에 충분하지 않습니다.

조사 과정에서 AI는 다음과 같은 질문에도 답해야 할 수 있습니다:

• 가장 최근의 배포 (deployment)에서 무엇이 변경되었는가?
• 현재 에러율 (error rate)은 얼마인가?
• 장애 (incident)가 언제 시작되었는가?
• 작업 항목 (work item)이 실제로 요청하는 것은 무엇인가?
• 현재 어떤 서비스들이 상태가 좋지 않은가 (unhealthy)?
• 관련 로그 파일 (log file)에 무엇이 나타나는가?
• 이와 유사한 장애 (incident)가 이전에 해결된 적이 있는가?

이 정보들은 이미 귀하의 팀이 사용하는 도구들에 존재합니다:

• Git 저장소 (Git repositories)
• 로깅 시스템 (Logging systems)
• 모니터링 대시보드 (Monitoring dashboards)
• 장애 관리 플랫폼 (Incident-management platforms)
• 작업 항목 시스템 (Work-item systems)
• 내부 문서 (Internal documentation)
• 커스텀 API (Custom APIs)

좋은 컨텍스트는 이 모든 정보를 하나의 거대한 문서로 복사하려고 시도해서는 안 됩니다.

대신, AI에게 현재 작업에 필요한 특정 정보를 검색할 수 있는, 범위가 제한된(scoped) 가급적 읽기 전용(read-only)의 방식을 제공해야 합니다.

따라서 컨텍스트의 세 가지 구성 요소는 세 가지 서로 다른 질문에 답합니다:

오래된 가정(stale assumptions)으로부터 검색 근거를 찾지 못하는 어시스턴트.

규칙이 없는 어시스턴트는 잘못된 동작을 매우 효율적으로 수행할 수 있습니다.

도메인 지식(domain knowledge)이 없는 어시스턴트는 그럴듯하게 들리지만 귀하의 시스템에는 적용되지 않는 조언을 생성할 수 있습니다.

신뢰할 수 있는 결과를 얻으려면 이 세 가지가 모두 필요하며, 이들은 현재 당면한 작업의 범위 내로 제한되어야 합니다.

처음에는 수동으로 구축할 수 있습니다

엔지니어 한 명이 새로운 플랫폼을 도입하지 않고도 유용한 컨텍스트를 구성할 수 있습니다.

예를 들어, 다음과 같은 작업을 할 수 있습니다:

• 팀의 규칙과 컨벤션(conventions)을 포함하는 마크다운(Markdown) 파일을 작성합니다.
• 관련 런북(runbook)과 트러블슈팅 가이드(troubleshooting guide)를 첨부합니다.
• 어시스턴트에게 작업과 관련된 디렉토리에 대한 접근 권한을 부여합니다.
• 관련 로그 발췌본을 붙여넣습니다.
• 장애(incident) 또는 작업 항목(work-item) 설명을 포함합니다.
• 어떤 시스템과 동작이 범위 외(out of scope)인지 설명합니다.

이 접근 방식은 잘 작동합니다.

이 방식은 AI가 실제로 무엇을 필요로 하는지 결정하도록 강제하기 때문에 종종 올바른 첫 번째 단계가 됩니다. 그 결정 과정에서 많은 가치가 창출됩니다.

AI 코딩 어시스턴트를 진지하게 사용해 본 사람이라면 아마 이미 이와 유사한 작업을 수행해 보았을 것입니다.

문제는 수동으로 구성된 컨텍스트가 틀렸다는 것이 아닙니다.

문제는 그것이 한 사람과 한 순간의 범위를 넘어 확장(scale)되지 않는다는 점입니다.

수동으로 구성된 컨텍스트가 무너지는 이유

컨텍스트가 팀의 관행이 되는 즉시 몇 가지 실패 모드(failure modes)가 나타납니다.

정보가 노후화됩니다 (It becomes stale)

지난달 프롬프트에 복사해 넣은 런북 (runbook)은 그 이후에 업데이트되었을 수 있습니다.

아무도 오래된 복사본을 교체하는 것을 기억하지 못하므로, AI는 더 이상 현실을 반영하지 않는 지침을 바탕으로 계속해서 추론을 수행합니다.

이는 오래된 문서가 초래하는 것과 동일한 위험을 만들어내지만, 차이점은 이제 그 오래된 자료가 확신에 찬 권장 사항을 생성하는 데 사용된다는 점입니다.

엔지니어 간에 전달되지 않습니다 (It does not transfer between engineers)

정교하게 구성된 컨텍스트 (context)가 오직 한 명의 엔지니어에게만 존재할 수 있습니다:

• 로컬 파일 (Local files)
• 채팅 기록 (Chat history)
• 프롬프트 템플릿 (Prompt templates)
• 개인 메모 (Personal notes)
• 메모리 (Memory)

다음 엔지니어가 온콜 (on call)에 투입되면, 그들은 이를 다시 구축해야 합니다.

사람들 사이에서 드리프트(drift)가 발생합니다

두 명의 엔지니어가

좋은 컨텍스트 습관을 반복 가능한 시스템으로 전환하기

이것이 우리가 NeatContext를 통해 해결하고자 하는 문제입니다.

NeatContext는 소스 자료를 해당 자료를 소유한 팀과 가깝게 유지하면서, 컨텍스트(context)의 세 가지 구성 요소인 규칙(rules), 지식(knowledge), 검색(retrieval)을 조립하는 구조화된 방법을 제공합니다.

규칙은 도메인 프로필(domain profiles)에 존재합니다

도메인 프로필은 팀의 다음 사항들을 Markdown 기반으로 정의한 것입니다:

• 가드레일 (Guardrails)
• 컨벤션 (Conventions)
• 에스컬레이션 로직 (Escalation logic)
• 운영 기대치 (Operational expectations)
• 중요한 제약 사항 (Important constraints)

특정 작업에 적합한 프로필이 연결되므로, AI는 해당 팀이 정의한 경계 내에서 작동합니다.

지식은 버전 관리되는 소스 자료로 유지됩니다

런북 (Runbooks), 트러블슈팅 가이드 (troubleshooting guides), 아키텍처 노트 (architecture notes) 및 기타 문서들은 로컬 파일 또는 버전 관리되는 소스 파일로 유지됩니다.

이들은 모델 내에 영구적으로 구워져(baked) 들어가지 않습니다.

런북이 변경되면 소스도 변경됩니다. 재학습(retraining) 단계가 필요 없으며, 모델 가중치(model weights) 내부에 숨겨진 복사본이 존재하여 조용히 오래된 정보(stale)가 될 위험도 없습니다.

최신 정보는 읽기 전용 확장 기능(read-only extensions)을 통해 가져옵니다

모든 외부 시스템을 컨텍스트 문서로 복사하는 대신, 팀은 다음과 같은 도구들에 대해 범위가 지정된 읽기 전용 확장 기능을 연결할 수 있습니다:

• Git 저장소 (Git repositories)
• 내부 문서 (Internal documentation)
• 장애 관리 시스템 (Incident systems)
• 모니터링 플랫폼 (Monitoring platforms)
• 커스텀 API (Custom APIs)

컨텍스트는 특정 작업에 어떤 확장 기능이 사용 가능한지를 정의합니다.

자격 증명(Credentials)은 프롬프트(prompts)에 직접 배치되는 대신 운영 체제의 자격 증명 저장소에 유지됩니다.

컨텍스트는 작업별로 범위가 지정됩니다

운영 장애(production incident)가 발생했다고 해서 회사의 모든 문서, 저장소 및 도구에 접근할 필요는 없습니다.

각 작업에 대해 다음과 같은 관련 항목을 선택할 수 있습니다:

• 도메인 프로필 (Domain profiles)
• 지식 디렉토리 (Knowledge directories)
• 외부 도구 (External tools)
• 데이터 소스 (Data sources)

이를 통해 배경 소음(background noise), 관련 없는 정보, 그리고 신호 희석(signal dilution)을 줄일 수 있습니다.

동일한 컨텍스트를 팀에서 재사용할 수 있습니다

팀은 컨텍스트를 한 번 정의하면 여러 조사 과정에서 재사용할 수 있습니다.

다음번 온콜(on-call) 엔지니어는 이를 기억에서 다시 재구축하는 대신, 동일한 규칙, 지식, 그리고 검색 경계(retrieval boundaries)를 전달받게 됩니다.

NeatContext의 팀 라이브러리(team library)를 사용하면 도메인 프로필, 지식 및 확장 기능을 팀원 간에 읽기 전용(read-only)으로 공유할 수 있습니다.

무엇이 제공되었는지에 대한 기록이 남습니다

NeatContext는 AI에게 어떤 컨텍스트가 전달되었는지를 보여주는 로컬 활동 로그(activity log)를 유지합니다.

답변을 검토해야 할 때, 엔지니어는 나중에 컨텍스트를 재구성하려고 애쓰는 대신 입력값(inputs)을 통해 답변의 근거를 추적할 수 있습니다.

NeatContext는 또 다른 AI 모델이 아닙니다

한 가지 중요한 설계 선택 사항을 명확히 해야 합니다:

NeatContext는 AI 모델을 포함하지 않습니다.

NeatContext는 어시스턴트가 전달받기 전에 사용자의 문서를 읽거나, 순위를 매기거나, 요약하지 않습니다.

대신, 컨텍스트 경계(context boundary)를 정의하고 선택된 프로필, 폴더 및 읽기 전용 도구들을 사용자가 이미 사용 중인 다음과 같은 AI 클라이언트(AI client)에 연결합니다:

• Claude Code
• Codex CLI
• Claude Desktop
• ChatGPT Desktop

실제 읽기와 추론(reasoning)은 승인된 AI 클라이언트가 수행합니다.

컨텍스트는 두 번째 모델에 의해 추론되는 것이 아니라, 사람에 의해 명시적으로 정의됩니다.

다시 말해, NeatContext는 수동으로 조립된 프롬프트(prompts) 뒤에 숨겨진 유용한 습관들을 다음과 같이 지속 가능한 형태로 변환합니다:

• 정의됨 (Defined)
• 버전 관리됨 (Versioned)
• 범위가 지정됨 (Scoped)
• 공유 가능함 (Shareable)
• 현재 시스템에 연결됨 (Connected to current systems)

실제 작동 모습

다음 데모는 각 팀이 고유한 도메인 컨텍스트를 제공할 때, 동일한 장애(incident) 상황에서도 팀마다 서로 다른 조치가 필요할 수 있음을 보여줍니다.

핵심 요약 (The takeaway)

효율적인 컨텍스트는 단순히 더 큰 프롬프트가 아닙니다.

그것은 다음과 같은 요소들의 의도적인 조합입니다:

1. 규칙 (Rules): AI가 무엇을 수행할 것으로 기대되는지, 그리고 무엇을 수행할 수 있는지 정의합니다.
2. 지식 (Knowledge): 귀하의 시스템이 어떻게 작동하는지 설명합니다.
3. 검색 (Retrieval): 팀이 의존하는 시스템으로부터 최신 정보를 제공합니다.

이 세 가지 모두 작업 범위에 맞춰 엄격하게 제한(scoped tightly)되어야 합니다.

오늘날에는 이러한 컨텍스트를 수동으로 구성할 수 있으며, 그렇게 하는 것은 충분히 가치가 있습니다. 이는 어떤 정보가 실제로 AI 생성 답변의 품질을 변화시키는지 식별하는 데 도움이 됩니다.

하지만 AI 보조 엔지니어링 (AI-assisted engineering)이 개인적인 기술을 넘어 팀의 관행이 되려면, 컨텍스트는 다음과 같은 특성을 갖추어야 합니다:

• 버전 관리 (Versioned)
• 범위 제한 (Scoped)
• 공유 가능 (Shareable)
• 반복 가능 (Repeatable)
• 실제 시스템과의 연결 (Connected to real systems)

이것이 바로 저희가 NeatContext를 통해 해결하고자 하는 문제입니다.

또한 GitHub에서 NeatContext 데모를 직접 체험해 보실 수 있습니다.

현재 여러분은 AI 도구에 도메인 특화 컨텍스트 (domain-specific context)를 어떻게 제공하고 계신가요? 어떤 방식이 효과적인지, 그리고 어느 지점에서 프로세스가 무너지기 시작하는지 여러분의 의견을 듣고 싶습니다.