A persistent, Git-versioned map of your whole codebase and database schema that coding agents read before they touch anything. Local-first MCP server + CLI in Go: a governed repository index of code knowledge that gives Claude Code, Codex, Cursor, and opencode long-term context, memory, and code intelligence.

AOCI-CODE – AI 코딩 에이전트를 위한 영구적이고 Git 버전 관리되는 코드베이스 인덱스

개요

AOCI-CODE는 소프트웨어 프로젝트의 일반 텍스트 인덱스를 생성하는 경량 Go 기반 명령줄 도구이자 로컬 MCP (Model-Control-Protocol) 서버입니다. 이 인덱스는 각 소스 파일의 목적, 의존성, 제공되는 공개 심볼 및 명확하지 않은 제약 조건을 기록합니다. 인덱스는 코드와 함께 존재하며 Git으로 버전 관리되고, 코드 변경에 따라 자동으로 업데이트됩니다.

AI 에이전트에게 중요한 이유

일괄 이해 – LLM 기반 코딩 어시스턴트(Claude Code, Cursor, OpenCode, Codex 등)는 AOCI 인덱스를 로드하여 리포지토리를 반복적으로 스캔할 필요 없이 한 번의 패스로 프로젝트 전체를 읽을 수 있습니다.
신속한 인수인계 – 새로운 개발자나 에이전트가 코드베이스를 인계받을 때, 기존 인덱스를 에이전트에 지정하기만 하면 각 파일의 역할, 계약, 제약 조건을 즉시 파악할 수 있습니다.
지속적인 유지보수 – MCP 서버가 리포지토리를 모니터링하고 변경 후 영향을 받는 항목에 플래그를 지정하면 에이전트가 이를 업데이트하여 인덱스가 실제 코드와 항상 일치하도록 유지합니다.
로컬 전용, 개인정보 보호 우선 – 모든 처리는 개발자의 머신에서 이루어지며, 소스 코드나 자격 증명이 외부로 전송되지 않습니다.

핵심 개념

개념	설명
FRAS 항목	파일당 한 줄: `F` (기능/목적), `R` (필수 읽기), `A` (사용 가능한 심볼), `S` (안전 제약 조건). 예: `atomic.go[CG9L]: F:Provides durable replace CAS …`
루트 파일 (`aoci.txt`)	현재 "CognitionSet"에 속하는 인덱스 파일을 선언합니다.
메타 파일 (`aoci.meta.txt`)	태그 사전, FRAS 규칙 및 작성 제약 조건을 보관합니다.
코드 파일 (`aoci.code.txt`)	소스 파일에 대해 모델이 생성한 FRAS 항목입니다.
데이터베이스 파일 (`aoci.database.txt`)	MySQL/PostgreSQL/openGauss용 선택적 테이블 수준 항목입니다.
MCP 서버	코딩 에이전트와 인덱스 사이를 중재하며 `init`, `scan`, `maintain` 등을 처리하는 로컬 프로세스입니다.

표준 워크플로우

설치 바이너리(서명된 릴리스 다운로드 또는 make build).
초기화 리포지토리: aoci init --locale en-US --agent codex. 설정 파일, .gitignore 항목 및 빈 인덱스 스켈레톤이 작성됩니다.
스캔 리포지토리: aoci scan. 에이전트가 관리 파일을 읽고, 모델이 FRAS 항목을 작성하며, 인덱스 파일이 생성됩니다.
UI 시작 (선택 사항): aoci ui --detach --json – 인덱스 상태, 커버리지 비율, 보류 중인 업데이트를 보여주는 웹 패널을 제공합니다.
일반 개발. 코드나 테스트가 변경되면 MCP 서버가 영향을 받는 항목에 플래그를 지정하고 에이전트가 자동으로 업데이트합니다.
일관성 검증: 언제든지 aoci verify 또는 aoci check를 실행합니다.

지원 환경

OS – Linux, macOS, Windows (단일 바이너리, CGO 불필요).
에이전트 – MCP 프로토콜을 지원하는 모든 LLM 기반 코딩 에이전트(Codex, Claude Code, Cursor, OpenCode 등).
데이터베이스 – MySQL, PostgreSQL, openGauss 6.0.5 (테이블 수준 인식은 선택 사항).

AI 툴체인에의 통합

AOCI-CODE는 LLM 모델과 코드베이스 사이에 위치합니다:

LLM model → (writes) → AOCI index (plain-text) → MCP server → Coding agent → Code / Tests

모델은 간결한 FRAS 항목만 생성하면 되고, 에이전트는 인덱스를 사용하여 변경 사항을 계획하므로 컨텍스트 크기가 줄어들고 리포지토리 스캔 반복이 제거됩니다.

시작하기 (퀵스타트)

# 1. 서명된 릴리스를 다운로드하거나 소스에서 빌드
# 2. 바이너리를 안정적인 절대 경로(예: /usr/local/bin/aoci)에 배치
# 3. 프로젝트 루트에서 실행:

aoci init --locale en-US --agent codex

aoci scan

# 4. 에이전트에게 UI를 시작하고 인덱스를 구축하도록 요청
AOCI MCP 서버가 연결되었는지 확인한 후, 이 프로젝트의 AOCI 인덱스를 구축하십시오.

UI는 http://127.0.0.1:8080/#/project와 같은 링크를 반환하며, 커버리지, 보류 중인 업데이트 및 FRAS 항목의 검색 가능한 뷰를 보여줍니다.

라이선스 및 상태

버전 – v0.1.0-rc17 (릴리스 후보).
라이선스 – Fair Source License 1.1 + MIT (FSL-1.1-MIT).
성숙도 – 초기 단계이지만 최대 70만 줄의 상용 코드베이스에서 이미 사용 중입니다.

aoci-spec/aoci-code