AI 코딩 에이전트는 자신이 추측하고 있다는 사실을 결코 말하지 않습니다. 틀린 답을 내놓기 전에 머뭇거리지도 않고, 세 모듈 떨어진 곳의 무언가를 망가뜨리기 직전에 속도를 늦추지도 않으며, 이 부분은 확실하지 않다고 인정하는 불안한 주석을 남기지도 않습니다. 맞든 혹은 처참하게 틀리든, 에이전트는 동일하게 깔끔하고 자신감 넘치며 주석이 잘 달린 코드를 일정한 속도로 전달합니다. 왜냐하면 언어 모델(Language Model)에서 자신감이란 설계가 실제로 유효한지가 아니라, 다음 토큰(Token)이 얼마나 그럴듯해 보이는지를 추적하기 때문입니다. 징후는 없습니다. 그 단일한 특성, 즉 밑바탕에 아무런 교정(Calibration) 장치 없이 유창한 출력을 내놓는다는 점이 유능한 에이전트를 실제 코드베이스(Codebase)에서 진정으로 위험하게 만드는 요소이며, 이것이 바로 제가 AgentScaffold를 구축하여 관리하고자 하는 문제입니다.

세 가지 구조적 격차(Structural Gaps)가 실무에서 이를 위험하게 만듭니다. 첫째, 에이전트는 중요한 경계선들, 즉 새로운 세션, 압축된 컨텍스트 윈도우(Context Window), 혹은 내일 같은 저장소(Repo)를 이어받을 팀원의 에이전트 사이에서 지속적인 메모리(Durable Memory)를 갖지 못합니다. 단일 대화 안에서는 컨텍스트를 잘 유지하지만, 이러한 경계선을 넘어서는 순간 에이전트는 처음부터 다시 시작하며 어제 도출했던 모든 것을 즐겁게 재도출합니다. 둘째, 에이전트는 스스로 내버려 두면 숙련된 엔지니어가 보여주는 일관된 엄격함 없이 각 계획에 조금씩 다르게 접근합니다. 이는 게으름 때문이 아니라, 루프(Loop) 내의 그 어떤 것도 이를 요구하지 않기 때문입니다. 셋째, 에이전트는 학습하지 않습니다. 12번째 계획에서 실수를 발견하더라도, 동일한 유형의 실수가 40번째 계획에서 마치 새로워진 것처럼, 그리고 똑같이 자신만만하게 다시 나타납니다. 그 교훈을 앞으로 전달하는 것은 아무것도 없습니다.

저의 경력은 Boeing에서의 13년 간의 산업 공학자(Industrial Engineer)로서의 경험과, Salesforce 및 Dropbox에서의 8년 이상 데이터 과학자(Data Scientist)로서의 용량 공학(Capacity Engineering) 경험을 아우릅니다. 산업 공학자로서 배웠고 제 커리어 전반에 걸쳐 지속되어 온 사고방식은 바로 시스템 수준의 사고방식(Systems-level mindset)입니다. 이는 설계가 잘못된 프로세스를 식별하고 그것이 시스템의 시간과 자원에 미치는 피해를 포착하는 습관, 표준의 부재가 어떻게 변동성(Variation)을 잠입시키는지, 그리고 거버넌스 프레임워크(Governance framework)가 없을 때 실수가 어떻게 눈에 보이게 혹은 보이지 않게 축적되어 원래 설계가 전달하고자 했던 결과물을 침식시키는지에 대한 통찰입니다. AI 에이전트로 소프트웨어를 구축하는 것은 또 다른 하나의 프로세스일 뿐이며, 오늘날의 에이전트 도구들은 표준이나 거버넌스 프레임워크 없이 이를 실행하고 있습니다. 즉, 앞서 언급한 세 가지 방식 모두에서 동시에 실패하고 있습니다. AgentScaffold는 이 문제들을 해결하기 위해 구축된 거버넌스 프레임워크입니다. 에이전트가 상태(State)를 잃어버리지 않도록 하는 메모리(Memory), 실수가 배포되기 전에 포착되도록 하는 피어 리뷰(Peer Review), 그리고 표준이 느슨해지는 대신 시간이 지남에 따라 강화되도록 하는 지속적 개선 루프(Continuous improvement loop)를 제공합니다.

