From 1744270a958cba9f82384d657e8ef8ccbf92acba Mon Sep 17 00:00:00 2001 From: toki Date: Fri, 29 May 2026 05:41:30 +0900 Subject: [PATCH] =?UTF-8?q?docs(readme):=20README=EB=A5=BC=20=ED=95=9C?= =?UTF-8?q?=EA=B5=AD=EC=96=B4=EB=A1=9C=20=EC=A0=95=EB=A6=AC=ED=95=9C?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 101 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 71 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 8b55e73..c95fd8a 100644 --- a/README.md +++ b/README.md @@ -1,39 +1,80 @@ - +## 현재 상태 -TODO: Put a short description of the package here that helps potential users -know whether this package might be useful for them. +- Dart SDK `>=3.2.3 <4.0.0`을 기준으로 한다. +- `lib/dart_framework.dart`가 주요 공개 API 진입점이다. +- 플랫폼 분기는 `lib/platform/platform_stub.dart`, `lib/platform/platform_io.dart`, `lib/platform/platform_web.dart`의 조건부 import 구조를 사용한다. +- `lib/charset/**`에는 EUC-KR, EUC-JP, GBK, Shift-JIS, UTF 계열 문자셋 처리 코드와 매핑 테이블이 있다. +- `lib/subtitle/**`에는 SMI, SRT, VTT 파서가 있다. +- `lib/utils/slack/**`에는 Slack message 전송 helper가 있다. +- `*.g.dart` 파일은 `json_serializable` 기반 생성물이며 직접 수정하지 않는다. -## Features +## 빠른 시작 -TODO: List what your package can do. Maybe include images, gifs, or videos. +의존성을 가져온다. -## Getting started - -TODO: List prerequisites and provide or point to information on how to -start using the package. - -## Usage - -TODO: Include short and useful examples for package users. Add longer examples -to `/example` folder. - -```dart -const like = 'sample'; +```bash +dart pub get ``` -## Additional information +테스트를 실행한다. -TODO: Tell users more about the package: where to find more information, how to -contribute to the package, how to file issues, what response they can expect -from the package authors, and more. +```bash +dart test +``` + +예제 코드를 실행한다. + +```bash +dart run example/dart_framework_example.dart +``` + +## 주요 명령 + +| 목적 | 명령 | 비고 | +|------|------|------| +| 의존성 설치 | `dart pub get` | `pubspec.yaml` 기준으로 패키지를 가져온다. | +| 테스트 실행 | `dart test` | `test/` 아래 테스트를 실행한다. | +| 예제 실행 | `dart run example/dart_framework_example.dart` | 공개 API 사용 예시를 확인한다. | +| 생성 코드 갱신 | `dart run build_runner build` | `json_serializable` 생성물이 바뀔 때만 실행한다. | + +## 구조 + +| 경로 | 역할 | +|------|------| +| `lib/dart_framework.dart` | 패키지 공개 API 진입점 | +| `lib/core/` | 애플리케이션, 앱 데이터, 예외 관리 기본 구조 | +| `lib/platform/` | I/O, Web, stub 플랫폼 분기와 process/isolate helper | +| `lib/charset/` | 문자셋 변환과 코드 페이지 매핑 | +| `lib/subtitle/` | 자막 파서 | +| `lib/utils/` | path, string, system, startup, Slack helper | +| `lib/encrypt/` | 암호화 helper | +| `lib/model/`, `lib/data/` | 공유 데이터 모델과 생성 코드 | +| `test/` | 패키지 테스트 | +| `example/` | 사용 예시 | +| `agent-ops/` | AI agent 작업 규칙과 공통 skill | + +## 작업 맥락 + +- 작업 전 `AGENTS.md`와 `agent-ops/rules/project/rules.md`를 읽는다. +- 변경 경로에 맞는 domain rule이 있으면 `agent-ops/rules/project/domain/*/rules.md`를 먼저 확인한다. +- `lib/charset/**`의 문자셋 테이블과 매핑 파일은 대량 데이터 성격이 있으므로 불필요한 포맷 변경을 피한다. +- 공개 API를 바꾸면 `lib/dart_framework.dart`와 관련 top-level export 파일을 함께 확인한다. +- 생성 파일인 `*.g.dart`는 소스 변경 후 build runner로 갱신하며 손으로 고치지 않는다. + +## 개발 흐름 + +1. 변경할 경로의 domain rule을 확인한다. +2. 공개 API, 플랫폼 분기, 생성 코드 여부를 먼저 판단한다. +3. 변경 범위에 맞는 최소 테스트를 실행한다. +4. 필요한 경우 `dart test`로 전체 테스트를 확인한다. + +## 참고 문서 + +- `AGENTS.md` +- `agent-ops/rules/project/rules.md` +- `pubspec.yaml` +- `CHANGELOG.md`