oto/agent-ops/rules/project/rules.md

oto 프로젝트 규칙

응답 언어

한국어로 응답한다.

프로젝트 개요

OTO CLI는 YAML 파일로 정의된 빌드/배포 파이프라인을 실행하는 Dart CLI 도구다. Jenkins, FTP, Git, Slack/Mattermost, iOS/Flutter/Android 빌드 등 다양한 CI/CD 작업을 커맨드로 추상화하고 파이프라인 엔진이 순차 실행한다.

실행 흐름

bin/main.dart
  └── Application (singleton)
        └── DataComposer  ← YAML + Jenkins env 파싱
              └── Pipeline
                    └── Command.byType(CommandType) → Command.execute(DataCommand)

주요 구조

lib/
├── cli/                         # CLI 레이어 (명령 파싱, 스케줄러 관리)
└── oto/
    ├── application.dart         # 싱글턴 오케스트레이터, BuildType enum
    ├── commands/                # 커맨드 구현체 (카테고리별)
    ├── core/                    # 태그 시스템, 데이터 합성, 정의 데이터
    ├── data/                    # JSON 직렬화 데이터 모델
    └── pipeline/                # 파이프라인 실행 엔진

참고: lib/framework/ 모듈이 제거되었습니다. 기존 기능은 lib/oto/ 내부로 통합되었습니다. 현재 dart_framework는 외부 Git 의존성으로만 사용합니다.

기술 스택

• 언어: Dart (SDK >=2.18.6 <4.0.0)
• 의존성: dart_framework (커스텀), http, json_annotation, cron, xml
• 코드 생성: json_serializable + build_runner (dart run build_runner build)

BuildType

Value	설명
jenkins	CI 모드 – Jenkins 환경 변수에서 워크스페이스·환경 읽기
test	로컬 테스트 모드 – 하드코딩된 테스트 데이터 사용
file	로컬 파일 경로에서 파이프라인 YAML 읽기
scheduler	스케줄러 데몬 모드

태그 시스템 (lib/oto/core/tag_system.dart)

• 읽기 태그 <!namespace.key> — 런타임 저장소에서 값 치환
• 쓰기 태그 <@namespace.key> — 커맨드 결과를 property에 저장

태그가 문자열 전체인 경우 원본 타입 유지 (List 등), 부분 삽입이면 toString() 변환.

데이터 모델 컨벤션

• 모든 커맨드 파라미터는 DataParam (lib/oto/data/base_data.dart) 상속
• JSON 직렬화: json_annotation 사용, 생성 파일은 *.g.dart
• CommandSpec — 커맨드의 category, dataModel, samplePath 메타데이터
• DataCommon – Jenkins 환경 데이터 (workspace, job name, build number 등)
• DataCommand (command_data.dart) – 모든 Command.execute()에 전달되는 통합 컨테이너

새 커맨드 추가 절차

