AOCI-CODE logo — AI-Oriented Cognition Infrastructure

AOCI-CODE

코딩 에이전트가 작성하고 로컬 MCP 서버가 관리하는, 전체 코드베이스의 지속적이며 Git으로 버전 관리되는 지도입니다. 에이전트는 매번 작업을 수행할 때마다 리포지토리를 다시 읽을 필요 없이, 한 번만 이 지도를 읽고 시스템을 파악합니다.

🇺🇸 English | 🇨🇳 简体中文

Status

Runtime

MCP

License

기능 설명 (What it does)

흐름을 잃지 않고 대규모 시스템 구축. Codex, Claude Code, Cursor, OpenCode 등 유사한 에이전트에서, 사용자의 에이전트는 이미 전체 시스템(각 파일의 용도, 의존성, 그리고 무엇이 깨져서는 안 되는지)을 알고 있는 상태에서 모든 작업을 시작합니다. 요청마다 코드베이스를 검색하고 다시 읽는 과정을 멈춥니다. 전문 개발자가 아닌 사람들도 자신만의 시스템을 계속 개선할 수 있으며, 전문 개발자들은 전체 시스템을 에이전트에게 맡기고 아키텍처와 디자인에 집중할 수 있습니다.

단 한 단계로 기존 시스템 인수. 최대 약 500,000 라인까지의 기존 코드베이스를 에이전트가 바라보게 하고 인덱스 생성을 요청합니다. 에이전트는 각 영역을 얼마나 잘 알고 있는지 보고한 후, 그 지점부터 개발을 이어갑니다. 실제 한계는 라인 수가 아니라 인덱스의 크기입니다: 약 300K 토큰의 인덱스로 오늘날 700,000 라인의 상용 시스템이 이렇게 개발됩니다.

사람, 에이전트 또는 대화를 처음부터 다시 시작하지 않고 변경할 수 있습니다. 인덱스는 코드 옆의 저장소에 존재하며 Git으로 버전 관리됩니다. 프로젝트가 다른 사람에게 넘어가거나, 에이전트가 바뀌거나, 새로운 대화를 시작할 때, 인덱스를 한 번 읽는 것만으로도 중단된 지점부터 이어서 작업을 진행합니다.

첫 번째 인덱스 생성 후에는 유지보수가 자동입니다. MCP 서버는 코드 변경을 감지하고 업데이트가 필요한 항목들을 발행(issue)합니다. 에이전트는 각 작업을 완료할 때마다 해당 항목들을 채워 넣기 때문에, 인덱스는 현재 코드와 일치하며 사용자가 유지보수를 위해 멈출 필요가 없습니다.

구조 (What it looks like)

파일당 한 줄로, 모델이 실제 소스에서 작성합니다. 다음은 이 저장소 자체의 인덱스에 있는 실제 항목입니다:

atomic.go[CG9L]: F:지속 가능한 대체 CAS(replace CAS), 생성 CAS(create CAS), 원자적 쓰기(atomic writes), 그리고 클로버 없는 복구 이동(no-clobber recovery moves)을 제공한다 | R:코드:internal/fs/atomic_exchange_linux.go,code:internal/fs/atomic_exchange_windows.go,code:internal/fs/lock.go | A:AtomicWrite,AtomicWriteCAS,AtomicCreateCAS,AtomicMoveCAS | S:네이티브 발행(Native publication)은 덮어쓰는 이름 변경으로 저하되지 않으며; 경쟁 조건(race), unsafe 타입 또는 검증 불가능한 바이트가 있는 경우 제3자 상태를 보존한다

F는 파일이 책임지는 내용, R은 함께 읽어야 하는 것, A는 호출자가 의존하는 것, 그리고 S는 코드에서 추론할 수 없지만 잘못해서는 안 되는 내용을 의미합니다. 태그 [CG9L]은 파일을 레이어(layer), 도메인(domain), 중요도(importance), 크기(size)별로 배치합니다. 이와 같은 몇백 줄이 전체 시스템을 다루며, 에이전트는 이를 한 번에 읽을 수 있습니다. 항목 형식에서 각 필드를 설명합니다.

CodeGraph와 무엇이 다른가요?

