From d7cebbd70f8d7f6b1062219d261159d9af017b37 Mon Sep 17 00:00:00 2001 From: ikjeong Date: Wed, 10 Dec 2025 09:45:03 +0000 Subject: [PATCH] docs: update documentation for category feature --- README.md | 25 +++++ docs/ARCHITECTURE.md | 7 ++ docs/COMMAND.md | 206 ++++++++++++++++++++++++++++++++------ internal/cmd/README.md | 7 +- internal/mcp/README.md | 16 ++- internal/server/README.md | 7 +- npm/README.md | 25 +++++ pkg/schema/README.md | 13 ++- 8 files changed, 271 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index d2104ca..83641b1 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,10 @@ Symphony는 AI 개발환경(IDE, MCP 기반 LLM Tooling)을 위한 정책 기반 - [사용 가능한 MCP 도구](#사용-가능한-mcp-도구) - [`query_conventions`](#query_conventions) - [`validate_code`](#validate_code) + - [`list_category`](#list_category) + - [`add_category`](#add_category) + - [`edit_category`](#edit_category) + - [`remove_category`](#remove_category) - [컨벤션 파일](#컨벤션-파일) - [요구사항](#요구사항) - [지원 플랫폼](#지원-플랫폼) @@ -29,6 +33,7 @@ Symphony는 AI 개발환경(IDE, MCP 기반 LLM Tooling)을 위한 정책 기반 - 자연어로 컨벤션 정의 - LLM이 MCP를 통해 필요한 컨벤션만 추출하여 컨텍스트에 포함 - LLM이 MCP를 통해 코드 변경사항에 대한 컨벤션 준수 여부를 검사 +- 카테고리 기반 규칙 분류 및 관리 - RBAC 기반 접근 제어 --- @@ -80,6 +85,26 @@ sym dashboard - 코드가 정의된 규칙을 따르는지 검사합니다. - 필수 파라미터: `files` +### `list_category` + +- 프로젝트에 정의된 카테고리 목록을 조회합니다. +- 파라미터 없음 + +### `add_category` + +- 새 카테고리를 추가합니다 (배치 지원). +- 필수 파라미터: `categories` (배열) + +### `edit_category` + +- 기존 카테고리를 편집합니다 (배치 지원). +- 필수 파라미터: `edits` (배열) + +### `remove_category` + +- 카테고리를 삭제합니다 (배치 지원). +- 필수 파라미터: `names` (배열) + --- ## 컨벤션 파일 diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index aa811c7..165441c 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -141,6 +141,9 @@ AI 코딩 도구(Claude Code, Cursor 등)와 stdio를 통해 통신합니다. | `query_conventions` | 프로젝트 컨벤션 조회 | | `validate_code` | 코드 변경사항 검증 | | `list_category` | 카테고리 목록 조회 | +| `add_category` | 카테고리 추가 (배치 지원) | +| `edit_category` | 카테고리 편집 (배치 지원) | +| `remove_category` | 카테고리 삭제 (배치 지원) | #### HTTP Server (`internal/server`) @@ -152,6 +155,10 @@ AI 코딩 도구(Claude Code, Cursor 등)와 stdio를 통해 통신합니다. | `POST /api/policy` | 정책 저장 | | `GET /api/roles` | 역할 목록 조회 | | `POST /api/select-role` | 역할 선택 | +| `GET /api/categories` | 카테고리 목록 조회 | +| `POST /api/categories` | 카테고리 추가 | +| `PUT /api/categories/{name}` | 카테고리 편집 | +| `DELETE /api/categories/{name}` | 카테고리 삭제 | ### Layer 3: Core diff --git a/docs/COMMAND.md b/docs/COMMAND.md index 99891e5..f151dbb 100644 --- a/docs/COMMAND.md +++ b/docs/COMMAND.md @@ -41,6 +41,9 @@ Symphony (`sym`)는 코드 컨벤션 관리와 RBAC(역할 기반 접근 제어) - [query\_conventions](#query_conventions) - [validate\_code](#validate_code) - [list\_category](#list_category) + - [add\_category](#add_category) + - [edit\_category](#edit_category) + - [remove\_category](#remove_category) - [등록 방법](#등록-방법) - [LLM 프로바이더](#llm-프로바이더) - [지원 프로바이더](#지원-프로바이더) @@ -372,19 +375,27 @@ sym validate --timeout 60 ### sym category -**설명**: 사용 가능한 모든 컨벤션 카테고리와 설명을 표시합니다. +**설명**: 컨벤션 카테고리를 관리합니다. -user-policy.json에 정의된 카테고리를 표시합니다. `sym init` 실행 시 7개의 기본 카테고리(security, style, documentation, error_handling, architecture, performance, testing)가 생성됩니다. 사용자는 이 카테고리를 수정, 삭제하거나 새로운 카테고리를 추가할 수 있습니다. +user-policy.json에 정의된 카테고리를 조회, 추가, 편집, 삭제할 수 있습니다. `sym init` 실행 시 7개의 기본 카테고리(security, style, documentation, error_handling, architecture, performance, testing)가 생성됩니다. + +**서브커맨드**: +- `list` - 카테고리 목록 조회 +- `add` - 새 카테고리 추가 +- `edit` - 기존 카테고리 편집 +- `remove` - 카테고리 삭제 + +**관련 파일**: `internal/cmd/category.go` + +--- + +#### sym category list + +**설명**: 모든 카테고리와 설명을 표시합니다. **문법**: ``` -sym category -``` - -**예시**: -```bash -# 카테고리 목록 조회 -sym category +sym category list ``` **출력 예시**: @@ -399,36 +410,115 @@ sym category • documentation Documentation rules (comments, docstrings, etc.) +``` - • error_handling - Error handling and exception management rules +--- - • architecture - Code structure and architecture rules +#### sym category add - • performance - Performance optimization rules +**설명**: 새 카테고리를 추가합니다. - • testing - Testing rules (coverage, test patterns, etc.) +**문법**: +``` +sym category add +sym category add -f ``` -**사용자 정의 카테고리**: +**플래그**: +- `-f, --file` - 배치 추가를 위한 JSON 파일 -user-policy.json에 `category` 필드를 추가하여 사용자 정의 카테고리를 추가하거나 기존 카테고리 설명을 변경할 수 있습니다: +**예시**: +```bash +# 단일 추가 +sym category add accessibility "Accessibility rules (WCAG, ARIA, etc.)" + +# 배치 추가 +sym category add -f categories.json +``` +**배치 파일 형식** (`categories.json`): ```json -{ - "version": "1.0", - "category": [ - {"name": "security", "description": "보안 관련 규칙 (인증, 인가, 취약점 방지 등)"}, - {"name": "naming", "description": "네이밍 컨벤션 규칙 (변수, 함수, 클래스 등)"} - ], - "rules": [...] -} +[ + {"name": "security", "description": "Security rules"}, + {"name": "performance", "description": "Performance rules"} +] ``` -**관련 파일**: `internal/cmd/category.go` +--- + +#### sym category edit + +**설명**: 기존 카테고리의 이름 또는 설명을 변경합니다. + +**문법**: +``` +sym category edit [--name ] [--description ] +sym category edit -f +``` + +**플래그**: +- `--name` - 새 카테고리 이름 +- `--description` - 새 설명 +- `-f, --file` - 배치 편집을 위한 JSON 파일 + +**예시**: +```bash +# 설명만 변경 +sym category edit security --description "Updated security rules" + +# 이름 변경 (관련 규칙도 자동 업데이트) +sym category edit old-name --name new-name + +# 이름과 설명 모두 변경 +sym category edit security --name sec --description "Security conventions" + +# 배치 편집 +sym category edit -f edits.json +``` + +**배치 파일 형식** (`edits.json`): +```json +[ + {"name": "security", "new_name": "sec"}, + {"name": "performance", "description": "New description"} +] +``` + +**참고**: 카테고리 이름 변경 시 해당 카테고리를 참조하는 모든 규칙이 자동으로 업데이트됩니다. + +--- + +#### sym category remove + +**설명**: 카테고리를 삭제합니다. + +**문법**: +``` +sym category remove [names...] +sym category remove -f +``` + +**플래그**: +- `-f, --file` - 삭제할 카테고리 이름이 담긴 JSON 파일 + +**예시**: +```bash +# 단일 삭제 +sym category remove deprecated-category + +# 다중 삭제 +sym category remove cat1 cat2 cat3 + +# 배치 삭제 +sym category remove -f names.json +``` + +**배치 파일 형식** (`names.json`): +```json +["cat1", "cat2", "cat3"] +``` + +**참고**: 규칙이 참조하고 있는 카테고리는 삭제할 수 없습니다. 먼저 해당 규칙을 삭제하거나 다른 카테고리로 변경해야 합니다. --- @@ -440,6 +530,9 @@ user-policy.json에 `category` 필드를 추가하여 사용자 정의 카테고 - `query_conventions`: 주어진 컨텍스트에 대한 컨벤션 쿼리 - `validate_code`: 코드의 컨벤션 준수 여부 검증 - `list_category`: 사용 가능한 카테고리 목록 조회 +- `add_category`: 카테고리 추가 (배치 지원) +- `edit_category`: 카테고리 편집 (배치 지원) +- `remove_category`: 카테고리 삭제 (배치 지원) **통신 방식**: stdio (Claude Desktop, Claude Code, Cursor 등 MCP 클라이언트와 통합) @@ -726,6 +819,63 @@ Available categories (7): Use query_conventions with a specific category to get rules for that category. ``` +#### add_category + +카테고리를 추가합니다 (배치 모드). + +**입력 스키마**: + +| 파라미터 | 타입 | 필수 | 설명 | +|----------|------|------|------| +| `categories` | array | 예 | `{name, description}` 객체 배열 | + +**예시**: +```json +{ + "categories": [ + {"name": "accessibility", "description": "Accessibility rules (WCAG, ARIA)"}, + {"name": "i18n", "description": "Internationalization rules"} + ] +} +``` + +#### edit_category + +카테고리를 편집합니다 (배치 모드). 이름 변경 시 규칙 참조도 자동 업데이트됩니다. + +**입력 스키마**: + +| 파라미터 | 타입 | 필수 | 설명 | +|----------|------|------|------| +| `edits` | array | 예 | `{name, new_name?, description?}` 객체 배열 | + +**예시**: +```json +{ + "edits": [ + {"name": "security", "description": "Updated security rules"}, + {"name": "style", "new_name": "formatting"} + ] +} +``` + +#### remove_category + +카테고리를 삭제합니다 (배치 모드). 규칙이 참조하는 카테고리는 삭제할 수 없습니다. + +**입력 스키마**: + +| 파라미터 | 타입 | 필수 | 설명 | +|----------|------|------|------| +| `names` | array | 예 | 삭제할 카테고리 이름 배열 | + +**예시**: +```json +{ + "names": ["deprecated-category", "unused-category"] +} +``` + ### 등록 방법 ```bash diff --git a/internal/cmd/README.md b/internal/cmd/README.md index 1c82baf..8d94c40 100644 --- a/internal/cmd/README.md +++ b/internal/cmd/README.md @@ -20,7 +20,7 @@ cmd/ ├── llm.go # sym llm status|test|setup 명령어 (LLM 관리) ├── mcp.go # sym mcp 명령어 (MCP 서버) ├── mcp_register.go # MCP 서버 등록 헬퍼 함수 -├── category.go # sym category 명령어 (카테고리 목록) +├── category.go # sym category list|add|edit|remove 명령어 (카테고리 관리) ├── survey_templates.go # 커스텀 survey UI 템플릿 └── README.md ``` @@ -102,7 +102,10 @@ cmd/ | `runLLMTest(cmd, args)` | llm.go:107 | llm test 실행 | | `runLLMSetup(cmd, args)` | llm.go:142 | llm setup 실행 | | `runMCP(cmd, args)` | mcp.go:37 | mcp 실행 | -| `runCategory(cmd, args)` | category.go:27 | category 실행 | +| `runCategoryList(cmd, args)` | category.go:138 | category list 실행 | +| `runCategoryAdd(cmd, args)` | category.go:165 | category add 실행 | +| `runCategoryEdit(cmd, args)` | category.go:240 | category edit 실행 | +| `runCategoryRemove(cmd, args)` | category.go:353 | category remove 실행 | #### 헬퍼 함수 - 초기화 diff --git a/internal/mcp/README.md b/internal/mcp/README.md index 739f728..36d0fa2 100644 --- a/internal/mcp/README.md +++ b/internal/mcp/README.md @@ -53,8 +53,13 @@ mcp/ | `RPCError` | server.go:184 | JSON-RPC 에러 타입 | | `QueryConventionsInput` | server.go:190 | query_conventions 입력 스키마 | | `ValidateCodeInput` | server.go:196 | validate_code 입력 스키마 | -| `ListCategoryInput` | server.go:202 | list_category 입력 스키마 | -| `QueryConventionsRequest` | server.go:244 | 컨벤션 조회 요청 | +| `ListCategoryInput` | server.go:201 | list_category 입력 스키마 | +| `CategoryItem` | server.go:206 | 카테고리 항목 (배치용) | +| `CategoryEditItem` | server.go:212 | 카테고리 편집 항목 (배치용) | +| `AddCategoryInput` | server.go:225 | add_category 입력 스키마 | +| `EditCategoryInput` | server.go:230 | edit_category 입력 스키마 | +| `RemoveCategoryInput` | server.go:235 | remove_category 입력 스키마 | +| `QueryConventionsRequest` | server.go:330 | 컨벤션 조회 요청 | | `ConventionItem` | server.go:250 | 컨벤션 항목 | | `ValidateCodeRequest` | server.go:411 | 검증 요청 | | `ViolationItem` | server.go:416 | 위반 항목 | @@ -90,8 +95,13 @@ mcp/ | `convertUserPolicy(userPath, codePath)` | 정책 변환 래퍼 | | `getRBACInfo()` | RBAC 정보 생성 | | `saveValidationResults(result, violations, hasErrors)` | 검증 결과 저장 | +| `handleListCategory()` | 카테고리 목록 핸들러 | +| `handleAddCategory(input)` | 카테고리 추가 핸들러 | +| `handleEditCategory(input)` | 카테고리 편집 핸들러 | +| `handleRemoveCategory(input)` | 카테고리 삭제 핸들러 | +| `saveUserPolicy()` | 정책 파일 저장 | ## 참고 문헌 -- [MCP 도구 스키마](../../docs/COMMAND.md#mcp-도구-스키마) - query_conventions, validate_code, list_category 입력/출력 스펙 +- [MCP 도구 스키마](../../docs/COMMAND.md#mcp-도구-스키마) - query_conventions, validate_code, list_category, add_category, edit_category, remove_category 입력/출력 스펙 - [MCP 통합 가이드](../../docs/COMMAND.md#mcp-통합) - 지원 도구 및 등록 방법 diff --git a/internal/server/README.md b/internal/server/README.md index 2691b8b..9ff40e8 100644 --- a/internal/server/README.md +++ b/internal/server/README.md @@ -67,7 +67,7 @@ type Server struct { - `hasPermissionForRoleWithPolicy(role, permission string, policy *schema.UserPolicy) (bool, error)` - 제공된 정책으로 권한 확인 - `checkPermissionForRole(userRole, permission string, policy *schema.UserPolicy) (bool, error)` - 권한 검사 핵심 로직 -**HTTP 핸들러 (14개):** +**HTTP 핸들러 (19개):** | 핸들러 | 라우트 | 설명 | |--------|--------|------| @@ -87,6 +87,11 @@ type Server struct { | handlePolicyTemplateDetail | GET /api/policy/templates/{name} | 특정 템플릿 상세 | | handleUsers | GET /api/users | 모든 사용자 목록 | | handleConvert | POST /api/policy/convert | 정책 변환 실행 | +| handleCategories | /api/categories | GET/POST/PUT/DELETE 라우터 | +| handleGetCategories | GET /api/categories | 카테고리 목록 조회 | +| handleAddCategory | POST /api/categories | 카테고리 추가 | +| handleEditCategory | PUT /api/categories/{name} | 카테고리 편집 | +| handleDeleteCategory | DELETE /api/categories/{name} | 카테고리 삭제 | ## 참고 문헌 diff --git a/npm/README.md b/npm/README.md index d2104ca..83641b1 100644 --- a/npm/README.md +++ b/npm/README.md @@ -17,6 +17,10 @@ Symphony는 AI 개발환경(IDE, MCP 기반 LLM Tooling)을 위한 정책 기반 - [사용 가능한 MCP 도구](#사용-가능한-mcp-도구) - [`query_conventions`](#query_conventions) - [`validate_code`](#validate_code) + - [`list_category`](#list_category) + - [`add_category`](#add_category) + - [`edit_category`](#edit_category) + - [`remove_category`](#remove_category) - [컨벤션 파일](#컨벤션-파일) - [요구사항](#요구사항) - [지원 플랫폼](#지원-플랫폼) @@ -29,6 +33,7 @@ Symphony는 AI 개발환경(IDE, MCP 기반 LLM Tooling)을 위한 정책 기반 - 자연어로 컨벤션 정의 - LLM이 MCP를 통해 필요한 컨벤션만 추출하여 컨텍스트에 포함 - LLM이 MCP를 통해 코드 변경사항에 대한 컨벤션 준수 여부를 검사 +- 카테고리 기반 규칙 분류 및 관리 - RBAC 기반 접근 제어 --- @@ -80,6 +85,26 @@ sym dashboard - 코드가 정의된 규칙을 따르는지 검사합니다. - 필수 파라미터: `files` +### `list_category` + +- 프로젝트에 정의된 카테고리 목록을 조회합니다. +- 파라미터 없음 + +### `add_category` + +- 새 카테고리를 추가합니다 (배치 지원). +- 필수 파라미터: `categories` (배열) + +### `edit_category` + +- 기존 카테고리를 편집합니다 (배치 지원). +- 필수 파라미터: `edits` (배열) + +### `remove_category` + +- 카테고리를 삭제합니다 (배치 지원). +- 필수 파라미터: `names` (배열) + --- ## 컨벤션 파일 diff --git a/pkg/schema/README.md b/pkg/schema/README.md index 3f4f0f3..ad5f658 100644 --- a/pkg/schema/README.md +++ b/pkg/schema/README.md @@ -62,7 +62,7 @@ pkg/schema/ ### CategoryDef -카테고리 정의 구조체입니다. +카테고리 정의 구조체입니다. 규칙을 관심 영역별로 분류하여 조직화합니다. ```go type CategoryDef struct { @@ -71,6 +71,17 @@ type CategoryDef struct { } ``` +**기본 카테고리** (`sym init` 실행 시 생성): +- `security` - 보안 규칙 (인증, 인가, 취약점 방지) +- `style` - 코드 스타일 및 포맷팅 규칙 +- `documentation` - 문서화 규칙 (주석, docstring) +- `error_handling` - 에러 처리 및 예외 관리 +- `architecture` - 코드 구조 및 아키텍처 규칙 +- `performance` - 성능 최적화 규칙 +- `testing` - 테스팅 규칙 (커버리지, 테스트 패턴) + +**관리 명령어**: `sym category list|add|edit|remove` + ### UserPolicy 메인 정책 구조체입니다.