01 / 공통으로 남길 것
프로젝트 설명과 배포 규칙을
매번 다시 찾지 않도록
AI 에이전트와 개발할 때 반복해서 설명하던 맥락과 절차를 스킬과 프로젝트 문서로 묶은 사내 프로젝트입니다.
초기에는 탐색·계획·구현·리뷰·보고를 세분화하고 오케스트레이터로 연결했습니다. 모델의 판단과 실행 능력이 좋아지면서, 세부 지시를 늘리기보다 공통 흐름과 작업별 맥락을 나누는 방향으로 바꿨습니다.
02 / 명세와 실행의 연결
OpenSpec으로 정하고,
Superpowers로 구현한다
spec-driven-workflow는 두 도구의 역할을 잇는 스킬입니다. OpenSpec에서 문제와 요구사항을 정리하고, 확정한 태스크를 Superpowers의 구현·리뷰·검증 흐름으로 이어 갑니다. 변경을 확인한 뒤에는 OpenSpec에서 명세를 정리합니다.
요구사항과 코드 사이를 태스크와 검증 결과로 연결합니다.
전체 연결 읽기 · 2개
- 요구사항 확정 → 구현과 검증
- 구현과 검증 → 명세에 반영
일반적인 기능 개발과 동작 변경에는 전체 흐름을 적용하고, 오탈자나 문구 수정은 필요한 확인만 거칩니다. 검증도 현재 변경이 미치는 범위에 맞춥니다. 변경 범위에 맞춰 에이전트 검증을 정한 기록에 적용 기준과 한계를 정리했습니다.
실제 스킬에 정의한 적용 범위
새 동작·기능, 여러 파일이나 모듈에 걸친 변경, DB·API 계약 변경, 해석이 갈리는 요구사항과 원인이 불명확한 버그를 전체 절차의 대상으로 둡니다. 프로젝트의 지시 파일과 사용자가 정한 작업 범위도 함께 확인합니다.
OpenSpec 루트가 없는 프로젝트에는 명세 생성과 정리 단계를 적용하지 않고 구현·검증 흐름을 사용합니다. 별도 요청 없이 OpenSpec 프로젝트를 초기화하지 않습니다.
요구사항의 정합성과 완료 판단은 작업을 조율하는 모델이 맡고, 정해진 태스크 구현은 서브에이전트에 나눕니다. 검증 실패나 예상 밖 동작은 원인을 조사한 뒤 수정합니다.
03 / 맥락이 머무는 위치
개발 습관은 프로젝트에,
배포 방법은 제품에
같은 회사의 제품이라도 기술 스택과 폴더 구조, 실행 환경과 배포 방식은 다릅니다. 공통 개발 절차에 모든 정보를 넣으면 한 제품의 규칙이 다른 작업까지 따라옵니다.
저장소 전체의 개발·검증 방법은 루트에, 모듈의 책임과 제약은 해당 폴더 가까이에 둡니다. 제품별 플러그인은 배포 스킬과 환경·실행 정보를 묶습니다. 프로젝트 문서도 필요한 판단과 실행 방법을 담는다는 점에서 스킬처럼 활용합니다.
맥락의 위치를 표현한 개념 삽화
- 저장소의 맥락
- 사용하는 기술과 전체 구조, 개발·검증 방법, 공통 작업 습관.
- 모듈의 맥락
- 해당 영역의 책임과 제약, 변경할 때 함께 확인할 내용.
- 제품별 플러그인
- 배포 스킬과 제품에 필요한 구체적인 정보·실행 절차.
- 공통 개발 절차
- 제품이 달라도 공유하는 요구사항 확정과 구현·검증의 흐름.
04 / 함께 읽을 문서
BCD와 위키 작성 기준은
여러 제품에서 함께 쓴다
개발과 배포는 제품의 차이를 따라가지만, 현재 동작을 조사하고 다른 사람이 읽을 문서로 설명하는 일은 여러 제품에서 반복됩니다. BCD와 위키 문서 작성에 필요한 스킬은 공통으로 공유합니다.
BCD는 제품의 현재 화면과 동작을 정리해 변경 방향을 논의하는 문서입니다. BCD 작성 스킬은 화면의 진행 순서 안에서 입력, 처리와 결과를 설명하도록 구성했습니다. AI 기능은 실제 호출 단위와 모델, 프롬프트·조건 분기를 조사하고, 주요 화면은 실제 스크린샷으로 연결합니다. 기획자와 개발자가 현재 동작을 같은 문서에서 확인하고 변경 방향을 논의하기 위한 기준입니다.
화면 코드만 보고 서버 동작을 단정하지 않고, 조사한 사실과 변경 제안을 구분합니다. 입력값을 누가 채우는지, 언제 적용되는지, 결과에 어떤 영향을 주는지까지 확인합니다. 프롬프트 원문은 설명을 다듬는 과정에서 바꾸지 않습니다.
05 / 다시 쓸 판단
Xinics Brain은 계속 보강한다
공통 개발 절차와 프로젝트 문서만으로 이전 작업의 판단을 모두 이어 갈 수는 없습니다. 왜 특정 선택을 했는지, 어느 환경에서 문제가 생겼는지, 어떤 검증으로 확인했는지는 다음 작업에서도 다시 필요합니다.
Xinics Brain은 이런 결정과 제약, 실패 원인과 검증 근거를 다시 참고할 수 있도록 남기는 역할을 맡습니다. 대화 전체를 늘리는 대신, 적용 범위와 출처를 따라 현재 작업에서 쓸 만한 판단을 찾는 방향으로 계속 보강하고 있습니다.
적용 범위와 근거를 확인해 다음 작업으로
전체 연결 읽기 · 3개
- 적용 범위 → 판단의 근거
- 판단의 근거 → 현재의 유효성
- 현재의 유효성 → 다음 작업
Night Owl은 언제 어디서 실행하고 어떤 기록을 남길지 맡고, 개발 스킬은 그 실행 안에서 필요한 절차와 맥락을 제공합니다. 예약 실행에서도 생성된 변경의 검토와 병합 판단은 사람에게 돌아옵니다.
06 / 검증과 판단을 남기는 기준
절차의 완료와 코드의 정확성을 구분한다
명세를 따랐거나 기억을 검색했다는 기록만으로 코드의 정확성이 보장되지는 않습니다. 현재 변경을 검증하고, 참고한 이전 판단도 지금의 조건에서 다시 확인해야 합니다. 품질과 생산성의 정량적인 변화는 아직 측정하지 않았습니다.
선택해서 보기 · 가상 워크플로 평가 예시
가상 평가 예시 · 실측 전
맥락 설명과 문서 재작업을 살펴보기
같은 범위의 변경 요청에서 매번 맥락을 설명하는 방식과, 프로젝트 지침·공통 흐름·작성 스킬을 읽는 방식을 비교하는 가상 시나리오입니다.
수치·표본 설정·피드백은 평가 화면을 설명하기 위해 만든 가상 예시입니다. 실제 동료에게서 수집한 기록이나 의견이 아니며, 개선 효과를 입증하지 않습니다.
| 관찰할 과정 · 단위 | 기존 방식 대화마다 설명 · 개별 작성 | 도구 사용 프로젝트 지침 · 작성 스킬 | 가상 차이 실제 개선율 아님 |
|---|---|---|---|
| 프로젝트 맥락 재설명분 / 작업 | 12 | 8 | 33.3% |
| 작업 절차 준비분 / 작업 | 6 | 4.5 | 25% |
| 문서 수정 회차회 / 문서 | 2.5 | 1.8 | 28% |
표본·계산식·관찰 범위와 다음 평가
가상 작업 동일 범위의 변경 요청과 검토 문서 작성
가상 표본 설정 역할 시나리오 6종 × 작업 4회 = 방식별 24회. 참여자를 모집하거나 수행한 실험이 아닙니다.
같은 변경 범위·자료·모델·문서 완료 기준을 가정하고 작업마다 검토 문서 1건을 작성합니다. 시간은 사람이 직접 설명하거나 설정하는 작업당 평균이며, 생성·대기는 제외합니다. 수정 회차는 같은 작업 수만큼 작성한 문서의 건당 평균입니다.
가상 차이 = (기존 방식 값 − 도구 사용 값) ÷ 기존 방식 값. 가상 평균값으로 계산한 비율이며, 실제 개선율이나 인과관계의 근거가 아닙니다.
표의 각 값은 방식별 24회 평균을 가정합니다.
- 프로젝트 맥락 재설명의 관찰 범위
- 첫 맥락 설명부터 기술 스택·제약·참고 자료를 전달할 때까지의 사람 작업 시간.
- 작업 절차 준비의 관찰 범위
- 맥락 전달 후 요구사항 정리·검증 순서·작성 기준 설정을 마칠 때까지의 사람 작업 시간.
- 문서 수정 회차의 관찰 범위
- 초안 이후 범위·구조·근거 누락을 고쳐 동일한 검토 기준에 도달할 때까지. 코드 수정은 제외.
관련 기술 기록
만들며 마주한 문제와 선택을 기술 기록으로 이어 읽습니다.
매 턴 전체 검사 대신 변경한 영역부터 확인하기
AI Commons의 턴 종료 hook은 서버와 클라이언트 전체를 자동 수정하고 검사했습니다. hook을 제거하고 코드 수정 완료에 검사를 연결하면서, 범위 선택과 결과 확인의 책임을 명시했습니다.