AOCI-CODE

AOCI-CODE

코드베이스 전체를 Git으로 버전 관리되는 영속적인 지도로 — 코딩 에이전트가 작성하고, 로컬 MCP 서버가 관리합니다. 에이전트는 한 번 읽으면 시스템을 파악하므로, 매 작업마다 저장소를 다시 읽지 않습니다.

🇺🇸 English | 🇨🇳 简体中文

무엇을 하는가

큰 시스템을 흐름을 놓치지 않고 구축하세요. Codex, Claude Code, Cursor, OpenCode 및 유사한 에이전트에서, 에이전트는 모든 작업을 시작할 때 이미 전체 시스템을 알고 있습니다: 각 파일의 용도, 의존 관계, 그리고 깨져서는 안 되는 것이 무엇인지까지. 매 요청마다 코드베이스를 검색하고 다시 읽는 일이 사라집니다. 전문 개발자가 아닌 사람도 자신의 시스템을 계속 발전시킬 수 있고, 전문 개발자는 전체 시스템을 에이전트에 맡기고 아키텍처와 설계에 집중할 수 있습니다.

기존 시스템을 한 번에 인수하세요. 최대 약 50만 줄 규모의 기존 코드베이스를 에이전트에 지정하고 인덱스 구축을 요청하세요. 에이전트는 각 영역을 얼마나 잘 아는지 보고한 뒤, 그 지점부터 개발을 이어갑니다. 실질적인 한계는 줄 수가 아니라 인덱스의 크기입니다: 70만 줄 규모의 상용 시스템이 현재 이 방식으로 개발되고 있으며, 인덱스는 약 30만 토큰입니다.

사람, 에이전트, 대화를 바꿔도 처음부터 다시 시작하지 마세요. 인덱스는 코드 옆 저장소에 있으며 Git으로 버전 관리됩니다. 프로젝트가 다른 사람에게 넘어가거나, 에이전트를 바꾸거나, 새 대화를 열어도 인덱스를 한 번 읽으면 이전 상태에서 이어집니다.

첫 인덱스 이후에는 유지 관리가 자동입니다. MCP 서버가 코드 변경을 감지하고 업데이트가 필요한 항목을 발행합니다. 에이전트는 각 작업을 마치면서 해당 항목을 채우므로, 인덱스는 현재 코드와 일치하며 유지 관리를 위해 멈출 필요가 없습니다.

어떻게 보이는가

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

atomic.go[CG9L]: F:Provides durable replace CAS, create CAS, atomic writes, and no-clobber recovery moves | R:code: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 never degrades to an overwriting rename; on a race, unsafe type, or unverifiable bytes, preserve third-party state

F는 파일이 담당하는 책임, R은 함께 읽어야 하는 것, A는 호출자가 의존하는 것, S는 코드에서 추론할 수 없지만 틀리면 안 되는 것입니다. 태그 [CG9L]는 파일을 계층, 도메인, 중요도, 크기로 배치합니다. 이런 줄이 수백 개면 전체 시스템을 포괄하며, 에이전트는 한 번에 읽을 수 있습니다. 항목 형식에서 각 필드를 설명합니다.

CodeGraph와 무엇이 다른가?

• CodeGraph는 코드를 심볼과 호출의 그래프로 파싱합니다. 에이전트가 질문하면 정확한 소스와 호출 경로를 반환합니다. 당면한 작업을 위한 정밀 조회 도구입니다.
• AOCI-CODE는 모델이 파일과 테이블당 한 줄씩 작성합니다: 용도, 연결 관계, 깨져서는 안 되는 것. 에이전트는 전체 인덱스를 먼저 읽으므로 작업 시작 전에 시스템을 파악합니다. 인덱스는 Git에 있으며 코드와 동기화됩니다.
• 둘 다 사용하세요: 시스템을 파악하려면 인덱스, 작업 중 정확한 코드를 가져오려면 CodeGraph.

전체 비교에서는 RAG, LSP, 저장소 맵도 다룹니다.

예상할 점

첫 인덱스는 시간이 걸립니다. 에이전트는 관리 대상 파일을 모두 읽고 파일당 한 항목을 작성합니다: 모델과 에이전트 속도에 따라 코드 20만 줄당 약 1시간입니다. 배치로 실행되며 중단되면 멈춘 지점에서 재개합니다.

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

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

빠른 시작

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

AOCI-CODE project: https://github.com/aoci-spec/aoci-code

Download the latest release package for this operating system and CPU architecture from
https://github.com/aoci-spec/aoci-code/releases, and follow the installation instructions
on the Release page to verify it. If no compatible release package exists, or if I
explicitly request the latest source, build it from the official repository.

After extracting the package, place aoci (aoci.exe on Windows) at a stable absolute path.
Then use that absolute path to do the following for my project:

1. Run init to initialize AOCI and integrate MCP for the current host; if this host does
   not write project configuration (Cursor, for example), give me the configuration I
   need to paste myself
2. Run scan

   scan takes its file inventory from Git, so do not add the cognition assets
   init writes (aoci.txt, aoci.meta.txt, aoci.code.txt, AGENTS.md) to .gitignore
   or .git/info/exclude — an ignored asset is silently skipped and the index
   cannot be built. Leave the host-config ignore init writes for itself as it is.

3. Tell me to restart the agent so the newly written MCP server takes effect

Stop after those three steps and do not build the index yet — I will tell you to continue
after the restart.

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

First confirm the AOCI MCP server is connected, then build the AOCI index for this project. When it is complete, give me the AOCI panel link.

에이전트는 aoci ui --detach --json로 패널을 백그라운드에서 시작하고 링크를 전달합니다. AOCI 패널에서 표시 내용과 기타 명령을 다룹니다.

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

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

Build the AOCI database index for this project.

컨텍스트가 압축되었거나 에이전트가 시스템에 대한 이해를 재구축하길 원한다면 다음을 보내세요:

Using only AOCI, establish whole-framework cognition of this project, tell me your mastery of each area as a percentage, and whether you can take over development.

작동 방식

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

AOCI-CODE는 시스템을 이해하고 변경하는 데 실제로 중요한 것을 심볼과 의미를 결합한 밀도 높은 평문 인덱스로 정제합니다. 모델 컨텍스트가 제한적일 때 에이전트는 인덱스를 먼저 읽고 프로젝트의 핵심 정보 대부분을 한 번에 얻은 다음 작업을 시작합니다. 이는 반복적인 검색과 재학습을 줄이고, 작업과 세션 전반에 걸쳐 이해를 이어갑니다.

• 일회성 요약이 아닙니다. 인덱스는 시스템과 함께 진화하며 프로젝트에 남아 있어 Git으로 diff, 리뷰, 버전 관리, 롤백할 수 있습니다.
• "파일이 어디 있는지" 이상입니다. 책임, 강한 관계, 공개 계약, 트랜잭션 경계, 호환성 제약 등 코드 구조에서 추론하기 어려운 것들을 기록합니다.
• 이식 가능합니다. 인덱스는 프로젝트와 함께 저장되며 모델, 에이전트, 세션에 묶이지 않습니다. 코드와 정렬되어 있는 한, 어떤 에이전트와 이후 세션도 이해를 처음부터 재구축하지 않고 재사용할 수 있습니다.
• 코드와 데이터베이스를 함께. 모델은 데이터베이스 테이블에 대해 별도의 테이블 수준 인덱스를 구축할 수 있습니다. 함께 제공되면 둘은 에이전트에게 시스템의 더 완전한 그림을 제공합니다.

인덱스는 프로젝트와 함께 저장되는 관리된 평문 파일 집합입니다:

• **Root (aoci.txt)**는 현재 인덱스를 구성하는 요소를 선언하며 활성화 진입점입니다.
• **Meta (aoci.meta.txt)**는 태그 사전, FRAS 규칙, 작성 제약을 담습니다.
• **Code (aoci.code.txt)**는 코드 및 기타 저장소 자산에 대해 모델이 작성한 항목을 담습니다.
• **Database (aoci.database.txt)**는 데이터베이스 인지가 활성화된 경우 선택적 테이블 수준 항목을 담습니다.

Root, Meta, 그리고 참여하는 객체 Volume이 함께 Whole-Index를 구성합니다. 그 위의 워크플로는 세 단계입니다:

1. 거버넌스 하에 인덱스 구축. 모델은 소스 코드와 승인된 증거를 읽습니다. AOCI-CODE는 Managed Scope와 index 역할로 모델이 모든 관리 대상 객체에 대해 작성하는 항목을 관리합니다.
2. 행동 전에 읽기. 에이전트는 프로젝트 규칙, 라이브 가이드, 현재 Whole-Index를 읽은 다음 당면한 작업에 대한 소스와 기타 증거를 확인합니다.
3. 검증된 변경 후 유지 관리. 코드와 테스트가 안정되면 프로젝트 규칙과 MCP 워크플로가 에이전트에게 영향을 받은 항목을 업데이트하고 인덱스를 aligned 상태로 되돌리도록 합니다.

