lsaint/aikito

aikito은(는) 무엇을 하나요?

목적

Aikito를 지속성 있는 Agent 리소스의 표준(Git 관리) 소스로 사용하고, 해당 리소스를 지원되는 코딩 에이전트와 프로젝트에 동기화합니다.

개념 모델

CLI 소스와 사용자 작업 공간을 분리하여 유지합니다:

~/aikito-src   CLI 소스 체크아웃
~/aikito       표준 사용자 작업 공간

작업 공간에는 진실의 원천이 포함됩니다:

~/aikito/
├── agents.toml
├── skills.toml
├── subagents.toml
├── mcps/
├── global/AGENTS.md
├── skills/
├── memory/
└── projects/<name>/

Agent 설정 디렉토리와 프로젝트 .agents/ 디렉토리는 런타임 진입점이며, 독립적인 소스가 아닙니다. 먼저 표준 작업 공간 파일을 수정한 다음 CLI로 동기화하세요.

작업 공간이 ~/aikito가 아닌 경우 AIKITO_DIR을 사용하세요. CLI가 작업 공간 내에 있다고 가정하지 말고, 설치된 aikito 명령어를 사용하세요.

부트스트랩

CLI가 설치되지 않은 경우 공식 소스 저장소를 사용하고, 체크아웃을 향후 작업 공간과 분리하여 유지하세요:

git clone https://github.com/lsaint/aikito.git "$HOME/aikito-src"
export PATH="$HOME/aikito-src/bin:$PATH"

복제 전에 대상 디렉토리에 관련 없는 사용자 데이터가 없는지 확인하세요. 사용자의 지시 없이 기존 체크아웃을 덮어쓰지 마세요.

작업 공간을 초기화하고 확인합니다:

aikito init workspace ~/aikito
aikito status

aikito init workspace는 CLI 소스 트리, 다른 소스 체크아웃, 인식되지 않은 비어 있지 않은 디렉토리를 거부합니다. 이러한 가드를 우회하지 마세요. 초기화 후, 아무것도 동기화하기 전에 생성된 파일을 확인하세요.

안전 프로토콜

• 읽기 전용 탐색으로 시작합니다: 관련 표준 파일을 검사하고, aikito status를 실행하며, 리소스별 상태 명령어를 사용합니다.
• --apply 없이 aikito adopt를 먼저 실행합니다. 사용자에게 적용 계획, 충돌 및 자격 증명 처리를 보여줍니다.
• 이를 지원하는 동기화 명령어에는 --dry-run을 사용합니다.
• 관리되지 않는 대상과 충돌하는 지침은 사용자의 결정 사항으로 처리합니다. 조용히 덮어쓰지 마세요.
• API 키, 토큰, 비밀번호, OAuth 자료를 Aikito 작업 공간 및 Git에 보관하지 마세요. 표준 MCP 구성에 환경 변수 참조를 저장합니다.
• 명시적인 force 또는 prune 작업 전에 경고하고, 검토된 대상에 한정합니다.
• 로컬 Git 저장소를 게시해도 안전한 것으로 취급하지 마세요. 원격을 추가하거나 푸시하기 전에 메모리와 구성을 개인 데이터 검토합니다.
• 작업 공간과 대상 Agent 설정 모두에서 관련 없는 사용자 변경 사항을 보존합니다.

리소스 라우팅

전역 지침 및 스킬

표준 소스:

~/aikito/global/AGENTS.md
~/aikito/skills.toml
~/aikito/skills/<skill-name>/

변경 사항 검토 후:

aikito sync global --dry-run
aikito sync global
aikito status
aikito show skills
aikito show skill <target>
aikito edit skill <target>

생성된 Agent 고유 지침 또는 스킬 항목을 독립적인 소스로 편집하지 마세요.

전역 스킬을 추가, 이름 변경 또는 제거할 때는 디렉토리 전용 편집이 아닌 크로스 런타임 마이그레이션으로 처리합니다:

• skills.toml, 공개 내보내기 허용 목록, 이전 스킬 이름에 대한 참조를 업데이트합니다.
• 전역 스킬을 로드하는 모든 지원되는 Agent가 agents.toml과 aikito init 템플릿에 올바른 skills_path를 가지고 있는지 확인합니다. Agent CLI와 해당 IDE가 동일한 전역 스킬 디렉토리를 사용한다고 가정하지 마세요.
• 관련 테스트를 실행한 다음 aikito sync global과 aikito status를 실행합니다.
• 각 관리되는 Agent 대상을 검사하고 새 스킬이 표시되고 이전 이름에 대한 오래된 링크가 사라졌는지 확인합니다.
• 프로젝트가 의도적으로 재정의하거나 복사하지 않는 한, 전역 스킬을 프로젝트 agent.toml 파일에 보관하지 마세요.

