AI-translated from English; not yet reviewed by a fluent editor.

# Archon 기반 소프트웨어 팩토리를 설정하고 작업 하나 검토하기

> 고정된 버전의 관리자 문서를 바탕으로 제품 목표와 실행 검증부터 사람의 병합 결정까지 Archon 개발 작업 하나를 계획하고 검토합니다. BIG CHANGE는 이 팩토리를 실행하지 않았습니다.

By BIG CHANGE Editorial

Published: 2026-10-19T14:43:34.857Z
Updated: 2026-10-19T14:43:34.857Z
Canonical: https://bigchange.ai/blog/archon-software-factory-reviewed-issue

![Conceptual charcoal illustration of one reviewer studying an unbranded two-column code change printout clipped to a wall rail.](https://bigchange.ai/api/media/file/archon-reviewed-code-change-v2.png)
AI-generated conceptual illustration by BIG CHANGE; no factory installation, issue delivery, code review outcome or product interface is depicted.

이 [AI Software Factory 저장소](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/README.md)는 제품 목표와 작업에서 Archon이 만드는 풀 리퀘스트까지의 경로를 설명합니다. 설치와 워크플로 검사는 시작일 뿐입니다. 관리자의 [첫 한 시간 안내](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/docs/first-hour.md)는 실제 전체 과정 검증이 아직 필요하다고 밝힙니다. 이 글은 팩토리 커밋 `9e2d85298b45497031009597a6ae0811b66fe6d6`와 여기에 고정된 Archon 리비전 `fad09169ea1b43512bc7ee88470d47f960a3e0f8`를 따릅니다. 문서와 코드를 읽은 안내이며, BIG CHANGE의 설치·실행 보고가 아닙니다.

앱 저장소나 PRD, GitHub 권한, 모델 제공업체 계정을 관리하는 팀을 위한 절차입니다. 관리자는 팩토리를 복제해 자신의 저장소에 설치하는 방법을 명시합니다. 고정된 팩토리 트리에는 라이선스나 고지 파일이 없으며, 이 안내는 더 넓은 재사용·재배포 권리를 입증하지 않습니다. Archon의 MIT 라이선스는 별도 Archon 소스에 적용됩니다. 제공업체의 비밀 정보는 작업 설명, 프롬프트, 로그, 검토 기록에 넣지 마세요.

## 큰 변화

- **달라지는 점:** 고정된 Archon 워크플로 팩으로 제품 범위, 작업 계획, 코딩, 독립 검토, 실행 검사를 연결합니다. 팩토리는 프로젝트 입력과 실행기를 제공하고, 공유 팩은 AI 단계를 담당합니다.
- **중요한 이유:** 팀은 작업에서 구체적인 변경, CI 결과, 실행 중인 후보까지 추적한 뒤 병합을 결정할 수 있습니다. 설치 검사만으로는 추적이 불완전하며, 관리자도 실제 통합 검증이 남았다고 밝힙니다.
- **지켜볼 점:** 첫 유용한 증거는 납품 리비전이 의미 있는 사용자 흐름과 독립적인 별도 검증을 통과하고 팀에 비용과 검토 기록이 보이는 실제 작업입니다. 일정과 배포는 그 검토 후에도 별도 결정입니다.

## 1. 저장소, 권한, 고정된 소스 확인하기

관리자의 [설치 안내](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/README.md#instructions-for-the-agent)는 Git, Python 3.10 이상, 인증한 `gh` (`workflow` 범위), GitHub 원격 저장소, 코딩 에이전트, Bun, uv를 요구합니다. Git도 워크플로 파일을 푸시할 수 있어야 합니다(`gh auth setup-git`). 에이전트 실행 전에 기존 테스트·시작·CI 명령, 브랜치 보호, GitHub 접근, 제공업체 인증, 모델 과금을 확인하세요. 실행에 필요한 저장소와 워크플로 권한만 부여합니다.

앱 저장소 밖에 팩토리를 복제하고 지정 커밋을 체크아웃합니다. 문서의 설치 명령은 *앱* 루트에서 실행합니다.

```bash
git clone https://github.com/coleam00/ai-software-factory ~/ai-software-factory
git -C ~/ai-software-factory checkout 9e2d85298b45497031009597a6ae0811b66fe6d6
python ~/ai-software-factory/bin/factory.py init
```

필요하면 `python3`를 사용하세요. 설치 프로그램은 팩토리와 프로젝트 템플릿을 복사하고 [`pack.json`](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/template/factory/pack.json)에 지정된 Archon 소스를 설치합니다. 이 커밋의 README와 팩은 모두 `fad09169ea1b43512bc7ee88470d47f960a3e0f8`를 지정합니다. 설치 프로그램은 제공업체 인증, 모델 등급 선택, 일정 시작을 하지 않습니다. 저장소에서 변경을 수용하기 전에 실제 파일 차이를 확인하세요.

설치된 Archon 설정 안내에 따라 제공업체와 지원 모델 식별자를 구성합니다. `harness/harness.config.json`에 실제 정적 검사·단위 테스트 명령을 넣습니다. GitHub가 브랜치 보호 정보를 보고하지 못하면 병합에 필요한 CI 작업을 `required_checks`에 적습니다. `protected_paths`를 검토해 목표, 검증 체계, 팩토리 정책 변경에 사람이 관여하게 합니다. 템플릿은 일반 검사 명령과 `required_checks`를 비워 둡니다. 복사만으로 쓸 수 있는 승인 기준이 생기지 않습니다.

## 2. 현재 제품의 목표와 검증 작성하기

파일 `MISSION.md`에 제품 목적, 엄격한 한계, 있을 법하지만 범위 밖인 요청을 적습니다. `harness/END-TO-END.md`에는 현재 앱이 실제로 마칠 수 있는 사용자 흐름 두 개에서 다섯 개와 사용자가 얻는 가치를 씁니다. 아직 만들지 않은 기능이 필요한 흐름은 첫 납품을 막습니다. `.factory/holdout/HOLDOUT.md`에는 동작 조합이나 경계 상황을 확인하는 별도 사례를 씁니다. 같은 작업 사본에 접근하는 개발자에게 디렉터리 이름이 사례를 숨겨 주지는 않습니다. 정말 비공개인 사례는 사본 밖에 두고 검증 측에만 전달하세요.

PRD만 있는 저장소라면 [README](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/README.md#instructions-for-the-agent)는 문서에서 목표, 예정된 사용자 흐름, 검증 명령을 도출하도록 요구합니다. 첫 작업 제안은 제품을 실행 가능하게 만들고 시작 명령, 상태·빌드 식별 확인 경로, 테스트, CI를 명시해야 합니다. 작업 게시를 허용하기 전에 제안을 검토하세요.

흐름을 Archon 실행 워크플로가 기대하는 시나리오 입력으로 바꿉니다. 설치된 [`factory/RUNTIME_HOST.md`](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/template/factory/RUNTIME_HOST.md)에 따라 납품 커밋의 앱 스냅샷, 새 상태, 상태·빌드 식별 검사, 허용된 Python 또는 Node 시작 명령을 준비합니다. 문서의 호스트는 원격 데이터베이스, 컨테이너, 클라우드 자원을 자신이 관리하는 실행 자원으로 지원하지 않습니다. 이를 사용하는 앱에는 별도로 정당화한 검증 구성이 필요합니다. 로컬 호스트 검사 성공이 해당 자원의 격리를 입증하지 않습니다.

평가기 전에 실제 사용자 가치를 시험하는 통과 기준선을 만들고, 관련 있는 의도적 결함은 실패하며 잘못된 후보 식별 정보는 판정 불가 결과를 내는지 확인합니다. 호스트 안내에는 입력과 정확한 예상 필드가 있으며 `expectations_passed: true`, `baseline_verified: true`도 포함됩니다. 실제 원시 반환값과 후보 식별 정보를 증거로 보관하세요. 페이지 로딩만 확인하거나 최종 상태를 직접 만들어 놓는 테스트는 충분하지 않습니다.

## 3. 설치를 검사한 뒤 작업 하나 선택하기

앱 루트에서 실행합니다.

```bash
python factory/consumer.py doctor
python factory/consumer.py list
```

`doctor`는 고정 소스, 명령 기능, 사용 가능한 워크플로를 검사합니다. `list`는 발견한 워크플로를 보여 줍니다. 어느 명령도 제공업체가 작업을 끝낼 수 있는지, CI가 통과하는지, 앱이 실행되는지 입증하지 않습니다. 납품 전 보고된 문제를 해결하고 일정은 꺼 두세요.

기존 코드베이스라면 결과와 승인 검사가 분명한 작은 작업 하나를 작성합니다. README는 분류, 납품, 검토를 거쳐 PR로 진행하는 다음 명령을 설명합니다.

```bash
python factory/consumer.py run archon-ship --input target=https://github.com/OWNER/REPO/issues/1 --input discovery_publication=preview --detach --json
```

작업 URL을 직접 관리하는 것으로 바꾸세요. `discovery_publication=preview`를 명시하면 검토의 연관 발견 사항을 작업으로 게시하지 않습니다. 고정된 `archon-ship`의 기본값은 `auto`입니다. 실행 시나리오와 별도 검증 입력이 준비된 뒤에만 `archon-lifecycle`을 사용합니다. 작업은 `target`, 해당 경로는 `scenario`, `holdout`으로 전달하고 `merge_mode=approve`, `discovery_publication=preview`도 지정합니다. 프로젝트가 허용한 `merge_method`도 필요하며 값은 `merge`, `squash`, `rebase` 중 하나입니다. 예를 들어 저장소가 허용할 때만 `merge_method=squash`를 쓰세요. 이 흐름은 실행·별도 사례 검증, 수정, 병합 관문을 포함합니다. 승인 모드는 병합 전에 사람의 결정을 남깁니다. 워크플로의 준비 완료 표시는 그 결정이 아닙니다. 팩토리 실행 호스트의 문서화된 `--runtime-host`는 포그라운드 전용이며 `--detach`, `--resume`과 함께 쓸 수 없습니다.

PRD용으로 문서화된 백로그 명령은 다음과 같습니다.

```bash
python factory/consumer.py run archon-backlog --input 'prd=docs/PRD.md' --input publication=approve
```

따옴표 안의 `docs/PRD.md`를 앱 작업 사본 기준 실제 PRD 경로로 바꾸세요. 게시 전에 제안된 작업 순서를 검토합니다. 첫 작업이 선언한 앱 시작 방식과 식별 계약으로 실행 호스트를 연결하고, 준비한 사용자 흐름과 별도 사례를 사용해 `archon-lifecycle`로 처리합니다. 첫 작업도 이후 작업과 똑같이 꼼꼼히 검사하세요.

## 4. 승인 전에 차이와 실제 동작 평가하기

반환된 실행 ID를 보관합니다. 제어 프로그램은 진행과 증거 확인용 `get <run-id> --json --events`, `status --all --json`을 제공합니다. 작업과 계획을 `MISSION.md`와 대조하고, 실제 PR 차이와 최신 리비전에 대한 독립 검토를 읽고, 필수 CI 결과와 보호 경로 보고서를 확인합니다. 납품 리비전에서 제품 사용자 흐름을 실행하고 후보 식별 정보를 포함한 원시 실행·별도 검증 결과를 확인합니다. 관찰한 사용자 결과와 승인 기준을 비교하세요. 미흡한 PR은 수정하도록 돌려보내야 합니다. README는 병합 대기열에서 보류된 납품 실행에 `archon-deliver --adopt <run id>`를 설명합니다.

검사 통과 후 저장소 권한을 가진 사람만 병합을 승인해야 합니다. 배포에는 프로젝트별 배포·상태·식별 명령과 배포 후 리비전 재확인이 필요합니다. PR 병합만으로 배포가 입증되지 않습니다. 첫 작업 동안 일정을 꺼 두고 반복 실행 여부는 따로 결정하세요.

관리자의 [비용 안내](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/README.md#cost)는 실행당 고정 가격을 제시하지 않습니다. 첫날부터 토큰을 측정하고 반복을 켜기 전에 작은 작업 하나의 모델 호출을 살피라고 권합니다. 요금은 제공업체, 모델, 계정 약관에 달려 있습니다. BIG CHANGE는 이 팩토리의 지출을 측정하지 않았습니다.

실행 중인 작업에도 명시적인 중단 결정이 필요합니다. [제어 프로그램 코드](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/template/factory/consumer.py)에서 `halt`는 새 시작과 후속 진행을 막고 `cancel <run-id>`는 활성 작업을 대상으로 합니다. `pause`는 타이머 시작을 멈추지만 진행 중 작업의 깨우기는 허용합니다. 어느 명령도 실제 실행 상태와 원격 저장소 변경 확인을 대신하지 않습니다.

## 출처와 더 읽을 자료

- [고정 버전 팩토리 README](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/README.md): 설치, 명령, 제품 입력, 워크플로 선택, 명시된 한계. 관리자의 설명이며 BIG CHANGE 실행의 증거가 아닙니다.
- [고정 팩 명세](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/template/factory/pack.json)와 [제어 프로그램 코드](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/template/factory/consumer.py): Archon 리비전, 제공 워크플로, status·halt·cancel·pause의 차이.
- [첫 한 시간 안내](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/docs/first-hour.md)와 [실행 호스트 안내](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/template/factory/RUNTIME_HOST.md): 관리자의 검증 유보와 후보에 연결된 실행 검사 요건.
- [코딩 에이전트와 완료된 작업에 관한 BIG CHANGE 관련 보도](https://bigchange.ai/articles/ai-coding-agents-review-output-study): 완성된 결과를 확인하기 위한 맥락입니다. 별개 연구를 다루며 이 팩토리 구현의 시간순 후속 보도가 아닙니다.

## Sources

- [README.md](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/README.md) — 관리자의 설치, 프로젝트 파일, 워크플로, 작업·PRD 경로, 병합 정책과 운영 한계.
- [pack.json](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/template/factory/pack.json) — 정확한 Archon 리비전, 워크플로, 명령줄 기능. 고정 README와 일치합니다.
- [first-hour.md](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/docs/first-hour.md) — 설치 순서와 실제 전체 과정 검증이 필요하다는 명시적 설명.
- [consumer.py](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/template/factory/consumer.py) — doctor/list, 워크플로 호출, status, halt, pause, cancel 구현.
- [RUNTIME_HOST.md](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/template/factory/RUNTIME_HOST.md) — 후보 연결, 기준선과 의도적 결함 보정, 지원 앱 형태 및 한계.
- [harness.config.json](https://github.com/coleam00/ai-software-factory/blob/9e2d85298b45497031009597a6ae0811b66fe6d6/template/harness/harness.config.json) — 빈 프로젝트 검사 명령·필수 검사와 기본 보호 경로.
- [LICENSE](https://github.com/coleam00/Archon/blob/fad09169ea1b43512bc7ee88470d47f960a3e0f8/LICENSE) — Archon 라이선스 조건이며 별도 팩토리 저장소의 사용 허가를 입증하지 않습니다.
- [archon-ship.yaml](https://github.com/coleam00/Archon/blob/fad09169ea1b43512bc7ee88470d47f960a3e0f8/.archon/workflows/sdlc/ship/archon-ship.yaml) — 발견 사항 게시 기본값은 auto이며 preview는 연관 발견을 게시하지 않습니다.
- [archon-lifecycle.yaml](https://github.com/coleam00/Archon/blob/fad09169ea1b43512bc7ee88470d47f960a3e0f8/.archon/workflows/sdlc/lifecycle/archon-lifecycle.yaml) — merge, squash, rebase 중 명시적 병합 방식이 필요합니다.
- [archon-backlog.yaml](https://github.com/coleam00/Archon/blob/fad09169ea1b43512bc7ee88470d47f960a3e0f8/.archon/workflows/sdlc/backlog/archon-backlog.yaml) — PRD는 작업 사본 내부 경로로 지정합니다.
- [BIG CHANGE](https://bigchange.ai/articles/ai-coding-agents-review-output-study) — 완료 결과 검증을 위한 관련 있지만 별개의 맥락.