이 파일들은 저장소의 평문이므로 Git이 버전 관리합니다. 인덱스가 현재 시스템 버전과 정렬되어 있는 한, 어떤 에이전트와 이후 세션도 동일한 Whole-Index를 읽고 재사용할 수 있습니다.

수동 통합

정식 소스에서 AOCI-CODE를 받거나 GitHub Releases의 서명된 패키지를 사용하세요. 사전 빌드된 바이너리를 사용하기 전에 설치 가이드의 기본, 권장, 전체 검증 수준을 따르고 어느 수준이 완료되었는지 보고하세요. 이 README와 검증된 바이너리의 안정적인 절대 경로를 신뢰하는 코딩 에이전트(예: Codex, Claude Code, Cursor, OpenCode)에게 전달하세요. 에이전트는 프로젝트 내 지시에 따라 AOCI를 초기화하고, MCP를 통합하고, 첫 인덱스를 구축할 수 있습니다.

첫 인덱스에 걸리는 시간은 저장소 크기에 따라 다릅니다. 일반적인 통합은 네 단계입니다: 바이너리 준비, 에이전트 또는 직접 대상 저장소 초기화, 호스트에 "인덱스 구축" 요청, 정렬 검증. 그 후에는 매 요청을 "인덱스 유지 관리"로 끝낼 필요가 없습니다. 프로젝트 규칙과 MCP 워크플로가 관리 대상 객체가 변경될 때마다 에이전트가 인덱스를 점진적으로 유지 관리하도록 합니다.

요구 사항

• 검증된 릴리스 패키지 또는 정식 AOCI-CODE 소스 저장소의 체크아웃.
• 소스 빌드에만 해당: go.mod, make 및 저장소가 요구하는 기타 도구가 선언한 Go 툴체인.
• 지원되는 MCP 호스트(예: Codex, Claude Code, Cursor, OpenCode).
• 대상 저장소에 대한 일반적인 읽기 및 쓰기 액세스.

AOCI-CODE는 모델 제공자 API가 아니라 MCP 호스트와 통합됩니다. DeepSeek 및 기타 모델은 이를 실행하는 에이전트나 호스트가 표준 stdio MCP를 지원하고 도구 계약을 따를 수 있다면 AOCI-CODE를 사용할 수 있습니다; 모델 이름만으로는 호환성이 확립되지 않습니다.

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

현재 RC: 검증된 패키지 사용 또는 소스에서 빌드

[!IMPORTANT] AOCI-CODE v0.1.0-rc22는 현재 릴리스 후보입니다. FSL-1.1-MIT에 따른 Fair Source/소스 공개 소프트웨어입니다; LICENSE를 참조하세요. 정식 소스에서 빌드하거나 릴리스 검증 절차를 따른 후 v0.1.0-rc22 GitHub Release의 서명된 패키지를 사용하세요.

서명된 Release 바이너리는 자신을 aoci version 0.1.0-rc22로 식별합니다. 소스 빌드는 대신 정확한 체크아웃을 식별하며 v0.1.0-rc22-1-g<short-commit>(해당되는 경우 -dirty 추가)와 같은 개발 버전을 보고할 수 있으며, Git 커밋과 함께 표시됩니다. 이는 서로 다른 빌드 입력이며 버전 충돌이 아닙니다.

GitHub CLI로 다운로드하려면 먼저 인증한 다음 태그된 Release 자산을 다운로드하세요:

gh auth login
gh release download v0.1.0-rc22 --repo aoci-spec/aoci-code

익명 다운로드의 경우 브라우저에서 v0.1.0-rc22 Release 페이지를 열고 필요한 아카이브와 검증 자산을 다운로드하세요.

소스에서 빌드하려면 정식 저장소를 복제하고 바이너리를 빌드한 후 결과 경로를 안정적으로 유지하세요:

git clone https://github.com/aoci-spec/aoci-code.git
cd aoci-code
mkdir -p build
make build
./build/aoci --version

Windows에서는 PowerShell에서 동일한 소스를 빌드하세요:

git clone https://github.com/aoci-spec/aoci-code.git
Set-Location .\aoci-code
New-Item -ItemType Directory -Force .\build | Out-Null
make build
.\build\aoci.exe --version

그런 다음 이 README를 이미 프로젝트를 신뢰하는 에이전트에게 전달하고 요청하세요:

Read this AOCI-CODE README and use the built aoci binary at its stable absolute path
to initialize AOCI for the current project, integrate MCP, and run scan. Stop there and
tell me to restart the agent; I will ask you to build the index afterwards.

에이전트는 프로젝트 루트를 식별하고, 빌드된 바이너리에 대한 안정적인 절대 경로를 사용하며, 현재 호스트에 맞는 초기화를 실행하고, 호스트 재시작이나 실제 사람의 승인이 필요할 때 이를 명확히 알려야 합니다. 바이너리는 AOCI-CODE 체크아웃에 그대로 두거나 공유 도구 디렉터리로 옮겨도 되지만, MCP 구성이 올바른 절대 경로를 가리켜야 합니다.

수동 초기화

AOCI를 직접 초기화하려면 대상 저장소 루트에서 다음을 실행하거나, --repo을 통해 명시적 경로를 전달하십시오:

AOCI=/absolute/path/to/aoci-code/build/aoci
"$AOCI" --repo . init --locale en-US --agent codex
"$AOCI" --repo . scan

init은 로캘 구성, 관리되는 AGENTS.md 규칙 블록, Git 경계, 그리고 빈 인덱스 골격을 작성합니다. 구성과 프롬프팅은 호스트마다 다릅니다. 호스트 통합을 참조하십시오. 이는 파일 이름, 디렉터리, 또는 AST로부터 비즈니스 의미를 만들어내지 않습니다.

새 저장소의 경우, 첫 번째 scan이 관리되는 Baseline을 설정합니다. 이미 거버넌스가 적용된 Baseline이 있는 프로젝트에서 관리 범위를 추가, 제거 또는 변경하는 것은 공식 Scope Change 워크플로를 거칩니다. scan --force는 거버넌스 사실을 재정의하기 위한 지름길이 아닙니다. --force 또한 해결되지 않은 드리프트, 영수증, 또는 복구 경계를 지울 수 없습니다.

$Aoci = (Resolve-Path "C:\path\to\aoci-code\build\aoci.exe").Path
& $Aoci --repo . init --locale en-US --agent codex
& $Aoci --repo . scan

에이전트가 첫 인덱스를 빌드하도록 하기 (중요)

초기화와 scan이 완료되면, 에이전트 세션이 이미 AOCI 도구를 노출하고 있는지 확인하십시오. 그렇지 않다면 새로 고치거나 재시작하십시오. 그런 다음 대상 프로젝트에 대해 에이전트에 다음을 입력하십시오:

First confirm the AOCI MCP server is connected, then build the AOCI index for this project. When it is complete, give me the AOCI panel link.

에이전트는 aoci ui --detach --json로 백그라운드에서 패널을 시작하고 링크를 전달합니다. AOCI 패널은 패널이 보여주는 내용과 기타 명령을 다룹니다.

호스트는 프로젝트의 AOCI 규칙과 라이브 가이드를 읽고, 소스 코드, 테스트, 구성, 그리고 관련 증거를 검사한 다음, 역할이 index인 모든 관리 객체에 대해 FRAS 후보를 작성합니다. Plan, Stage, Check, Diff, CAS, 또는 Apply를 직접 조율할 필요는 없습니다.

첫 인덱스가 완료되면, 평소처럼 일반적인 개발 요청을 보내십시오. 예를 들어:

Add priorities to tasks, including the frontend, backend, database, and test changes.

"마지막에 AOCI 인덱스를 유지하라"고 덧붙일 필요가 없습니다. 프로젝트 규칙과 MCP는 에이전트가 코드와 테스트가 안정되면 인덱스 변경을 확인하고, 공식 워크플로를 통해 영향을 받은 항목을 업데이트하도록 합니다. 프로젝트가 automation.mode=auto을 사용하는 경우, AOCI-CODE는 실제 사람의 승인이 필요하거나, 외부 작업을 수행해야 하거나, 복구를 입증할 수 없거나, 안전 검사가 실패하거나, 제3자 동시성 충돌이 발견될 때만 개입합니다. 다른 자동화 모드는 자체 런타임 계약을 따릅니다.

정렬 확인

온보딩이 완료되면 다음을 실행하십시오:

"$AOCI" --repo . verify
"$AOCI" --repo . check

인덱스와 현재 관리 소스는 aligned로 다시 수렴해야 합니다. 그렇지 않다면 먼저 라이브 가이드를 참조하십시오. 내부 상태 머신을 래퍼 스크립트에 복제하지 마십시오:

"$AOCI" --repo . index agent guide --agent codex --json

기본 진단 실행

"$AOCI" --repo . capabilities
"$AOCI" --repo . doctor

호스트가 실제로 어떤 AOCI에 연결되어 있는지 확인하려면, 디스크에 있는 것이 아니라 서버가 자신에 대해 보고하는 내용을 읽으십시오. 모든 aoci_overview check_only 응답 또는 모든 aoci_maintain 응답에서 cognition_receipt.mcp_service_version는 실행 중인 버전이고 runtime_repository_root은 그것이 관리하는 저장소입니다. 일치하는 바이너리 경로는 프로젝트의 .mcp.json 또는 동등한 호스트 구성에 있는 command입니다: .codex/config.toml, opencode.json, 또는 .cursor/mcp.json. 디스크의 바이트를 교체해도 실행 중인 MCP 프로세스는 바뀌지 않으므로, 업그레이드나 롤백 후에는 해당 사실을 기준으로 다시 확인하십시오.

일회성 둘러보기에는 저장소에서 examples/minimal-repository를 사용하십시오.

make fast

make full
./build/aoci --version

mkdir -p build
CGO_ENABLED=0 go build -o build/aoci ./cmd/aoci

초기화 후 나타나는 것

일반적인 저장소에는 다음과 같은 인덱스 파일이 포함됩니다:

aoci.txt                    Root: declares the current CognitionSet and participating Volumes
aoci.meta.txt               Meta: tag dictionary, FRAS rules, and authoring constraints
aoci.code.txt               Code: model-authored entries for code and repository assets
aoci.database.txt           Database: optional table-level entries; absent by default
.aoci/
├── config.json             Team policy, Locale, Scope, and budgets
├── baseline.json           Governed Baseline for source, index, and database bindings
├── curation.json           Optional file-level include/exclude decisions
└── ...                     Drafts, Ledger, transactions, and recovery evidence; normally not committed to Git

새 프로젝트를 초기화하면 Root, Meta, 그리고 빈 Code Volume이 생성되며, Database는 기본적으로 존재하지 않습니다. AOCI-CODE는 저장소나 데이터베이스에 대한 비즈니스 의미를 스스로 생성하지 않습니다.

aoci init --agent <name>는 추가로 호스트 통합 구성을 작성합니다 (.mcp.json, .claude/settings.json, .codex/config.toml, 또는 opencode.json). 이 구성의 명령과 저장소 경로는 머신에 종속된 절대 경로입니다. 해당 파일을 저장소의 .gitignore에 추가하고 커밋하지 마십시오. 커밋된 사본은 다른 모든 머신에서 깨지며, 설치 프로그램이 키 존재 여부로 기존 항목을 감지하기 때문에 그곳에서 init을 다시 실행하면 깨진 경로가 조용히 유지됩니다.

개발 작업이 실행되는 방식

아래 두 다이어그램은 AOCI의 내부 구현이 아니라 여러분이 경험하는 워크플로를 보여줍니다.

새 프로젝트: 먼저 간단한 시스템을 구축한 후 AOCI 도입

flowchart TD
    I["The user proposes a product idea and requirements"] --> S["Use the agent's existing capabilities to build a simple new system"]
    S --> Q["Integrate AOCI MCP"]
    Q --> V["The agent builds the Whole-Index and verifies aligned"]
    V --> N["The user continues with ordinary development requests"]
    N --> M["The agent completes code, tests, and incremental index maintenance"]
    M --> N

새 시스템은 첫 코드 줄부터 AOCI-CODE가 필요하지 않습니다. 먼저 에이전트의 기존 기능으로 프로토타입을 구축하십시오. 대략 10,000–30,000줄이 도입하기 좋은 시점입니다(엄격한 임계값은 아님). 세션 간 연속성을 더 일찍 원하는 팀은 더 빨리 통합할 수 있습니다.

기존 프로젝트: 저장소를 인덱싱한 후 반복

flowchart TD
    R["Existing repository, tests, configuration, and optional Schema"] --> B["Build AOCI-CODE from canonical source<br/>Request index generation"]
    B --> E["The agent inspects the existing system and writes the first index"]
    E --> V["Verify, Check, and Guide converge to aligned"]
    V --> T["The user submits an ordinary development task"]
    T --> C["The agent modifies code and runs quality checks"]
    C --> U["MCP guides the agent through index maintenance"]
    U --> G["The index and the current system return to aligned"]
    G --> T

첫 인덱스가 완료되면 두 흐름 모두 일상적으로 동일하게 작동합니다. 여러분은 비즈니스 또는 엔지니어링 요구 사항을 설명하고, 에이전트는 Whole-Index와 현재 증거를 결합하여 개발과 검증을 수행하며, 작업을 마무리하면서 MCP를 통해 변경된 객체를 업데이트합니다. 내부 Plan, Stage, Diff, CAS, 또는 Baseline 명령을 배울 필요가 없으며, 모든 프롬프트에서 유지 관리 요구 사항을 반복할 필요도 없습니다.

공식 쓰기가 시작되기 전에 전체 배치가 거부되면 인덱스는 변경되지 않습니다. 공식 쓰기가 시작된 후 워크플로가 중단되면, 시스템은 불변 의도, 쓰기 증거, 그리고 복구 상태를 유지한 다음, 입증 가능한 사후 이미지에서 재개하거나 정확한 사전 이미지로 롤백합니다. 제3자 바이트 충돌은 페일 클로즈드로 처리됩니다. AOCI-CODE는 "쓰기를 완료"하기 위해 외부 수정을 절대 덮어쓰지 않습니다.

최종 상태는 항상 applied, repair_required, 또는 stopped 중 하나입니다. stopped는 성공이 아니며, 반드시 아무것도 쓰이지 않았다는 것을 의미하지도 않습니다. failed_step, 공식 쓰기 증거, 그리고 가이드가 반환하는 복구 조치를 검사하십시오.

누가 무엇을 하는가: 모델과 AOCI-CODE

모델은 의미를 소유한다

호스트 모델은 소스 코드, 테스트, 구성, 문서, 그리고 필요한 모든 증거를 읽은 다음 다음을 결정합니다:

• 객체가 실제로 무엇을 담당하는지;
• 어떤 파일, 모듈, 또는 데이터베이스 객체가 안전하게 변경하기 위해 고려해야 하는 강한 관계인지;
• 어떤 API, 명령, 형식, 또는 관찰 가능한 계약을 노출하는지;
• 어떤 트랜잭션, 권한 부여, 동시성, 캐싱, 배포, 호환성, 또는 이력 제약이 일반적인 구조만으로는 추론할 수 없는지.

AOCI-CODE는 파일 이름, 경로, 확장자, AST, 또는 템플릿으로부터 FRAS를 조립하지 않으며, 모델이 작성한 것을 조용히 다시 쓰지 않습니다.

AOCI-CODE는 거버넌스를 소유한다

AOCI-CODE는 다음을 담당합니다:

1. Safe Inventory, Managed Scope, 그리고 현재 Baseline 설정;
2. 현재 Whole-Index 전달 및 그 정체성 확인;
3. 결정론적 계획, 대상 집합, 그리고 소스 SHA-256 값 생성;
4. 후보 구조, 태그 사전, 관계 정체성, 범위, 소유권, 예산, 그리고 영향 범위 검증;
5. 검사, diff, 그리고 리뷰 콘텐츠 간의 바인딩 보존;
6. 교차 프로세스 잠금, CAS, 그리고 원자적 쓰기로 전체 배치 커밋;
7. 쓰기 후 실패 시 Baseline 전진, 원장 추가, 그리고 복구 증거 보존;
8. Verify, Check, 그리고 가이드를 통해 현재 거버넌스 상태를 다시 입증;
9. 두 번째 진실 원천을 생성하지 않고 권위 있는 자산으로부터 Lineage, Relations, Impact, Snapshot, 그리고 Evolution 관찰 도출.

모든 것이 녹색인 머신 결과는 인코딩된 구조적 및 거버넌스 계약이 유지됨을 의미할 뿐이며, 모델이 작성한 모든 진술이 올바르다는 것을 의미하지는 않습니다.

인덱스가 구성되는 방식

AOCI 인덱스에는 두 계층이 있습니다: 인덱스 규칙과 인덱스 항목입니다. 제품은 두 가지 물리적 레이아웃을 지원하며, 이들은 하나의 파일 형식이 아닙니다.

Volumes v1 레이아웃

Volumes 프로젝트는 책임을 분리합니다:

• aoci.txt는 Root일 뿐입니다. 현재 CognitionSet에 참여하는 Volumes를 선언합니다.
• aoci.meta.txt는 Meta를 보유합니다: 태그 사전, FRAS 규칙, 예산, 그리고 작성 계약.
• aoci.code.txt은 코드 객체에 대한 항목을 보유합니다.
• aoci.database.txt은 Database Cognition이 활성화된 경우 데이터베이스 객체에 대한 항목을 보유합니다.