구체적으로, 이는 Python 패키지(pip install agentscaffold)입니다. MCP 서버로 작동하므로 Cursor, Claude Code, Windsurf 또는 해당 프로토콜을 지원하는 모든 도구와 함께 사용할 수 있으며, 결정론적(Deterministic)이고 지루해야 할 부분들을 위해 CLI를 제공합니다.

Layer 1: Memory — 스크롤백 버퍼(Scrollback buffer)가 아닌 지식 그래프(Knowledge Graph)

scaffold index는 사용자의 저장소(Repository)를 DuckDB + DuckPGQ 속성 그래프(Property graph)로 파싱합니다. Tree-sitter는 Python, TypeScript, JavaScript, Go, Rust, Java, C, C++ 등 8가지 언어를 처리하며, 함수(Functions), 클래스(Classes), 메서드(Methods), 인터페이스(Interfaces)를 추출함과 동시에 이들 사이의 IMPORTS 및 CALLS 엣지(Edges)를 연결합니다. 이것은 단순히 미화된 태그 파일이 아니라 실제 그래프입니다. 코드에만 국한되지 않기 때문에 약 20개의 노드 유형(Node types)과 40개의 엣지 유형(Edge types)을 가집니다.

이것이 단순한 화려한 ctags 그 이상인 이유는, 동일한 인덱스가 거버넌스 산출물(governance artifacts) — 계획(plans), 인터페이스 계약(interface contracts), ADR(Architecture Decision Records), 스파이크(spikes), 연구(studies), 리뷰 결과(review findings), 백로그 항목(backlog items) — 을 수용하고 이를 설명하는 코드와 연결하기 때문입니다. 리뷰 결과는 아무도 다시 찾아보지 않을 채팅 로그 속에 묻힌 문장이 아닙니다. 그것은 관련된 정확한 파일 및 함수에 부착된 노드(node)입니다. "우리가 어디서 멈췄고, 무엇이 차단되어 있는가?"라고 물으면, 에이전트는 어제의 상태를 재구성하기 위해 수십 개의 파일을 읽고 다시 잃어버리는 대신, 단 한 번의 MCP 호출로 최근 계획, 미결된 결과, 그리고 다음 단계들을 가져옵니다.

몇 가지 그래프 엔지니어링(graph engineering) 세부 사항은 다음과 같습니다:

• 증분 인덱싱(Incremental indexing)은 비용 측면에서 정직합니다. 모든 파일은 SHA-256 콘텐츠 해시를 가지며, (mtime, size) 프리필터(prefilter)를 통해 변경되지 않은 파일은 다시 해싱하는 번거로움 없이 건너뜁니다. 엣지 재해결(Edge re-resolution)은 변경된 파일과 해당 파일을 직접 임포트(import)하는 파일로 범위가 제한되며, 저장할 때마다 전체 저장소(full-repo)를 다시 빌드하지 않습니다.
• 검색 성능이 우아하게 저하됩니다(Search degrades gracefully). 하이브리드 검색(Hybrid search)은 구조적 매칭(structural matches)과 의미적 매칭(semantic matches)을 결합합니다 (all-MiniLM-L6-v2, 384-dim, reciprocal rank fusion으로 병합). 임베딩(embeddings)을 생략하면 키워드 검색(keyword search)으로 전환되며, 결과가 좋지 않을 때 이를 조용히 제공하여 사용자가 좋은 결과라고 오해하게 만드는 대신, 전환되었음을 명시적으로 알립니다.
• "알 수 없음(unknown)"을 "없음(no)"으로 혼동하는 것을 거부합니다. 호출(call) 및 임포트(import) 엣지는 파싱된 언어에 대해서만 존재하므로, Markdown, YAML, shell은 구조적으로 보이지 않습니다. 영향도 쿼리(impact query) 결과가 비어 있을 때, 도구는 이를 '사용되지 않음(unused)'이 아닌 '확인되지 않음(unconfirmed)'으로 라벨링하고 grep 폴백(fallback)을 제공합니다. 호출자가 0개라는 것은 "찾지 못했다"는 의미이지, "없다"는 의미가 아닙니다. 에이전트가 과도하게 자신감이 있어서 존재하는 제품이라면, 무엇을 삭제해도 안전한지에 대해서도 과도하게 자신감을 가져서는 안 됩니다.