CodeGraph는 코드를 심볼(symbols)과 호출(calls)의 그래프로 구문 분석합니다. 에이전트가 질문을 할 때, 정확한 소스 코드와 호출 경로를 반환합니다. 이는 현재 작업에 대한 정밀한 조회 도구입니다.
AOCI-CODE는 모델에게 파일당 한 줄씩 테이블 형태로 작성하게 합니다: 해당 파일의 목적, 연결되는 대상, 그리고 깨지면 안 되는 부분. 에이전트는 작업을 시작하기 전에 전체 인덱스를 먼저 읽기 때문에 시스템을 파악할 수 있습니다. 이 인덱스는 Git에 저장되며 코드와 동기화됩니다.
둘 다 사용하세요: 시스템을 알기 위해 인덱스를 사용하고, 작업 중 정확한 코드를 가져오기 위해 CodeGraph를 사용합니다.

The full comparison에서는 RAG, LSP, 그리고 리포지토리 맵(repo maps)과의 차이점도 다룹니다.

기대할 수 있는 점

첫 번째 인덱스 생성에 시간이 걸립니다. 에이전트는 관리되는 모든 파일을 읽고 파일당 하나의 항목을 작성합니다. 모델과 에이전트의 속도에 따라 20만 줄의 코드 당 약 한 시간이 소요됩니다. 이 과정은 배치(batches)로 실행되며, 중단되면 멈춘 지점부터 재개됩니다.

데이터베이스가 있나요? 인덱싱하세요. MySQL과 PostgreSQL이 지원되며, openGauss 6.0.5와 제약 조건도 지원합니다. MySQL의 경우 5.7.6 이상이어야 하며, MariaDB는 지원하지 않습니다. 코드 인덱스를 먼저 구축한 다음 데이터베이스 인덱스를 구축하세요. 코드 및 테이블 수준의 지식이 함께 제공되면 에이전트는 시스템을 더욱 완벽하게 이해할 수 있습니다.

로컬 전용: 사용자 시스템에서 읽기 전용이며, 인터넷 연결이나 저장된 자격 증명이 필요 없습니다. AOCI-CODE는 소스 코드와 데이터베이스 테이블 구조만 읽으며, 비즈니스 데이터는 절대 다루지 않습니다. 인덱스 파일과 자체 상태를 프로젝트 디렉터리 내에 작성하며, 상태 페이지 등록은 사용자 캐시 디렉터리에 합니다. 인터넷에 접속하거나 아무것도 업로드하지 않습니다: 열리는 연결은 사용자가 선언한 데이터베이스, 카탈로그 메타데이터용, 그리고 자체 루프백(loopback) 상태 페이지로만 한정됩니다. 데이터베이스 자격 증명은 환경 변수 이름으로 참조되며 절대 저장되지 않습니다. 인덱스 텍스트는 이미 사용 중인 모델 채널을 통해 사용자 자신의 에이전트에 의해 로컬에서 작성되므로, AOCI-CODE가 새로운 데이터를 내보내지 않습니다.

빠른 시작

에이전트에게 다음 지침을 주어 AOCI-CODE를 다운로드하고 연결하도록 하세요. 에이전트를 재시작한 후, 두 번째 지침을 보내 인덱스를 빌드하세요.

AOCI-CODE 프로젝트: https://github.com/aoci-spec/aoci-code

이 운영 체제 및 CPU 아키텍처에 대한 최신 릴리스 패키지를 다음에서 다운로드합니다...

에이전트를 재시작한 후, 이것을 보내세요:

먼저 AOCI MCP 서버가 연결되었는지 확인한 다음, 이 프로젝트를 위한 AOCI 인덱스를 빌드하세요. 완료되면 저에게 AOCI 패널 링크를 주세요.

에이전트는 aoci ui --detach --json을 사용하여 백그라운드에서 패널을 시작하고 링크를 제공합니다. AOCI 패널은 표시되는 내용과 다른 명령어들을 다룹니다.

재시작하는 이유: 인덱스는 AOCI의 MCP 도구를 통해 작성되며, init을 실행했던 세션에는 init이 방금 작성한 MCP 서버가 로드되지 않았기 때문입니다. MCP 서버를 동적으로 로드하는 호스트는 재시작이 필요하지 않을 수 있으며, 호스트 통합에서 알려주는 방법을 설명합니다.