Code와 Database Volume은 동일한 FRAS 라인 구조를 공유하지만, 독립적인 객체 정체성, 증거 바인딩, 소유권, 그리고 수명 주기를 가집니다. Root, Meta, 그리고 객체 Volume이 함께 Whole-Index를 형성합니다. aoci.txt Root만 읽는 것으로는 전체 시스템을 읽었다고 주장할 수 없습니다.

지도라고 생각하십시오:

• 인덱스 규칙은 지도의 범례와 좌표계입니다.
• 인덱스 항목은 각 위치를 설명하는 마커입니다.
• Root는 현재 지도 세트의 카탈로그 및 버전 진입점입니다.
• Volume은 동일한 프로토콜에 의해 관리되지만 자체 증거 원천과 수명 주기를 가진 별도의 시트입니다.

인덱스 헤더의 모습

Root와 Meta는 각각 머신이 읽는 헤더 라인으로 시작합니다. 다음은 en-US 프로젝트 이름이 my-service인 새 프로젝트에 대해 aoci init가 작성하는 내용이며, 활성화 진입점인 Root부터 시작합니다:

#AOCI-ROOT-MANIFEST: 1
#Format-Version: cognition-volumes/v1
#Locale: en-US
#Project: my-service
#Global-Invariants: -
#Volume: id=meta kind=meta path=aoci.meta.txt format=meta-v1 depends=- state=enabled
#Volume: id=code kind=code path=aoci.code.txt format=object-fras-v2 depends=meta state=enabled

각 #Volume: 라인은 하나의 참여 Volume을 그 정체성, 종류, 경로, 형식, 의존성, 그리고 활성화 상태와 함께 선언합니다. 여기에 선언되지 않은 Volume은 작업 트리에 무엇이 있든 현재 CognitionSet의 일부가 아닙니다. Database Cognition을 활성화하면 #Volume: id=database kind=database path=aoci.database.txt format=table-fras-v2 depends=meta state=enabled 라인이 하나 더 추가됩니다.

그런 다음 Meta는 모든 항목을 관리하는 규칙으로 시작합니다:

#AOCI-META-VOLUME: 1
#Object-Protocol: repository-cognition-object/v2
#FRAS-Discipline: 2
#FRAS-v2-Limits-Authority: machine-contract
#S-Admission: non-inferable-and-error-preventing
#S quota: C9-8≤600 C7-4≤200 C3-1≤50
#Object-Kinds: code=file database=table

#FRAS-v2-Limits-Authority: machine-contract는 핵심 라인입니다. 필드 제한은 이 텍스트가 아니라 바이너리에 속하므로, 프로젝트는 자체 Meta를 편집하여 이를 넓힐 수 없습니다. #S-Admission와 #S quota은 특히 S 필드를 관리합니다: 거기에 무엇이 기록될 수 있는지, 그리고 각 중요도 밴드가 얼마나 많은 문자를 사용할 수 있는지입니다. 태그 사전은 이 라인들 바로 뒤에 이어집니다. 아래에서 전체가 표시됩니다.

Code Volume은 단일 라인 #AOCI-CODE-VOLUME: 1로 시작하며, 그 이후의 모든 것은 디렉터리 섹션과 항목입니다.

이것들은 새 프로젝트가 시작하는 값이며, 고정된 프로토콜 상수가 아닙니다. 이후에는 각 저장소의 자체 Root와 Meta가 권위 있습니다. 오래된 프로젝트는 사용자 정의 태그 사전을 가질 수 있으며, --locale zh-CN로 초기화된 프로젝트는 #Locale: zh-CN를 작성하고 그에 따라 #S quota: 키를 현지화합니다.

인덱스 규칙이 정의하는 것

Volumes v1에서 프로젝트의 Meta Volume이 이러한 규칙을 저장하며, Legacy 레이아웃에서는 단일 헤더에 위치합니다. 프로젝트마다 다른 태그 사전을 사용할 수 있지만, 기본 FRAS 구조는 동일하게 유지됩니다.

이 README는 이러한 규칙을 읽는 방법만 설명합니다. 구체적이고 실행 가능한 규칙은 현재 프로젝트의 Meta 또는 Legacy 헤더, AOCI 가이드, 정식 명세를 따르십시오.

하나의 항목이 기록하는 것 (FRAS)

규칙이 마련되면, 모델은 index 역할을 가진 모든 관리 대상 객체에 대해 하나의 항목을 작성합니다. observe 역할은 변경 관찰에만 참여하고, exclude 역할은 의도적으로 제외된 것을 표시하며, 둘 다 정식 항목을 소유하지 않습니다. AOCI는 FRAS를 사용하여 항목에서 가장 중요한 네 가지 정보를 구성합니다:

• F — Function(기능): 객체가 책임지는 것.
• R — Relations(관계): 객체를 이해하거나 안전하게 변경하기 위해 함께 고려해야 하는 다른 객체.
• A — API: 객체가 노출하는 인터페이스, 명령, 형식 또는 관찰 가능한 계약.
• S — Non-obvious constraints(비자명한 제약): F, R, A가 다루지 않지만 객체를 안전하게 이해하거나 변경하기 위해 필요한 중요한 정보로, 핵심 제약, 예외, 경계, 특수 의미 등이 포함됩니다. S는 처음 세 필드를 반복해서는 안 됩니다.

예를 들어, ===.../internal/fs/=== 디렉터리 섹션 내에서 항목은 basename을 사용합니다:

atomic.go[CG9L]: F:Provides durable replace CAS, create CAS, atomic writes, and no-clobber recovery moves | R:code: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 never degrades to an overwriting rename; on a race, unsafe type, or unverifiable bytes, preserve third-party state 

디렉터리 섹션과 basename은 코드 객체 아이덴티티로 해석됩니다. 교차 Volume 또는 시스템 프로젝션의 경우 code:internal/fs/atomic.go과 같은 정규 아이덴티티로 확장됩니다. 데이터베이스 객체는 database://primary/public/orders과 같은 자체 정규 아이덴티티를 사용합니다.

항목은 두 부분으로 구성됩니다:

atomic.go [CG9L]
└─ object ─┘ └ tags ┘

F: Core responsibility
R: Strong relationships that must be understood together
A: External interface or contract
S: Important additional information beyond F, R, and A

간결한 태그는 각 객체에 아키텍처 계층, 기능 도메인, 중요도, 선택적 기술적 특성, 크기에 대한 좌표를 부여합니다. 태그 사전은 프로젝트의 Meta Volume 또는 Legacy 헤더에 의해 정의됩니다. 프로그램은 사전과 구조를 검증하지만, 비즈니스 의미를 결정하지는 않습니다.

S는 개요, 일반적인 요약, 또는 F, R, A의 반복이 아닙니다. 처음 세 필드가 다루지 않으며 이해나 엔지니어링 정확성에 영향을 미치는 중요한 정보를 추가합니다. 예를 들어:

• Redis 접근 실패 시 데이터베이스로 폴백해야 함;
• 특정 테이블은 AutoMigrate에 들어가서는 안 됨;
• 레거시 호환 분기는 일반적인 정리로 제거되어서는 안 됨;
• 쓰기 실패 후 원본 파일이 보존되어야 함.

모델은 실제 소스 코드와 증거로부터 이를 작성합니다. AOCI-CODE는 항목의 구조를 검증하고, 소스 파일에 바인딩하며, 정식 인덱스에 들어가는 방식을 관리합니다.

시작 태그 사전 읽기

다음 발췌는 현재 en-US Volume Meta 템플릿(textassets/en-US/templates/volume-meta.txt.tmpl)에서 그대로 복사한 것입니다. 이는 시작 사전이며 보편적 어휘가 아닙니다: 각 저장소의 정식 Meta가 여전히 권위를 가집니다. 시작 사전은 D 사전을 선언하지 않습니다; D는 선택적 축으로 남아 있으며 현재 정식 Meta가 선언한 경우에만 사용할 수 있습니다.

