소프트웨어의 공통 이해

이 문서는 자라는 중인 질문입니다. 아직 증거를 모으고 있으며, 내용이 바뀔 수 있습니다.

한 줄로 말하면

소프트웨어의 공통 이해는 팀이 코드에 적힌 문법보다 더 넓게, 각 개념의 뜻과 경계·불변조건·소유권·설계 이유를 같은 방식으로 이해하는 상태야.¹

비유로 이해하기

공통 이해는 여러 사람이 한 도시의 지도를 함께 읽는 일과 비슷해. 도로 이름만 아는 것으로는 부족해. 어디까지가 어느 구역인지, 어떤 길은 일방통행인지, 어느 시설을 누가 관리하는지까지 알아야 다른 사람이 낸 경로를 이어서 갈 수 있지.

이 비유는 여기까지야. 소프트웨어의 지도는 완성된 한 장의 문서가 아니야. 문서와 코드에 일부가 있고, 코드 리뷰와 대화와 논쟁을 거치며 계속 갱신돼. 누군가에게 변경을 설명하는 과정 자체가 지도의 빈 곳을 드러내기도 해.¹

정확한 정의

공통 이해는 팀 구성원이 단어를 똑같이 외운다는 뜻이 아니야. 적어도 다음 질문에 대해 서로의 답이 크게 어긋나지 않는 상태를 말해.

이 개념은 무엇을 뜻하고 어디까지 포함하나?
시스템의 경계는 어디에 있고, 반드시 지켜야 할 불변조건은 무엇인가?
어떤 부분을 누가 소유하고, 변경이 다른 부분에 어떤 영향을 주나?
지금의 설계가 왜 이런 모양이 되었나?

이 이해는 한 장소에만 저장되지 않아. 문서와 코드에 명시된 내용도 있지만, 변경을 설명하고 질문에 답하고 이견을 조정하는 협업 과정에도 남아. 그래서 공통 이해는 문서의 양과 같지 않고, 변경을 앞에 두고 팀이 같은 시스템을 보고 있는지 확인할 수 있는 능력에 가까워.¹

flowchart LR
    A["코드·문서·설계"] --> B["변경 설명"]
    B --> C["질문·리뷰·조율"]
    C --> D["공통 이해 갱신"]
    D --> A

왜 중요한가

변경 작업의 마찰은 모두 낭비가 아니야. 다른 사람의 코드를 읽고, 질문하고, 의존하는 팀과 조율하는 시간에는 내 이해를 상대에게 맞추고, 서로 시스템을 다르게 알고 있지는 않은지 확인하는 기능이 들어 있어.¹

AI 에이전트가 코드 변경을 빠르게 만들면 이 과정의 일부가 짧아질 수 있어. 그렇다고 공통 이해까지 자동으로 생기는 것은 아니야. 변경의 속도와 팀의 이해가 함께 움직이지 않으면, 코드는 바뀌었는데 왜 그렇게 바뀌었는지·어떤 경계를 지켜야 하는지·누가 책임지는지는 더 흐려질 수 있어.

이 지점은 소프트웨어 팩토리와도 이어져. 에이전트에게 변경을 맡기는 구조에서는 프롬프트나 지식 베이스만이 아니라, 사람이 기준과 패턴과 확인 지점을 설계해야 해. 공통 이해는 그 기준이 팀 안에서 공유되는 바탕이야.

또 agentic workflow와 컨텍스트 엔지니어링을 읽을 때도 같은 질문이 필요해. 에이전트에게 어떤 자료와 규칙을 보여 줄지 정하려면, 먼저 팀이 무엇을 중요한 맥락으로 여기는지 알고 있어야 하거든.

실제 예시

저장 계층을 바꾸는 상황을 생각해 보자. 변경자는 먼저 기존 코드를 읽고, 저장 계층을 소유한 사람에게 질문하고, 그 서비스에 의존하는 다른 팀과 조율할 수 있어. 이 과정은 느리지만, 저장 계층의 경계와 유지해야 할 조건을 두 사람이 같은 언어로 맞추는 시간이기도 해.¹

AI 에이전트가 같은 변경을 만들면 파일을 읽고 패치를 제안하는 단계는 빨라질 수 있어. 하지만 에이전트가 어떤 불변조건을 보존해야 하는지, 왜 특정 계층이 분리돼 있는지, 어떤 팀이 최종 책임을 지는지는 별도로 드러나야 해. 따라서 에이전트가 만든 diff를 승인하는 일은 문법 오류만 찾는 일이 아니라, 변경이 팀의 공통 이해와 맞는지 확인하는 일이 돼.

헷갈리지 말아야 할 점

공통 이해는 만장일치가 아니야. 의견이 다를 수 있지만, 무엇이 다르고 어떤 경계를 지켜야 하는지는 함께 볼 수 있어야 해.
마찰은 무조건 줄일 대상이 아니야. 반복적인 대기와 중복 질문은 줄일 수 있어도, 설명·질문·리뷰가 만드는 동기화 기능까지 없애면 이해의 빈자리가 남을 수 있어.¹
문서화와 같은 말도 아니야. 문서가 있어도 코드·대화·리뷰와 어긋나면 공통 이해가 있다고 보기 어려워. 문서화는 이해를 보존하고 전달하는 한 방법이야.
에이전트의 컨텍스트를 늘리면 해결되는 문제도 아니야. 필요한 개념과 경계가 팀 안에서 먼저 정리되지 않았다면, 더 많은 파일을 보여 주는 것만으로 설계 이유가 선명해지지는 않아.

남은 질문들

팀은 어떤 개념·경계·불변조건을 반드시 기록해야 할까?
에이전트가 만든 변경에서 공통 이해의 누락을 어떤 리뷰나 테스트로 발견할 수 있을까?
설명·질문·조율의 동기화 기능을 남기면서 협업의 반복 마찰만 줄이는 방법은 무엇일까?

Simon Willison, 「Quoting Armin Ronacher」(2026-07-14) Simon Willison’s Weblog ↩︎ ↩︎² ↩︎³ ↩︎⁴ ↩︎⁵ ↩︎⁶ ↩︎⁷

🥚

Explorer

Recent Notes

Redfin