otherness — 프로젝트 에이전트 컨텍스트

이게 무엇인가

otherness는 자율 소프트웨어 개발 시스템입니다. 단일 세션이 조정자, 엔지니어, 적대적 QA, 스크럼 마스터, 제품 관리자의 역할을 순차적으로 반복하며 인간의 입력 없이 수행합니다. AGENTS.md, docs/aide/, .otherness/state.json을 읽어 GitHub에서 호스팅되는 모든 프로젝트에서 작동한 후, 자율적으로 작업 큐를 생성하고, 기능을 구현하고, PR을 검토하고, 릴리스를 제공합니다.

otherness는 현재 자기 자신 위에서 실행 중입니다. 이 에이전트가 otherness를 개선하면, 해당 개선 사항은 다음 실행 시 자체 업데이트 메커니즘(git -C ~/.otherness pull)을 통해 otherness를 사용하는 모든 프로젝트에 배포됩니다.

상태: 활성. 코어 루프 안정적. 자기 개선 모드 활성화됨.

⚠️ 글로벌 배포 경고 — 모든 병합 전에 읽으십시오 agents/standalone.md 또는 agents/bounded-standalone.md에 대한 변경 사항은 다음 세션 시작 시 전 세계적으로 otherness를 사용하는 모든 프로젝트에 즉시 배포됩니다. 이러한 파일은 가장 위험이 높은 변경 표면입니다. 아래 '변경 위험 등급'을 참조하십시오.

SDLC 프로세스

팀 프로세스는 ~/.otherness/agents/standalone.md에 내장되어 있습니다. 이 파일에는 프로젝트별 컨텍스트만 포함됩니다.

프로젝트 구성

PROJECT_NAME:   otherness
CLI_BINARY:     ""
PR_LABEL:       otherness
REPORT_ISSUE:   741
REPORT_URL:     https://github.com/pnz1990/otherness/issues/741
BOARD_URL:      ""
BUILD_COMMAND:  bash scripts/validate.sh
TEST_COMMAND:   bash scripts/test.sh
LINT_COMMAND:   bash scripts/lint.sh
VULN_COMMAND:   ""

아키텍처

otherness는 OpenCode(AI 코딩 에이전트 런타임)가 읽는 마크다운 명령 파일의 모음입니다. 컴파일된 바이너리, 서버, 데이터베이스가 없습니다. "제품"은 이러한 명령이 생성하는 자율 에이전트 루프의 품질입니다.

배포 모델: ~/.otherness/agents/는 git 저장소입니다. 모든 에이전트는 시작 시 git -C ~/.otherness pull을 통해 자체 업데이트됩니다. pnz1990/otherness:main에 병합된 PR은 다음 실행 시 모든 사용자에게 배포됩니다.

런타임 종속성: OpenCode(에이전트 실행), gh CLI(모든 GitHub 상호 작용), git(VCS + 작업 트리 격리 + 자체 업데이트), python3 stdlib(YAML 파싱, JSON 상태).

상태: 전용 _state 브랜치의 .otherness/state.json입니다. 절대 main에 있지 않습니다. 병렬 세션은 브랜치 푸시를 분산 잠금으로 사용합니다.

