코드 인텔리전스: 터미널과 코드 그래프

빌드를 돌렸는데 스택 트레이스가 여든 줄이나 쏟아지며 실패합니다. AI에게 왜 그런지 묻고 싶지만, 그 출력을 전부 채팅창에 복사해 붙이는 건 번거롭습니다. 이 틈은 더 큰 곳에서도 벌어집니다. 워크스페이스 옆에는 코드베이스가 있습니다. 설계 노트는 기능을 설명하고 어딘가의 함수가 그걸 구현하지만, 이 둘을 이어주는 것이 없습니다.

이 레슨은 그 틈을 메우는 두 개발자 도구를 다룹니다. 하나는 터미널 독입니다. 워크스페이스 창 안에서 도는 진짜 셸에, AI로 가는 다리가 키 하나로 놓입니다. 다른 하나는 코드 인텔리전스입니다. 노트에 쓰는 것과 같은 트리플 규율로 소스 코드를 그래프로 매핑합니다.

아래쪽에 도킹된 진짜 터미널

터미널 독은 VSCode식 하단 패널로, 진짜 셸을 PTY, 즉 운영체제가 제공하는 실제 터미널 채널에서 실행합니다. macOS에서는 zsh나 bash, Windows에서는 PowerShell이나 cmd가 뜹니다. 프롬프트, 색상, 알리아스, 잡 컨트롤, vim, less까지 전부 단독 터미널과 똑같이 동작합니다. 실제로 단독 터미널이기 때문입니다.

셸은 $SHELL 환경 변수에서 가져와 로그인 셸로 시작하므로 내 PATH와 알리아스가 그대로 로드됩니다. 새 셸은 활성 워크스페이스 폴더에서 시작해서 ls만 쳐도 내 노트가 바로 보입니다.

독을 열면 에디터가 세로로 갈라질 뿐 아무것도 가리지 않습니다. 독은 워크스페이스가 열려 있을 때만 나타납니다. 홈 화면에서는 버튼이 숨고 단축키도 동작하지 않습니다.