프로젝트에 데이터베이스가 있는 경우 (PostgreSQL 및 MySQL 지원, 제한된 openGauss 6.0.5 추가), 그것도 인덱싱하세요. 소스를 데이터베이스 코그니션에 설명된 대로 선언하고, 호스트 환경에 연결 문자열 환경 변수를 제공하세요 (AOCI는 자격 증명을 저장하지 않습니다). 그런 다음 다음을 보내세요:

이 프로젝트를 위한 AOCI 데이터베이스 인덱스를 빌드하세요.

만약 컨텍스트가 압축되었거나, 에이전트가 시스템에 대한 자신만의 그림을 다시 만들기를 원한다면, 이것을 보내세요:

AOCI만을 사용하여 이 프로젝트의 전체 프레임워크 코그니션을 확립하고, 각 영역에 대한 숙련도를 백분율로 알려주며, 개발을 인수할 수 있는지 여부를 알려주세요.

작동 방식

**AOCI (AI 기반 인지 인프라)는 코딩 에이전트와 소프트웨어 시스템 사이에 위치하는 방법론이자 프로토콜입니다. 모델은 추론하고, 에이전트는 계획하고 실행하며, AOCI는 에이전트가 행동하기 전에 읽을 수 있도록 코드, 설정, 테스트 및 데이터베이스 구조를 포함하여 시스템의 최신 설명을 유지합니다. AOCI-CODE는 이 프로젝트 자체로, aoci CLI, MCP 서버, 그리고 이들이 유지하는 인덱스를 의미합니다.

AOCI-CODE는 시스템을 이해하고 변경하는 데 실제로 중요한 것들을 기호와 의미를 결합한 밀도 높은 일반 텍스트 인덱스로 추출합니다. 모델의 컨텍스트가 제한적일 때, 에이전트는 먼저 이 인덱스를 읽어 프로젝트의 핵심 정보를 한 번에 얻고 작업을 시작합니다. 이는 반복적인 검색과 재학습을 줄여주며, 이해도를 작업과 세션 전반에 걸쳐 유지시킵니다.

단순한 일회성 요약이 아닙니다. 이 인덱스는 시스템과 함께 진화하며 프로젝트 내에 남아있어 Git을 사용하여 차이점 비교(diff), 검토, 버전 관리 및 롤백할 수 있습니다.
'파일의 위치' 그 이상입니다. 책임 영역(responsibilities), 강력한 관계(strong relationships), 공개 계약(public contracts), 트랜잭션 경계(transaction boundaries), 호환성 제약 조건(compatibility constraints) 등 코드 구조만으로는 추론하기 어려운 것들을 기록합니다.
이식성이 뛰어납니다 (Portable). 이 인덱스는 모델, 에이전트 또는 세션에 종속되지 않고 프로젝트와 함께 저장됩니다. 코드를 기반으로 하지만, 어떤 에이전트도 그리고 나중의 세션도 처음부터 이해도를 재구축할 필요 없이 이를 재사용할 수 있습니다.
코드와 데이터베이스를 통합합니다. 모델은 데이터베이스 테이블에 대한 별도의 테이블 레벨 인덱스를 구축할 수 있습니다. 이 두 가지가 함께 제공되어 에이전트에게 시스템의 더 완전한 그림을 제시합니다.

이 인덱스는 프로젝트와 함께 저장되는 일련의 관리된 일반 텍스트 파일들로 구성됩니다:

**Root (aoci.txt)**는 현재 인덱스를 구성하는 요소와 활성화 진입점(activation entry point)을 선언합니다.
**Meta (aoci.meta.txt)**는 태그 사전(tag dictionary), FRAS 규칙, 그리고 작성 제약 조건(authoring constraints)을 담고 있습니다.
**Code (aoci.code.txt)**는 코드 및 기타 리포지토리 자산에 대한 모델이 작성한 항목들을 담고 있습니다.
**Database (aoci.database.txt)**는 데이터베이스 인지(Database Cognition)가 활성화된 경우 선택적인 테이블 수준의 항목들을 담고 있습니다.

Root, Meta, 그리고 참여하는 객체 볼륨들(object Volumes)은 함께 전체 인덱스(Whole-Index)를 형성합니다. 이 위에 구축되는 워크플로우는 세 단계로 이루어져 있습니다:

거버넌스 하에 인덱스 구축. 모델은 소스 코드와 승인된 증거(evidence)를 읽습니다. AOCI-CODE는 관리 범위(Managed Scope)와 index 역할을 가진 모든 관리 객체에 대해 모델이 작성하는 항목들을 관장합니다.
행동 전 읽기. 에이전트는 프로젝트 규칙, 라이브 가이드(live guide), 그리고 현재의 전체 인덱스를 읽은 후, 수행해야 할 작업과 관련된 소스 및 기타 증거를 확인합니다.
검증된 변경 후 유지보수. 코드와 테스트가 안정화되면, 프로젝트 규칙과 MCP 워크플로우는 에이전트에게 영향을 받은 항목들을 업데이트하고 인덱스를 aligned 상태로 되돌리도록 지시합니다.

이 파일들은 리포지토리 내의 일반 텍스트(plain text)이기 때문에 Git으로 버전 관리됩니다. 인덱스는 현재 시스템 버전과 정렬된 상태를 유지하지만, 어떤 에이전트와 나중 세션이라도 동일한 전체 인덱스를 읽고 재사용할 수 있습니다.

수동 통합 (Manual integration)

AOCI-CODE는 표준 소스(canonical source)에서 가져오거나 GitHub Releases의 서명된 패키지(signed package)를 사용하십시오. 사전 구축된 바이너리(prebuilt binary)를 사용하기 전에, 설치 가이드에서 기본(basic), 권장(recommended), 또는 전체(full) 검증 수준을 따르고, 완료된 수준을 보고하십시오. 이 README와 검증된 바이너리의 안정적인 절대 경로를 Codex, Claude Code, Cursor, 또는 OpenCode와 같은 신뢰하는 코딩 에이전트에게 제공하십시오. 해당 에이전트는 인 프로젝트 지침(in-project instructions)을 따라 AOCI를 초기화하고, MCP를 통합하며, 첫 번째 인덱스를 구축할 수 있습니다.

첫 번째 인덱스를 생성하는 데 걸리는 시간은 저장소 크기에 따라 달라집니다. 일반적인 통합 과정은 네 단계로 이루어집니다. 바이너리를 준비하고, 에이전트 또는 사용자가 대상 저장소를 초기화하며, 호스트에게 '인덱스 빌드'를 요청하고, 정렬을 검증하는 것입니다. 그 후에는 모든 요청 끝에 '인덱스를 유지 관리하라(maintain the index)'라는 명령어를 사용할 필요가 없습니다. 프로젝트 규칙과 MCP 워크플로우는 관리되는 객체가 변경될 때마다 에이전트가 인덱스를 점진적으로 유지 관리하도록 합니다.

요구 사항 (Requirements)

검증된 릴리스 패키지 또는 표준 AOCI-CODE 소스 저장소의 체크아웃본.
소스 빌드만 해당: go.mod에 명시된 Go 툴체인, make, 그리고 저장소가 필요로 하는 기타 도구들.
Codex, Claude Code, Cursor, 또는 OpenCode와 같은 지원되는 MCP 호스트.
대상 저장소에 대한 일반적인 읽기 및 쓰기 접근 권한.

AOCI-CODE는 모델 제공자 API가 아닌 MCP 호스트와 통합됩니다. DeepSeek과 다른 모델들은 에이전트 또는 해당 모델을 실행하는 호스트가 표준 stdio MCP를 지원하고 도구 계약(tool contract)을 따를 수 있을 때 AOCI-CODE를 사용할 수 있습니다. 단순히 모델 이름만으로는 호환성을 보장할 수 없습니다.

서명된 패키지 경로와 실행 파일 검증 명령어는 설치 가이드에 있습니다. 소스 빌드 경로는 아래와 같습니다.

AOCI-CODE: 전체 코드베이스를 영구적이고 Git 버전 관리하는 지도

요약

핵심 포인트

AOCI-CODE

기능 설명 (What it does)

구조 (What it looks like)

CodeGraph와 무엇이 다른가요?

기대할 수 있는 점

빠른 시작

작동 방식

수동 통합 (Manual integration)

요구 사항 (Requirements)

현재 RC: 검증된 패키지를 사용하거나 소스에서 빌드하기

댓글

AOCI-CODE

기능 설명 (What it does)

구조 (What it looks like)

CodeGraph와 무엇이 다른가요?

기대할 수 있는 점

빠른 시작

작동 방식

수동 통합 (Manual integration)

요구 사항 (Requirements)

현재 RC: 검증된 패키지를 사용하거나 소스에서 빌드하기