모듈 구조는 Leiden 알고리즘(graspologic을 통해 구현)에서 가져왔으며, 이는 밀접하게 결합된 파일들을 클러스터링(clustering)하여 디렉토리 트리에서 추측하는 대신 실제 경계가 어디인지 확인할 수 있게 해줍니다.

레이어 2: 피어 리뷰 (Peer review) — 코드가 존재하기도 전에 허점을 지적할 준비가 된 당신의 디지털 스프린트 팀

이 부분은 에이전트를 제어(governance) 없이 실행할 때 사람들이 흔히 건너뛰는 대목입니다. 에이전트가 자신의 계획을 스스로 검토하는 것은 리뷰가 아닙니다. 그것은 숙제를 작성한 것과 동일한 모델이 자신의 숙제에 점수를 매기는 것과 같으며, 숙제를 작성할 때 가졌던 바로 그 사각지대(blind spots)를 그대로 가진 채 매번 스스로에게 만점을 부여하게 됩니다. 계획이 구현되기 전에 필요한 것은 제대로 된 설계 리뷰(design review)가 필요로 하는 것과 같습니다. 즉, 논쟁에서 이기기 위해서가 아니라, 당신이 직접 작성했기 때문에 정작 보지 못하는 부분—가정(assumptions), 예외 케이스(edge cases), 오류 경로(error paths), 그리고 통합 지점(integration points)을 쿡쿡 찔러볼 수 있는 다른 누군가가 그 자리에 있어야 한다는 것입니다.

AgentScaffold는 코드 한 줄이 작성되기 전에 해당 리뷰를 실행합니다. '악마의 대변인(devil's-advocate)' 단계는 가장 위험한 가정과 계획이 조용히 실패할 수 있는 방식들을 추적합니다. 확장 리뷰(expansion review)는 누락된 예외 케이스, 문서화되지 않은 오류 경로, 그리고 파일 영향도 지도(file-impact map)가 편리하게 잊어버린 소비자(consumers)들을 찾아냅니다. 트레이딩(trading), MLOps, 데이터 엔지니어링(data-engineering), 인프라(infrastructure), API 서비스(api-services), 웹 앱(webapp), 모바일(mobile), 임베디드(embedded), 게임 개발(game-dev), 연구(research) 등 총 10개의 도메인 팩(domain pack)을 설치하면, 해당 분야에 맞춰 조정된 표준과 프롬프트(prompts)를 갖춘 전문 리뷰어가 등장합니다. 예를 들어, 트레이딩 팩의 퀀트 아키텍트(quant architect)는 전략이 거래 시점에 가질 수 없었던 데이터로 학습된 백테스트(backtest)에서의 앞서보기 편향(look-ahead bias)을 잡아냅니다. 웹 앱 리뷰어는 모두가 나중에 수정하겠다고 계획하는 접근성(accessibility) 및 성능 문제를 지적합니다. 또한, 이러한 리뷰는 그래프(graph)에 기반하기 때문에,

그 결과 발견된 사항들이 지속적으로 남게 됩니다. 하나의 발견 사항을 기록하면, 이는 계획(plan) 및 파일(file)과 연결된 ReviewFinding 노드가 되며, 심각도(severity)에 따라 순위가 매겨집니다. 그리고 누군가 실제로 이를 해결할 때까지 해당 계획에 대한 모든 향후 리뷰에서 다시 나타납니다. 다음 세션 — 다른 에이전트, 새로운 창, 오늘 아침의 기억이 없는 상태 — 은 이 위험을 어렵게 다시 발견하는 대신, "이 위험은 이미 알려져 있으며 해결되지 않은 상태임"이라는 지점에서 시작합니다. 한 번 포착된 위험은 단 한 번의 비용만 발생해야 합니다.

레이어 3: 지속적 개선(Continuous improvement) — 리뷰어를 날카롭게 만드는 루프

