npm - @didim365/agent-cli-core - Versions diffs - 0.1.0 → 0.1.2 - Mend

@didim365/agent-cli-core 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1076) hide show

package/dist/docs/CONTRIBUTING.md DELETED Viewed

@@ -1,554 +0,0 @@
-# How to contribute
-We would love to accept your patches and contributions to this project. This
-document includes:
-- **[Before you begin](#before-you-begin):** Essential steps to take before
-  becoming a Gemini CLI contributor.
-- **[Code contribution process](#code-contribution-process):** How to contribute
-  code to Gemini CLI.
-- **[Development setup and workflow](#development-setup-and-workflow):** How to
-  set up your development environment and workflow.
-- **[Documentation contribution process](#documentation-contribution-process):**
-  How to contribute documentation to Gemini CLI.
-We're looking forward to seeing your contributions!
-## Before you begin
-### Sign our Contributor License Agreement
-Contributions to this project must be accompanied by a
-[Contributor License Agreement](https://cla.developers.google.com/about) (CLA).
-You (or your employer) retain the copyright to your contribution; this simply
-gives us permission to use and redistribute your contributions as part of the
-project.
-If you or your current employer have already signed the Google CLA (even if it
-was for a different project), you probably don't need to do it again.
-Visit <https://cla.developers.google.com/> to see your current agreements or to
-sign a new one.
-### Review our Community Guidelines
-This project follows
-[Google's Open Source Community Guidelines](https://opensource.google/conduct/).
-## Code contribution process
-### Get started
-The process for contributing code is as follows:
-1.  **Find an issue** that you want to work on. If an issue is tagged as
-    `🔒Maintainers only`, this means it is reserved for project maintainers. We
-    will not accept pull requests related to these issues. In the near future,
-    we will explicitly mark issues looking for contributions using the
-    `help  wanted` label. If you believe an issue is a good candidate for
-    community contribution, please leave a comment on the issue. A maintainer
-    will review it and apply the `help-wanted` label if appropriate. Only
-    maintainers should attempt to add the `help-wanted` label to an issue.
-2.  **Fork the repository** and create a new branch.
-3.  **Make your changes** in the `packages/` directory.
-4.  **Ensure all checks pass** by running `npm run preflight`.
-5.  **Open a pull request** with your changes.
-### Code reviews
-All submissions, including submissions by project members, require review. We
-use [GitHub pull requests](https://docs.github.com/articles/about-pull-requests)
-for this purpose.
-If your pull request involves changes to `packages/cli` (the frontend), we
-recommend running our automated frontend review tool. **Note: This tool is
-currently experimental.** It helps detect common React anti-patterns, testing
-issues, and other frontend-specific best practices that are easy to miss.
-To run the review tool, enter the following command from within Gemini CLI:
-```text
-/review-frontend <PR_NUMBER>
-```
-Replace `<PR_NUMBER>` with your pull request number. Authors are encouraged to
-run this on their own PRs for self-review, and reviewers should use it to
-augment their manual review process.
-### Self assigning issues
-To assign an issue to yourself, simply add a comment with the text `/assign`.
-The comment must contain only that text and nothing else. This command will
-assign the issue to you, provided it is not already assigned.
-Please note that you can have a maximum of 3 issues assigned to you at any given
-time.
-### Pull request guidelines
-To help us review and merge your PRs quickly, please follow these guidelines.
-PRs that do not meet these standards may be closed.
-#### 1. Link to an existing issue
-All PRs should be linked to an existing issue in our tracker. This ensures that
-every change has been discussed and is aligned with the project's goals before
-any code is written.
-- **For bug fixes:** The PR should be linked to the bug report issue.
-- **For features:** The PR should be linked to the feature request or proposal
-  issue that has been approved by a maintainer.
-If an issue for your change doesn't exist, we will automatically close your PR
-along with a comment reminding you to associate the PR with an issue. The ideal
-workflow starts with an issue that has been reviewed and approved by a
-maintainer. Please **open the issue first** and wait for feedback before you
-start coding.
-#### 2. Keep it small and focused
-We favor small, atomic PRs that address a single issue or add a single,
-self-contained feature.
-- **Do:** Create a PR that fixes one specific bug or adds one specific feature.
-- **Don't:** Bundle multiple unrelated changes (e.g., a bug fix, a new feature,
-  and a refactor) into a single PR.
-Large changes should be broken down into a series of smaller, logical PRs that
-can be reviewed and merged independently.
-#### 3. Use draft PRs for work in progress
-If you'd like to get early feedback on your work, please use GitHub's **Draft
-Pull Request** feature. This signals to the maintainers that the PR is not yet
-ready for a formal review but is open for discussion and initial feedback.
-#### 4. Ensure all checks pass
-Before submitting your PR, ensure that all automated checks are passing by
-running `npm run preflight`. This command runs all tests, linting, and other
-style checks.
-#### 5. Update documentation
-If your PR introduces a user-facing change (e.g., a new command, a modified
-flag, or a change in behavior), you must also update the relevant documentation
-in the `/docs` directory.
-See more about writing documentation:
-[Documentation contribution process](#documentation-contribution-process).
-#### 6. Write clear commit messages and a good PR description
-Your PR should have a clear, descriptive title and a detailed description of the
-changes. Follow the [Conventional Commits](https://www.conventionalcommits.org/)
-standard for your commit messages.
-- **Good PR title:** `feat(cli): Add --json flag to 'config get' command`
-- **Bad PR title:** `Made some changes`
-In the PR description, explain the "why" behind your changes and link to the
-relevant issue (e.g., `Fixes #123`).
-### Forking
-If you are forking the repository you will be able to run the Build, Test and
-Integration test workflows. However in order to make the integration tests run
-you'll need to add a
-[GitHub Repository Secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository)
-with a value of `GEMINI_API_KEY` and set that to a valid API key that you have
-available. Your key and secret are private to your repo; no one without access
-can see your key and you cannot see any secrets related to this repo.
-Additionally you will need to click on the `Actions` tab and enable workflows
-for your repository, you'll find it's the large blue button in the center of the
-screen.
-### Development setup and workflow
-This section guides contributors on how to build, modify, and understand the
-development setup of this project.
-### Setting up the development environment
-**Prerequisites:**
-1.  **Node.js**:
-    - **Development:** Please use Node.js `~20.19.0`. This specific version is
-      required due to an upstream development dependency issue. You can use a
-      tool like [nvm](https://github.com/nvm-sh/nvm) to manage Node.js versions.
-    - **Production:** For running the CLI in a production environment, any
-      version of Node.js `>=20` is acceptable.
-2.  **Git**
-### Build process
-To clone the repository:
-```bash
-git clone https://github.com/google-gemini/gemini-cli.git # Or your fork's URL
-cd gemini-cli
-```
-To install dependencies defined in `package.json` as well as root dependencies:
-```bash
-npm install
-```
-To build the entire project (all packages):
-```bash
-npm run build
-```
-This command typically compiles TypeScript to JavaScript, bundles assets, and
-prepares the packages for execution. Refer to `scripts/build.js` and
-`package.json` scripts for more details on what happens during the build.
-### Enabling sandboxing
-[Sandboxing](#sandboxing) is highly recommended and requires, at a minimum,
-setting `GEMINI_SANDBOX=true` in your `~/.env` and ensuring a sandboxing
-provider (e.g. `macOS Seatbelt`, `docker`, or `podman`) is available. See
-[Sandboxing](#sandboxing) for details.
-To build both the `gemini` CLI utility and the sandbox container, run
-`build:all` from the root directory:
-```bash
-npm run build:all
-```
-To skip building the sandbox container, you can use `npm run build` instead.
-### Running the CLI
-To start the Gemini CLI from the source code (after building), run the following
-command from the root directory:
-```bash
-npm start
-```
-If you'd like to run the source build outside of the gemini-cli folder, you can
-utilize `npm link path/to/gemini-cli/packages/cli` (see:
-[docs](https://docs.npmjs.com/cli/v9/commands/npm-link)) or
-`alias gemini="node path/to/gemini-cli/packages/cli"` to run with `gemini`
-### Running tests
-This project contains two types of tests: unit tests and integration tests.
-#### Unit tests
-To execute the unit test suite for the project:
-```bash
-npm run test
-```
-This will run tests located in the `packages/core` and `packages/cli`
-directories. Ensure tests pass before submitting any changes. For a more
-comprehensive check, it is recommended to run `npm run preflight`.
-#### Integration tests
-The integration tests are designed to validate the end-to-end functionality of
-the Gemini CLI. They are not run as part of the default `npm run test` command.
-To run the integration tests, use the following command:
-```bash
-npm run test:e2e
-```
-For more detailed information on the integration testing framework, please see
-the [Integration Tests documentation](/docs/integration-tests.md).
-### Linting and preflight checks
-To ensure code quality and formatting consistency, run the preflight check:
-```bash
-npm run preflight
-```
-This command will run ESLint, Prettier, all tests, and other checks as defined
-in the project's `package.json`.
-_ProTip_
-after cloning create a git precommit hook file to ensure your commits are always
-clean.
-```bash
-echo "
-# Run npm build and check for errors
-if ! npm run preflight; then
-  echo "npm build failed. Commit aborted."
-  exit 1
-fi
-" > .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit
-```
-#### Formatting
-To separately format the code in this project by running the following command
-from the root directory:
-```bash
-npm run format
-```
-This command uses Prettier to format the code according to the project's style
-guidelines.
-#### Linting
-To separately lint the code in this project, run the following command from the
-root directory:
-```bash
-npm run lint
-```
-### Coding conventions
-- Please adhere to the coding style, patterns, and conventions used throughout
-  the existing codebase.
-- Consult
-  [GEMINI.md](https://github.com/google-gemini/gemini-cli/blob/main/GEMINI.md)
-  (typically found in the project root) for specific instructions related to
-  AI-assisted development, including conventions for React, comments, and Git
-  usage.
-- **Imports:** Pay special attention to import paths. The project uses ESLint to
-  enforce restrictions on relative imports between packages.
-### Project structure
-- `packages/`: Contains the individual sub-packages of the project.
-  - `a2a-server`: A2A server implementation for the Gemini CLI. (Experimental)
-  - `cli/`: The command-line interface.
-  - `core/`: The core backend logic for the Gemini CLI.
-  - `test-utils` Utilities for creating and cleaning temporary file systems for
-    testing.
-  - `vscode-ide-companion/`: The Gemini CLI Companion extension pairs with
-    Gemini CLI.
-- `docs/`: Contains all project documentation.
-- `scripts/`: Utility scripts for building, testing, and development tasks.
-For more detailed architecture, see `docs/architecture.md`.
-### Debugging
-#### VS Code
-0.  Run the CLI to interactively debug in VS Code with `F5`
-1.  Start the CLI in debug mode from the root directory:
-    ```bash
-    npm run debug
-    ```
-    This command runs `node --inspect-brk dist/gemini.js` within the
-    `packages/cli` directory, pausing execution until a debugger attaches. You
-    can then open `chrome://inspect` in your Chrome browser to connect to the
-    debugger.
-2.  In VS Code, use the "Attach" launch configuration (found in
-    `.vscode/launch.json`).
-Alternatively, you can use the "Launch Program" configuration in VS Code if you
-prefer to launch the currently open file directly, but 'F5' is generally
-recommended.
-To hit a breakpoint inside the sandbox container run:
-```bash
-DEBUG=1 gemini
-```
-**Note:** If you have `DEBUG=true` in a project's `.env` file, it won't affect
-gemini-cli due to automatic exclusion. Use `.gemini/.env` files for gemini-cli
-specific debug settings.
-### React DevTools
-To debug the CLI's React-based UI, you can use React DevTools. Ink, the library
-used for the CLI's interface, is compatible with React DevTools version 4.x.
-1.  **Start the Gemini CLI in development mode:**
-    ```bash
-    DEV=true npm start
-    ```
-2.  **Install and run React DevTools version 4.28.5 (or the latest compatible
-    4.x version):**
-    You can either install it globally:
-    ```bash
-    npm install -g react-devtools@4.28.5
-    react-devtools
-    ```
-    Or run it directly using npx:
-    ```bash
-    npx react-devtools@4.28.5
-    ```
-    Your running CLI application should then connect to React DevTools.
-    ![](/docs/assets/connected_devtools.png)
-### Sandboxing
-#### macOS Seatbelt
-On macOS, `gemini` uses Seatbelt (`sandbox-exec`) under a `permissive-open`
-profile (see `packages/cli/src/utils/sandbox-macos-permissive-open.sb`) that
-restricts writes to the project folder but otherwise allows all other operations
-and outbound network traffic ("open") by default. You can switch to a
-`restrictive-closed` profile (see
-`packages/cli/src/utils/sandbox-macos-restrictive-closed.sb`) that declines all
-operations and outbound network traffic ("closed") by default by setting
-`SEATBELT_PROFILE=restrictive-closed` in your environment or `.env` file.
-Available built-in profiles are `{permissive,restrictive}-{open,closed,proxied}`
-(see below for proxied networking). You can also switch to a custom profile
-`SEATBELT_PROFILE=<profile>` if you also create a file
-`.gemini/sandbox-macos-<profile>.sb` under your project settings directory
-`.gemini`.
-#### Container-based sandboxing (all platforms)
-For stronger container-based sandboxing on macOS or other platforms, you can set
-`GEMINI_SANDBOX=true|docker|podman|<command>` in your environment or `.env`
-file. The specified command (or if `true` then either `docker` or `podman`) must
-be installed on the host machine. Once enabled, `npm run build:all` will build a
-minimal container ("sandbox") image and `npm start` will launch inside a fresh
-instance of that container. The first build can take 20-30s (mostly due to
-downloading of the base image) but after that both build and start overhead
-should be minimal. Default builds (`npm run build`) will not rebuild the
-sandbox.
-Container-based sandboxing mounts the project directory (and system temp
-directory) with read-write access and is started/stopped/removed automatically
-as you start/stop Gemini CLI. Files created within the sandbox should be
-automatically mapped to your user/group on host machine. You can easily specify
-additional mounts, ports, or environment variables by setting
-`SANDBOX_{MOUNTS,PORTS,ENV}` as needed. You can also fully customize the sandbox
-for your projects by creating the files `.gemini/sandbox.Dockerfile` and/or
-`.gemini/sandbox.bashrc` under your project settings directory (`.gemini`) and
-running `gemini` with `BUILD_SANDBOX=1` to trigger building of your custom
-sandbox.
-#### Proxied networking
-All sandboxing methods, including macOS Seatbelt using `*-proxied` profiles,
-support restricting outbound network traffic through a custom proxy server that
-can be specified as `GEMINI_SANDBOX_PROXY_COMMAND=<command>`, where `<command>`
-must start a proxy server that listens on `:::8877` for relevant requests. See
-`docs/examples/proxy-script.md` for a minimal proxy that only allows `HTTPS`
-connections to `example.com:443` (e.g. `curl https://example.com`) and declines
-all other requests. The proxy is started and stopped automatically alongside the
-sandbox.
-### Manual publish
-We publish an artifact for each commit to our internal registry. But if you need
-to manually cut a local build, then run the following commands:
-```
-npm run clean
-npm install
-npm run auth
-npm run prerelease:dev
-npm publish --workspaces
-```
-## Documentation contribution process
-Our documentation must be kept up-to-date with our code contributions. We want
-our documentation to be clear, concise, and helpful to our users. We value:
-- **Clarity:** Use simple and direct language. Avoid jargon where possible.
-- **Accuracy:** Ensure all information is correct and up-to-date.
-- **Completeness:** Cover all aspects of a feature or topic.
-- **Examples:** Provide practical examples to help users understand how to use
-  Gemini CLI.
-### Getting started
-The process for contributing to the documentation is similar to contributing
-code.
-1. **Fork the repository** and create a new branch.
-2. **Make your changes** in the `/docs` directory.
-3. **Preview your changes locally** in Markdown rendering.
-4. **Lint and format your changes.** Our preflight check includes linting and
-   formatting for documentation files.
-   ```bash
-   npm run preflight
-   ```
-5. **Open a pull request** with your changes.
-### Documentation structure
-Our documentation is organized using [sidebar.json](/docs/sidebar.json) as the
-table of contents. When adding new documentation:
-1. Create your markdown file **in the appropriate directory** under `/docs`.
-2. Add an entry to `sidebar.json` in the relevant section.
-3. Ensure all internal links use relative paths and point to existing files.
-### Style guide
-We follow the
-[Google Developer Documentation Style Guide](https://developers.google.com/style).
-Please refer to it for guidance on writing style, tone, and formatting.
-#### Key style points
-- Use sentence case for headings.
-- Write in second person ("you") when addressing the reader.
-- Use present tense.
-- Keep paragraphs short and focused.
-- Use code blocks with appropriate language tags for syntax highlighting.
-- Include practical examples whenever possible.
-### Linting and formatting
-We use `prettier` to enforce a consistent style across our documentation. The
-`npm run preflight` command will check for any linting issues.
-You can also run the linter and formatter separately:
-- `npm run lint` - Check for linting issues
-- `npm run format` - Auto-format markdown files
-- `npm run lint:fix` - Auto-fix linting issues where possible
-Please make sure your contributions are free of linting errors before submitting
-a pull request.
-### Before you submit
-Before submitting your documentation pull request, please:
-1. Run `npm run preflight` to ensure all checks pass.
-2. Review your changes for clarity and accuracy.
-3. Check that all links work correctly.
-4. Ensure any code examples are tested and functional.
-5. Sign the
-   [Contributor License Agreement (CLA)](https://cla.developers.google.com/) if
-   you haven't already.
-### Need help?
-If you have questions about contributing documentation:
-- Check our [FAQ](/docs/faq.md).
-- Review existing documentation for examples.
-- Open [an issue](https://github.com/google-gemini/gemini-cli/issues) to discuss
-  your proposed changes.
-- Reach out to the maintainers.
-We appreciate your contributions to making Gemini CLI documentation better!

package/dist/docs/ai_adapter/01-overview.md DELETED Viewed

@@ -1,155 +0,0 @@
-# 01. 프로젝트 개요
-## 1.1 배경
-Gemini CLI는 Google의 Gemini 모델을 터미널에서 직접 사용할 수 있는 오픈소스 AI 에이전트입니다. 현재는 Gemini API만 지원하지만, 다양한 LLM 프로바이더(Claude, OpenAI GPT, Llama 등)를 지원하면 사용자에게 더 많은 선택권을 제공할 수 있습니다.
-### 1.1.1 현재 지원 인증 방식
-- Google OAuth (개인 계정)
-- Gemini API Key
-- Vertex AI (엔터프라이즈)
-- Google Cloud ADC
-### 1.1.2 확장 필요성
-- 사용자마다 선호하는 LLM 프로바이더가 다름
-- 특정 작업에 최적화된 모델 선택 필요
-- 프로바이더 장애 시 대체 옵션 필요
-- 비용 최적화를 위한 모델 선택 유연성
-## 1.2 목표
-### 주요 목표
-1. **다중 프로바이더 지원**: Gemini, Claude, OpenAI GPT 등 주요 LLM 프로바이더 지원
-2. **어댑터 패턴 도입**: 새로운 프로바이더 추가가 용이한 확장 가능한 구조
-3. **하위 호환성 유지**: 기존 Gemini 사용자에게 영향 없음
-4. **설정 기반 전환**: 환경 변수 또는 설정 파일로 프로바이더 선택
-### 비목표 (Scope 외)
-- 프로바이더별 고유 기능 완전 지원 (1차 버전에서는 공통 기능만)
-- 프로바이더 간 실시간 전환 (세션 시작 시 선택)
-- 비용 추적 및 최적화 기능
-## 1.3 현재 상태 분석
-### 1.3.1 코드베이스 구조
-```
-packages/
-├── cli/                 # 터미널 UI (React/Ink)
-│   └── src/
-│       ├── core/        # 인증, 초기화
-│       └── config/      # 사용자 설정
-│
-└── core/                # 백엔드 로직
-    └── src/
-        ├── core/        # LLM 클라이언트, 콘텐츠 생성
-        ├── tools/       # 파일, 셸, 웹 도구
-        ├── config/      # 모델 설정
-        └── routing/     # 모델 라우팅
-```
-### 1.3.2 핵심 컴포넌트 분석
-| 컴포넌트 | 파일 | 역할 | 라인 수 |
-|----------|------|------|---------|
-| GeminiClient | `core/client.ts` | 세션 관리, 턴 처리, 압축, 훅 | ~1,048 |
-| BaseLlmClient | `core/baseLlmClient.ts` | 상태 없는 API 호출 래퍼 | ~339 |
-| ContentGenerator | `core/contentGenerator.ts` | 콘텐츠 생성 인터페이스 | ~200 |
-| GeminiChat | `core/geminiChat.ts` | 채팅 상태 관리 | ~1000 |
-| ModelRouterService | `routing/modelRouterService.ts` | 모델 라우팅 전략 | ~120 |
-**참고**: `GeminiChat`은 Gemini 전용 응답 처리, 스트리밍, 도구 사용 로직을 포함하고 있어 리팩토링 복잡도가 높습니다.
-### 1.3.3 기존 추상화 수준
-**장점 (Well-designed)**
-- `ContentGenerator` 인터페이스가 핵심 추상화 포인트로 존재
-- 팩토리 패턴으로 구현체 생성
-- 데코레이터 패턴으로 로깅, 레코딩 등 기능 추가 가능
-- 모델 라우팅 서비스가 전략 패턴으로 구현됨
-**단점 (Coupling issues)**
-- `@google/genai` SDK 타입에 직접 의존
-- Gemini 전용 로직이 여러 파일에 분산
-- 모델 기능 플래그가 Gemini 기준으로 하드코딩
-### 1.3.4 의존성 현황
-```json
-{
-  "@google/genai": "1.30.0",
-  "@modelcontextprotocol/sdk": "^1.23.0",
-  "google-auth-library": "^9.11.0"
-}
-```
-## 1.4 기존 ContentGenerator 구현체
-현재 `ContentGenerator` 인터페이스를 구현한 클래스들:
-| 구현체 | 용도 | 설명 |
-|--------|------|------|
-| `GoogleGenAI` | 프로덕션 | Gemini API 직접 호출 |
-| `CodeAssistServer` | 프로덕션 | Google Cloud CodeAssist (OAuth) |
-| `LoggingContentGenerator` | 데코레이터 | 텔레메트리 추가 |
-| `FakeContentGenerator` | 테스트 | 미리 정의된 응답 반환 |
-| `RecordingContentGenerator` | 테스트 | 응답 녹화/재생 |
-## 1.5 식별된 문제점
-### P1: 타입 결합도
-```typescript
-// 현재: @google/genai 타입에 직접 의존
-import { GenerateContentResponse } from '@google/genai';
-// 문제: 다른 프로바이더는 다른 응답 구조를 가짐
-```
-### P2: Gemini 전용 로직 산재
-```typescript
-// packages/core/src/config/models.ts
-export function isGemini2Model(model: string): boolean { ... }
-export function supportsMultimodalFunctionResponse(model: string): boolean { ... }
-// 문제: 다른 프로바이더의 모델 특성 처리 불가
-```
-### P3: 하드코딩된 토큰 제한
-```typescript
-// geminiChat.ts
-const THINKING_TOKEN_CAP = 8192;
-// 문제: 프로바이더/모델별로 다른 제한 필요
-```
-### P4: 인증 방식 제한
-```typescript
-// AuthType이 Google 서비스에 특화됨
-enum AuthType {
-  LOGIN_WITH_GOOGLE = 'oauth-personal',
-  USE_GEMINI = 'gemini-api-key',
-  USE_VERTEX_AI = 'vertex-ai',
-  LEGACY_CLOUD_SHELL = 'cloud-shell',
-  COMPUTE_ADC = 'compute-default-credentials',
-  // Claude, OpenAI 등 없음
-}
-```
-## 1.6 성공 기준
-### 기능적 요구사항
-- [ ] Claude API를 통한 대화 가능
-- [ ] OpenAI GPT API를 통한 대화 가능
-- [ ] 기존 Gemini 기능 100% 동작
-- [ ] 설정 파일로 기본 프로바이더 지정 가능
-- [ ] 환경 변수로 프로바이더 전환 가능
-### 비기능적 요구사항
-- [ ] 새 프로바이더 추가 시 기존 코드 수정 최소화
-- [ ] 기존 테스트 100% 통과
-- [ ] 성능 저하 없음 (응답 지연 < 50ms 증가)
-### 품질 요구사항
-- [ ] 프로바이더별 단위 테스트 커버리지 > 80%
-- [ ] 통합 테스트 시나리오 정의 및 통과
-- [ ] 문서화 완료 (사용자 가이드, 개발자 가이드)