1. lib/oto/data/*_data.dart에 데이터 모델 정의 (DataParam 상속)
2. lib/oto/commands/command.dart의 CommandType enum에 값 추가
3. Command 상속하여 커맨드 클래스 구현
4. Command.register(..., spec: CommandSpec(...))에 구현체/데이터 모델/샘플 경로 등록
5. lib/oto/commands/command_registry.dart의 registerAllCommands()에 등록 함수 연결
6. 관련 assets/yaml/sample/** 샘플 갱신 필요 여부 확인
7. @JsonSerializable 클래스 추가/변경 시 dart run build_runner build 실행

에러 처리

• Application.build()는 catch (e, stacktrace) (Exception이 아닌 Error 포함 캐치)
• 에러 시 BuildResult.failure(..., exitCode: 10)을 반환하고 CLI 진입점이 부모 프로세스에 실패 exit code를 전달

스킬 기반 작업 흐름

• agent-ops 초기화, domain rule 생성, skill 생성, commit/push, agent-ops sync 계열 요청은 사용자가 명시적으로 요청한 경우에만 agent-ops/skills/common/router.md를 먼저 읽고 해당 SKILL.md를 따른다.
• 도메인 룰 갱신/검토 요청은 agent-ops/skills/common/update-domain-rule/SKILL.md를 따른다.
• 새 도메인 rule 생성이 필요한 경우 agent-ops/skills/common/create-domain-rule/SKILL.md를 따른다.
• YAML 작성 요청은 코드 분석보다 sample 도메인 rule과 assets/yaml/sample/**를 우선 참조한다.
• 코드 변경 요청은 먼저 아래 도메인 매핑에서 해당 rule을 읽고, 변경 후 도메인 rule의 검증 기준을 따른다.

도메인 룰 로딩

• 아래 도메인 매핑에 해당하는 작업에서 해당 domain 최초 진입 시 domain rule을 1회 읽는다.
• 더 구체적인 경로 패턴이 있으면 그 rule을 우선 적용한다.
• 이미 읽은 domain rule은 같은 세션에서 반복해서 읽지 않는다.

마일스톤 컨텍스트 로딩

• 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 agent-ops/roadmap/current.md를 먼저 읽는다.
• 요청이 기본 Milestone 범위에 맞으면 기본 Milestone 문서를 같은 세션에서 1회 읽는다.
• 요청이 기본 Milestone과 맞지 않으면 current.md의 진행 중인 Milestone 목록에서 가장 관련 있는 Milestone 문서를 같은 세션에서 1회 읽는다.
• 진행 중인 Milestone에도 맞지 않는 요청은 무리하게 Milestone에 끼워 넣지 않는다.
  • 버그 수정, 테스트 보강, 작은 문서 수정, 기존 기능 유지보수처럼 제품 방향을 바꾸지 않는 작업은 관련 domain rule만 적용하고 진행한다.
  • 새 기능, 구조 변경, 장기 방향에 영향을 주는 작업이면 agent-ops/roadmap/ROADMAP.md의 Milestone 인덱스를 확인하고, 로드맵 밖 작업으로 진행할지 또는 로드맵을 갱신할지 사용자에게 확인한다.
• agent-ops/roadmap/ROADMAP.md는 로드맵 생성/갱신, Phase 전환, Milestone 추가/수정 요청이 있을 때만 읽는다.
• 작업 요청이 선택된 Milestone의 Goal 또는 Non-Goals와 충돌하면 구현 전에 사용자에게 알리고 방향을 확인한다.

도메인 매핑

경로 패턴	도메인	rules.md
bin/main.dart	cli	agent-ops/rules/project/domain/cli/rules.md
lib/oto/pipeline/**	pipeline	agent-ops/rules/project/domain/pipeline/rules.md
lib/oto/commands/**	command	agent-ops/rules/project/domain/command/rules.md
lib/oto/data/**	command	agent-ops/rules/project/domain/command/rules.md
lib/cli/commands/scheduler/**	scheduler	agent-ops/rules/project/domain/scheduler/rules.md
lib/cli/commands/command_scheduler.dart	scheduler	agent-ops/rules/project/domain/scheduler/rules.md
lib/cli/**	cli	agent-ops/rules/project/domain/cli/rules.md
lib/oto/application.dart	core	agent-ops/rules/project/domain/core/rules.md
lib/oto/core/**	core	agent-ops/rules/project/domain/core/rules.md
lib/oto/utils/**	core	agent-ops/rules/project/domain/core/rules.md
assets/script/**/jenkins_env_params.*	core	agent-ops/rules/project/domain/core/rules.md
assets/template/**	command	agent-ops/rules/project/domain/command/rules.md
assets/yaml/sample/**	sample	agent-ops/rules/project/domain/sample/rules.md
assets/package/**	cli	agent-ops/rules/project/domain/cli/rules.md
assets/bin/**	cli	agent-ops/rules/project/domain/cli/rules.md
assets/script/**	cli	agent-ops/rules/project/domain/cli/rules.md
pubspec.yaml	framework	agent-ops/rules/project/domain/framework/rules.md
analysis_options.yaml	framework	agent-ops/rules/project/domain/framework/rules.md

test/**는 별도 도메인으로 고정하지 않는다. 테스트 변경 시 검증 대상 production 경로의 domain rule을 읽고, 여러 도메인을 검증하는 테스트면 관련 domain rule을 함께 읽는다.

스킬 라우팅

요청 키워드	수행 방법
agent-ops 세팅해줘, scaffold 만들어줘, 초기화해줘	agent-ops/skills/common/init-agent-ops/SKILL.md 수행
yaml 짜줘, 파이프라인 만들어줘, 자동화 작성, 빌드 yaml	agent-ops/rules/project/domain/sample/rules.md 읽고 해당 샘플 참조
도메인 업데이트, domain rule 갱신, 도메인 검토, domain 스캔	agent-ops/skills/common/update-domain-rule/SKILL.md 수행
domain rule 만들어줘, rules.md 생성, 새 도메인 규칙	agent-ops/skills/common/create-domain-rule/SKILL.md 수행
skill 만들어줘, SKILL.md 생성, 새 스킬 추가	agent-ops/skills/common/create-skill/SKILL.md 수행
로드맵 만들어줘, roadmap 생성, 마일스톤 설계, goal/phase 구조 잡아줘	agent-ops/skills/common/create-roadmap/SKILL.md 수행
로드맵 업데이트, roadmap 갱신, 마일스톤 갱신, phase 변경, 현재 마일스톤 변경, 로드맵 한국어 전환, 로드맵 번역	agent-ops/skills/common/update-roadmap/SKILL.md 수행
계획 세워줘, 구현 계획, PLAN.md, plan	agent-ops/skills/common/plan/SKILL.md 수행
코드 리뷰해줘, 리뷰 진행해, 리뷰해줘, code review, CODE_REVIEW.md, 리뷰 루프	agent-ops/skills/common/code-review/SKILL.md 수행
커밋해줘, 푸시해줘, commit, push, 반영해줘	agent-ops/skills/common/commit-push/SKILL.md 수행
agent-ops 싱크해, agent-ops 동기화해, agentic-framework에 올려줘, agent-ops를 [프로젝트]로 싱크해	agent-ops/skills/common/sync-push/SKILL.md 수행
agent-ops pull해, agent-ops 가져와, agentic-framework에서 가져와, agent-ops 내려받아	agent-ops/skills/common/sync-pull/SKILL.md 수행