#Canonical-Tag-Authoring: compact A+B+C+[D]+E; dotted form is read compatibility only
#Code canonical identity example: code:path/to/file.go
#Code Entry example: file.go[EG7T]: F:Runs the example application | R:code:config/load.go | A:main | S:Exits non-zero when the config file is missing; it never falls back to built-in defaults
#[Tag dictionary: code]
#A Layer: C-SharedFoundation E-EntryBoundary A-ApplicationOrchestration D-DomainLogic K-AlgorithmComputation M-Middleware P-Persistence I-IntegrationAdapter R-RuntimeFoundation L-LibrarySDK F-DeclarativeConfiguration O-OperationsDelivery T-TestValidation S-DocumentationSpecification X-DevelopmentTooling Z-Other
#B Module: G-CrossDomain U-UserInteraction B-CoreBusiness D-DataState I-IdentityAccess N-NetworkProtocol M-MessageEvent S-SecurityPrivacy C-ConfigurationPolicy O-Observability R-ReliabilityRecovery P-PerformanceResource W-WorkflowScheduling A-AnalyticsIntelligence H-HardwareDevice L-Localization V-BuildRelease Q-QualityAssurance E-ExtensionPlugin Z-Other
#C Importance: 9-highest 8-very-high 7-high 6-above-average 5-medium 4-below-average 3-low 2-very-low 1-lowest
#E Scale: L-large>400 M-medium200-400 S-small100-200 T-tiny<100
#[Tag dictionary: database]
#A Layer: E-EntityMaster T-TransactionFact R-RelationMapping M-DetailDependent C-ReferenceDictionary S-StateStorage H-HistoryVersion L-LogAudit Q-QueueOutbox A-AggregateProjection K-KeyValueConfiguration B-DocumentLargeObject Z-Other
#B Module: G-CrossDomain B-CoreBusiness I-IdentityAccess T-OrganizationTenant U-UserExperience F-FinanceBilling K-ContentKnowledge C-ConfigurationPolicy W-WorkflowTask M-MessageEvent N-ExternalIntegration S-SecurityPrivacy O-ObservabilityAudit R-ReliabilityRecovery P-PerformanceResource A-AnalyticsIntelligence H-HardwareDevice L-Localization V-BuildRelease Q-QualityTesting E-ExtensionPlugin Z-Other
#C Importance: 9-highest 8-very-high 7-high 6-above-average 5-medium 4-below-average 3-low 2-very-low 1-lowest
#E Scale: L-large>400 M-medium200-400 S-small100-200 T-tiny<100

시작 코드 사전에서 [CG9L]은 C SharedFoundation, G CrossDomain, 9 최고 중요도, L 대규모를 의미하며, D 값은 존재하지 않습니다. 이는 기존 항목을 읽는 방법을 설명하는 것이지, 모델이 태그를 할당하는 방법을 설명하는 것이 아닙니다. 모델은 여전히 소스와 수용된 증거에 기반하여 현재 프로젝트 Meta에서 태그를 선택합니다.

Cognition Volumes

AOCI-CODE는 하나의 논리적 Whole-Index를 유지하며, 각 종류의 인덱스는 자체 파일, 소유권, 라이프사이클을 가집니다.

각 객체는 정확히 하나의 유효한 소유자를 가집니다. 객체를 잘못된 Volume에 배치하면 소유권 충돌이 발생합니다. AOCI-CODE는 기계가 잘못된 소유자, 올바른 소유자, 현재 객체 사실을 증명할 수 있을 때만 이를 수정하며, 유사한 이름으로 소유권을 추측하지 않습니다.

Code Volume, Database Volume, 범위는 함께 진화할 수 있지만, 하나의 관리되는 커밋 경계를 공유합니다. 하나의 도메인을 적용할 때 다른 도메인의 기존 Baseline 프로젝션을 폐기해서는 안 됩니다. Volume 적용, Baseline 업데이트, 관련 범위 프로젝션은 하나의 일관된 트랜잭션 결과로 게시되거나 증명 가능한 복구로 진입합니다. "파일은 성공했지만 다른 Volume에 baseline이 없는" 반쯤 완료된 상태를 남기지 않습니다.

호스트 통합

aoci init는 항상 관리되는 에이전트 규칙을 작성하지만, 호스트 통합은 다릅니다:

• Codex는 프로젝트 수준 MCP 구성을 받으며, --hooks와 함께 컨텍스트 압축 프롬프트와 SessionStart(compact)를 받습니다. 여전히 파일 편집 훅은 설치하지 않습니다.
• Claude Code는 PreToolUse 훅을 설치할 수 있습니다.
• OpenCode V1은 엄격한 프로젝트 수준 opencode.json을 받습니다.
• Cursor는 참조 구성 스니펫만 반환하며, 프로젝트에 아무것도 작성하지 않습니다.

구성 후, 현재 호스트 세션이 이미 AOCI 도구를 노출하는지 확인하십시오. 새 서버를 로드하지 않은 경우에만 해당 프로젝트 세션을 새로 고치거나 다시 여십시오. 새 세션은 일반적으로 규칙과 Whole-Index를 한 번 읽습니다. 인덱스 아이덴티티가 유효하게 유지되고 알려진 호스트 압축이 발생하지 않은 동안, 이후 작업은 모델이 이미 가진 것을 재사용하며, 전체 인덱스가 기계적으로 다시 주입되지 않습니다.

aoci --repo /absolute/path/to/repository init --agent codex
aoci --repo /absolute/path/to/repository init --agent codex --hooks
aoci --repo /absolute/path/to/repository init --agent claude --hooks
aoci --repo /absolute/path/to/repository init --agent opencode
aoci --repo /absolute/path/to/repository init --agent cursor

Codex --hooks는 압축 핸드오프를 영수증 아이덴티티, 미완료 쓰기 또는 복구 상태, 즉시 재로드 지시로 제한하며, Whole-Index 또는 Overview/Attestation 본문을 보유하거나 요약해서는 안 됩니다. PreCompact 훅은 호스트 압축 입력에 주입하거나 기록을 삭제할 수 없으므로, 단독으로 이를 강제할 수 없습니다. 의존하기 전에 Codex /hooks를 통해 설치된 프로젝트 훅을 검토하고 신뢰하십시오.

Legacy 출력은 기존 호스트 및 보고서와의 호환성을 위해 Levels 0–4를 유지합니다. 현재 cognition-state/v2는 모델의 시스템 그림이 얼마나 사용 가능한지를 Levels 0–3으로 표현하며, 엄격한 증명과 거버넌스 사실을 독립적인 차원으로 분리합니다:

이러한 차원은 서로를 대체하지 않습니다. Attestation은 현재 자료에 대한 전달 범위와 아이덴티티 일관성만 증명하며, 에이전트가 가능한 모든 미래 작업을 완전히 이해했음을 의미하지는 않습니다. 오직 current_system_cognition_reliable=true만이 완전한 현재 시스템 이해에 대한 무조건적 주장을 허용합니다.

AOCI 패널

aoci ui는 이 머신에서 읽기 전용 패널을 제공하므로, 에이전트에게 묻지 않고도 인덱스 상태를 볼 수 있습니다:

• 인덱스 헤더와 Code / Database Volumes 그대로 (=== 섹션 라인은 그대로 유지, 필터링 가능, 전체 복사 가능); "All" 탭은 에이전트가 Overview를 통해 받는 것과 정확히 동일한 완전한 인덱스
• 예산 대비 인덱스 토큰, Overview 청크 계획
• 인덱스가 커버하는 코드 양: 파일, 라인, 토큰, 압축 비율; 데이터베이스 테이블 수
• 거버넌스 상태와 드리프트, Managed Scope, 호스트 통합, 실행 중인 aoci mcp 프로세스
• 에이전트에게 다음에 줄 명령과 프롬프트, 복사 버튼 포함

페이지는 중국어와 영어 간 전환되며, 새로 고침 간격은 선택 가능합니다(기본 30초).

하나의 WSL에 여러 aoci mcp 서버가 있습니까? Linux와 WSL에서 패널은 현재 사용자의 모든 aoci mcp 프로세스와 해당 저장소를 검색하고, 상단 탭으로 전환하며, 디스크에서 바이너리가 교체된 서버를 표시합니다. 경계: 루프백 주소에만 바인딩하며(다른 바인드는 거부됨), GET과 HEAD에만 응답하고, 잠금을 잡지 않으며, 원장에 아무것도 추가하지 않고, 저장소의 어떤 바이트도 변경하지 않는다. 이는 aoci mcp과 무관한 별도 프로세스이며, MCP 서버는 여전히 소켓을 열지 않는다. 백그라운드 패널의 등록 정보는 사용자의 캐시 디렉터리에 존재하며, 저장소에는 절대 존재하지 않는다.

일반적인 CLI 명령

일반적인 조합:

# Initialization and first Baseline
aoci --repo . init --locale en-US --agent codex
aoci --repo . scan

# Verification and governance gates for Cognition Volumes
aoci --repo . verify --json
aoci --repo . check --json

# Live Guide; do not duplicate the state machine in a wrapper
aoci --repo . index agent guide --agent codex --json

# Capabilities and diagnostics
aoci --repo . capabilities
aoci --repo . doctor

# Database Evidence, Access, and Cognition lifecycle
aoci --repo . database --help
aoci --repo . database source access --source primary --json
aoci --repo . database cognition status
aoci --repo . cognition plan --help

# Derived System Cognition observations
aoci --repo . cognition system lineage
aoci --repo . cognition system relations