• 타이틀바: 오른쪽 도구 묶음에 있는 사각 터미널 아이콘입니다. 툴팁은 "터미널"과 ⌘` 를 함께 보여주고, 독이 열려 있는 동안 눌린 상태로 보입니다.
• 키보드: ⌘` (Windows/Linux는 Ctrl+`)로 독을 토글합니다. VSCode와 똑같습니다. 설정 ▸ "단축키"의 "터미널 토글"에서 다시 지정할 수 있습니다.
• macOS 메뉴 바: View ▸ "Toggle Terminal".
• "모두 검색" 팔레트(⌘⇧F): "터미널 토글" 항목을 실행합니다. 지금 지정된 단축키가 함께 표시됩니다.
• GitHub 로그인: 자동 기기 인증을 쓸 수 없을 때, 대화상자가 gh auth login을 안내하며 "터미널 열기" 버튼을 내밉니다.

탭, 그리고 숨기기 vs 종료

패널을 접는 것은 종료가 아닙니다. 셰브론이나 ⌘ 로 닫으면 그냥 숨겨질 뿐, 셸은 계속 돌고 스크롤백도 살아 있습니다. 커서가 터미널 안에 있어도 ⌘ 는 동작하고, 프로세스를 끝내는 건 ✕("터미널 종료")뿐입니다.

exit를 치거나 크래시가 나서 셸이 스스로 종료되면 흐릿한 "[process exited]" 한 줄이 찍힙니다. 죽은 탭은 닫을 때까지 그대로 남습니다. 재시작 버튼은 없으니 그 탭을 종료하고 새로 여세요.

셸을 AI에 건네기

여기가 단독 터미널은 못 하는 부분입니다. 채팅 입력창에서 @를 치면 멘션 픽커에 "터미널" 카테고리가 있습니다. 터미널 하나를 고르면 @터미널 1 같은 칩이 메시지에 들어가고, 고른 순간의 최근 출력이 스냅샷으로 함께 실립니다.

"이 빌드 왜 실패했어?"라고 물으면 에이전트가 그 출력을 읽습니다. 복사해 붙일 일도, 스크린샷도 필요 없습니다.

코드 인텔리전스: 코드를 트리플로

두 번째 도구는 워크스페이스에 소스 코드가 있으면 곧바로 깨어납니다. 로컬 인덱서가 그 코드를 읽습니다. 빠른 로컬 파서라서 AI 모델도, 네트워크도 쓰지 않습니다.

이 인덱서는 모든 심볼과 파일 간 관계를 트리플로 워크스페이스별 코드 그래프 저장소에 기록합니다. 함수, 메서드, 클래스, 구조체, 열거형, 트레이트, 모듈, 타입 별칭, 상수까지 전부입니다. .gitignore를 지키고, 숨김 폴더를 건너뛰고, 파일당 약 8ms로 돌아서 빠르고 무료입니다.

이 결정론적 지도 위에 선택적 클라우드 패스가 얹힙니다. 먼저 동의를 받은 뒤, 짧은 코드 발췌를 임베딩해 코드를 의미로 검색할 수 있게 만듭니다. 그러면서 코드가 노트, 개념과 하나의 벡터 공간에서 만나는데, 이것이 교차 모달 브리지입니다.

graph.ts      임포트 →   types.ts
buildGraph()  호출 →     parseNote()
NoteIndex     확장 →     BaseIndex
render.ts     참조 →     buildGraph()

PTY (의사 터미널)

운영체제 수준의 진짜 터미널 채널입니다. 그래서 독 안에서 프롬프트, 색상, vim, 잡 컨트롤이 전부 정상 동작합니다.

코드 그래프 / 코드 인덱스

소스 코드의 결정론적 로컬 지도입니다. 파일과 심볼이 노드이고, 호출, 임포트, 확장, 참조가 엣지이며, 워크스페이스별 트리플로 저장됩니다.

시맨틱 코드 임베딩

선택적 클라우드 패스입니다. 한 번만 동의하면 됩니다. 코드를 정확한 단어 대신 의미로 검색하게 해줍니다.

교차 모달 브리지

코드 심볼과 노트, 개념 라벨이 하나의 벡터 공간에 임베딩됩니다. 그래서 "이 개념에 가장 가까운 코드"와 그 반대를 매치 %로 순위 매길 수 있습니다.

LSP (언어 서버)

PATH에서 찾는 외부 언어별 서버로, 자동완성, 호버, 정의 이동을 제공합니다. 없으면 에디터는 코드 그래프 탐색으로 조용히 대신합니다.

코드 인텔리전스가 나타나는 곳

• 워크스페이스 사이드바에는 코드 탭이 활성일 때 "코드 컨텍스트" 그룹이 생깁니다. "코드 그래프" 섹션은 실시간 배지("색인됨" / "색인 안 됨" / "파싱 오류")를 달고 "정의된 심볼", "사용하는 곳", "사용하는 대상"을 나열합니다. 행 하나하나가 점프이고, 관계가 칩으로 붙습니다: 호출 / 임포트 / 확장 / 참조.
• 같은 그룹의 "관련 지식"은 캐럿을 따라다닙니다. 함수 위에 커서를 두면 의미상 가장 가까운 노트와 개념이 나오고, "그래프로 보기"가 그 심볼을 중심에 둔 3D 별자리를 엽니다.
• "관련 코드"는 노트의 문서 사이드바와 엔티티 페이지 양쪽에 붙습니다. 산문이나 360° 프로필에서 그것을 구현한 심볼로 바로 건너갑니다.
• 코드 인텔리전스 패널의 "개념 ↔ 코드"에서는 개념을 검색하고, 펼치면 매치 %로 순위 매긴 심볼이 나옵니다. 클릭하면 파일이 열립니다.
• 채팅에서는 인덱스가 완성되면 에이전트가 세 가지 능력을 얻습니다. 저장소의 지도를 그리고, 코드를 의미로 검색하고, 심볼의 이웃을 따라갑니다. 워크스페이스 검색 결과에도 "코드" 섹션이 생깁니다.
• 3D 그래프의 "코드 표시" 토글은 코드 파일을 별도 노드 클래스로 그려줍니다. 파일 트리는 아직 처리되지 않은 코드 파일에 빨간 상태 점을, 파싱 오류에는 경고 삼각형을 표시합니다.

외부 언어 서버가 설치되어 있으면 고전적인 IDE 기능이 그 위에 얹힙니다. F12(또는 Cmd+클릭)로 정의 이동, Shift+F12로 참조 찾기, F2로 파일을 넘나드는 이름 변경, ⇧⌥F로 포맷, 타이핑 중 진단 밑줄까지. 서버 없이 코드 파일을 열면 설치 안내 토스트가 한 번 뜨고, 그때까지 에디터는 코드 그래프 탐색으로 조용히 대신합니다.

이것이 개발자를 위한 한 쌍입니다. 키 하나 거리의 진짜 셸과 채팅으로 이어지는 칩 하나짜리 다리, 그리고 노트와 같은 트리플 규율로 매핑된 코드베이스. 아이디어와 구현이 드디어 서로를 찾아냅니다. 같은 트리플이 좌표를 품으면, 에이전트가 그것을 지도 위에 그려 줍니다.