프로젝트

작업 공간은 중앙 진실의 원천이며 일반적으로 한 번 존재합니다. 프로젝트 등록은 하나의 코드 디렉토리와 해당 프로젝트별 Agent 리소스를 나타냅니다. 요청된 지침, 스킬 선택 또는 메모리가 프로젝트별이고 현재 코드 디렉토리가 등록되지 않은 경우, 사용자에게 등록할지 물어보세요. 전역 리소스에 대해 프로젝트를 등록하지 마세요.

확인 후, 해당 코드 디렉토리에서 프로젝트를 초기화합니다:

aikito init project

디렉토리 이름과 현재 경로가 기본값입니다. 필요한 경우 명시적 인수를 사용합니다:

aikito init project <name> <path>

이 명령어는 표준 프로젝트 스켈레톤을 생성하고 해당 .agents/ 런타임을 동기화합니다. 기존에 관리되지 않는 런타임 리소스나 다른 경로에 바인딩된 프로젝트 이름은 사용자의 충돌 사항으로 처리하고 우회하지 마세요.

프로젝트 구성은 다음 아래에 속합니다:

~/aikito/projects/<name>/agent.toml
~/aikito/projects/<name>/AGENTS.md
~/aikito/projects/<name>/memory/

다음과 같이 동기화 및 확인합니다:

aikito show projects
aikito show project <name>
aikito sync project <name> --dry-run
aikito sync project <name>
aikito status
aikito diff
aikito show memory

프로젝트 지침과 메모리는 표준 소스에 연결된 상태로 유지됩니다. 프로젝트 스킬은 sync_mode를 따릅니다: link는 심볼릭 링크를 유지하고, copy는 프로젝트 Git 추적을 위한 관리 복사본을 생성합니다. aikito status로 복사된 스킬 변동을 감지하고, aikito diff로 표준 스킬과 비교합니다. 동기화는 변동된 복사본을 교체하지 않습니다. 살아남아야 할 변경 사항을 병합하거나, 검토 후에만 aikito sync project <name> --force를 사용하세요.

대상 .agents/skills/와 .agents/memory/ 디렉토리는 Aikito에 의해 독점적으로 관리됩니다. 알 수 없는 항목은 충돌이며 프로젝트 동기화에 의해 절대 삭제되지 않습니다. 관련 없는 파일을 그곳에 저장하지 마세요.

MCP 서버

표준 소스:

~/aikito/mcps/*.toml

미리보기, 적용 및 확인:

aikito sync mcp --dry-run
aikito sync mcp
aikito show mcp

라이브 Agent 확인이 유용한 경우에만 aikito show mcp --live를 사용하세요. 지원되는 인증 흐름에는 aikito auth mcp <agent> <server>를 사용하세요. 캡처된 자격 증명을 출력, 보관 또는 커밋하지 마세요.

서브에이전트

표준 소스:

~/aikito/subagents.toml
~/aikito/subagents/

미리보기, 적용 및 확인:

aikito sync subagents --dry-run
aikito sync subagents
aikito show subagents
aikito show subagent <target>
aikito edit subagent <target>

--prune을 사용하기 전에 고아 관리 파일을 검토하세요. 단지 상태를 녹색으로 만들기 위해 관리되지 않는 대상을 강제로 사용하지 마세요.

메모리

전역 메모리는 ~/aikito/memory/ 아래에 속합니다. 프로젝트별 메모리는 ~/aikito/projects/<name>/memory/ 아래에 속합니다.

aikito show memory [target]
aikito edit memory <target>

별도의 durable-memory 스킬을 사용하여 지식이 언제 충분히 지속 가능한지, 어떤 범위가 소유하는지, 버전을 어떻게 관리할지 결정합니다.

채택

가져오기 전에 기존 Agent 구성을 미리 봅니다:

aikito adopt

사용자가 계획을 검토하고 지침 충돌을 해결한 후에만:

aikito adopt --apply

적용은 ~/.aikito/backups/adopt_<timestamp> 아래에 타임스탬프가 있는 백업을 생성합니다. 채택은 리소스를 작업 공간으로 가져옵니다. Agent 고유 구성은 명시적인 동기화 중에만 변경됩니다.

확인 및 현재 동작

모든 쓰기 작업 후, 가장 좁은 관련 상태 명령어를 실행하고 보고된 대상을 확인합니다. 설치된 버전에서 지원되는 옵션에 대한 권위는 aikito <command> --help를 사용하세요. 소스 체크아웃에서 작업하는 경우, 현재 아키텍처와 안전 모델에 대해 해당 루트 README 및 관련 문서를 참조하세요.