# MCP stdio Server
aoci --repo . mcp

Plan, Stage, Check, Diff, Apply, Curation, Scope Change, Bootstrap, Migration, 복구 명령은 여전히 존재한다. 실행 중인 바이너리가 반환하는 가이드를 따르며, 내부 상태 머신을 스크립트에 복사하지 말 것.

"읽기 전용" 명령에 관하여

verify, check, index score, index inventory의 경우 "읽기 전용"은 정형 인덱스와 Baseline이 수정되지 않음을 의미하며, 파일 시스템 쓰기가 엄격히 0임을 의미하지는 않는다. Ledger가 활성화되면 네 명령 모두 로컬 Ledger에 추가할 수 있으며, verify는 Verify History 쓰기도 시도한다. 감사 쓰기 실패는 기존 종료 코드나 거버넌스 기준을 변경하지 않는다.

엄격한 무파일쓰기 작업이 필요한 경우 격리된 복사본을 사용하라. 현재 공개 CLI는 모든 Ledger 및 Verify History 쓰기를 비활성화하는 일괄 스위치를 노출하지 않는다. System Cognition 명령은 두 번째 정형 상태를 생성하지 않지만, 일반 CLI 호출은 여전히 현재 버전의 Ledger 및 로컬 이력 기록에 대한 런타임 계약을 따른다.

MCP 서버

aoci mcp은 상주 데몬이 필요 없으며 stdio를 통해 정확히 아홉 개의 도구를 노출한다:

MCP 모드에서 stdout은 JSON-RPC용으로 예약되며, 로그와 진단은 stderr로 간다. 실행 중인 바이너리가 제공하는 도구 설명, JSON 스키마, 머신 상태 값이 권위 있는 정보이며, 이 README는 시작점일 뿐이다.

현재 릴리스는 기존 CLI와 거버넌스 커널을 통해 System Cognition 기능을 제공한다. 이는 열 번째 MCP 도구를 추가하거나 기존 아홉 개의 이름, 목적, stdio 계약을 변경하지 않는다.

장기 실행 세션과 Whole-Index 전달

새 대화가 시작될 때 에이전트는 일반적으로 현재 저장소, 인덱스 버전, AOCI 서비스 아이덴티티와 일치하는 시스템 그림을 얻기 위해 하나의 완전한 Overview를 로드한다. 모델이 그 그림에 여전히 의존할 수 있는 동안에는 매 작업이나 도구 호출 전에 다시 로드할 필요가 없다.

같은 대화 내에서 모델은 알려진 호스트 컨텍스트 압축 이후를 제외하고는 자신의 상태에 따라 다시 로드할지 결정한다. 압축된 핸드오프는 수신 아이덴티티, 미완료 쓰기 또는 복구 상태, 즉시 재로드 지시만 보존할 수 있으며, Whole-Index 또는 Overview의 헤더, 항목, 청크, 챌린지, 증명 본문을 보존하거나 요약해서는 안 된다. 그 핸드오프에 복사된 인덱스 내용이나 수신은 모델의 현재 그림이 신뢰할 수 있음을 증명할 수 없다.

알려진 압축 이후 비즈니스 작업을 계속하기 전에, 에이전트는 규칙이 더 이상 신뢰할 수 있게 존재하지 않으면 규칙을 다시 로드하고, 새로운 이벤트 ID로 context_compaction을 선언하며, 하나의 일반적인 전체 Overview 커서, 확인, 증명 시퀀스를 완료한다. check_only와 cognition probe는 대체물이 아니다. 새로운 완전한 전송 이후에도 기존의 부분적 또는 실패한 증명 규칙은 두 번째 자동 Overview 없이 소스 바인딩된 계속을 여전히 허용한다. 알려진 압축이 없는 의미적 변경이나 주요 단계 경계의 경우, AOCI는 갱신 임계값, 체크포인트, 아이덴티티 팩트를 제공하며, 모델은 해당 작업을 위해 시스템 수준 그림을 복원해야 하는지 결정한다.

각 완전한 Overview의 본문은 시작 마커, 현재 정형 인덱스의 정확한 내용, 종료 마커로 구성된다.

Overview가 프로젝트의 청크 예산을 초과할 때:

1. 전달은 청크 1로 즉시 시작된다;
2. 에이전트는 마지막 청크까지 next_cursor를 자동으로 따라야 한다;
3. 에이전트는 전달된 Whole-Index를 사용하여 하나의 증명을 제출한다;
4. 로컬 검색, 오래된 기억, 보충 소스 읽기, 직접 파일 읽기는 완전한 전달로 제시되어서는 안 된다;
5. 대기 중인 복구 또는 일관성 없는 스냅샷은 내용을 혼합하지 않고 fail closed된다.

overview_delivery.chunk_tokens은 유일한 전달 크기 설정이다. 기본값은 7000이며, 유효 범위는 4000부터 24000까지이다. check_only=true은 청크 체인이 없는 간결한 체크포인트이다.

AOCI는 aoci_overview에 도구별 결과 크기 허용치를 선언한다. 그렇지 않으면 대용량 도구 결과를 디스크에 저장하고 모델의 컨텍스트에는 미리보기만 넣게 되는 호스트(인덱스 전달의 경우 조용한 실패)는 이 도구에 대해서만 해당 임계값을 높인다. Claude Code에서 이는 전체 24000를 사용 가능하게 하여, 480개 객체 인덱스를 다섯 개 대신 세 개의 청크로 전달한다. 아무것도 프로브되지 않는다: 선언은 정적이며, 이를 인식하지 못하는 호스트는 MCP 사양이 요구하는 대로 이를 무시한다.

갱신 임계값은 기본적으로 30개의 서로 다른 의미 경로이며, 프로젝트별로 구성할 수도 있다. 정확한 계산 규칙은 Cognition Refresh 문서와 런타임 계약을 따르라.

Database Cognition

AOCI-CODE는 명시적이고 좁은 접근 경계를 통해 데이터베이스 구조를 동일한 인덱스와 동일한 거버넌스 아래로 가져올 수 있다:

Explicit database command
  → Read-only PostgreSQL/MySQL/openGauss system catalogs
  → Canonical schema evidence
  → Human acceptance of the evidence hash
  → The host model writes table-level FRAS from complete evidence
  → Entries are bound to the evidence and enter governed apply

• 데이터베이스가 구성되지 않았거나 명시적 데이터베이스 명령이 실행되지 않으면 데이터베이스 네트워크 접근이 발생하지 않는다.
• 기본 테이블의 스키마 메타데이터만 읽으며, 비즈니스 행은 읽지 않는다; 뷰, 루틴, 주석은 현재 수집 범위 밖이다.
• DDL 또는 DML이 실행되지 않는다.
• 호스트 이름, 사용자 이름, DSN, 자격 증명 값은 인덱스 파일에 절대 기록되지 않는다.
• Database Cognition apply는 오프라인으로 실행되며 쓰기 중에 데이터베이스에 다시 연결하지 않는다.
• 프로그램은 구조적 증거를 보존하고 비교하지만, 테이블 책임, 관계, 고가치 제약은 여전히 모델이 작성한다.

MySQL 지원은 5.7.6 이상을 포함한다. 수집기는 서버 버전을 읽고 해당 릴리스가 응답할 수 있는 카탈로그 쿼리만 실행한다: CHECK 제약은 8.0.16부터, 인덱스 표현식은 8.0.13부터, 인덱스 가시성은 8.0.0부터. 5.7 서버는 빈 check 목록을 기록하는데, 5.7은 CHECK 구문을 파싱하고 아무것도 저장하지 않기 때문이다; 증거는 모든 지원 릴리스에서 동일한 형태를 가진다. MariaDB는 지원되지 않으며 MySQL로 읽히지 않고 거부된다.

초기 openGauss 프로파일은 의도적으로 A/PG 호환 모드의 openGauss 6.0.5 LTS와 일반 비파티션 기본 테이블로 제한된다. 지원되지 않는 카탈로그 기능은 조용히 PostgreSQL 팩트로 축소되지 않고 fail closed된다; 이는 MogDB, GaussDB, Dolphin/B/MySQL 모드, 파티션 또는 서브파티션, 컬럼 스토어, MOT, 외부 또는 임시 테이블, 뷰, 루틴, 트리거에 대한 지원을 주장하지 않는다.

여기서 fail-closed 감지는 지원되지 않는 의미를 가진 선택된 가시적 테이블 유사 객체에 적용된다. 루틴과 트리거는 v1 테이블 객체 도메인 밖에 남아 있으며 테이블 팩트로 표현되지 않는다.

