137 lines
8.1 KiB
Markdown
137 lines
8.1 KiB
Markdown
# 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은 같은 세션에서 반복해서 읽지 않는다.
|
||
|
||
## 도메인 매핑
|
||
|
||
| 경로 패턴 | 도메인 | 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` 수행 |
|