만약 나머지 두 레이어를 버려야 한다면 제가 남겨둘 레이어는 바로 이것이며, 이는 산업 공학(industrial-engineering)의 플레이북에서 직접 가져온 개념입니다. 단순히 결함(defect)을 수정하는 것이 아니라, 결함이 통과할 수 있게 만든 프로세스(process)를 수정하여 동일한 유형의 실수가 같은 방식으로 두 번 발생하지 않도록 하는 것입니다.

구현 후에는 사후 검토(post-implementation review)를 통해 구축된 내용과 계획된 내용을 비교합니다. 이는 단순히 만족스럽다는 고개를 끄덕이는 것이 아니라, 실제 차이(diff)를 확인하는 과정입니다. 회고(retrospective)를 통해 무엇이 잘 작동했는지, 무엇이 계획보다 오래 걸렸는지, 그리고 아무도 예상하지 못했던 것은 무엇인지를 learnings_tracker에 기록합니다. 그다음 실제로 중요한 단계가 이어집니다. 이러한 학습 내용들이 다음 계획의 리뷰가 실행될 대상인 아티팩트(artifacts)로 다시 통합됩니다. 반복되는 프로세스 실수는 AGENTS.md의 한 줄이 됩니다. 구조적 격차(structural gap)는 계획 템플릿(plan template)의 변경 사항이 됩니다. 계속해서 재발하는 위험 패턴은 악마의 대변인(devil's-advocate) 프롬프트 자체의 새로운 질문이 됩니다. 코딩 실수는 구현 표준(implementation standard)의 한 줄이 됩니다.

솔직히 말하자면, 이 루프는 마법처럼 스스로 재작성하는 것이 아니라 프로세스 주도적입니다. 라이프사이클 도구들이 그래프 상태를 소유합니다. 즉, 발견 사항을 기록하고, 계획에 '검토 완료' 스탬프를 찍고, 구조화된 회고(retro) 보고서를 전달하며, 에이전트는 사용자의 참여 하에 파일을 업데이트합니다. 이 프레임워크는 래칫(ratchet)과 체크리스트를 제공할 뿐입니다. 뒤에서 몰래 규칙서를 재작성하지 않습니다. 계획하고, 실행하고, 점검하고, 조치하는 것(Plan, do, check, act)은 '조치' 단계가 아무도 다시 보지 않을 좋은 의도가 아니라, 에이전트 자체의 운영 규칙에 대한 구체적인 차이점(diff)으로 나타납니다. 사용자가 습관을 들이는 것이 필요합니다. 매주 학습 추적기(learnings tracker)를 읽고 그 안에 있는 내용을 실제로 통합해야 합니다. 프로세스이지만, 효과가 있습니다.

실제 레포지토리에 기록되는 것들

'거버넌스 프레임워크(Governance framework)'라는 말은 아무도 열어보지 않는 바인더처럼 들립니다. 하지만 실제로는 에이전트에게 그것들을 어떻게 사용해야 하는지를 알려주는 일련의 템플릿, 표준, 규칙들의 집합체입니다. 템플릿은 지식 작업에서 표준이 생산 라인에서 하는 것과 정확히 같은 역할을 합니다. 즉, 변동성을 제거합니다. 모든 계획, 결정, 실험이 동일한 방식으로 기록될 때, 에이전트는 자신이 불편하다고 느끼는 단계를 조용히 건너뛸 수 없게 되고, 다음 사람—또는 다음 세션—은 항상 어디를 봐야 하고 '완료'가 무엇을 의미하는지 알게 됩니다. scaffold init은 프로젝트에 다음과 같이 기록합니다:

• Plan templates (계획 템플릿) (feature, bugfix, refactor) — 계획은 파일 영향 지도(file-impact map), 테스트 계획, 실행 단계, 그리고 롤백 계획(rollback plan) 없이는 초안 상태를 벗어날 수 없습니다. 이는 "테스트는 나중에 생각하자"라는 식의 태도를 조용히 종식시키는 표준이 됩니다.
• A spike template (스파이크 템플릿) — 불확실성이 높은 작업을 위한 것입니다. 전체 계획을 확정하기 전에 위험한 가정을 압박 테스트(pressure-tests)하는 시간 제한적 조사(time-boxed investigation)이며, 막연한 "괜찮아 보이네" 대신 명시적인 진행(proceed) / 피벗(pivot) / 보류(defer) 결정을 강제합니다.
• A study template (스터디 템플릿) — 실험, A/B 테스트, 그리고 어블레이션(ablations)을 위한 것입니다: 가설, 변형(variants), 지표(metrics), 결론을 포함합니다. 결과는 노트북에서 스크롤되어 사라지고 다시는 볼 수 없는 숫자가 되는 대신, 그래프 내의 지속적인 스터디(Study)로 남게 됩니다.
• An ADR template (ADR 템플릿) — 결정 사항, 검토했던 대안들, 그리고 그 이유를 기록하는 아키텍처 결정 기록(architecture decision records)입니다. 6개월 후 누군가 "도대체 왜 이걸 이런 방식으로 만들었나요?"라고 물을 때 답변이 존재하게 되며, 그래프를 통해 어떤 ADR이 어떤 계획을 관장하는지 추적할 수 있습니다.
• Review prompts (리뷰 프롬프트) — 리뷰어들이 사용하는 악마의 대변인(devil's-advocate), 확장(expansion), 그리고 회고(retrospective) 스크립트이며, 개선 루프(improvement loop)가 시간이 지남에 따라 정교화하는 바로 그 파일들입니다.
• Implementation standards (구현 표준) — 에러, 로깅(logging), 설정(config), 테스트를 위한 표준으로, 이를 통해 5번의 세션이 지난 후의 에이전트가 당신의 로깅 컨벤션을 처음부터 다시 발명하는 일을 방지합니다.
• Agent rules and state (에이전트 규칙 및 상태) — AGENTS.md와 더불어 플랫폼별 .cursor/rules, CLAUDE.md, .windsurfrules를 포함하여 Cursor, Claude Code, Windsurf가 모두 하나의 운영 매뉴얼을 읽도록 합니다. 또한 workflow_state.md, backlog.md, learnings_tracker.md를 통해 코드 그래프와 마찬가지로 컨텍스트가 세션 경계를 넘어 생존할 수 있게 합니다.

이 중 어떤 것도 당신이 이미 작성한 내용을 덮어쓰지 않습니다. 생성된 콘텐츠는 관리되는 블록(managed blocks)에 저장되고, 기존 파일에는 내용이 추가되며, 그래프의 런타임 아티팩트(runtime artifacts)는 자동으로 .gitignore에 추가됩니다.

파일 트리를 읽는 것보다 직접 보는 것을 선호하신다면, 새로 초기화된 프로젝트의 짧은 투어를 준비했습니다. scaffold init이 생성하는 폴더와 파일들, 그리고 거버넌스 레이어(governance layer)와 그래프 백엔드(graph backend)가 실제로 어떻게 결합되는지 살펴보겠습니다.

솔직한 수치, 그리고 이 패키지가 적합하지 않은 경우

효율성 측면의 이점은 실재하지만, 몇 가지 주의 사항이 있습니다. 평가 하네스(eval harness)에서 에이전트가 의도된 방식대로 도구(tools)를 통해 경로를 탐색할 때, 방향 설정(orientation), 영향 분석(impact analysis), 전체 계획 검토(full plan review)와 같은 작업에서 토큰 사용량은 약 46% 감소하고 도구 호출(tool calls)은 84% 감소하는 원시적인(raw) 감소율을 보였습니다. 하지만 에이전트가 항상 정해진 경로로만 움직이지 않는다는 점 — 때로는 단 한 번의 호출로 답을 줄 수 있는 도구를 두고 여러 번 grep하며 헤매기도 한다는 점 — 을 고려하여 재현 동작(replay-behavioral) 관점에서 보면 수치는 37% / 68%에 더 가깝습니다. 품질을 조정한 수치로는 약 33% / 61%에 도달합니다. 이 낮은 수치들이 가장 솔직한 수치이며, 만약 다른 누군가가 저에게 이 패키지를 판매하려 한다면 제가 가장 먼저 확인할 부분입니다.