openGauss 경로는 공식 Connector v1.0.8 소스에 대한 AOCI의 검토된 로컬 패치를 사용한다. 엄격한 파서는 검토된 연결 매개변수만 허용하며 주변의 PG*, 서비스, 비밀번호 파일, 홈 디렉터리, 로거 구성을 소비하지 않는다. 숫자 루프백 주소 외부의 TCP 연결은 명시적으로 sslmode=verify-full를 사용해야 하며(제공되는 경우 sslrootcert의 절대 신뢰 루트 경로도 함께), 최소 TLS 1.2를 사용해야 한다; TLS 다운그레이드 모드는 거부된다. sslmode=disable은 로컬/테스트 경계로 사용되는 명시적 Unix 소켓 또는 숫자 루프백 주소에 대해서만 허용된다. 데이터베이스 관리자는 대화 외부에서 해당 DSN을 제공하고 최소 권한 계정을 프로비저닝할 책임이 있다.

Database Volume은 기본적으로 존재하지 않는다. 프로젝트가 Database Cognition을 명시적으로 활성화하고 증거, 바인딩, 라이프사이클 거버넌스를 완료한 후에만 Whole-Index에 들어간다.

데이터베이스 접근 온보딩: DSN 세부 사항을 이해할 필요가 없습니다

데이터베이스 소스에 대해 민감하지 않은 아이덴티티만 선언하면 된다. --credential-env이 생략되면 AOCI는 소스 ID로부터 안정적인 환경 변수 참조를 도출한다; 예를 들어 primary은 AOCI_DB_PRIMARY_DSN에 매핑된다:

aoci --repo . database source add \
  --source-id primary \
  --engine postgresql \
  --database-name app \
  --namespace public

그런 다음 읽기 전용 접근 사전 점검을 사용하여 외부 환경이 해당 참조를 제공했는지 확인한다:

aoci --repo . database source access --source primary --json

이 명령은 데이터베이스에 연결하지 않고, 자격 증명 값을 반환하지 않으며, 대화에 DSN을 붙여넣도록 요구하지 않는다. 데이터베이스 또는 인프라 관리자는 AOCI 프로세스 외부에서 환경 변수를 제공하고 시스템 카탈로그에 대한 읽기 전용 최소 권한 접근을 부여한다. 소스 구성은 비밀 값이 아닌 자격 증명 참조 이름만 저장한다.

현재 릴리스 후보는 환경 자격 증명 제공자만 제공한다. Vault, Kubernetes Secret, AWS/GCP/Azure와 같은 클라우드 비밀 관리자는 향후 버전에서 동일한 제공자 경계를 통해 통합될 수 있다; 오늘날에는 사용할 수 없으며, 이 README는 그렇지 않다고 암시하지 않는다. 이 분리는 계정 형식, DSN 인코딩, 시크릿 수명 주기 관리를 일반 사용자로부터 멀리 유지하면서 권한 부여를 명시적으로 유지합니다. AOCI는 자격 증명을 자동으로 검색하거나, .env을 스캔하거나, 시크릿 파일을 읽거나, 데이터베이스 관리자의 권한 부여 경계를 우회하지 않습니다.

시스템 인지 기반

코드 및 데이터베이스 인덱스 위에, AOCI-CODE는 파생된 시스템 인지 관찰 세트를 제공합니다. 이들은 "이 객체는 어디에서 왔는가?", "데이터베이스 변경이 어떤 코드 객체에 영향을 미칠 수 있는가?", "과거 관찰과 현재 사이에 무엇이 변경되었는가?"와 같은 질문에 답합니다. 이들은 권위 있는 사실의 새로운 계층을 만들지 않습니다.

# Where an index object came from, with its evidence and receipt bindings
aoci --repo . cognition system lineage

# Volume containment and dependencies plus resolved model-authored R relationships
aoci --repo . cognition system relations

# Find code impact from a database object along formal R relationships
aoci --repo . cognition system impact \
  --object database://primary/public/orders

# Save a historical observation on the caller side
aoci --repo . cognition system snapshot --json > previous.json

# Compare a caller-supplied historical observation with the current derived projection
aoci --repo . cognition system evolution \
  --snapshot-file previous.json

권한 경계

모든 시스템 인지 결과는 derived=true을 보고하며, 관계 투영은 추가로 authoritative=false을 보고합니다. Cognition Volume, 스키마 증거 바인딩, Baseline 지문, 영수증 바인딩된 식별자는 기저의 권위로 남습니다. 해석되지 않은 R 관계는 불완전한 결과나 진단을 생성하며, 프로그램은 추측하여 채우지 않습니다.

AOCI-CODE는 지식 그래프 시스템이 아닙니다. 좁은 관계 투영은 편리한 관계 뷰이지만, 두 번째 상태 관리 시스템, 독립적인 쓰기 경로, 새로운 사실 저장소를 소유하지 않습니다. 파생 출력은 삭제하고 현재 권위 있는 자산으로부터 재계산할 수 있습니다. 투영이 권위 있는 자산과 충돌하면 자산이 우선합니다.

실행 모드, 프라이버시, 데이터 경계

• AOCI-CODE는 기본적으로 로컬 우선이며, 기본 클라우드 엔드포인트, 호스팅 소스 업로드 서비스, 필수 백그라운드 서버가 없습니다.
• 에이전트 네이티브 모드의 데이터 처리는 선택한 호스트와 그 제품 정책에 따라 달라지며, AOCI-CODE는 호스트를 대신하여 데이터를 업로드하지 않습니다.
• 데이터베이스 네트워크 접근은 명시적으로 트리거되어야 하며 읽기 전용 스키마 메타데이터로 제한됩니다.
• 원장, 초안, 트랜잭션, 복구 증거는 기본적으로 .aoci/ 아래에 저장되며 일반적으로 Git에서 무시됩니다; 인덱스 파일과 팀 거버넌스 자산은 Git에 커밋될 수 있습니다.
• 시스템 인지 투영은 기존 권위 있는 자산으로부터 로컬에서 계산되며 그래프 데이터베이스, 벡터 데이터베이스, 원격 그래프 서비스를 요구하지 않습니다.

레포 맵, RAG, LSP, 코드 그래프와의 차이

검색, AST, LSP, 코드 그래프, RAG는 구조적 및 검색 질문에 능숙합니다. AOCI-CODE는 다른 작업을 수행합니다: 관리 범위를 포괄하고 소프트웨어와 함께 점진적으로 진화하는 시스템의 버전 관리된 설명을 유지합니다. 얻는 것:

• 전체 인덱스(Whole-Index). 각 작업에 대해 즉석에서 조립된 단편이 아닌, 현재 관리 범위를 포괄하는 하나의 시스템 맵.
• FRAS 항목. index 역할을 가진 모든 객체에 대한 책임, 강한 관계, 공개 계약, 고가치 제약.
• 세션 간 지속성. 인덱스 파일이 저장소와 함께 있으므로 이후 세션과 다른 에이전트가 동일한 버전을 재사용함.
• 관리 범위(Managed Scope). 어떤 객체가 인덱스에 들어가고, 어떤 객체가 변경 관찰만 되며, 어떤 객체가 의도적으로 제외되는지에 대한 명시적 기록.
• 드리프트 감지. Missing, Orphan, Stale, Unbaselined, 줄바꿈 변경, 큐레이션 차이, 작성에서 제외된 소스(비어 있음, 바이너리, 초과 크기)를 구분함.
• 거버넌스된 업데이트. 후보는 소스 바인딩, 계획, 검증, 검토, CAS, 원자적 쓰기, Baseline, 복구 워크플로를 통해 정식 파일에 들어감.
• 전달 증명. 청크, 커서, 영수증, 챌린지가 전체 인덱스가 완전히 전달되었음을 증명함.
• 데이터베이스 인지. 명시적으로 수용된 PostgreSQL/MySQL/openGauss 스키마 증거로부터 구축되고 거버넌스되는 테이블 수준 항목.
• 시스템 투영. 권위 있는 인덱스와 그 바인딩으로부터 파생된 계보, 좁은 관계, 데이터베이스-코드 영향, 스냅샷, 진화 관찰로, 권위 있는 상태를 복제하지 않음; 영향은 명시적으로 모델이 작성한 R 관계만 순회함.

AOCI-CODE는 기존 도구를 대체하기보다 보완합니다.

권장 조합: AOCI-CODE는 전역 의미 사전(prior)을 제공하고; 코드 그래프, LSP, 검색, 소스는 정밀한 증거를 제공하며; 테스트와 런타임 결과는 최종 수용을 제공합니다. AOCI의 관계 투영은 정밀한 호출 그래프를 대체하지 않습니다: 구조적 Volume 포함 관계와 Root 의존성 엣지를 노출하며, 의미 엣지는 모델이 명시적으로 작성한 강한 관계로 제한됩니다.

기술 스택

AOCI-CODE는 Neo4j, 벡터 데이터베이스, 장기 실행 데몬, AOCI 클라우드 서비스를 요구하지 않습니다. 데이터베이스 인지가 활성화되면 대상 데이터베이스는 AOCI 자체의 상태 저장소가 아닌 명시적이고 읽기 전용인 스키마 증거 소스일 뿐입니다.

