docs(readme): README를 한국어로 정리한다

README.md

@@ -1,39 +1,80 @@
-<!-- 
-This README describes the package. If you publish this package to pub.dev,
-this README's contents appear on the landing page for your package.
+# dart-app-core
 
-For information about how to write a good package README, see the guide for
-[writing package pages](https://dart.dev/guides/libraries/writing-package-pages). 
+`dart-app-core`는 Dart 애플리케이션에서 반복해서 쓰는 공통 기능을 모아둔 라이브러리 패키지다. 패키지 이름은 `dart_framework`이며, 앱 초기화, 플랫폼별 I/O 추상화, 문자셋 변환, 자막 파싱, Slack 전송, 간단한 암호화/유틸리티 기능을 제공한다.
 
-For general information about developing packages, see the Dart guide for
-[creating packages](https://dart.dev/guides/libraries/create-library-packages)
-and the Flutter guide for
-[developing packages and plugins](https://flutter.dev/developing-packages). 
--->
+## 현재 상태
 
-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`