스킬: agents/skills/*.md — 엔지니어 및 QA 단계에서 로드되는 재사용 가능한 체크리스트입니다. /otherness.learn에 의해 증가합니다.

패키지 레이아웃

~/.otherness/              ← 저장소 루트(이 경로에 git clone)
  agents/
    standalone.md          ← 얇은 오케스트레이터: 상태 관리, 시작, 루프 스켈레톤, 하드 규칙
    bounded-standalone.md  ← 범위가 지정된 에이전트 — standalone.md를 감싸는 50줄
    onboard.md             ← 기존 프로젝트 온보딩
    otherness.learn.md     ← 학습 에이전트 — 오픈 소스에서 내면화
    otherness.arch-audit.md ← 아키텍처 감사 에이전트
    gh-features.md         ← GitHub API 참조
    phases/                ← 단계 구현(standalone.md에 의해 로드됨)
      coord.md             ← 1단계: 하트비트, 속도 제한, 큐 생성 잠금, 부실 감시, 클레임
      eng.md               ← 2단계: 스펙/계획/작업(speckit 통합), 구현, 메모리
      qa.md                ← 3단계: 적대적 검토, 스펙 준수, 병합, 아카이브
      sm.md                ← 4단계: 트라이지, 부실 복구, 메트릭, 교차 프로젝트 학습
      pm.md                ← 5단계: 제품 검증, 로드맵 상태, 경쟁사 확인
    skills/                ← 재사용 가능한 스킬 파일
      declaring-designs.md         ← 스펙 품질 표준
      reconciling-implementations.md  ← QA 체크리스트
      agent-coding-discipline.md   ← 정밀 변경, 검증 가능한 목표
      autonomous-workflow-patterns.md ← 워크플로우 디자인 패턴
      architectural-audit.md       ← 4렌즈 감사 방법론
      contribution-hygiene.md      ← PR 및 커밋 규율
      agent-responsibility.md      ← 판단 및 책임 패턴
      role-based-agent-identity.md       ← 역할 정체성 패턴
      ephemeral-pr-artifacts.md           ← PR 운영 패턴
      explicit-anti-patterns.md           ← 안티 패턴 문서
      triage-discipline.md                ← SM 트라이지 프로세스
      PROVENANCE.md                       ← 학습 세션 감사 추적
      README.md                           ← 스킬 인덱스
  boundaries/
    README.md
    example.boundary
  docs/
    aide/
      vision.md
      roadmap.md
      definition-of-done.md
      progress.md
  .otherness/
    state.json                 ← _state 브랜치에만 있음
  .opencode/
    command/
      otherness.run.md
      otherness.run.bounded.md
      otherness.setup.md
      otherness.status.md
      otherness.upgrade.md
      otherness.learn.md
      otherness.arch-audit.md
      otherness.cross-agent-monitor.md
  otherness-config.yaml
  otherness-config-template.yaml
  AGENTS.md
  README.md
  onboarding-new-project.md
  onboarding-existing-project.md
  scripts/
    validate.sh                ← BUILD_COMMAND 대상
    test.sh                    ← TEST_COMMAND 대상
    lint.sh                    ← LINT_COMMAND 대상

변경 위험 등급

이 섹션은 가장 중요합니다. 모든 PR은 병합 전에 분류되어야 합니다.

등급	파일	위험	병합 게이트
CRITICAL	`agents/standalone.md`, `agents/bounded-standalone.md`, `agents/phases/*.md`	모든 프로젝트에 즉시 배포됩니다. 잘못된 명령은 모든 otherness 사용자의 다음 세션을 중단시킬 수 있습니다.	[NEEDS HUMAN] 병합 전 검토 필요. 자율 병합 금지.
HIGH	`agents/onboard.md`, `agents/otherness.learn.md`, `otherness-config-template.yaml`, `onboarding-*.md`	새 프로젝트 설정 또는 학습 루프에 영향을 미칩니다.	QA가 참조 프로젝트에 대해 확인해야 합니다. 테스트 통과 시 자율 병합 허용됩니다.
MEDIUM	`agents/skills/*.md`, `agents/gh-features.md`, `boundaries/`	추가적인 지식입니다. 회귀의 영향이 낮습니다.	표준 QA 주기. 자율 병합.
LOW	`docs/`, `README.md`, `AGENTS.md`, `scripts/`	문서 및 스캐폴딩. 런타임 영향 없음.	자율 병합.

CRITICAL 등급 규칙: agents/standalone.md, agents/bounded-standalone.md, 또는 agents/phases/*.md를 건드리는 모든 PR은 PR에 [NEEDS HUMAN: critical-tier-change]를 게시해야 하며 자율적으로 병합되어서는 안 됩니다. 인간 검토를 위해 남겨두십시오.

otherness에서 "테스트"의 의미

otherness에는 단위 테스트가 없습니다. 그 정확성은 실제 프로젝트에서 실행하고 동작을 관찰함으로써만 검증할 수 있습니다.

scripts/validate.sh(BUILD_COMMAND)는 다음 구조적 검사를 수행합니다:

하드코딩된 프로젝트 경로 없음 — 에이전트, 단계 및 스킬 파일은 실행 가능한 명령 컨텍스트에서 특정 프로젝트를 참조해서는 안 됩니다. PROVENANCE.md 및 HTML 주석 출처 메타데이터는 예외입니다.
스킬 참조 확인 — standalone.md 및 agents/phases/*.md의 모든 Load skill: read ... 참조가 디스크 또는 저장소에 있는 기존 파일을 가리킵니다.
필수 파일 존재 — 필요한 세트에 나열된 모든 에이전트 파일, 단계 파일, 스킬 파일, 문서 및 명령 파일이 존재합니다.
자체 업데이트 존재 — standalone.md에 git -C ~/.otherness pull 자체 업데이트 블록이 포함되어 있습니다.

scripts/test.sh(TEST_COMMAND)는 4가지 유효성 검사 확인을 모두 실행하고 다음을 추가로 수행합니다:

통합 테스트 — _state 브랜치를 확인하여 지난 72시간 이내에 활동이 있는지 확인함으로써 참조 프로젝트( otherness-config.yaml의 monitor.projects에서 otherness가 아닌 첫 번째 항목)에서 otherness가 올바르게 실행 중인지 확인합니다.

scripts/lint.sh(LINT_COMMAND)는 python3(외부 도구 필요 없음)을 사용하여 에이전트 파일의 구조적 정확성을 확인합니다: CRLF 줄 끝, 널 바이트, standalone.md의 필수 단계 헤더.

자기 개선 루프

otherness가 자기 자신 위에서 실행될 때 개선 영역은 다음과 같습니다:

에이전트 루프 품질 — 독립 에이전트가 더 나은 결정을 내리는가? 측정: 참조 프로젝트의 배치당 [NEEDS HUMAN] 에스컬레이션 감소, 항목당 병합 시간 단축.
스킬 깊이 — /otherness.learn 세션에서 스킬 파일이 증가하고 있는가? 측정: PROVENANCE.md 항목 수, 스킬 파일 수.
온보딩 마찰 — /otherness.onboard가 완전하고 정확한 docs/aide/ 파일을 생성하는가? 측정: 온보딩 후 필요한 수동 편집 횟수.
문서 정확성 — README.md가 실제 동작과 일치하는가? 측정: PM 검증 여정 통과.
도구 — scripts/validate.sh, scripts/test.sh, scripts/lint.sh가 실제 회귀를 발견하는가? 측정: 이러한 스크립트가 시간이 지남에 따라 개선됩니다.

PM 단계는 otherness가 유래한 커뮤니티(Hermes, Multica, Archon)와 매 배치마다 비교하고, 해결할 가치가 있는 격차를 식별해야 합니다.

안티 패턴(QA는 다음을 포함하는 PR을 차단합니다)

패턴	발견 주체
`[NEEDS HUMAN]` 레이블 없이 CRITICAL 등급 PR 병합	QA — 하드 차단
`standalone.md`에 프로젝트별 경로 하드코딩(예: fleet 프로젝트 이름, owner/repo 슬러그)	QA
우아한 폴백 없이 누락된 선택적 파일을 차단하는 에이전트 명령	QA
모든 OpenCode 세션에서 사용할 수 없는 도구를 참조하는 스킬 파일	QA
시작 시 자체 업데이트 `git pull` 제거 또는 약화	QA — 하드 차단
병렬 세션 안전성을 확인하지 않고 `_state` 브랜치 쓰기 패턴 변경	QA — 하드 차단
구현 없는 작업 `[x]`	QA

레이블 분류

그룹	레이블
종류	`kind/enhancement`, `kind/bug`, `kind/chore`, `kind/docs`
영역	`area/agent-loop`, `area/skills`, `area/onboarding`, `area/tooling`, `area/docs`
우선순위	`priority/critical`, `priority/high`, `priority/medium`, `priority/low`
크기	`size/xs`, `size/s`, `size/m`, `size/l`, `size/xl`
위험	`risk/critical`, `risk/high`, `risk/medium`, `risk/low`
유형	`epic`
워크플로우	`otherness`, `needs-human`, `blocked`

제품 검증 시나리오(PM 단계)

PM 에이전트는 참조 프로젝트를 관찰하여 otherness를 검증합니다. 참조 프로젝트는 otherness-config.yaml의 monitor.projects 아래에 있는 otherness가 아닌 첫 번째 항목입니다. 아래 명령은 $REFERENCE_PROJECT를 자리 표시자로 사용합니다 — 실제 프로젝트 슬러그(예: owner/my-project)로 바꾸십시오.

시나리오 1: 참조 프로젝트가 활성 상태임

REFERENCE_PROJECT=$(python3 -c "
import re
in_monitor=in_projects=False
for line in open('otherness-config.yaml'):
    if re.match(r'^monitor:',line): in_monitor=True
    if in_monitor and re.match(r'\s+projects:',line): in_projects=True
    if in_projects:
        m=re.match(r'\s+- (.+)',line)
        if m:
            r=m.group(1).strip()
            if not r.endswith('/otherness'): print(r); break
")
gh api "repos/$REFERENCE_PROJECT/branches/_state" \
  --jq '.commit.commit.committer.date'
# 72시간 이내여야 합니다. 더 오래된 경우: otherness가 참조 프로젝트에서 중단되었습니다.

통과: _state가 72시간 이내의 커밋을 보여줍니다.

시나리오 2: 참조 프로젝트에 열린 PR 또는 최근 병합이 있음

gh pr list --repo $REFERENCE_PROJECT --json number,title,state,createdAt \
  --jq '.[] | "\(.state) \(.createdAt) \(.title)"' | head -5

통과: 지난 7일 이내에 최소 하나의 PR이 열리거나 병합되었습니다.

시나리오 3: 스킬이 성장하고 있음

ls ~/.otherness/agents/skills/ | wc -l
# ≥ 4여야 합니다(처음 시작한 4개). 성장은 /otherness.learn이 실행되었음을 의미합니다.
tail -20 ~/.otherness/agents/skills/PROVENANCE.md

통과: PROVENANCE.md에 지난 30일 이내에 날짜가 지정된 항목이 하나 이상 있습니다.

시나리오 4: README가 실제 동작과 일치함

README.md를 읽고 agents/standalone.md와 교차 참조하십시오. 확인: README에 나열된 모든 명령이 .opencode/command/에 존재합니다. 확인: 스택 다이어그램에 나열된 모든 에이전트 파일이 디스크에 존재합니다. 발견된 각 불일치에 대해 kind/docs 이슈를 엽니다.

시나리오 5: 자기 개선이 진행 중임

OTHERNESS_REPO=$(python3 -c "
import re
for line in open('otherness-config.yaml'):
    m=re.match(r'^\s+repo:\s*(.+)',line)
    if m: print(m.group(1).strip()); break
")
gh pr list --repo $OTHERNESS_REPO --state merged \
  --json mergedAt,title --jq '.[] | "\(.mergedAt) \(.title)"' | head -10

통과: 지난 14일 이내에 최소 하나의 PR이 병합되었습니다. 0인 경우: otherness가 최근에 자체 개선되지 않았습니다. 이유를 조사하고 이슈를 엽니다.

에이전트가 수정해서는 안 되는 파일

AGENTS.md (이 파일)
docs/aide/vision.md
docs/aide/roadmap.md
otherness-config-template.yaml (변경 위험 등급 HIGH — QA만, 자율 아님)

미래 위험: 글로벌 배포 모델

향후 고려를 위한 문서(옵션 B):

현재, otherness 메인 브랜치에 병합된 모든 PR은 git -C ~/.otherness pull을 통해 otherness를 사용하는 모든 프로젝트에 즉시 배포됩니다. 이것은 옵션 A입니다 — 빠르고, 간단하며, 버전 관리 오버헤드가 없습니다.

위험: agents/standalone.md의 버그가 모든 otherness 세션을 동시에 중단시킵니다. 현재는 다음을 통해 완화됩니다: CRITICAL 등급에 인간 검토 필요, 참조 프로젝트에 대한 통합 테스트, 에이전트 루프가 회복력이 있다는 사실(잘못된 명령은 충돌 대신 [NEEDS HUMAN]을 유발합니다).

옵션 B(버전화된 릴리스)로 업그레이드해야 하는 경우:

otherness가 >10개의 다른 저장소에서 사용될 때
CRITICAL 등급 회귀가 테스트 이외의 프로젝트에 실제 피해를 입혔을 때
사용자가 세션 간 안정성 보장이 필요할 때

옵션 B 설계: git 태그를 릴리스로 사용, 프로젝트가 otherness-config.yaml에서 태그를 고정, /otherness.upgrade가 변경 로그 검토 단계와 함께 고정을 업데이트. git pull 자체 업데이트가 git checkout <pinned-tag>가 됩니다.

pnz1990/otherness

otherness란 무엇인가요?

즐겨 사용하는 AI에게 물어보기

문서