FAQ

Legacy status --deep이 여전히 드리프트를 표시하는 이유는 무엇인가요?

status --deep, index score, index agent plan은 Legacy 전용입니다. Cognition Volumes 저장소의 경우, 라이브 가이드를 실행하고 호스트가 일반적인 인자 없는 aoci_maintain를 사용하도록 하며, aoci_update_entry를 통해 완전한 현재 배치를 제출하고, Verify, Check, 가이드로 마무리하세요. Baseline을 직접 수정하거나 소스 바인딩 및 복구 단계를 건너뛰지 마세요.

Legacy 레이아웃 자체는 더 이상 사용되지 않습니다. Volumes v1은 신규 및 마이그레이션된 저장소를 위한 지원 경로이며, Legacy 전용 명령은 v0.2.0에서 제거될 예정입니다; 그 전에 aoci cognition migration로 Legacy 저장소를 마이그레이션하세요.

aoci --repo . index agent guide --agent codex --json

호스트가 잘못된 AOCI를 시작한 이유는 무엇인가요?

프로젝트 수준 MCP 구성의 실행 파일 경로를 검사하고 안정적인 절대 경로인지 확인한 다음, 다음을 실행하세요:

/absolute/path/to/aoci --version
/absolute/path/to/aoci --repo . doctor

디스크의 파일만이 아니라 로드된 stdio 서버를 확인하려면, 호스트 프로세스의 실제 실행 파일, 명령줄 --repo, 재시작 후의 프로세스 정체성도 검사하세요.

데이터베이스 계정을 만들고 DSN을 직접 제공해야 하나요?

DSN 구문을 이해할 필요는 없으며, 채팅으로 시크릿을 보내서도 안 됩니다. 민감하지 않은 소스 정체성을 선언한 후, AOCI는 안정적인 환경 변수 참조를 제공합니다. 데이터베이스 관리자는 여전히 읽기 전용 시스템 카탈로그 접근 권한을 가진 외부 최소 권한 계정을 만들고 그 참조를 런타임 환경에 제공해야 합니다. 현재 버전은 조직을 대신하여 데이터베이스 계정을 생성하거나 시크릿 저장소를 자동으로 읽지 않습니다.

CI에서 실행할 수 있나요?

예. 스캐닝, 검증, 거버넌스 게이트, 결정론적 검사는 새 항목을 작성하지 않고 실행됩니다. 정확한 명령, 감사 쓰기, 종료 코드는 현재 바이너리의 --help, JSON 스키마, 프로젝트의 CI 문서를 따르세요.

AOCI 결과가 모두 녹색이면 의미가 올바르다는 것을 증명하나요?

아니오. 녹색 결과는 인코딩된 구조적 및 거버넌스 조건이 성립함을 증명합니다. 모델이 작성한 내용은 여전히 소스 코드, 스키마, 테스트, 런타임 결과, 사람 검토와 대조하여 확인해야 합니다.

시스템 인지 그래프는 새로운 진실의 원천인가요?

아니오. 현재 기능은 독립적인 그래프 플랫폼이 아닌 좁은 관계 투영입니다. 정식 인덱스, 증거, 영수증, Baseline으로부터만 결과를 계산하며 새로운 권위 있는 사실을 영속화하지 않습니다. 또한 프로그램은 임포트, SQL, 파일 이름, 유사성으로부터 의미 관계를 자동으로 생성하지 않습니다.

문서

문서 및 공개 계약 링크는 v0.1.0-rc22에 고정되어 있어, 이 README를 바이너리 Release 아카이브에서 읽을 때도 유효하게 유지됩니다. 해당 아카이브에는 저장소의 docs/ 또는 spec/public/ 디렉터리가 포함되지 않습니다.

블랙박스 검증 스위트

저장소에는 scripts/blackbox/ 아래에 네 개의 독립적인 블랙박스 스위트가 포함되어 있으며, 이들은 빌드된 aoci 바이너리를 프로세스 외부에서, 오직 공개 stdio MCP 프로토콜과 CLI를 통해서만 검증합니다:

• 프로토콜 적합성 — MCP 와이어 표면에 대한 53개의 읽기 전용 검사로, 로케일에 따라 달라지는 문장은 zh-CN 아래에서 반복됩니다;
• 장애 주입 시나리오 — 커서 변조, 크래시 복구, 경쟁하는 작성자, 그리고 일회용 픽스처 저장소에서의 쓰기 전 훅을 다루는 75개의 시나리오;
• 동결된 실제 프로젝트에 대한 수명 주기 — 커밋된 세 개의 픽스처 프로젝트: repo-a(TypeScript)와 repo-b(Python + MySQL)은 전체 init-에서-재정렬까지의 수명 주기를 실행하며, repo-c(453개 파일의 계층형 서비스)는 추가로 머신 배치 한도에서의 다중 배치 작성을 구동합니다. 선택적 모델 트랙은 실제 AI 에이전트 — OpenCode 설치가 노출하는 모든 모델 — 를 두 개의 작은 저장소에 통과시키고 공개 표면에서 최종 상태를 채점합니다.
• 업그레이드 축 — 릴리스된 각 버전당 80개의 검사로, 열 가지 저장소 형태에 걸쳐 수행됩니다: 공개된 모든 릴리스는 자체 바이너리로 저장소를 빌드하고 작성하며, 그런 다음 테스트 대상 바이너리는 아이덴티티를 이동시키거나, Scope Change를 요구하거나, 형식 자산을 재작성하지 않고 그것을 관리해야 하며, 그 후 작성하는 내용은 다른 경로의 체크아웃을 정렬된 상태로 유지해야 합니다; 열 번째 형태에서는 역할이 뒤바뀌어, 공개된 모든 릴리스가 테스트 대상 바이너리가 작성한 저장소를 크래시나 재작성 없이 읽어야 합니다. 나머지 세 스위트는 모든 픽스처를 테스트 대상 바이너리로 생성하므로, 버전 간에 변경된 원본 이미지는 구조적으로 그들에게 보이지 않습니다.

이들은 빌드된 바이너리 위에 Python 3와 git만 필요로 하며(MySQL 스위트에는 Docker; 모델 트랙에는 OpenCode와 자체 모델 구독), 따라서 저장소 클론은 자체 빌드, 플랫폼 포팅, 또는 포크를 검증할 수 있고, AOCI_BIN는 적합성 및 시나리오 스위트를 spec/public/의 공개 계약을 주장하는 모든 대체 바이너리로 지정할 수 있습니다. 이 스위트들은 저장소 클론에 존재하며, 바이너리 Release 아카이브에는 포함되지 않습니다. 명령과 결과 해석은 scripts/blackbox/README.md을 참조하십시오.

연구, 지식 재산, 그리고 라이선스

AOCI-CODE 연구 논문과 산출물은 공개된 방법, 실험 프로토콜, 그리고 결과를 공개적으로 기술할 수 있습니다. 특허 출원, 허여된 범위, 법적 상태, 소유자, 그리고 영역적 효력은 법적 사실이며, 내부 README, 과거 버전 번호, 또는 검증되지 않은 재진술에 근거하여 제품 설명에 추가되어서는 안 됩니다.

특정 특허 번호, 허여 날짜, 또는 범위를 향후 공개해야 하는 경우, 권리 보유자와 법률 고문이 공식 공개 기록과 대조하여 검증하고 이를 전용 IP, NOTICE, 또는 법률 문서에 기재해야 합니다. 이 README는 해당 권위 있는 파일로만 링크해야 하며, 특허 범위를 스스로 확장하거나 특허 상태를 소프트웨어 라이선스로 제시해서는 안 됩니다.

커뮤니티

WeChat 또는 WeCom(企业微信)으로 코드를 스캔하여 AOCI 프로젝트 그룹에 참여하고 유지관리자 및 다른 사용자와 대화하십시오. 버그 보고와 기능 요청은 검색 가능하도록 GitHub issues로 제출하고, 의심되는 취약점은 SECURITY.md에 설명된 대로 비공개로 보고하되, 그룹에서는 절대 보고하지 마십시오.

AOCI-CODE는 에이전트가 더 많은 코드를 보게 만드는 것이 아닙니다. 그것은 에이전트가 모든 행동 전에 시스템에 대한 최신의, 구조화된, 추적 가능한, 그리고 관리되는 이해를 갖도록 합니다. Git은 코드의 버전을 관리하고, 데이터베이스 마이그레이션은 데이터 구조의 버전을 관리하며, AOCI-CODE는 에이전트가 시스템에 대해 아는 것의 버전을 관리하고, 그 지식이 진화하는 방식의 추적성, 거버넌스 일관성, 그리고 복구 경계를 함께 관리합니다.