diff --git a/ko/.github/FUNDING.yml b/ko/.github/FUNDING.yml new file mode 100644 index 00000000..4d12c5e4 --- /dev/null +++ b/ko/.github/FUNDING.yml @@ -0,0 +1,3 @@ +# These are supported funding model platforms +github: [luongnv89] # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2] +buy_me_a_coffee: luongnv89 # Replace with a single Buy Me a Coffee username diff --git a/ko/.github/ISSUE_TEMPLATE/bug_report.md b/ko/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 00000000..e7d288f5 --- /dev/null +++ b/ko/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,43 @@ +--- +name: Bug Report +about: Report an issue with an example, guide, or documentation +title: "[BUG] " +labels: bug +assignees: '' + +--- + +## Description +Brief description of the issue. + +## Steps to Reproduce +1. Step 1 +2. Step 2 +3. Step 3 + +## Expected Behavior +What should happen? + +## Actual Behavior +What actually happened? + +## Environment +- **Claude Code Version**: (e.g., 1.0.5) +- **Operating System**: (e.g., macOS 14.1, Ubuntu 22.04, Windows 11) +- **Python Version**: (if relevant, e.g., 3.11) +- **Affected Component**: (e.g., 01-slash-commands, 03-skills, etc.) + +## Example Code +If applicable, provide the example code that's not working: +``` +[Insert code here] +``` + +## Screenshots +If applicable, add screenshots showing the issue. + +## Additional Context +Any other context that might help us understand the issue? + +## Possible Solution +If you have a suggestion for fixing this, share it here. diff --git a/ko/.github/ISSUE_TEMPLATE/config.yml b/ko/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..54941052 --- /dev/null +++ b/ko/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: false +contact_links: + - name: Claude Code Documentation + url: https://code.claude.com/docs/en/overview + about: Official Claude Code documentation + - name: Discussions + url: https://github.com/luongnv89/claude-howto/discussions + about: Ask questions and share ideas with the community + - name: Anthropic Cookbook + url: https://github.com/anthropics/anthropic-cookbook + about: Official examples and guides from Anthropic diff --git a/ko/.github/ISSUE_TEMPLATE/documentation.md b/ko/.github/ISSUE_TEMPLATE/documentation.md new file mode 100644 index 00000000..925db2e7 --- /dev/null +++ b/ko/.github/ISSUE_TEMPLATE/documentation.md @@ -0,0 +1,44 @@ +--- +name: Documentation Issue +about: Report unclear documentation, typos, or missing information +title: "[DOCS] " +labels: documentation +assignees: '' + +--- + +## Type of Issue +- [ ] Typo or grammar error +- [ ] Unclear explanation +- [ ] Missing information +- [ ] Broken link or reference +- [ ] Outdated content +- [ ] Better example needed + +## Location +Which section has the issue? +- **File**: (e.g., README.md, 03-skills/README.md) +- **Section**: (e.g., "Installation Quick Reference") +- **Line/Area**: (if specific) + +## Current Content +What does it currently say? +``` +[Paste the current text here] +``` + +## Issue Description +What's wrong with it? + +## Suggested Improvement +How could this be improved or clarified? +``` +[Provide improved text or suggestion here] +``` + +## Why This Matters +How does this issue impact users? + +## Related Documentation +Links to related sections: +- Related Guide: diff --git a/ko/.github/ISSUE_TEMPLATE/feature_request.md b/ko/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 00000000..8cee1a42 --- /dev/null +++ b/ko/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,46 @@ +--- +name: Feature Request +about: Suggest a new example, guide, or improvement +title: "[FEATURE] " +labels: enhancement +assignees: '' + +--- + +## Description +Describe the feature or improvement you'd like to see. + +## Problem It Solves +What problem or gap does this address? + +Examples: +- There's no example of X feature +- The current documentation for Y is unclear +- We need a guide for Z use case +- The structure could be improved by... + +## Use Case +When and how would this be used? Include real-world scenarios. + +## Proposed Solution +How should this be implemented or documented? + +## Example +If applicable, provide an example of what you envision: +``` +[Insert example here] +``` + +## Related Examples +Link any existing related examples or guides: +- Existing Guide: +- Feature: (e.g., Skills, Hooks, Subagents) + +## Additional Context +Any other information that might be helpful? + +## Acceptance Criteria +How would you know this feature is complete? +- [ ] Criterion 1 +- [ ] Criterion 2 +- [ ] Criterion 3 diff --git a/ko/.github/ISSUE_TEMPLATE/question.md b/ko/.github/ISSUE_TEMPLATE/question.md new file mode 100644 index 00000000..ad5d99d3 --- /dev/null +++ b/ko/.github/ISSUE_TEMPLATE/question.md @@ -0,0 +1,40 @@ +--- +name: Question +about: Ask a question about Claude Code or this guide +title: "[QUESTION] " +labels: question +assignees: '' + +--- + +## Question +What would you like to know? + +## Context +Provide some background or context for your question: +- What are you trying to do? +- What have you already tried? +- What examples or guides have you looked at? + +## Relevant Topic +Which topic is this related to? +- [ ] Slash Commands +- [ ] Memory +- [ ] Skills +- [ ] Subagents +- [ ] MCP Protocol +- [ ] Hooks +- [ ] Plugins +- [ ] Checkpoints +- [ ] Advanced Features +- [ ] CLI Reference +- [ ] Other + +## What You've Tried +Have you already tried anything? What was the result? + +## Expected Outcome +What would help you solve this? + +## Additional Resources +Any links or resources that might be relevant? diff --git a/ko/.github/SECURITY_REPORTING.md b/ko/.github/SECURITY_REPORTING.md new file mode 100644 index 00000000..69721a88 --- /dev/null +++ b/ko/.github/SECURITY_REPORTING.md @@ -0,0 +1,309 @@ +# Security Vulnerability Reporting + +This file explains how to report security vulnerabilities to the Claude How To project. + +## Quick Links + +- **Private Reporting**: https://github.com/luongnv89/claude-howto/security/advisories +- **Security Policy**: [SECURITY.md](../SECURITY.md) +- **Report Template**: See below + +## Report a Vulnerability + +### Option 1: GitHub Private Vulnerability Report (RECOMMENDED) + +This is the preferred method for reporting security vulnerabilities. + +**Steps:** +1. Go to: https://github.com/luongnv89/claude-howto/security/advisories +2. Click "Report a vulnerability" +3. Fill in the details (use template below) +4. Submit + +**Advantages:** +- Keeps vulnerability private until fix is released +- Automatic notifications to maintainers +- Built-in collaboration features +- Integrated with GitHub security tools + +### Option 2: GitHub Security Alert (For Dependencies) + +If you discover a vulnerability in a dependency: + +1. Go to: https://github.com/luongnv89/claude-howto/security/advisories +2. Review the alert +3. Create a pull request with the fix +4. Tag with `security` label + +### Option 3: Private Email (If GitHub unavailable) + +If you cannot use GitHub's reporting system: + +**Coming soon**: Security contact email will be added here + +For now, use GitHub's private vulnerability reporting as described above. + +## Vulnerability Report Template + +Use this template when reporting a vulnerability: + +``` +**Title**: [Brief description of vulnerability] + +**Severity**: [Critical/High/Medium/Low] +Estimated CVSS Score: [0-10] + +**Type**: [Code/Documentation/Dependency/Configuration] + +**Affected Component**: +- File: [path/to/file.py] +- Section: [Section name if documentation] +- Version: [latest/specific version] + +**Description**: +[Clear explanation of what the vulnerability is] + +**Potential Impact**: +[What could an attacker do with this vulnerability?] +[Who could be affected?] + +**Steps to Reproduce**: +1. [First step] +2. [Second step] +3. [Third step] +[Expected result vs actual result] + +**Proof of Concept** (if available): +[Code or steps to demonstrate the vulnerability] + +**Suggested Fix**: +[Your recommended solution, if you have one] + +**Additional Context**: +[Any other relevant information] + +**Your Information**: +- Name: [Your name or anonymous] +- Email: [Your email] +- Credit: [How you'd like to be credited, if at all] +``` + +## What Happens After You Report + +### Timeline + +1. **Immediate (< 1 hour)** + - Automatic notification sent to project maintainers + +2. **Within 24 hours** + - Initial assessment of the report + - Confirmation that we received it + - Preliminary severity assessment + +3. **Within 48 hours** + - Detailed response from security team + - Questions for clarification (if needed) + - Timeline for fix (if vulnerability confirmed) + +4. **Within 1-7 days** (depends on severity) + - Fix developed and tested + - Security advisory prepared + - Fix released and public advisory published + +### Communication + +We will keep you informed through: +- GitHub private vulnerability discussion +- Email (if provided) +- Updates in the discussion thread + +You can: +- Ask clarifying questions +- Provide additional information +- Suggest improvements to the fix +- Request timeline adjustments + +### Disclosure Timeline + +**Critical Issues (CVSS 9.0-10.0)** +- Fix: Released immediately (within 24 hours) +- Disclosure: Public advisory issued same day +- Notice: 24 hours advance notice to reporter + +**High Issues (CVSS 7.0-8.9)** +- Fix: Released within 48-72 hours +- Disclosure: Public advisory on release +- Notice: 5 days advance notice to reporter + +**Medium Issues (CVSS 4.0-6.9)** +- Fix: Included in next regular update +- Disclosure: Public advisory on release +- Notice: Coordinated timing + +**Low Issues (CVSS 0.1-3.9)** +- Fix: Included in next regular update +- Disclosure: Advisory on release +- Notice: Same day as release + +## Security Vulnerability Criteria + +### In Scope + +We accept reports on: + +- **Code Vulnerabilities** + - Injection attacks (command, SQL, etc.) + - Cross-site scripting (XSS) in examples + - Authentication/authorization flaws + - Path traversal vulnerabilities + - Cryptography issues + +- **Documentation Security** + - Exposed secrets or credentials + - Insecure code patterns + - Security anti-patterns + - Misleading security claims + +- **Dependency Vulnerabilities** + - Known CVEs in dependencies + - Supply chain attacks + - Malicious dependencies + +- **Configuration Issues** + - Insecure defaults + - Missing security headers + - Credential exposure in examples + +### Out of Scope + +We do NOT accept reports on: + +- Vulnerabilities in Claude Code itself (contact Anthropic) +- Vulnerabilities in external services +- Theoretical vulnerabilities without proof +- Issues already reported to upstream projects +- Social engineering or phishing +- User education/training issues + +## Responsible Disclosure Guidelines + +### Do's โœ… + +- **Report privately** before public disclosure +- **Be specific** with file paths and line numbers +- **Provide proof** of the vulnerability +- **Give us time** to fix (coordinated disclosure) +- **Update** if you discover more details +- **Be professional** in all communications +- **Respect confidentiality** until we publish + +### Don'ts โŒ + +- **Don't publicly disclose** before we fix +- **Don't exploit** the vulnerability beyond testing +- **Don't modify** other users' data +- **Don't demand** payment or favors +- **Don't share** the vulnerability with others +- **Don't use** it in any harmful way +- **Don't spam** with non-security related issues + +## Coordinated Disclosure + +We practice responsible disclosure: + +1. **Private Report**: You report to us privately +2. **Our Assessment**: We evaluate and assess severity +3. **Fix Development**: We develop and test a fix +4. **Advance Notice**: We give you advance notice before public disclosure +5. **Public Release**: We release fix and advisory together +6. **Your Credit**: We acknowledge your contribution (if desired) + +**Timeline varies based on severity** (see section above) + +## After the Fix is Released + +### Public Advisory + +A public security advisory will include: +- Description of the vulnerability +- Affected versions +- Severity (CVSS score) +- Steps to remediate +- Link to the fix +- Credit to reporter (with permission) + +### Your Recognition + +If you wish to be credited: +- Your name/handle in the advisory +- Link to your profile/website +- Mention in release notes +- Addition to hall of fame (if created) + +### No Compensation + +Please note: +- This is a volunteer-run open-source project +- We cannot offer financial rewards +- We do offer recognition and credit +- Your contribution helps the community + +## Security Research + +If you're conducting security research: + +1. **Get Permission**: Contact maintainers first +2. **Define Scope**: Agree on what you'll test +3. **Report Findings**: Use this process +4. **Respect Timeline**: Allow time for fixes +5. **Publish Responsibly**: Coordinate with us + +## Questions? + +For questions about this process: + +1. Check [SECURITY.md](../SECURITY.md) for detailed policy +2. Look at [FAQ](#faq) section below +3. Open a discussion with `[SECURITY]` label +4. Use private vulnerability reporting for sensitive questions + +## FAQ + +**Q: Will my report be kept confidential?** +A: Yes, until the fix is released. We only share details with those working on the fix. + +**Q: How long do I need to wait before public disclosure?** +A: We follow responsible disclosure timelines based on severity (24 hours to 7 days). You can agree to extend this if needed. + +**Q: Will I get credit?** +A: Yes, in the security advisory and release notes (unless you prefer anonymity). + +**Q: What if the vulnerability is minor?** +A: All legitimate security issues are taken seriously. Even minor fixes will be acknowledged. + +**Q: Can I report vulnerabilities in documentation only?** +A: Yes! Documentation security is important too. Examples with insecure patterns are in scope. + +**Q: What if I'm not sure if something is a security issue?** +A: Report it anyway! If it's not a security issue, we'll let you know. False positives are fine. + +**Q: Can I publicly discuss the vulnerability after reporting?** +A: No, please keep it private until we publish the advisory. Premature disclosure could put users at risk. + +**Q: How do I know you received my report?** +A: GitHub will send an automatic notification, and we'll follow up within 24 hours. + +**Q: What if I don't hear back?** +A: Check GitHub security advisories page. If you still don't see a response, you can follow up with a comment on the private report. + +## Resources + +- [SECURITY.md](../SECURITY.md) - Full security policy +- [CONTRIBUTING.md](../CONTRIBUTING.md) - Contributing guidelines +- [CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md) - Community standards +- [OWASP Vulnerability Disclosure](https://cheatsheetseries.owasp.org/cheatsheets/Vulnerability_Disclosure_Cheat_Sheet.html) - Responsible disclosure best practices +- [Coordinated Vulnerability Disclosure](https://cheatsheetseries.owasp.org/cheatsheets/Vulnerable_Dependency_Management_Cheat_Sheet.html) + +--- + +Thank you for helping keep this project secure! ๐Ÿ”’ diff --git a/ko/.github/TESTING.md b/ko/.github/TESTING.md new file mode 100644 index 00000000..b6783644 --- /dev/null +++ b/ko/.github/TESTING.md @@ -0,0 +1,341 @@ +# Testing Guide + +This document describes the testing infrastructure for Claude How To. + +## Overview + +The project uses GitHub Actions to automatically run tests on every push and pull request. Tests cover: + +- **Unit Tests**: Python tests using pytest +- **Code Quality**: Linting and formatting with Ruff +- **Security**: Vulnerability scanning with Bandit +- **Type Checking**: Static type analysis with mypy +- **Build Verification**: EPUB generation test + +## Running Tests Locally + +### Prerequisites + +```bash +# Install uv (fast Python package manager) +pip install uv + +# Or on macOS with Homebrew +brew install uv +``` + +### Setup Environment + +```bash +# Clone the repository +git clone https://github.com/luongnv89/claude-howto.git +cd claude-howto + +# Create virtual environment +uv venv + +# Activate it +source .venv/bin/activate # macOS/Linux +# or +.venv\Scripts\activate # Windows + +# Install development dependencies +uv pip install -r requirements-dev.txt +``` + +### Run Tests + +```bash +# Run all unit tests +pytest scripts/tests/ -v + +# Run tests with coverage +pytest scripts/tests/ -v --cov=scripts --cov-report=html + +# Run specific test file +pytest scripts/tests/test_build_epub.py -v + +# Run specific test function +pytest scripts/tests/test_build_epub.py::test_function_name -v + +# Run tests in watch mode (requires pytest-watch) +ptw scripts/tests/ +``` + +### Run Linting + +```bash +# Check code formatting +ruff format --check scripts/ + +# Auto-fix formatting issues +ruff format scripts/ + +# Run linter +ruff check scripts/ + +# Auto-fix linter issues +ruff check --fix scripts/ +``` + +### Run Security Scan + +```bash +# Run Bandit security scan +bandit -c pyproject.toml -r scripts/ --exclude scripts/tests/ + +# Generate JSON report +bandit -c pyproject.toml -r scripts/ --exclude scripts/tests/ -f json -o bandit-report.json +``` + +### Run Type Checking + +```bash +# Check types with mypy +mypy scripts/ --ignore-missing-imports --no-implicit-optional +``` + +## GitHub Actions Workflow + +### Triggered On + +- **Push** to `main` or `develop` branches (when scripts change) +- **Pull Request** to `main` (when scripts change) +- Manual workflow dispatch + +### Jobs + +#### 1. Unit Tests (pytest) + +- **Runs on**: Ubuntu latest +- **Python versions**: 3.10, 3.11, 3.12 +- **What it does**: + - Installs dependencies from `requirements-dev.txt` + - Runs pytest with coverage reporting + - Uploads coverage to Codecov + - Archives test results and coverage HTML + +**Outcome**: If any test fails, the workflow fails (critical) + +#### 2. Code Quality (Ruff) + +- **Runs on**: Ubuntu latest +- **Python version**: 3.11 +- **What it does**: + - Checks code formatting with `ruff format` + - Runs linter with `ruff check` + - Reports issues but doesn't fail the workflow + +**Outcome**: Non-blocking (warning only) + +#### 3. Security Scan (Bandit) + +- **Runs on**: Ubuntu latest +- **Python version**: 3.11 +- **What it does**: + - Scans for security vulnerabilities + - Generates JSON report + - Uploads report as artifact + +**Outcome**: Non-blocking (warning only) + +#### 4. Type Checking (mypy) + +- **Runs on**: Ubuntu latest +- **Python version**: 3.11 +- **What it does**: + - Performs static type analysis + - Reports type mismatches + - Helps catch bugs early + +**Outcome**: Non-blocking (warning only) + +#### 5. Build EPUB + +- **Runs on**: Ubuntu latest +- **Depends on**: pytest, lint, security (all must pass) +- **What it does**: + - Builds the EPUB file using `scripts/build_epub.py` + - Verifies the EPUB was created successfully + - Uploads EPUB as artifact + +**Outcome**: If build fails, the workflow fails (critical) + +#### 6. Summary + +- **Runs on**: Ubuntu latest +- **Depends on**: All other jobs +- **What it does**: + - Generates workflow summary + - Lists all artifacts + - Reports overall status + +## Writing Tests + +### Test Structure + +Tests should be placed in `scripts/tests/` with names like `test_*.py`: + +```python +# scripts/tests/test_example.py +import pytest +from scripts.example_module import some_function + +def test_basic_functionality(): + """Test that some_function works correctly.""" + result = some_function("input") + assert result == "expected_output" + +def test_error_handling(): + """Test that some_function handles errors gracefully.""" + with pytest.raises(ValueError): + some_function("invalid_input") + +@pytest.mark.asyncio +async def test_async_function(): + """Test async functions.""" + result = await async_function() + assert result is not None +``` + +### Test Best Practices + +- **Use descriptive names**: `test_function_returns_correct_value()` +- **One assertion per test** (when possible): Easier to debug failures +- **Use fixtures** for reusable setup: See `scripts/tests/conftest.py` +- **Mock external services**: Use `unittest.mock` or `pytest-mock` +- **Test edge cases**: Empty inputs, None values, errors +- **Keep tests fast**: Avoid sleep() and external I/O +- **Use pytest markers**: `@pytest.mark.slow` for slow tests + +### Fixtures + +Common fixtures are defined in `scripts/tests/conftest.py`: + +```python +# Use fixtures in your tests +def test_something(tmp_path): + """tmp_path fixture provides temporary directory.""" + test_file = tmp_path / "test.txt" + test_file.write_text("content") + assert test_file.read_text() == "content" +``` + +## Coverage Reports + +### Local Coverage + +```bash +# Generate coverage report +pytest scripts/tests/ --cov=scripts --cov-report=html + +# Open the coverage report in your browser +open htmlcov/index.html +``` + +### Coverage Goals + +- **Minimum coverage**: 80% +- **Branch coverage**: Enabled +- **Focus areas**: Core functionality and error paths + +## Pre-commit Hooks + +The project uses pre-commit hooks to run checks automatically before commits: + +```bash +# Install pre-commit hooks +pre-commit install + +# Run hooks manually +pre-commit run --all-files + +# Skip hooks for a commit (not recommended) +git commit --no-verify +``` + +Configured hooks in `.pre-commit-config.yaml`: +- Ruff formatter +- Ruff linter +- Bandit security scanner +- YAML validation +- File size checks +- Merge conflict detection + +## Troubleshooting + +### Tests Pass Locally but Fail in CI + +Common causes: +1. **Python version difference**: CI uses 3.10, 3.11, 3.12 +2. **Missing dependencies**: Update `requirements-dev.txt` +3. **Platform differences**: Path separators, environment variables +4. **Flaky tests**: Tests that depend on timing or order + +Solution: +```bash +# Test with the same Python versions +uv python install 3.10 3.11 3.12 + +# Test with clean environment +rm -rf .venv +uv venv +uv pip install -r requirements-dev.txt +pytest scripts/tests/ +``` + +### Bandit Reports False Positives + +Some security warnings may be false positives. Configure in `pyproject.toml`: + +```toml +[tool.bandit] +exclude_dirs = ["scripts/tests"] +skips = ["B101"] # Skip assert_used warning +``` + +### Type Checking Too Strict + +Relax type checking for specific files: + +```python +# Add at the top of file +# type: ignore + +# Or for specific lines +some_dynamic_code() # type: ignore +``` + +## Continuous Integration Best Practices + +1. **Keep tests fast**: Each test should complete in <1 second +2. **Don't test external APIs**: Mock external services +3. **Test in isolation**: Each test should be independent +4. **Use clear assertions**: `assert x == 5` not `assert x` +5. **Handle async tests**: Use `@pytest.mark.asyncio` +6. **Generate reports**: Coverage, security, type checking + +## Resources + +- [pytest Documentation](https://docs.pytest.org/) +- [Ruff Documentation](https://docs.astral.sh/ruff/) +- [Bandit Documentation](https://bandit.readthedocs.io/) +- [mypy Documentation](https://mypy.readthedocs.io/) +- [GitHub Actions Documentation](https://docs.github.com/en/actions) + +## Contributing Tests + +When submitting a PR: + +1. **Write tests** for new functionality +2. **Run tests locally**: `pytest scripts/tests/ -v` +3. **Check coverage**: `pytest scripts/tests/ --cov=scripts` +4. **Run linting**: `ruff check scripts/` +5. **Security scan**: `bandit -r scripts/ --exclude scripts/tests/` +6. **Update documentation** if tests change + +Tests are required for all PRs! ๐Ÿงช + +--- + +For questions or issues with testing, open a GitHub issue or discussion. diff --git a/ko/.github/markdown-link-check-config.json b/ko/.github/markdown-link-check-config.json new file mode 100644 index 00000000..12779570 --- /dev/null +++ b/ko/.github/markdown-link-check-config.json @@ -0,0 +1,87 @@ +{ + "ignorePatterns": [ + { + "pattern": "^https://docs\\.example\\.com", + "comment": "Example placeholder URLs in documentation templates" + }, + { + "pattern": "^\\./docs/", + "comment": "Example relative paths in documentation templates" + }, + { + "pattern": "^FORMS\\.md$|^REFERENCE\\.md$", + "comment": "Example file references in skill templates" + }, + { + "pattern": "^https://en\\.wikipedia\\.org/wiki/N%2B1", + "comment": "Wikipedia N+1 article - URL encoding issues" + }, + { + "pattern": "^https://twitter.com", + "comment": "Twitter/X links require authentication" + }, + { + "pattern": "^https://x.com", + "comment": "X (Twitter) links require authentication" + }, + { + "pattern": "^https://github.com/[^/]+/claude-howto", + "comment": "Self-referencing links" + }, + { + "pattern": "^https://docs\\.claude\\.com", + "comment": "Claude docs - URL structure may vary" + }, + { + "pattern": "^https://docs\\.anthropic\\.com", + "comment": "Anthropic docs - May have authentication or access restrictions" + }, + { + "pattern": "^https://code\\.claude\\.com", + "comment": "Claude Code docs - May have dynamic content or routing issues" + }, + { + "pattern": "^https://plugins\\.claude\\.com", + "comment": "Plugin marketplace - May have access restrictions" + }, + { + "pattern": "^https://medium\\.com", + "comment": "Medium posts - May have paywall or tracking restrictions" + }, + { + "pattern": "^https://modelcontextprotocol\\.io", + "comment": "MCP docs - May have infrastructure limitations" + }, + { + "pattern": "^https://discord\\.gg", + "comment": "Discord invite links - May expire or have access issues" + }, + { + "pattern": "^https://bsky\\.app", + "comment": "BlueSky links - May require authentication" + }, + { + "pattern": "^https://api\\.star-history\\.com", + "comment": "External badge service - May have rate limiting" + }, + { + "pattern": "^https://jazz\\.tools", + "comment": "External tool links - May have dynamic routing" + }, + { + "pattern": "^https://mcp\\.notion\\.com", + "comment": "Notion-hosted docs - May require authentication" + } + ], + "replacementPatterns": [ + { + "pattern": "^/", + "replacement": "https://github.com/luongnv89/claude-howto/blob/main/" + } + ], + "timeout": 10000, + "retryOn": [429, 503], + "retryCount": 3, + "fallbackRetryDelay": 5000, + "aliveStatusCodes": [200, 206] +} diff --git a/ko/.github/pull_request_template.md b/ko/.github/pull_request_template.md new file mode 100644 index 00000000..f2deaae7 --- /dev/null +++ b/ko/.github/pull_request_template.md @@ -0,0 +1,57 @@ +## Description +Brief summary of what this PR does. + +## Type of Change +- [ ] New example or template +- [ ] Documentation improvement +- [ ] Bug fix +- [ ] Feature guide +- [ ] Other (please describe) + +## Related Issues +Closes #(issue number) + +## Changes Made +- Change 1 +- Change 2 +- Change 3 + +## What to Review +What should reviewers focus on? + +## Files Changed +- `path/to/file1.md` +- `path/to/file2.md` + +## Testing +How have you tested this? +- [ ] Tested locally with Claude Code +- [ ] Verified examples work +- [ ] Checked links and references +- [ ] Reviewed for typos and clarity + +## Checklist +- [ ] Follows project structure and conventions +- [ ] Includes clear documentation/examples +- [ ] Code/examples are copy-paste ready +- [ ] All links are verified and working +- [ ] No sensitive information included (keys, tokens, credentials) +- [ ] Updated relevant README files +- [ ] Commit message follows conventional commit format +- [ ] No large files (>1MB) added + +## Screenshots or Examples +If applicable, show what this adds: +``` +[Example code or before/after comparison] +``` + +## Breaking Changes +Does this change any existing content or behavior? +- [ ] No breaking changes +- [ ] Yes, and it's documented below + +If yes, please describe: + +## Additional Notes +Any other information for reviewers? diff --git a/ko/.github/workflows/docs-check.yml b/ko/.github/workflows/docs-check.yml new file mode 100644 index 00000000..29738eb2 --- /dev/null +++ b/ko/.github/workflows/docs-check.yml @@ -0,0 +1,119 @@ +name: Documentation Checks + +on: + push: + branches: [main] + paths: + - '**.md' + - '.github/workflows/docs-check.yml' + - '.github/markdown-link-check-config.json' + - '.markdownlint.json' + - 'scripts/check_*.py' + pull_request: + branches: [main] + paths: + - '**.md' + - 'CONTRIBUTING.md' + - 'LICENSE' + - '.github/markdown-link-check-config.json' + - '.markdownlint.json' + - 'scripts/check_*.py' + +# Cancel in-progress runs for the same branch +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + markdown-lint: + name: Markdown Linting + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '18' + + - name: Install markdownlint-cli + run: npm install -g markdownlint-cli + + - name: Run Markdown Linter + run: markdownlint '**/*.md' --ignore node_modules --ignore .venv --config .markdownlint.json + + link-check: + name: Check Links + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Python + uses: actions/setup-python@v4 + with: + python-version: '3.11' + + - name: Run link check + run: python scripts/check_links.py + env: + LINK_CHECK_STRICT: "1" + + mermaid: + name: Mermaid Syntax + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '18' + + - name: Install mermaid CLI + run: npm install -g @mermaid-js/mermaid-cli + + - name: Setup Python + uses: actions/setup-python@v4 + with: + python-version: '3.11' + + - name: Validate Mermaid diagrams + run: python scripts/check_mermaid.py + env: + MERMAID_PUPPETEER_NO_SANDBOX: "true" + + cross-references: + name: Cross-reference Check + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Python + uses: actions/setup-python@v4 + with: + python-version: '3.11' + + - name: Validate cross-references + run: python scripts/check_cross_references.py + + summary: + name: Summary + needs: [markdown-lint, link-check, mermaid, cross-references] + runs-on: ubuntu-latest + if: always() + steps: + - name: Check Job Results + run: | + if [ "${{ needs.markdown-lint.result }}" = "failure" ] || \ + [ "${{ needs.link-check.result }}" = "failure" ] || \ + [ "${{ needs.mermaid.result }}" = "failure" ] || \ + [ "${{ needs.cross-references.result }}" = "failure" ]; then + echo "โŒ Some documentation checks failed" + exit 1 + else + echo "โœ… All documentation checks passed!" + fi diff --git a/ko/.github/workflows/pages.yml b/ko/.github/workflows/pages.yml new file mode 100644 index 00000000..855f3563 --- /dev/null +++ b/ko/.github/workflows/pages.yml @@ -0,0 +1,62 @@ +name: Deploy Website to GitHub Pages + +on: + push: + branches: + - main + paths: + - '**/*.md' + - 'scripts/build_website.py' + - 'scripts/vendor_assets.py' + - 'scripts/website_templates/**' + - '.github/workflows/pages.yml' + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: pages + cancel-in-progress: false + +jobs: + build: + name: Build static site + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Install uv + uses: astral-sh/setup-uv@v4 + with: + enable-cache: true + + - name: Cache vendor assets + uses: actions/cache@v4 + with: + path: scripts/.vendor-cache + key: vendor-${{ hashFiles('scripts/vendor_assets.py') }} + restore-keys: | + vendor- + + - name: Build website + run: uv run scripts/build_website.py --verbose + + - name: Upload Pages artifact + uses: actions/upload-pages-artifact@v3 + with: + path: site + + deploy: + name: Deploy to GitHub Pages + needs: build + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/ko/.github/workflows/release.yml b/ko/.github/workflows/release.yml new file mode 100644 index 00000000..518e0f7c --- /dev/null +++ b/ko/.github/workflows/release.yml @@ -0,0 +1,80 @@ +name: Build and Release EPUB + +on: + push: + tags: + - 'v*' + +jobs: + build: + name: Build EPUB (${{ matrix.lang }}) + runs-on: ubuntu-latest + strategy: + # Don't cancel other languages if one fails โ€” we still want to release + # whichever languages built successfully. + fail-fast: false + matrix: + lang: [en, vi, zh] + + steps: + - uses: actions/checkout@v4 + + - name: Install uv + uses: astral-sh/setup-uv@v4 + + - name: Install Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + + - name: Install Mermaid CLI + run: npm install -g @mermaid-js/mermaid-cli + + - name: Install Python dependencies + run: | + uv venv + uv pip install -r scripts/requirements-dev.txt + + - name: Build EPUB + run: | + echo '{"args":["--no-sandbox","--disable-setuid-sandbox"]}' > /tmp/puppeteer-ci.json + uv run scripts/build_epub.py \ + --lang ${{ matrix.lang }} \ + --puppeteer-config /tmp/puppeteer-ci.json + + - name: Upload EPUB artifact + uses: actions/upload-artifact@v4 + with: + name: epub-${{ matrix.lang }} + path: claude-howto-guide*.epub + if-no-files-found: error + retention-days: 7 + + release: + name: Publish GitHub Release + needs: build + # Release even if some language builds failed โ€” we still publish the + # artifacts that did build. `needs.build.result != 'cancelled'` guards + # against manually cancelled runs. + if: ${{ always() && needs.build.result != 'cancelled' }} + runs-on: ubuntu-latest + permissions: + contents: write + + steps: + - name: Download all EPUB artifacts + uses: actions/download-artifact@v4 + with: + path: dist + pattern: epub-* + merge-multiple: true + + - name: List built artifacts + run: ls -lh dist/ + + - name: Create Release + uses: softprops/action-gh-release@v2 + with: + files: dist/*.epub + generate_release_notes: true + fail_on_unmatched_files: true diff --git a/ko/.github/workflows/test.yml b/ko/.github/workflows/test.yml new file mode 100644 index 00000000..70352ce5 --- /dev/null +++ b/ko/.github/workflows/test.yml @@ -0,0 +1,228 @@ +name: Automated Testing + +on: + push: + branches: [main, develop] + paths: + - 'scripts/**' + - '.github/workflows/test.yml' + - 'pyproject.toml' + - 'requirements*.txt' + pull_request: + branches: [main] + paths: + - 'scripts/**' + - '.github/workflows/test.yml' + - 'pyproject.toml' + - 'requirements*.txt' + +# Cancel in-progress runs for the same branch +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + pytest: + name: Unit Tests (Python ${{ matrix.python-version }}) + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + python-version: ['3.10', '3.11', '3.12'] + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Install uv + uses: astral-sh/setup-uv@v4 + + - name: Set up Python ${{ matrix.python-version }} + run: uv python install ${{ matrix.python-version }} + + - name: Create venv and install dependencies + run: | + uv venv + uv pip install -r scripts/requirements-dev.txt + + - name: Run pytest + run: uv run pytest scripts/tests/ -v --tb=short --cov=scripts --cov-report=xml --cov-report=html + continue-on-error: false + + - name: Upload coverage to Codecov + uses: codecov/codecov-action@v3 + with: + files: ./coverage.xml + flags: unittests + name: codecov-python-${{ matrix.python-version }} + fail_ci_if_error: false + verbose: true + + - name: Archive test results + if: always() + uses: actions/upload-artifact@v4 + with: + name: pytest-results-${{ matrix.python-version }} + path: | + coverage.xml + htmlcov/ + retention-days: 7 + + lint: + name: Code Quality (Lint & Format) + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Install uv + uses: astral-sh/setup-uv@v4 + + - name: Set up Python + run: uv python install 3.11 + + - name: Create venv and install Ruff + run: | + uv venv + uv pip install ruff + + - name: Ruff Format Check + run: uv run ruff format --check scripts/ + + - name: Ruff Lint Check + run: uv run ruff check scripts/ + + security: + name: Security Scan + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Install uv + uses: astral-sh/setup-uv@v4 + + - name: Set up Python + run: uv python install 3.11 + + - name: Create venv and install Bandit + run: | + uv venv + uv pip install "bandit[toml]" + + - name: Run Bandit Security Scan + run: uv run bandit -c scripts/pyproject.toml -r scripts/ --exclude scripts/tests/ -f json -o bandit-report.json + + - name: Upload security report + uses: actions/upload-artifact@v4 + if: always() + with: + name: bandit-security-report + path: bandit-report.json + retention-days: 7 + + type-check: + name: Type Checking + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Install uv + uses: astral-sh/setup-uv@v4 + + - name: Set up Python + run: uv python install 3.11 + + - name: Create venv and install mypy + run: | + uv venv + uv pip install -r scripts/requirements-dev.txt mypy + + - name: Run mypy + run: uv run mypy scripts/ --config-file scripts/pyproject.toml + + build-epub: + name: Build EPUB Artifact + runs-on: ubuntu-latest + needs: [pytest, lint, security, type-check] + if: ${{ !failure() && !cancelled() }} + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Install uv + uses: astral-sh/setup-uv@v4 + + - name: Set up Python + run: uv python install 3.11 + + - name: Create venv and install dependencies + run: | + uv venv + uv pip install -r scripts/requirements-dev.txt + + - name: Install mmdc (Mermaid CLI) + run: npm install -g @mermaid-js/mermaid-cli + + - name: Build EPUB + run: | + echo '{"args":["--no-sandbox","--disable-setuid-sandbox"]}' > /tmp/puppeteer-ci.json + uv run scripts/build_epub.py --puppeteer-config /tmp/puppeteer-ci.json + + - name: Verify EPUB Created + run: | + if [ -f claude-howto-guide.epub ]; then + echo "โœ… EPUB built successfully" + ls -lh claude-howto-guide.epub + else + echo "โŒ EPUB file not found!" + exit 1 + fi + + - name: Upload EPUB Artifact + uses: actions/upload-artifact@v4 + with: + name: claude-howto-guide-epub + path: claude-howto-guide.epub + retention-days: 7 + compression-level: 0 + + summary: + name: Test Summary + needs: [pytest, lint, security, type-check, build-epub] + runs-on: ubuntu-latest + if: always() + + steps: + - name: Download all artifacts + uses: actions/download-artifact@v4 + + - name: Generate Summary + run: | + echo "# Test Summary" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "## Results" >> $GITHUB_STEP_SUMMARY + echo "- **Unit Tests**: ${{ needs.pytest.result }}" >> $GITHUB_STEP_SUMMARY + echo "- **Code Quality**: ${{ needs.lint.result }}" >> $GITHUB_STEP_SUMMARY + echo "- **Security Scan**: ${{ needs.security.result }}" >> $GITHUB_STEP_SUMMARY + echo "- **Type Checking**: ${{ needs.type-check.result }}" >> $GITHUB_STEP_SUMMARY + echo "- **EPUB Build**: ${{ needs.build-epub.result }}" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "## Artifacts" >> $GITHUB_STEP_SUMMARY + echo "- pytest-results-* (coverage and test results)" >> $GITHUB_STEP_SUMMARY + echo "- bandit-security-report (security scan JSON)" >> $GITHUB_STEP_SUMMARY + echo "- claude-howto-guide-epub (built EPUB file)" >> $GITHUB_STEP_SUMMARY + + - name: Check if all tests passed + if: | + needs.pytest.result != 'success' || + needs.build-epub.result != 'success' + run: | + echo "โŒ Critical tests failed" + exit 1 + + - name: All tests passed + if: success() + run: echo "โœ… All tests passed successfully!" diff --git a/ko/01-slash-commands/README.md b/ko/01-slash-commands/README.md new file mode 100644 index 00000000..711343c4 --- /dev/null +++ b/ko/01-slash-commands/README.md @@ -0,0 +1,649 @@ + + + Claude How To + + +# ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด + +## ๊ฐœ์š” + +์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด๋Š” ๋Œ€ํ™”ํ˜• ์„ธ์…˜ ๋™์•ˆ Claude์˜ ๋™์ž‘์„ ์ œ์–ดํ•˜๋Š” ๋‹จ์ถ•ํ‚ค์ž…๋‹ˆ๋‹ค. ์—ฌ๋Ÿฌ ์œ ํ˜•์ด ์žˆ์Šต๋‹ˆ๋‹ค: + +- **๋‚ด์žฅ ๋ช…๋ น์–ด**: Claude Code์—์„œ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค (`/help`, `/clear`, `/model`) +- **์Šคํ‚ฌ**: `SKILL.md` ํŒŒ์ผ๋กœ ์ƒ์„ฑ๋œ ์‚ฌ์šฉ์ž ์ •์˜ ๋ช…๋ น์–ด์ž…๋‹ˆ๋‹ค (`/optimize`, `/pr`) +- **ํ”Œ๋Ÿฌ๊ทธ์ธ ๋ช…๋ น์–ด**: ์„ค์น˜๋œ ํ”Œ๋Ÿฌ๊ทธ์ธ์—์„œ ์ œ๊ณตํ•˜๋Š” ๋ช…๋ น์–ด์ž…๋‹ˆ๋‹ค (`/frontend-design:frontend-design`) +- **MCP ํ”„๋กฌํ”„ํŠธ**: MCP ์„œ๋ฒ„์—์„œ ์ œ๊ณตํ•˜๋Š” ๋ช…๋ น์–ด์ž…๋‹ˆ๋‹ค (`/mcp__github__list_prs`) + +> **์ฐธ๊ณ **: ์‚ฌ์šฉ์ž ์ •์˜ ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด๋Š” ์Šคํ‚ฌ๋กœ ํ†ตํ•ฉ๋˜์—ˆ์Šต๋‹ˆ๋‹ค. `.claude/commands/`์— ์žˆ๋Š” ํŒŒ์ผ์€ ์—ฌ์ „ํžˆ ์ž‘๋™ํ•˜์ง€๋งŒ, ์Šคํ‚ฌ (`.claude/skills/`)์ด ์ด์ œ ๊ถŒ์žฅ๋˜๋Š” ์ ‘๊ทผ ๋ฐฉ์‹์ž…๋‹ˆ๋‹ค. ๋‘ ๊ฐ€์ง€ ๋ชจ๋‘ `/command-name` ๋‹จ์ถ•ํ‚ค๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. ์ „์ฒด ์ฐธ์กฐ๋Š” [์Šคํ‚ฌ ๊ฐ€์ด๋“œ](../03-skills/)๋ฅผ ์ฐธ์กฐํ•˜์‹ญ์‹œ์˜ค. + +## ๋‚ด์žฅ ๋ช…๋ น์–ด ์ฐธ์กฐ + +๋‚ด์žฅ ๋ช…๋ น์–ด๋Š” ์ผ๋ฐ˜์ ์ธ ์ž‘์—…์„ ์œ„ํ•œ ๋‹จ์ถ•ํ‚ค์ž…๋‹ˆ๋‹ค. **60๊ฐœ ์ด์ƒ์˜ ๋‚ด์žฅ ๋ช…๋ น์–ด**์™€ **5๊ฐœ์˜ ๋ฒˆ๋“ค ์Šคํ‚ฌ**์ด ์ œ๊ณต๋ฉ๋‹ˆ๋‹ค. Claude Code์—์„œ `/`๋ฅผ ์ž…๋ ฅํ•˜์—ฌ ์ „์ฒด ๋ชฉ๋ก์„ ๋ณด๊ฑฐ๋‚˜, `/` ๋’ค์— ๊ธ€์ž๋ฅผ ์ž…๋ ฅํ•˜์—ฌ ํ•„ํ„ฐ๋งํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +| Command | ๋ชฉ์  | +|---------|---------| +| `/add-dir ` | ์ž‘์—… ๋””๋ ‰ํ„ฐ๋ฆฌ ์ถ”๊ฐ€ | +| `/agents` | ์—์ด์ „ํŠธ ๊ตฌ์„ฑ ๊ด€๋ฆฌ | +| `/branch [name]` | ๋Œ€ํ™”๋ฅผ ์ƒˆ ์„ธ์…˜์œผ๋กœ ๋ถ„๊ธฐํ•ฉ๋‹ˆ๋‹ค (๋ณ„์นญ: `/fork`). ์ฐธ๊ณ : v2.1.77์—์„œ `/fork`๊ฐ€ `/branch`๋กœ ์ด๋ฆ„์ด ๋ณ€๊ฒฝ๋˜์—ˆ์Šต๋‹ˆ๋‹ค | +| `/btw ` | Claude๊ฐ€ ์ฃผ ์ž‘์—…์„ ์ˆ˜ํ–‰ํ•˜๋Š” ๋™์•ˆ ์ž„์‹œ ๋ณด์กฐ ์งˆ๋ฌธ์„ ํ•ฉ๋‹ˆ๋‹ค; ์ฃผ ๋Œ€ํ™” ์ปจํ…์ŠคํŠธ๋ฅผ ์˜ค์—ผ์‹œํ‚ค์ง€ ์•Š์Šต๋‹ˆ๋‹ค | +| `/cd ` | ํ”„๋กฌํ”„ํŠธ ์บ์‹œ๋ฅผ ์†์ƒ์‹œํ‚ค์ง€ ์•Š๊ณ  ์„ธ์…˜์„ ์ƒˆ ์ž‘์—… ๋””๋ ‰ํ„ฐ๋ฆฌ๋กœ ์ด๋™ํ•ฉ๋‹ˆ๋‹ค (v2.1.169์— ์ถ”๊ฐ€) | +| `/chrome` | Chrome ๋ธŒ๋ผ์šฐ์ € ํ†ตํ•ฉ ๊ตฌ์„ฑ | +| `/clear` | ๋Œ€ํ™” ์ง€์šฐ๊ธฐ (๋ณ„์นญ: `/reset`, `/new`) | +| `/color [color\|default]` | ํ”„๋กฌํ”„ํŠธ ๋ฐ” ์ƒ‰์ƒ์„ ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค. ์ธ์ž ์—†์ด `/color`๋ฅผ ์‚ฌ์šฉํ•˜๋ฉด ์ž„์˜์˜ ์„ธ์…˜ ์ƒ‰์ƒ์„ ์„ ํƒํ•ฉ๋‹ˆ๋‹ค (v2.1.128+); ์ƒ‰์ƒ ์ด๋ฆ„ ๋˜๋Š” 16์ง„์ˆ˜๋ฅผ ์ „๋‹ฌํ•˜์—ฌ ๋ช…์‹œ์ ์œผ๋กœ ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค. | +| `/compact [instructions]` | ์„ ํƒ์  ํฌ์ปค์Šค ์ง€์นจ์„ ์‚ฌ์šฉํ•˜์—ฌ ๋Œ€ํ™”๋ฅผ ์••์ถ•ํ•ฉ๋‹ˆ๋‹ค | +| `/config` | ์„ค์ • ์—ด๊ธฐ (๋ณ„์นญ: `/settings`) | +| `/context` | ์ปจํ…์ŠคํŠธ ์‚ฌ์šฉ๋Ÿ‰์„ ์ปฌ๋Ÿฌ ๊ทธ๋ฆฌ๋“œ๋กœ ์‹œ๊ฐํ™”ํ•ฉ๋‹ˆ๋‹ค | +| `/copy [N]` | ๋ณด์กฐ์ž์˜ ์‘๋‹ต์„ ํด๋ฆฝ๋ณด๋“œ์— ๋ณต์‚ฌํ•ฉ๋‹ˆ๋‹ค; `w`๋Š” ํŒŒ์ผ์— ์”๋‹ˆ๋‹ค | +| `/cost` | `/usage`์˜ ํƒ€์ดํ•‘ ๋‹จ์ถ•ํ‚ค ๋ณ„์นญ โ€” ๋น„์šฉ ํƒญ์„ ์—ฝ๋‹ˆ๋‹ค (v2.1.118+) | +| `/desktop` | ๋ฐ์Šคํฌํ†ฑ ์•ฑ์—์„œ ๊ณ„์† (๋ณ„์นญ: `/app`) | +| `/diff` | ์ปค๋ฐ‹๋˜์ง€ ์•Š์€ ๋ณ€๊ฒฝ ์‚ฌํ•ญ์— ๋Œ€ํ•œ ๋Œ€ํ™”ํ˜• Diff ๋ทฐ์–ด | +| `/doctor` | ์„ค์น˜ ์ƒํƒœ๋ฅผ ์ง„๋‹จํ•ฉ๋‹ˆ๋‹ค โ€” Claude๊ฐ€ ์‘๋‹ต ์ค‘์ผ ๋•Œ ์—ด ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค; ์ƒํƒœ ์•„์ด์ฝ˜์„ ํ‘œ์‹œํ•ฉ๋‹ˆ๋‹ค; `f`๋ฅผ ๋ˆŒ๋Ÿฌ ๋ฌธ์ œ๋ฅผ ์ž๋™ ์ˆ˜์ •ํ•ฉ๋‹ˆ๋‹ค (v2.1.116์—์„œ ํ–ฅ์ƒ; v2.1.178์—์„œ ๋” ๋ช…ํ™•ํ•œ ์•„์ด์ฝ˜์ด ์žˆ๋Š” ํ‰๋ฉด ํŠธ๋ฆฌ๋กœ ๋ ˆ์ด์•„์›ƒ ์ƒˆ๋กœ ๊ณ ์นจ) | +| `/effort [low\|medium\|high\|xhigh\|max\|auto]` | ๋Œ€ํ™”ํ˜• ํ™”์‚ดํ‘œ ํ‚ค ์Šฌ๋ผ์ด๋”๋ฅผ ํ†ตํ•ด ๋…ธ๋ ฅ ์ˆ˜์ค€์„ ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค. ์ˆ˜์ค€: `low` โ†’ `medium` โ†’ `high` โ†’ `xhigh` (v2.1.111์— ์ƒˆ๋กœ ์ถ”๊ฐ€) โ†’ `max`. Opus 4.8์˜ ๊ธฐ๋ณธ๊ฐ’์€ `high`์ž…๋‹ˆ๋‹ค (Opus 4.7์˜ ๊ฒฝ์šฐ `xhigh`); `xhigh`๋Š” Opus 4.8 ๋˜๋Š” 4.7์ด ํ•„์š”ํ•ฉ๋‹ˆ๋‹ค; `max`๋Š” Opus 4.8/4.7/4.6 ๋ฐ Sonnet 4.6์—์„œ ์ž‘๋™ํ•ฉ๋‹ˆ๋‹ค. ๋ฉ”๋‰ด๋Š” ๋˜ํ•œ `ultracode`๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค (๋ชจ๋ธ ๋…ธ๋ ฅ ์ˆ˜์ค€์€ ์•„๋‹ˆ์ง€๋งŒ `xhigh`๋ฅผ ๋ณด๋‚ด๊ณ  Claude๊ฐ€ ๋™์  ์›Œํฌํ”Œ๋กœ์šฐ๋ฅผ ์กฐ์ •ํ•˜๋„๋ก ํ•ฉ๋‹ˆ๋‹ค; ์„ธ์…˜ ์ „์šฉ) | +| `/exit` | REPL ์ข…๋ฃŒ (๋ณ„์นญ: `/quit`) | +| `/export [filename]` | ํ˜„์žฌ ๋Œ€ํ™”๋ฅผ ํŒŒ์ผ ๋˜๋Š” ํด๋ฆฝ๋ณด๋“œ๋กœ ๋‚ด๋ณด๋ƒ…๋‹ˆ๋‹ค | +| `/usage-credits` | ์†๋„ ์ œํ•œ์„ ์œ„ํ•œ ์ถ”๊ฐ€ ์‚ฌ์šฉ๋Ÿ‰ ๊ตฌ์„ฑ (v2.1.144์—์„œ `/extra-usage`์—์„œ ์ด๋ฆ„ ๋ณ€๊ฒฝ; `/extra-usage`๋Š” ์—ฌ์ „ํžˆ ๋ณ„์นญ์œผ๋กœ ์ž‘๋™ํ•ฉ๋‹ˆ๋‹ค) | +| `/fast [on\|off]` | ๋น ๋ฅธ ๋ชจ๋“œ ์ „ํ™˜ | +| `/feedback` | ํ”ผ๋“œ๋ฐฑ ์ œ์ถœ (๋ณ„์นญ: `/bug`). v2.1.141๋ถ€ํ„ฐ ์ตœ๊ทผ ์„ธ์…˜ (์ง€๋‚œ 24์‹œ๊ฐ„ ๋˜๋Š” 7์ผ)์„ ์ฒจ๋ถ€ํ•  ์ˆ˜ ์žˆ์œผ๋ฏ€๋กœ ์—ฌ๋Ÿฌ ์„ธ์…˜์— ๊ฑธ์นœ ๋ณด๊ณ ์„œ์— ์ปจํ…์ŠคํŠธ๊ฐ€ ํฌํ•จ๋ฉ๋‹ˆ๋‹ค. v2.1.178๋ถ€ํ„ฐ `/bug`๋Š” ์ œ์ถœ ์ „์— ์„ค๋ช…์ด ํ•„์š”ํ•ฉ๋‹ˆ๋‹ค. | +| `/focus` | ํฌ์ปค์Šค ๋ทฐ ์ „ํ™˜ (v2.1.110์— ์ถ”๊ฐ€; ํฌ์ปค์Šค ํ† ๊ธ€์„ ์œ„ํ•œ `Ctrl+O`๋ฅผ ๋Œ€์ฒด) | +| `/goal ` | ์„ธ์…˜ ์ˆ˜์ค€ ์™„๋ฃŒ ์กฐ๊ฑด์„ ๋“ฑ๋กํ•ฉ๋‹ˆ๋‹ค; Claude๋Š” ๋ชฉํ‘œ๊ฐ€ ๋‹ฌ์„ฑ๋  ๋•Œ๊นŒ์ง€ ๊ณ„์† ์ž‘์—…ํ•ฉ๋‹ˆ๋‹ค. `/goal clear`๋Š” ์ด๋ฅผ ์ œ๊ฑฐํ•ฉ๋‹ˆ๋‹ค. ํ™œ์„ฑ ๋ชฉํ‘œ๋Š” ์ƒํƒœ ํ‘œ์‹œ์ค„์— ๋‚˜ํƒ€๋‚˜๋ฉฐ, ๊ฒฝ๊ณผ ์‹œ๊ฐ„, ํ„ด ์ˆ˜, ํ† ํฐ ์‚ฌ์šฉ๋Ÿ‰์„ ๋ณด์—ฌ์ฃผ๋Š” ๋ผ์ด๋ธŒ ์˜ค๋ฒ„๋ ˆ์ด ํŒจ๋„์ด ํ•จ๊ป˜ ํ‘œ์‹œ๋ฉ๋‹ˆ๋‹ค (v2.1.139์— ์ถ”๊ฐ€). | +| `/help` | ๋„์›€๋ง ํ‘œ์‹œ | +| `/hooks` | ํ›„ํฌ ๊ตฌ์„ฑ ๋ณด๊ธฐ | +| `/ide` | IDE ํ†ตํ•ฉ ๊ด€๋ฆฌ | +| `/init` | `CLAUDE.md` ์ดˆ๊ธฐํ™”. ๋Œ€ํ™”ํ˜• ํ๋ฆ„์„ ์œ„ํ•ด `CLAUDE_CODE_NEW_INIT=1` ์„ค์ • | +| `/insights` | ์„ธ์…˜ ๋ถ„์„ ๋ณด๊ณ ์„œ ์ƒ์„ฑ | +| `/install-github-app` | GitHub Actions ์•ฑ ์„ค์ • | +| `/install-slack-app` | Slack ์•ฑ ์„ค์น˜ | +| `/keybindings` | ํ‚ค ๋ฐ”์ธ๋”ฉ ๊ตฌ์„ฑ ์—ด๊ธฐ | +| `/less-permission-prompts` | ์ตœ๊ทผ Bash/MCP ๋„๊ตฌ ํ˜ธ์ถœ์„ ๋ถ„์„ํ•˜๊ณ  ๊ถŒํ•œ ํ”„๋กฌํ”„ํŠธ ๊ฐ์†Œ๋ฅผ ์œ„ํ•ด `.claude/settings.json`์— ์šฐ์„ ์ˆœ์œ„๊ฐ€ ์ง€์ •๋œ ํ—ˆ์šฉ ๋ชฉ๋ก์„ ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค (v2.1.111์— ์ถ”๊ฐ€) | +| `/login` | Anthropic ๊ณ„์ • ์ „ํ™˜ | +| `/logout` | Anthropic ๊ณ„์ •์—์„œ ๋กœ๊ทธ์•„์›ƒ | +| `/mcp` | MCP ์„œ๋ฒ„ ๋ฐ OAuth ๊ด€๋ฆฌ | +| `/memory` | `CLAUDE.md` ํŽธ์ง‘, ์ž๋™ ๋ฉ”๋ชจ๋ฆฌ ์ „ํ™˜ | +| `/mobile` | ๋ชจ๋ฐ”์ผ ์•ฑ์šฉ QR ์ฝ”๋“œ (๋ณ„์นญ: `/ios`, `/android`) | +| `/model [model]` | ์™ผ์ชฝ/์˜ค๋ฅธ์ชฝ ํ™”์‚ดํ‘œ๋กœ ๋…ธ๋ ฅ์— ๋”ฐ๋ผ ๋ชจ๋ธ์„ ์„ ํƒํ•ฉ๋‹ˆ๋‹ค. v2.1.153๋ถ€ํ„ฐ ์„ ํƒ์€ ์ƒˆ ์„ธ์…˜์˜ **๊ธฐ๋ณธ๊ฐ’์œผ๋กœ ์ €์žฅ๋ฉ๋‹ˆ๋‹ค** (IDE์™€ ์ผ์น˜); ์„ ํƒ ํ›„ `s`๋ฅผ ๋ˆŒ๋Ÿฌ ํ˜„์žฌ ์„ธ์…˜์—๋งŒ ์ ์šฉํ•ฉ๋‹ˆ๋‹ค. (`modelPicker:setAsDefault` ํ‚ค ๋ฐ”์ธ๋”ฉ์ด `modelPicker:thisSessionOnly`๋กœ ์ด๋ฆ„์ด ๋ณ€๊ฒฝ๋˜์—ˆ์Šต๋‹ˆ๋‹ค; ์ด์ „ `d` ์•ก์…˜์€ ์ด์ œ `s`์ž…๋‹ˆ๋‹ค.) | +| `/passes` | Claude Code ๋ฌด๋ฃŒ ์ฃผ ๊ณต์œ  | +| `/permissions` | ๊ถŒํ•œ ๋ณด๊ธฐ/์—…๋ฐ์ดํŠธ (๋ณ„์นญ: `/allowed-tools`) | +| `/plan [description]` | ๊ณ„ํš ๋ชจ๋“œ ์ง„์ž… | +| `/plugin` | ํ”Œ๋Ÿฌ๊ทธ์ธ ๊ด€๋ฆฌ | +| `/proactive` | `/loop`์˜ ๋ณ„์นญ (v2.1.105์— ์ถ”๊ฐ€) | +| `/powerup` | ์• ๋‹ˆ๋ฉ”์ด์…˜ ๋ฐ๋ชจ๊ฐ€ ์žˆ๋Š” ๋Œ€ํ™”ํ˜• ๋ ˆ์Šจ์„ ํ†ตํ•ด ๊ธฐ๋Šฅ ๋ฐœ๊ฒฌ | +| `/privacy-settings` | ๊ฐœ์ธ ์ •๋ณด ์„ค์ • (Pro/Max ์ „์šฉ) | +| `/release-notes` | ๋ณ€๊ฒฝ ๋กœ๊ทธ ๋ณด๊ธฐ | +| `/recap` | ์„ธ์…˜์œผ๋กœ ๋Œ์•„์˜ฌ ๋•Œ ์„ธ์…˜ ์š”์•ฝ / ์š”์•ฝ ํ‘œ์‹œ (v2.1.108์— ์ถ”๊ฐ€) | +| `/reload-plugins` | ํ™œ์„ฑ ํ”Œ๋Ÿฌ๊ทธ์ธ ๋‹ค์‹œ ๋กœ๋“œ | +| `/reload-skills` | ์„ธ์…˜์„ ๋‹ค์‹œ ์‹œ์ž‘ํ•˜์ง€ ์•Š๊ณ  ์Šคํ‚ฌ ๋””๋ ‰ํ„ฐ๋ฆฌ ๋‹ค์‹œ ์Šค์บ” (v2.1.152์— ์ถ”๊ฐ€) | +| `/remote-control` | claude.ai์—์„œ ์›๊ฒฉ ์ œ์–ด (๋ณ„์นญ: `/rc`) | +| `/remote-env` | ๊ธฐ๋ณธ ์›๊ฒฉ ํ™˜๊ฒฝ ๊ตฌ์„ฑ | +| `/rename [name]` | ์„ธ์…˜ ์ด๋ฆ„ ๋ณ€๊ฒฝ | +| `/resume [session]` | ๋Œ€ํ™” ์žฌ๊ฐœ (๋ณ„์นญ: `/continue`) | +| `/review ` | GitHub PR์„ ๊ฒ€ํ† ํ•ฉ๋‹ˆ๋‹ค. v2.1.186๋ถ€ํ„ฐ `/code-review medium`๊ณผ ๋™์ผํ•œ ๊ฒ€ํ†  ์—”์ง„์—์„œ ์‹คํ–‰๋ฉ๋‹ˆ๋‹ค. ๋กœ์ปฌ ์ž‘์—… Diff๋ฅผ ๊ฒ€ํ† ํ•˜๋ ค๋ฉด `/code-review`๋ฅผ ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค | +| `/rewind` | ๋Œ€ํ™” ๋ฐ/๋˜๋Š” ์ฝ”๋“œ ๋˜๊ฐ๊ธฐ (๋ณ„์นญ: `/checkpoint`) | +| `/sandbox` | ์ƒŒ๋“œ๋ฐ•์Šค ๋ชจ๋“œ ์ „ํ™˜ | +| `/schedule [description]` | ํด๋ผ์šฐ๋“œ ์˜ˆ์•ฝ ์ž‘์—… ์ƒ์„ฑ/๊ด€๋ฆฌ | +| `/scroll-speed <+N\|-N>` | ๋ผ์ด๋ธŒ ๋ฏธ๋ฆฌ๋ณด๊ธฐ๋ฅผ ํ†ตํ•ด TUI ๋ผ์ด๋ธŒ ๋ฏธ๋ฆฌ๋ณด๊ธฐ ์ฐฝ์˜ ๋งˆ์šฐ์Šค ํœ  ์Šคํฌ๋กค ์†๋„๋ฅผ ์กฐ์ •ํ•ฉ๋‹ˆ๋‹ค. `~/.claude/preferences.json`์— ๋จธ์‹ ๋ณ„๋กœ ์œ ์ง€๋ฉ๋‹ˆ๋‹ค (v2.1.139์— ์ถ”๊ฐ€). | +| `/security-review` | ๋ณด์•ˆ ์ทจ์•ฝ์  ์—ฌ๋ถ€๋ฅผ ์œ„ํ•ด ๋ธŒ๋žœ์น˜ ๋ถ„์„ | +| `/skills` | ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ์Šคํ‚ฌ ๋‚˜์—ด | +| `/stats` | `/usage`์˜ ํƒ€์ดํ•‘ ๋‹จ์ถ•ํ‚ค ๋ณ„์นญ โ€” ํ†ต๊ณ„ ํƒญ์„ ์—ฝ๋‹ˆ๋‹ค (์ผ์ผ ์‚ฌ์šฉ๋Ÿ‰, ์„ธ์…˜, ์—ฐ์† ๊ธฐ๋ก) (v2.1.118+) | +| `/stickers` | Claude Code ์Šคํ‹ฐ์ปค ์ฃผ๋ฌธ | +| `/status` | ๋ฒ„์ „, ๋ชจ๋ธ, ๊ณ„์ • ํ‘œ์‹œ | +| `/statusline` | ์ƒํƒœ ํ‘œ์‹œ์ค„ ๊ตฌ์„ฑ | +| `/tasks` | ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž‘์—… ๋‚˜์—ด/๊ด€๋ฆฌ | +| `/team-onboarding` | ํ”„๋กœ์ ํŠธ์˜ Claude Code ์„ค์ •์—์„œ ํŒ€์› ์˜จ๋ณด๋”ฉ ๊ฐ€์ด๋“œ๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค (v2.1.101์— ์ƒˆ๋กœ ์ถ”๊ฐ€) | +| `/terminal-setup` | ํ„ฐ๋ฏธ๋„ ํ‚ค ๋ฐ”์ธ๋”ฉ ๊ตฌ์„ฑ | +| `/theme` | ํ…Œ๋งˆ ์„ ํƒ๊ธฐ ์—ด๊ธฐ / ์‚ฌ์šฉ์ž ์ •์˜ ํ…Œ๋งˆ ๊ด€๋ฆฌ (v2.1.118). `~/.claude/themes/.json`์˜ JSON์„ ํ†ตํ•ด ์‚ฌ์šฉ์ž ์ •์˜ ํ…Œ๋งˆ ์ •์˜ | +| `/tui` | ๊นœ๋ฐ•์ž„ ์—†๋Š” ๋ Œ๋”๋ง์„ ์ œ๊ณตํ•˜๋Š” ์ „์ฒด ํ™”๋ฉด TUI (ํ…์ŠคํŠธ ์‚ฌ์šฉ์ž ์ธํ„ฐํŽ˜์ด์Šค) ๋ชจ๋“œ ์ „ํ™˜ (v2.1.110์— ์ถ”๊ฐ€) | +| `/ultraplan ` | ์šธํŠธ๋ผํ”Œ๋žœ ์„ธ์…˜์—์„œ ๊ณ„ํš ์ดˆ์•ˆ ์ž‘์„ฑ, ๋ธŒ๋ผ์šฐ์ €์—์„œ ๊ฒ€ํ†  | +| `/ultrareview` | ๋‹ค์ค‘ ์—์ด์ „ํŠธ ๋ถ„์„์„ ํ†ตํ•œ ํฌ๊ด„์ ์ธ ํด๋ผ์šฐ๋“œ ๊ธฐ๋ฐ˜ ์ฝ”๋“œ ๊ฒ€ํ†  (v2.1.111์— ์ถ”๊ฐ€) | +| `/undo` | `/rewind`์˜ ๋ณ„์นญ (v2.1.108์— ์ถ”๊ฐ€) | +| `/upgrade` | ์ƒ์œ„ ํ”Œ๋žœ ํ‹ฐ์–ด ์—…๊ทธ๋ ˆ์ด๋“œ ํŽ˜์ด์ง€ ์—ด๊ธฐ | +| `/usage` | ํ‘œ์ค€ ์‚ฌ์šฉ๋Ÿ‰ ๋Œ€์‹œ๋ณด๋“œ (v2.1.118) โ€” ํ”Œ๋žœ ์‚ฌ์šฉ๋Ÿ‰ ์ œํ•œ, ์†๋„ ์ œํ•œ, ๋น„์šฉ ๋ฐ ์ผ์ผ ์„ธ์…˜ ํ†ต๊ณ„๋ฅผ ๊ฒฐํ•ฉํ•ฉ๋‹ˆ๋‹ค. `/cost` ๋ฐ `/stats`๋Š” ํŠน์ • ํƒญ์„ ์—ฌ๋Š” ํƒ€์ดํ•‘ ๋‹จ์ถ•ํ‚ค ๋ณ„์นญ์ž…๋‹ˆ๋‹ค | +| `/voice` | ๋ˆŒ๋Ÿฌ์„œ ๋งํ•˜๊ธฐ ์Œ์„ฑ ๋ฐ›์•„์“ฐ๊ธฐ ์ „ํ™˜ | +| `/workflows` | ์‹คํ–‰ ์ค‘์ด๊ฑฐ๋‚˜ ์™„๋ฃŒ๋œ ๋™์  ์›Œํฌํ”Œ๋กœ์šฐ ์‹คํ–‰ ๋ณด๊ธฐ (v2.1.154์— ์ถ”๊ฐ€). [๋™์  ์›Œํฌํ”Œ๋กœ์šฐ](../09-advanced-features/README.md#dynamic-workflows) ์ฐธ์กฐ | + +> **`/cd`๊ฐ€ ์ค‘์š”ํ•œ ์ด์œ :** ๋””๋ ‰ํ„ฐ๋ฆฌ๋ฅผ ๋ณ€๊ฒฝํ•˜๋ฉด ์บ์‹œ ์›Œ๋ฐ์ด ์†์‹ค๋˜์–ด ๋‹ค์Œ ํ„ด์ด ๋Š๋ ค์ง€๊ณ  ๋น„์šฉ์ด ๋งŽ์ด ๋“ค ์ˆ˜ ์žˆ์—ˆ์Šต๋‹ˆ๋‹ค; `/cd`๋Š” ์ „ํ™˜ ์‹œ ํ”„๋กฌํ”„ํŠธ ์บ์‹œ๋ฅผ ๋ณด์กดํ•ฉ๋‹ˆ๋‹ค. + +### ๋ฒˆ๋“ค ์Šคํ‚ฌ + +์ด๋Ÿฌํ•œ ์Šคํ‚ฌ์€ Claude Code์™€ ํ•จ๊ป˜ ์ œ๊ณต๋˜๋ฉฐ ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด์ฒ˜๋Ÿผ ํ˜ธ์ถœ๋ฉ๋‹ˆ๋‹ค. + +| Skill | ๋ชฉ์  | +|-------|---------| +| `/batch ` | ์›ŒํฌํŠธ๋ฆฌ๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ๋Œ€๊ทœ๋ชจ ๋ณ‘๋ ฌ ๋ณ€๊ฒฝ์„ ์กฐ์ •ํ•ฉ๋‹ˆ๋‹ค | +| `/claude-api` | ํ”„๋กœ์ ํŠธ ์–ธ์–ด์— ๋Œ€ํ•œ Claude API ์ฐธ์กฐ ๋กœ๋“œ | +| `/debug [description]` | ๋””๋ฒ„๊ทธ ๋กœ๊น… ํ™œ์„ฑํ™” | +| `/loop [interval] ` | ์ง€์ •๋œ ๊ฐ„๊ฒฉ์œผ๋กœ ํ”„๋กฌํ”„ํŠธ๋ฅผ ๋ฐ˜๋ณต์ ์œผ๋กœ ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค | +| `/code-review [effort]` | ์„ ํƒํ•œ ๋…ธ๋ ฅ ์ˆ˜์ค€(์˜ˆ: `/code-review high`)์œผ๋กœ ํ˜„์žฌ Diff์—์„œ ์ •ํ™•์„ฑ ๋ฒ„๊ทธ๋ฅผ ๊ฒ€ํ† ํ•ฉ๋‹ˆ๋‹ค. ์›๋ž˜ v2.1.146์—์„œ `/simplify`๋ฅผ ํก์ˆ˜ํ–ˆ์ง€๋งŒ, v2.1.154์—์„œ `/simplify`๋Š” ๋ณ„๋„์˜ ๋ช…๋ น์–ด๋กœ ๋Œ์•„์™”์Šต๋‹ˆ๋‹ค | +| `/simplify` | ์ •๋ฆฌ ์ „์šฉ ๊ฒ€ํ† (์žฌ์‚ฌ์šฉ / ๋‹จ์ˆœํ™” / ํšจ์œจ์„ฑ / ๊ณ ๋„)๋ฅผ ์‹คํ–‰ํ•˜๊ณ  ์ˆ˜์ • ์‚ฌํ•ญ์„ ์ ์šฉํ•ฉ๋‹ˆ๋‹ค; ๋ฒ„๊ทธ๋ฅผ ์ฐพ์ง€ **์•Š์Šต๋‹ˆ๋‹ค** โ€” ๋ฒ„๊ทธ๋ฅผ ์ฐพ์œผ๋ ค๋ฉด `/code-review`๋ฅผ ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค. ์ž ์‹œ `/code-review --fix`์˜ ๋ณ„์นญ์ด์—ˆ์ง€๋งŒ (v2.1.152), v2.1.154์—์„œ ์ •๋ฆฌ ์ „์šฉ์ด ๋˜์—ˆ์Šต๋‹ˆ๋‹ค | + +### ์‚ฌ์šฉ๋˜์ง€ ์•Š๋Š” ๋ช…๋ น์–ด + +| Command | ์ƒํƒœ | +|---------|--------| +| `/output-style` | v2.1.73๋ถ€ํ„ฐ ์‚ฌ์šฉ๋˜์ง€ ์•Š์Œ | +| `/fork` | `/branch`๋กœ ์ด๋ฆ„ ๋ณ€๊ฒฝ๋จ (๋ณ„์นญ์€ ์—ฌ์ „ํžˆ ์ž‘๋™, v2.1.77) | +| `/pr-comments` | v2.1.91์—์„œ ์ œ๊ฑฐ๋จ โ€” PR ๋Œ“๊ธ€์„ ๋ณด๋ ค๋ฉด Claude์—๊ฒŒ ์ง์ ‘ ๋ฌธ์˜ํ•˜์‹ญ์‹œ์˜ค | +| `/vim` | v2.1.92์—์„œ ์ œ๊ฑฐ๋จ โ€” `/config` โ†’ ํŽธ์ง‘๊ธฐ ๋ชจ๋“œ๋ฅผ ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค | + +### ์ตœ๊ทผ ๋ณ€๊ฒฝ ์‚ฌํ•ญ + +- `/fork`๊ฐ€ `/branch`๋กœ ์ด๋ฆ„์ด ๋ณ€๊ฒฝ๋˜์—ˆ์œผ๋ฉฐ `/fork`๋Š” ๋ณ„์นญ์œผ๋กœ ์œ ์ง€๋ฉ๋‹ˆ๋‹ค (v2.1.77) +- `/output-style`์ด ์‚ฌ์šฉ๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค (v2.1.73) +- `/review `๋Š” ์ด์ œ `/code-review medium`๊ณผ ๋™์ผํ•œ ๊ฒ€ํ†  ์—”์ง„์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค (v2.1.186) +- `/effort` ๋ช…๋ น์–ด๊ฐ€ ์ถ”๊ฐ€๋˜์—ˆ์Šต๋‹ˆ๋‹ค; `max` ์ˆ˜์ค€์€ Opus 4.6+์—์„œ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค (์›๋ž˜ Opus 4.6 ์ „์šฉ) +- `/voice` ๋ช…๋ น์–ด๊ฐ€ ๋ˆŒ๋Ÿฌ์„œ ๋งํ•˜๊ธฐ ์Œ์„ฑ ๋ฐ›์•„์“ฐ๊ธฐ๋ฅผ ์œ„ํ•ด ์ถ”๊ฐ€๋˜์—ˆ์Šต๋‹ˆ๋‹ค +- `/schedule` ๋ช…๋ น์–ด๊ฐ€ ์˜ˆ์•ฝ ์ž‘์—…์„ ์ƒ์„ฑ/๊ด€๋ฆฌํ•˜๊ธฐ ์œ„ํ•ด ์ถ”๊ฐ€๋˜์—ˆ์Šต๋‹ˆ๋‹ค +- `/color` ๋ช…๋ น์–ด๊ฐ€ ํ”„๋กฌํ”„ํŠธ ๋ฐ” ์‚ฌ์šฉ์ž ์ •์˜๋ฅผ ์œ„ํ•ด ์ถ”๊ฐ€๋˜์—ˆ์Šต๋‹ˆ๋‹ค +- `/pr-comments`๊ฐ€ v2.1.91์—์„œ ์ œ๊ฑฐ๋จ โ€” PR ๋Œ“๊ธ€์„ ๋ณด๋ ค๋ฉด Claude์—๊ฒŒ ์ง์ ‘ ๋ฌธ์˜ํ•˜์‹ญ์‹œ์˜ค +- `/vim`์ด v2.1.92์—์„œ ์ œ๊ฑฐ๋จ โ€” ๋Œ€์‹  `/config` โ†’ ํŽธ์ง‘๊ธฐ ๋ชจ๋“œ๋ฅผ ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค +- `/ultraplan`์ด ๋ธŒ๋ผ์šฐ์ € ๊ธฐ๋ฐ˜ ๊ณ„ํš ๊ฒ€ํ†  ๋ฐ ์‹คํ–‰์„ ์œ„ํ•ด ์ถ”๊ฐ€๋˜์—ˆ์Šต๋‹ˆ๋‹ค +- `/powerup`์ด ๋Œ€ํ™”ํ˜• ๊ธฐ๋Šฅ ๋ ˆ์Šจ์„ ์œ„ํ•ด ์ถ”๊ฐ€๋˜์—ˆ์Šต๋‹ˆ๋‹ค +- `/sandbox`๊ฐ€ ์ƒŒ๋“œ๋ฐ•์Šค ๋ชจ๋“œ ์ „ํ™˜์„ ์œ„ํ•ด ์ถ”๊ฐ€๋˜์—ˆ์Šต๋‹ˆ๋‹ค +- `/model` ์„ ํƒ๊ธฐ๋Š” ์ด์ œ ์›์‹œ ๋ชจ๋ธ ID ๋Œ€์‹  ์‚ฌ๋žŒ์ด ์ฝ์„ ์ˆ˜ ์žˆ๋Š” ๋ ˆ์ด๋ธ” (์˜ˆ: "Sonnet 4.6")์„ ํ‘œ์‹œํ•ฉ๋‹ˆ๋‹ค +- `/resume`๋Š” `/continue` ๋ณ„์นญ์„ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค +- MCP ํ”„๋กฌํ”„ํŠธ๋Š” `/mcp____` ๋ช…๋ น์–ด ( [MCP ํ”„๋กฌํ”„ํŠธ๋ฅผ ๋ช…๋ น์–ด๋กœ](#mcp-ํ”„๋กฌํ”„ํŠธ๋ฅผ-๋ช…๋ น์–ด๋กœ) ์ฐธ์กฐ)๋กœ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค +- `/team-onboarding`์ด ํŒ€์› ์˜จ๋ณด๋”ฉ ๊ฐ€์ด๋“œ๋ฅผ ์ž๋™ ์ƒ์„ฑํ•˜๊ธฐ ์œ„ํ•ด ์ถ”๊ฐ€๋˜์—ˆ์Šต๋‹ˆ๋‹ค (v2.1.101) +- `/tui` ๋ช…๋ น์–ด๊ฐ€ ๊นœ๋ฐ•์ž„ ์—†๋Š” ์ „์ฒด ํ™”๋ฉด TUI ๋ Œ๋”๋ง์„ ์œ„ํ•ด ์ถ”๊ฐ€๋˜์—ˆ์Šต๋‹ˆ๋‹ค (v2.1.110) +- `/focus` ๋ช…๋ น์–ด๊ฐ€ ํฌ์ปค์Šค ๋ทฐ ์ „ํ™˜์„ ์œ„ํ•ด ์ถ”๊ฐ€๋˜์—ˆ์Šต๋‹ˆ๋‹ค; `Ctrl+O`๋Š” ์ด์ œ ์ž์„ธํ•œ ๋Œ€ํ™”๋ก๋งŒ ์ „ํ™˜ํ•ฉ๋‹ˆ๋‹ค (v2.1.110) +- `/recap` ๋ช…๋ น์–ด๊ฐ€ ์„ธ์…˜ ์ปจํ…์ŠคํŠธ ์š”์•ฝ์„ ์ˆ˜๋™์œผ๋กœ ํŠธ๋ฆฌ๊ฑฐํ•˜๊ธฐ ์œ„ํ•ด ์ถ”๊ฐ€๋˜์—ˆ์Šต๋‹ˆ๋‹ค (v2.1.108) +- `/undo`๊ฐ€ `/rewind`์˜ ๋ณ„์นญ์œผ๋กœ ์ถ”๊ฐ€๋˜์—ˆ์Šต๋‹ˆ๋‹ค (v2.1.108) +- `/proactive`๊ฐ€ `/loop`์˜ ๋ณ„์นญ์œผ๋กœ ์ถ”๊ฐ€๋˜์—ˆ์Šต๋‹ˆ๋‹ค (v2.1.105) +- `/effort`๋Š” ๋Œ€ํ™”ํ˜• ํ™”์‚ดํ‘œ ํ‚ค ์Šฌ๋ผ์ด๋”์™€ `high`์™€ `max` ์‚ฌ์ด์˜ ์ƒˆ๋กœ์šด `xhigh` ์ˆ˜์ค€์„ ์–ป์—ˆ์Šต๋‹ˆ๋‹ค; Opus 4.7 ํ”Œ๋žœ์˜ ๊ธฐ๋ณธ ๋…ธ๋ ฅ์€ `xhigh`๋กœ ์ƒํ–ฅ ์กฐ์ •๋˜์—ˆ์Šต๋‹ˆ๋‹ค (v2.1.111). Opus 4.8์˜ ๊ธฐ๋ณธ๊ฐ’์€ `high`์ž…๋‹ˆ๋‹ค (v2.1.154) +- `/ultrareview`๊ฐ€ ํฌ๊ด„์ ์ธ ํด๋ผ์šฐ๋“œ ๊ธฐ๋ฐ˜ ๋‹ค์ค‘ ์—์ด์ „ํŠธ ์ฝ”๋“œ ๊ฒ€ํ† ๋ฅผ ์œ„ํ•ด ์ถ”๊ฐ€๋˜์—ˆ์Šต๋‹ˆ๋‹ค (v2.1.111) +- `/less-permission-prompts`๊ฐ€ Bash/MCP ๋„๊ตฌ ํ˜ธ์ถœ์„ ๋ถ„์„ํ•˜๊ณ  `.claude/settings.json`์˜ ํ—ˆ์šฉ ๋ชฉ๋ก์„ ํ†ตํ•ด ๊ถŒํ•œ ํ”„๋กฌํ”„ํŠธ๋ฅผ ์ค„์ด๊ธฐ ์œ„ํ•ด ์ถ”๊ฐ€๋˜์—ˆ์Šต๋‹ˆ๋‹ค (v2.1.111) +- ์ž๋™ ๋ชจ๋“œ๋Š” Opus 4.7์˜ Max ๊ตฌ๋…์ž์—๊ฒŒ `--enable-auto-mode` ํ”Œ๋ž˜๊ทธ๊ฐ€ ๋” ์ด์ƒ ํ•„์š”ํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค (v2.1.112) +- `/goal`์ด ์ถ”๊ฐ€๋จ โ€” Claude๊ฐ€ ์—ฌ๋Ÿฌ ํ„ด์— ๊ฑธ์ณ ๋ชฉํ‘œ๋ฅผ ๋‹ฌ์„ฑํ•˜๊ธฐ ์œ„ํ•ด ๋…ธ๋ ฅํ•˜๋Š” ์„ธ์…˜ ์ˆ˜์ค€ ์™„๋ฃŒ ์กฐ๊ฑด; ์‹ค์‹œ๊ฐ„ ์˜ค๋ฒ„๋ ˆ์ด๋Š” ๊ฒฝ๊ณผ ์‹œ๊ฐ„, ํ„ด ์ˆ˜, ํ† ํฐ ์‚ฌ์šฉ๋Ÿ‰์„ ๋ณด์—ฌ์ค๋‹ˆ๋‹ค (v2.1.139) +- `/scroll-speed`๊ฐ€ ์ถ”๊ฐ€๋จ โ€” TUI ๋ผ์ด๋ธŒ ๋ฏธ๋ฆฌ๋ณด๊ธฐ ์ฐฝ์˜ ๋งˆ์šฐ์Šค ํœ  ์Šคํฌ๋กค ์†๋„๋ฅผ ์กฐ์ •ํ•ฉ๋‹ˆ๋‹ค; ๋จธ์‹ ๋ณ„๋กœ ์œ ์ง€๋ฉ๋‹ˆ๋‹ค (v2.1.139) +- `/reload-skills`๊ฐ€ ์ถ”๊ฐ€๋จ โ€” ์„ธ์…˜์„ ๋‹ค์‹œ ์‹œ์ž‘ํ•˜์ง€ ์•Š๊ณ  ์Šคํ‚ฌ ๋””๋ ‰ํ„ฐ๋ฆฌ๋ฅผ ๋‹ค์‹œ ์Šค์บ”ํ•ฉ๋‹ˆ๋‹ค (v2.1.152) +- `/model`์€ ์ด์ œ ์„ ํƒํ•œ ๋ชจ๋ธ์„ ์ƒˆ ์„ธ์…˜์˜ ๊ธฐ๋ณธ๊ฐ’์œผ๋กœ ์ €์žฅํ•ฉ๋‹ˆ๋‹ค; ์„ธ์…˜ ์ „์šฉ์œผ๋กœ `s`๋ฅผ ๋ˆ„๋ฅด์‹ญ์‹œ์˜ค (ํ‚ค ๋ฐ”์ธ๋”ฉ `modelPicker:setAsDefault` โ†’ `modelPicker:thisSessionOnly`) (v2.1.153) +- `/workflows`๊ฐ€ ์ถ”๊ฐ€๋จ โ€” ์‹คํ–‰ ์ค‘์ด๊ฑฐ๋‚˜ ์™„๋ฃŒ๋œ ๋™์  ์›Œํฌํ”Œ๋กœ์šฐ ์‹คํ–‰์„ ๋ด…๋‹ˆ๋‹ค (v2.1.154) +- `/simplify`๊ฐ€ `/code-review`์˜ ๋ฒ„๊ทธ ์ฐพ๊ธฐ์™€๋Š” ๋ณ„๊ฐœ๋กœ ๋ณ„๋„์˜ ์ •๋ฆฌ ์ „์šฉ ๊ฒ€ํ†  ๋ช…๋ น์–ด (์žฌ์‚ฌ์šฉ / ๋‹จ์ˆœํ™” / ํšจ์œจ์„ฑ / ๊ณ ๋„)๋กœ ๋Œ์•„์™”์Šต๋‹ˆ๋‹ค (v2.1.154) + +### `/goal` โ€” ์„ธ์…˜ ์ˆ˜์ค€ ์™„๋ฃŒ ์กฐ๊ฑด + +> **v2.1.139์— ์ƒˆ๋กœ ์ถ”๊ฐ€** + +`/goal`์„ ์‚ฌ์šฉํ•˜์—ฌ ํ˜„์žฌ ์„ธ์…˜์˜ ์™„๋ฃŒ ์กฐ๊ฑด์„ ๋“ฑ๋กํ•˜์‹ญ์‹œ์˜ค. Claude๋Š” ์—ฌ๋Ÿฌ ํ„ด์— ๊ฑธ์ณ ์ด๋ฅผ ๋‹ฌ์„ฑํ•˜๊ธฐ ์œ„ํ•ด ๋…ธ๋ ฅํ•˜๋ฉฐ, ์˜ค๋ฒ„๋ ˆ์ด ํŒจ๋„์€ ๊ฒฝ๊ณผ ์‹œ๊ฐ„, ํ„ด ์ˆ˜, ์‚ฌ์šฉ๋œ ํ† ํฐ์„ ๋ณด์—ฌ์ค๋‹ˆ๋‹ค. `/goal clear`๋กœ ์ง€์šธ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ๋Œ€ํ™”ํ˜• ๋ชจ๋“œ, `claude -p`, ์›๊ฒฉ ์ œ์–ด์—์„œ ์ž‘๋™ํ•ฉ๋‹ˆ๋‹ค. + +``` +User: /goal Migrate the payments service from REST to gRPC and get the integration tests passing. +Claude: Goal registered. I'll work toward this until you clear it. +[Goal panel: โฑ 0s ยท turns 0 ยท tokens 0] + +User: start by listing the REST endpoints +Claude: [does the work, panel updates] +``` + +### `/team-onboarding` โ€” ํŒ€์› ์˜จ๋ณด๋”ฉ ๊ฐ€์ด๋“œ + +> **v2.1.101์— ์ƒˆ๋กœ ์ถ”๊ฐ€** + +`/team-onboarding`์„ ์‚ฌ์šฉํ•˜์—ฌ ํ”„๋กœ์ ํŠธ์˜ ๋กœ์ปฌ Claude Code ์‚ฌ์šฉ๋Ÿ‰์—์„œ ํŒ€์› ์˜จ๋ณด๋”ฉ ๊ฐ€์ด๋“œ๋ฅผ ์ƒ์„ฑํ•˜์‹ญ์‹œ์˜ค. ์ด ๋ช…๋ น์–ด๋Š” `CLAUDE.md`, ์„ค์น˜๋œ ์Šคํ‚ฌ, ์„œ๋ธŒ ์—์ด์ „ํŠธ, ํ›„ํฌ ๋ฐ ์ตœ๊ทผ ์›Œํฌํ”Œ๋กœ์šฐ๋ฅผ ๊ฒ€์‚ฌํ•œ ๋‹ค์Œ, ์‹ ๊ทœ ๊ฐœ๋ฐœ์ž๊ฐ€ ๋น ๋ฅด๊ฒŒ ์ƒ์‚ฐ์„ฑ์„ ๋†’์ผ ์ˆ˜ ์žˆ๋„๋ก ๋•๋Š” ์˜จ๋ณด๋”ฉ ๋ฌธ์„œ๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. + +์ด๊ฒƒ์€ ๋‚ด์žฅ ๋ช…๋ น์–ด์ด๋ฏ€๋กœ ์„ค์น˜ํ•  ํ•„์š”๊ฐ€ ์—†์Šต๋‹ˆ๋‹ค. + +**์‚ฌ์šฉ๋ฒ•:** + +```bash +claude /team-onboarding +``` + +์ƒ์„ฑ๋œ ๊ฐ€์ด๋“œ๋Š” ๋‹ค์Œ์„ ์š”์•ฝํ•ฉ๋‹ˆ๋‹ค: + +- [`CLAUDE.md`](../02-memory/README.md)์˜ ํ”„๋กœ์ ํŠธ ๋ชฉ์  ๋ฐ ์ฃผ์š” ๊ทœ์น™ +- ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ [์Šคํ‚ฌ](../03-skills/README.md) ๋ฐ ์ž๋™ ํ˜ธ์ถœ ์‹œ๊ธฐ +- ๊ตฌ์„ฑ๋œ [์„œ๋ธŒ ์—์ด์ „ํŠธ](../04-subagents/README.md) ๋ฐ ๊ทธ ์ฑ…์ž„ +- ์ผ๋ฐ˜์ ์ธ ์ด๋ฒคํŠธ์—์„œ ์‹คํ–‰๋˜๋Š” [ํ›„ํฌ](../06-hooks/README.md) +- ์‹ ๊ทœ ์‚ฌ์šฉ์ž๊ฐ€ ์•Œ์•„์•ผ ํ•  ์ผ๋ฐ˜์ ์ธ ์›Œํฌํ”Œ๋กœ์šฐ + +**๊ฐ€์šฉ์„ฑ:** Claude Code v2.1.101 (2026๋…„ 4์›” 11์ผ)์— ์ถœ์‹œ๋˜์—ˆ์Šต๋‹ˆ๋‹ค. + +## ์‚ฌ์šฉ์ž ์ •์˜ ๋ช…๋ น์–ด (์ด์ œ ์Šคํ‚ฌ) + +์‚ฌ์šฉ์ž ์ •์˜ ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด๋Š” **์Šคํ‚ฌ๋กœ ํ†ตํ•ฉ**๋˜์—ˆ์Šต๋‹ˆ๋‹ค. ๋‘ ๊ฐ€์ง€ ์ ‘๊ทผ ๋ฐฉ์‹ ๋ชจ๋‘ `/command-name`์œผ๋กœ ํ˜ธ์ถœํ•  ์ˆ˜ ์žˆ๋Š” ๋ช…๋ น์–ด๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค: + +| ์ ‘๊ทผ ๋ฐฉ์‹ | ์œ„์น˜ | ์ƒํƒœ | +|----------|----------|--------| +| **์Šคํ‚ฌ (๊ถŒ์žฅ)** | `.claude/skills//SKILL.md` | ํ˜„์žฌ ํ‘œ์ค€ | +| **๋ ˆ๊ฑฐ์‹œ ๋ช…๋ น์–ด** | `.claude/commands/.md` | ์—ฌ์ „ํžˆ ์ž‘๋™ | + +์Šคํ‚ฌ๊ณผ ๋ช…๋ น์–ด๊ฐ€ ๊ฐ™์€ ์ด๋ฆ„์„ ๊ณต์œ ํ•˜๋Š” ๊ฒฝ์šฐ, **์Šคํ‚ฌ์ด ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค**. ์˜ˆ๋ฅผ ๋“ค์–ด, `.claude/commands/review.md`์™€ `.claude/skills/review/SKILL.md`๊ฐ€ ๋ชจ๋‘ ์กด์žฌํ•˜๋Š” ๊ฒฝ์šฐ, ์Šคํ‚ฌ ๋ฒ„์ „์ด ์‚ฌ์šฉ๋ฉ๋‹ˆ๋‹ค. + +### ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ ๊ฒฝ๋กœ + +๊ธฐ์กด `.claude/commands/` ํŒŒ์ผ์€ ๋ณ€๊ฒฝ ์—†์ด ๊ณ„์† ์ž‘๋™ํ•ฉ๋‹ˆ๋‹ค. ์Šคํ‚ฌ๋กœ ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ํ•˜๋ ค๋ฉด: + +**์ด์ „ (๋ช…๋ น์–ด):** +``` +.claude/commands/optimize.md +``` + +**์ดํ›„ (์Šคํ‚ฌ):** +``` +.claude/skills/optimize/SKILL.md +``` + +### ์™œ ์Šคํ‚ฌ์ธ๊ฐ€? + +์Šคํ‚ฌ์€ ๋ ˆ๊ฑฐ์‹œ ๋ช…๋ น์–ด์— ๋น„ํ•ด ์ถ”๊ฐ€ ๊ธฐ๋Šฅ์„ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค: + +- **๋””๋ ‰ํ„ฐ๋ฆฌ ๊ตฌ์กฐ**: ์Šคํฌ๋ฆฝํŠธ, ํ…œํ”Œ๋ฆฟ ๋ฐ ์ฐธ์กฐ ํŒŒ์ผ ๋ฒˆ๋“ค +- **์ž๋™ ํ˜ธ์ถœ**: Claude๋Š” ๊ด€๋ จ์„ฑ์ด ์žˆ์„ ๋•Œ ์Šคํ‚ฌ์„ ์ž๋™์œผ๋กœ ํŠธ๋ฆฌ๊ฑฐํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค +- **ํ˜ธ์ถœ ์ œ์–ด**: ์‚ฌ์šฉ์ž, Claude ๋˜๋Š” ๋‘˜ ๋‹ค ํ˜ธ์ถœํ•  ์ˆ˜ ์žˆ๋Š”์ง€ ์„ ํƒ +- **์„œ๋ธŒ ์—์ด์ „ํŠธ ์‹คํ–‰**: `context: fork`๋กœ ๊ฒฉ๋ฆฌ๋œ ์ปจํ…์ŠคํŠธ์—์„œ ์Šคํ‚ฌ ์‹คํ–‰ +- **์ ์ง„์  ๊ณต๊ฐœ**: ํ•„์š”ํ•  ๋•Œ๋งŒ ์ถ”๊ฐ€ ํŒŒ์ผ ๋กœ๋“œ + +### ์Šคํ‚ฌ๋กœ ์‚ฌ์šฉ์ž ์ •์˜ ๋ช…๋ น์–ด ์ƒ์„ฑํ•˜๊ธฐ + +`SKILL.md` ํŒŒ์ผ์ด ์žˆ๋Š” ๋””๋ ‰ํ„ฐ๋ฆฌ๋ฅผ ์ƒ์„ฑํ•˜์‹ญ์‹œ์˜ค: + +```bash +mkdir -p .claude/skills/my-command +``` + +**ํŒŒ์ผ:** `.claude/skills/my-command/SKILL.md` + +```yaml +--- +name: my-command +description: What this command does and when to use it +--- + +# My Command + +Instructions for Claude to follow when this command is invoked. + +1. First step +2. Second step +3. Third step +``` + +### ํ”„๋ก ํŠธ๋งคํ„ฐ ์ฐธ์กฐ + +| ํ•„๋“œ | ๋ชฉ์  | ๊ธฐ๋ณธ๊ฐ’ | +|-------|---------|---------| +| `name` | ๋ช…๋ น์–ด ์ด๋ฆ„ ( `/name`์ด ๋จ) | ๋””๋ ‰ํ„ฐ๋ฆฌ ์ด๋ฆ„ | +| `description` | ๊ฐ„๋žตํ•œ ์„ค๋ช… (Claude๊ฐ€ ์–ธ์ œ ์‚ฌ์šฉํ•ด์•ผ ํ• ์ง€ ์•„๋Š” ๋ฐ ๋„์›€์ด ๋จ) | ์ฒซ ๋ฒˆ์งธ ๋‹จ๋ฝ | +| `argument-hint` | ์ž๋™ ์™„์„ฑ์„ ์œ„ํ•œ ์˜ˆ์ƒ ์ธ์ˆ˜ | ์—†์Œ | +| `allowed-tools` | ๋ช…๋ น์–ด๊ฐ€ ๊ถŒํ•œ ์—†์ด ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ๋Š” ๋„๊ตฌ | ์ƒ์†๋จ | +| `model` | ์‚ฌ์šฉํ•  ํŠน์ • ๋ชจ๋ธ | ์ƒ์†๋จ | +| `disable-model-invocation` | `true`์ธ ๊ฒฝ์šฐ, ์‚ฌ์šฉ์ž๋งŒ ํ˜ธ์ถœํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค (Claude๋Š” ์•„๋‹˜) | `false` | +| `user-invocable` | `false`์ธ ๊ฒฝ์šฐ, `/` ๋ฉ”๋‰ด์—์„œ ์ˆจ๊น๋‹ˆ๋‹ค | `true` | +| `context` | `fork`๋กœ ์„ค์ •ํ•˜๋ฉด ๊ฒฉ๋ฆฌ๋œ ์„œ๋ธŒ ์—์ด์ „ํŠธ์—์„œ ์‹คํ–‰๋ฉ๋‹ˆ๋‹ค | ์—†์Œ | +| `agent` | `context: fork`๋ฅผ ์‚ฌ์šฉํ•  ๋•Œ์˜ ์—์ด์ „ํŠธ ์œ ํ˜• | `general-purpose` | +| `hooks` | ์Šคํ‚ฌ ๋ฒ”์œ„ ํ›„ํฌ (PreToolUse, PostToolUse, Stop) | ์—†์Œ | + +### ์ธ์ˆ˜ + +๋ช…๋ น์–ด๋Š” ์ธ์ˆ˜๋ฅผ ๋ฐ›์„ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค: + +**`$ARGUMENTS`๋ฅผ ์‚ฌ์šฉํ•œ ๋ชจ๋“  ์ธ์ˆ˜:** + +```yaml +--- +name: fix-issue +description: Fix a GitHub issue by number +--- + +Fix issue #$ARGUMENTS following our coding standards +``` + +์‚ฌ์šฉ๋ฒ•: `/fix-issue 123` โ†’ `$ARGUMENTS`๊ฐ€ "123"์ด ๋ฉ๋‹ˆ๋‹ค + +**`$0`, `$1` ๋“ฑ์„ ์‚ฌ์šฉํ•œ ๊ฐœ๋ณ„ ์ธ์ˆ˜:** + +```yaml +--- +name: review-pr +description: Review a PR with priority +--- + +Review PR #$0 with priority $1 +``` + +์‚ฌ์šฉ๋ฒ•: `/review-pr 456 high` โ†’ `$0`="456", `$1`="high" + +### ์‰˜ ๋ช…๋ น์–ด๋ฅผ ํ†ตํ•œ ๋™์  ์ปจํ…์ŠคํŠธ + +`` !`command` ``๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ํ”„๋กฌํ”„ํŠธ ์ „์— bash ๋ช…๋ น์–ด๋ฅผ ์‹คํ–‰ํ•˜์‹ญ์‹œ์˜ค: + +```yaml +--- +name: commit +description: Create a git commit with context +allowed-tools: Bash(git *) +--- + +## Context + +- Current git status: !`git status` +- Current git diff: !`git diff HEAD` +- Current branch: !`git branch --show-current` +- Recent commits: !`git log --oneline -5` + +## Your task + +Based on the above changes, create a single git commit. +``` + +### ํŒŒ์ผ ์ฐธ์กฐ + +`@`๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ํŒŒ์ผ ๋‚ด์šฉ์„ ํฌํ•จํ•˜์‹ญ์‹œ์˜ค: + +```markdown +Review the implementation in @src/utils/helpers.js +Compare @src/old-version.js with @src/new-version.js +``` + +## ํ”Œ๋Ÿฌ๊ทธ์ธ ๋ช…๋ น์–ด + +ํ”Œ๋Ÿฌ๊ทธ์ธ์€ ์‚ฌ์šฉ์ž ์ •์˜ ๋ช…๋ น์–ด๋ฅผ ์ œ๊ณตํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค: + +``` +/plugin-name:command-name +``` + +๋˜๋Š” ์ด๋ฆ„ ์ถฉ๋Œ์ด ์—†๋Š” ๊ฒฝ์šฐ ๋‹จ์ˆœํžˆ `/command-name`์ž…๋‹ˆ๋‹ค. + +**์˜ˆ์‹œ:** +```bash +/frontend-design:frontend-design +/commit-commands:commit +``` + +## MCP ํ”„๋กฌํ”„ํŠธ๋ฅผ ๋ช…๋ น์–ด๋กœ + +MCP ์„œ๋ฒ„๋Š” ํ”„๋กฌํ”„ํŠธ๋ฅผ ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด๋กœ ๋…ธ์ถœํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค: + +``` +/mcp____ [arguments] +``` + +**์˜ˆ์‹œ:** +```bash +/mcp__github__list_prs +/mcp__github__pr_review 456 +/mcp__jira__create_issue "Bug title" high +``` + +### MCP ๊ถŒํ•œ ๊ตฌ๋ฌธ + +๊ถŒํ•œ์—์„œ MCP ์„œ๋ฒ„ ์•ก์„ธ์Šค๋ฅผ ์ œ์–ดํ•ฉ๋‹ˆ๋‹ค: + +- `mcp__github` - ์ „์ฒด GitHub MCP ์„œ๋ฒ„ ์•ก์„ธ์Šค +- `mcp__github__*` - ๋ชจ๋“  ๋„๊ตฌ์— ๋Œ€ํ•œ ์™€์ผ๋“œ์นด๋“œ ์•ก์„ธ์Šค +- `mcp__github__get_issue` - ํŠน์ • ๋„๊ตฌ ์•ก์„ธ์Šค + +## ๋ช…๋ น์–ด ์•„ํ‚คํ…์ฒ˜ + +```mermaid +graph TD + A["User Input: /command-name"] --> B{"Command Type?"} + B -->|Built-in| C["Execute Built-in"] + B -->|Skill| D["Load SKILL.md"] + B -->|Plugin| E["Load Plugin Command"] + B -->|MCP| F["Execute MCP Prompt"] + + D --> G["Parse Frontmatter"] + G --> H["Substitute Variables"] + H --> I["Execute Shell Commands"] + I --> J["Send to Claude"] + J --> K["Return Results"] +``` + +## ๋ช…๋ น์–ด ์ˆ˜๋ช… ์ฃผ๊ธฐ + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude Code + participant FS as File System + participant CLI as Shell/Bash + + User->>Claude: Types /optimize + Claude->>FS: Searches .claude/skills/ and .claude/commands/ + FS-->>Claude: Returns optimize/SKILL.md + Claude->>Claude: Parses frontmatter + Claude->>CLI: Executes !`command` substitutions + CLI-->>Claude: Command outputs + Claude->>Claude: Substitutes $ARGUMENTS + Claude->>User: Processes prompt + Claude->>User: Returns results +``` + +## ์ด ํด๋”์—์„œ ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ๋ช…๋ น์–ด + +์ด ์˜ˆ์‹œ ๋ช…๋ น์–ด๋Š” ์Šคํ‚ฌ ๋˜๋Š” ๋ ˆ๊ฑฐ์‹œ ๋ช…๋ น์–ด๋กœ ์„ค์น˜ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +### 1. `/optimize` - ์ฝ”๋“œ ์ตœ์ ํ™” + +์„ฑ๋Šฅ ๋ฌธ์ œ, ๋ฉ”๋ชจ๋ฆฌ ๋ˆ„์ˆ˜ ๋ฐ ์ตœ์ ํ™” ๊ธฐํšŒ๋ฅผ ์œ„ํ•ด ์ฝ”๋“œ๋ฅผ ๋ถ„์„ํ•ฉ๋‹ˆ๋‹ค. + +**์‚ฌ์šฉ๋ฒ•:** +``` +/optimize +[Paste your code] +``` + +### 2. `/pr` - Pull Request ์ค€๋น„ + +๋ฆฐํŒ…, ํ…Œ์ŠคํŠธ, ์ปค๋ฐ‹ ํ˜•์‹ ์ง€์ •์„ ํฌํ•จํ•œ PR ์ค€๋น„ ์ฒดํฌ๋ฆฌ์ŠคํŠธ๋ฅผ ์•ˆ๋‚ดํ•ฉ๋‹ˆ๋‹ค. + +**์‚ฌ์šฉ๋ฒ•:** +``` +/pr +``` + +**์Šคํฌ๋ฆฐ์ƒท:** +![/pr](pr-slash-command.png) + +### 3. `/generate-api-docs` - API ๋ฌธ์„œ ์ƒ์„ฑ๊ธฐ + +์†Œ์Šค ์ฝ”๋“œ์—์„œ ํฌ๊ด„์ ์ธ API ๋ฌธ์„œ๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. + +**์‚ฌ์šฉ๋ฒ•:** +``` +/generate-api-docs +``` + +### 4. `/commit` - ์ปจํ…์ŠคํŠธ๊ฐ€ ์žˆ๋Š” Git ์ปค๋ฐ‹ + +๋ฆฌํฌ์ง€ํ† ๋ฆฌ์˜ ๋™์  ์ปจํ…์ŠคํŠธ๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ Git ์ปค๋ฐ‹์„ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. + +**์‚ฌ์šฉ๋ฒ•:** +``` +/commit [optional message] +``` + +### 5. `/push-all` - ์Šคํ…Œ์ด์ง€, ์ปค๋ฐ‹ ๋ฐ ํ‘ธ์‹œ + +๋ชจ๋“  ๋ณ€๊ฒฝ ์‚ฌํ•ญ์„ ์Šคํ…Œ์ด์ง•ํ•˜๊ณ , ์ปค๋ฐ‹์„ ์ƒ์„ฑํ•˜๋ฉฐ, ์•ˆ์ „ ๊ฒ€์‚ฌ๋ฅผ ํ†ตํ•ด ์›๊ฒฉ์œผ๋กœ ํ‘ธ์‹œํ•ฉ๋‹ˆ๋‹ค. + +**์‚ฌ์šฉ๋ฒ•:** +``` +/push-all +``` + +**์•ˆ์ „ ๊ฒ€์‚ฌ:** +- ์‹œํฌ๋ฆฟ: `.env*`, `*.key`, `*.pem`, `credentials.json` +- API ํ‚ค: ์‹ค์ œ ํ‚ค์™€ ํ”Œ๋ ˆ์ด์Šคํ™€๋” ๊ฐ์ง€ +- ๋Œ€์šฉ๋Ÿ‰ ํŒŒ์ผ: Git LFS ์—†์ด `>10MB` +- ๋นŒ๋“œ ์•„ํ‹ฐํŒฉํŠธ: `node_modules/`, `dist/`, `__pycache__/` + +### 6. `/doc-refactor` - ๋ฌธ์„œ ์žฌ๊ตฌ์„ฑ + +๋ช…ํ™•์„ฑ๊ณผ ์ ‘๊ทผ์„ฑ์„ ์œ„ํ•ด ํ”„๋กœ์ ํŠธ ๋ฌธ์„œ๋ฅผ ์žฌ๊ตฌ์„ฑํ•ฉ๋‹ˆ๋‹ค. + +**์‚ฌ์šฉ๋ฒ•:** +``` +/doc-refactor +``` + +### 7. `/setup-ci-cd` - CI/CD ํŒŒ์ดํ”„๋ผ์ธ ์„ค์ • + +ํ’ˆ์งˆ ๋ณด์ฆ์„ ์œ„ํ•ด Pre-commit Hook ๋ฐ GitHub Actions๋ฅผ ๊ตฌํ˜„ํ•ฉ๋‹ˆ๋‹ค. + +**์‚ฌ์šฉ๋ฒ•:** +``` +/setup-ci-cd +``` + +### 8. `/unit-test-expand` - ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€ ํ™•์žฅ + +ํ…Œ์ŠคํŠธ๋˜์ง€ ์•Š์€ ๋ถ„๊ธฐ ๋ฐ ์—ฃ์ง€ ์ผ€์ด์Šค๋ฅผ ๋Œ€์ƒ์œผ๋กœ ํ•˜์—ฌ ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€๋ฅผ ์ฆ๊ฐ€์‹œํ‚ต๋‹ˆ๋‹ค. + +**์‚ฌ์šฉ๋ฒ•:** +``` +/unit-test-expand +``` + +## ์„ค์น˜ + +### ์Šคํ‚ฌ๋กœ (๊ถŒ์žฅ) + +์Šคํ‚ฌ ๋””๋ ‰ํ„ฐ๋ฆฌ์— ๋ณต์‚ฌํ•ฉ๋‹ˆ๋‹ค: + +```bash +# Create skills directory +mkdir -p .claude/skills + +# For each command file, create a skill directory +for cmd in optimize pr commit; do + mkdir -p .claude/skills/$cmd + cp 01-slash-commands/$cmd.md .claude/skills/$cmd/SKILL.md +done +``` + +### ๋ ˆ๊ฑฐ์‹œ ๋ช…๋ น์–ด๋กœ + +๋ช…๋ น์–ด ๋””๋ ‰ํ„ฐ๋ฆฌ์— ๋ณต์‚ฌํ•ฉ๋‹ˆ๋‹ค: + +```bash +# Project-wide (team) +mkdir -p .claude/commands +cp 01-slash-commands/*.md .claude/commands/ + +# Personal use +mkdir -p ~/.claude/commands +cp 01-slash-commands/*.md ~/.claude/commands/ +``` + +## ๋‚˜๋งŒ์˜ ๋ช…๋ น์–ด ์ƒ์„ฑ + +### ์Šคํ‚ฌ ํ…œํ”Œ๋ฆฟ (๊ถŒ์žฅ) + +`.claude/skills/my-command/SKILL.md`๋ฅผ ์ƒ์„ฑํ•˜์‹ญ์‹œ์˜ค: + +```yaml +--- +name: my-command +description: What this command does. Use when [trigger conditions]. +argument-hint: [optional-args] +allowed-tools: Bash(npm *), Read, Grep +--- + +# Command Title + +## Context + +- Current branch: !`git branch --show-current` +- Related files: @package.json + +## Instructions + +1. First step +2. Second step with argument: $ARGUMENTS +3. Third step + +## Output Format + +- How to format the response +- What to include +``` + +### ์‚ฌ์šฉ์ž ์ „์šฉ ๋ช…๋ น์–ด (์ž๋™ ํ˜ธ์ถœ ์—†์Œ) + +Claude๊ฐ€ ์ž๋™์œผ๋กœ ํŠธ๋ฆฌ๊ฑฐํ•ด์„œ๋Š” ์•ˆ ๋˜๋Š” ๋ถ€์ž‘์šฉ์ด ์žˆ๋Š” ๋ช…๋ น์–ด์˜ ๊ฒฝ์šฐ: + +```yaml +--- +name: deploy +description: Deploy to production +disable-model-invocation: true +allowed-tools: Bash(npm *), Bash(git *) +--- + +Deploy the application to production: + +1. Run tests +2. Build application +3. Push to deployment target +4. Verify deployment +``` + +## ๋ชจ๋ฒ” ์‚ฌ๋ก€ + +| ๊ถŒ์žฅ ์‚ฌํ•ญ | ๋น„๊ถŒ์žฅ ์‚ฌํ•ญ | +|------|---------| +| ๋ช…ํ™•ํ•˜๊ณ  ํ–‰๋™ ์ง€ํ–ฅ์ ์ธ ์ด๋ฆ„์„ ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค | ์ผํšŒ์„ฑ ์ž‘์—…์„ ์œ„ํ•œ ๋ช…๋ น์–ด๋ฅผ ์ƒ์„ฑํ•˜์‹ญ์‹œ์˜ค | +| ํŠธ๋ฆฌ๊ฑฐ ์กฐ๊ฑด์ด ์žˆ๋Š” `description`์„ ํฌํ•จํ•˜์‹ญ์‹œ์˜ค | ๋ช…๋ น์–ด์— ๋ณต์žกํ•œ ๋…ผ๋ฆฌ๋ฅผ ๊ตฌ์ถ•ํ•˜์‹ญ์‹œ์˜ค | +| ๋ช…๋ น์–ด๋ฅผ ๋‹จ์ผ ์ž‘์—…์— ์ง‘์ค‘ํ•˜์‹ญ์‹œ์˜ค | ๋ฏผ๊ฐํ•œ ์ •๋ณด๋ฅผ ํ•˜๋“œ์ฝ”๋”ฉํ•˜์‹ญ์‹œ์˜ค | +| ๋ถ€์ž‘์šฉ์ด ์žˆ๋Š” ๊ฒฝ์šฐ `disable-model-invocation`์„ ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค | ์„ค๋ช… ํ•„๋“œ๋ฅผ ๊ฑด๋„ˆ๋›ฐ์‹ญ์‹œ์˜ค | +| ๋™์  ์ปจํ…์ŠคํŠธ์— `!` ์ ‘๋‘์‚ฌ๋ฅผ ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค | Claude๊ฐ€ ํ˜„์žฌ ์ƒํƒœ๋ฅผ ์•ˆ๋‹ค๊ณ  ๊ฐ€์ •ํ•˜์‹ญ์‹œ์˜ค | +| ๊ด€๋ จ ํŒŒ์ผ์„ ์Šคํ‚ฌ ๋””๋ ‰ํ„ฐ๋ฆฌ์— ์ •๋ฆฌํ•˜์‹ญ์‹œ์˜ค | ๋ชจ๋“  ๊ฒƒ์„ ํ•˜๋‚˜์˜ ํŒŒ์ผ์— ๋„ฃ์œผ์‹ญ์‹œ์˜ค | + +## ๋ฌธ์ œ ํ•ด๊ฒฐ + +### ๋ช…๋ น์–ด๋ฅผ ์ฐพ์„ ์ˆ˜ ์—†์Œ + +**ํ•ด๊ฒฐ์ฑ…:** +- ํŒŒ์ผ์ด `.claude/skills//SKILL.md` ๋˜๋Š” `.claude/commands/.md`์— ์žˆ๋Š”์ง€ ํ™•์ธํ•˜์‹ญ์‹œ์˜ค +- ํ”„๋ก ํŠธ๋งคํ„ฐ์˜ `name` ํ•„๋“œ๊ฐ€ ์˜ˆ์ƒ ๋ช…๋ น์–ด ์ด๋ฆ„๊ณผ ์ผ์น˜ํ•˜๋Š”์ง€ ํ™•์ธํ•˜์‹ญ์‹œ์˜ค +- Claude Code ์„ธ์…˜์„ ๋‹ค์‹œ ์‹œ์ž‘ํ•˜์‹ญ์‹œ์˜ค +- `/help`๋ฅผ ์‹คํ–‰ํ•˜์—ฌ ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ๋ช…๋ น์–ด๋ฅผ ํ™•์ธํ•˜์‹ญ์‹œ์˜ค + +### ๋ช…๋ น์–ด๊ฐ€ ์˜ˆ์ƒ๋Œ€๋กœ ์‹คํ–‰๋˜์ง€ ์•Š์Œ + +**ํ•ด๊ฒฐ์ฑ…:** +- ๋” ๊ตฌ์ฒด์ ์ธ ์ง€์นจ์„ ์ถ”๊ฐ€ํ•˜์‹ญ์‹œ์˜ค +- ์Šคํ‚ฌ ํŒŒ์ผ์— ์˜ˆ์‹œ๋ฅผ ํฌํ•จํ•˜์‹ญ์‹œ์˜ค +- bash ๋ช…๋ น์–ด๋ฅผ ์‚ฌ์šฉํ•˜๋Š” ๊ฒฝ์šฐ `allowed-tools`๋ฅผ ํ™•์ธํ•˜์‹ญ์‹œ์˜ค +- ๋จผ์ € ๊ฐ„๋‹จํ•œ ์ž…๋ ฅ์œผ๋กœ ํ…Œ์ŠคํŠธํ•˜์‹ญ์‹œ์˜ค + +### ์Šคํ‚ฌ๊ณผ ๋ช…๋ น์–ด ์ถฉ๋Œ + +๊ฐ™์€ ์ด๋ฆ„์˜ ์Šคํ‚ฌ๊ณผ ๋ช…๋ น์–ด๊ฐ€ ๋ชจ๋‘ ์กด์žฌํ•˜๋Š” ๊ฒฝ์šฐ, **์Šคํ‚ฌ์ด ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค**. ๋‘˜ ์ค‘ ํ•˜๋‚˜๋ฅผ ์ œ๊ฑฐํ•˜๊ฑฐ๋‚˜ ์ด๋ฆ„์„ ๋ณ€๊ฒฝํ•˜์‹ญ์‹œ์˜ค. + +## ๊ด€๋ จ ๊ฐ€์ด๋“œ + +- **[์Šคํ‚ฌ](../03-skills/)** - ์Šคํ‚ฌ(์ž๋™ ํ˜ธ์ถœ ๊ฐ€๋Šฅํ•œ ๊ธฐ๋Šฅ)์— ๋Œ€ํ•œ ์ „์ฒด ์ฐธ์กฐ +- **[๋ฉ”๋ชจ๋ฆฌ](../02-memory/)** - CLAUDE.md๋ฅผ ์‚ฌ์šฉํ•œ ์˜๊ตฌ ์ปจํ…์ŠคํŠธ +- **[์„œ๋ธŒ ์—์ด์ „ํŠธ](../04-subagents/)** - ์œ„์ž„๋œ AI ์—์ด์ „ํŠธ +- **[ํ”Œ๋Ÿฌ๊ทธ์ธ](../07-plugins/)** - ๋ฒˆ๋“ค ๋ช…๋ น์–ด ์ปฌ๋ ‰์…˜ +- **[ํ›„ํฌ](../06-hooks/)** - ์ด๋ฒคํŠธ ๊ธฐ๋ฐ˜ ์ž๋™ํ™” + +## ์ถ”๊ฐ€ ์ž๋ฃŒ + +- [๊ณต์‹ ๋Œ€ํ™”ํ˜• ๋ชจ๋“œ ๋ฌธ์„œ](https://code.claude.com/docs/en/interactive-mode) - ๋‚ด์žฅ ๋ช…๋ น์–ด ์ฐธ์กฐ +- [๊ณต์‹ ์Šคํ‚ฌ ๋ฌธ์„œ](https://code.claude.com/docs/en/skills) - ์™„์ „ํ•œ ์Šคํ‚ฌ ์ฐธ์กฐ +- [CLI ์ฐธ์กฐ](https://code.claude.com/docs/en/cli-reference) - ๋ช…๋ น์ค„ ์˜ต์…˜ + +--- + +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: 2026๋…„ 6์›” 24์ผ +**Claude Code ๋ฒ„์ „**: 2.1.187 +**์ถœ์ฒ˜**: +- https://code.claude.com/docs/en/slash-commands +- https://code.claude.com/docs/en/interactive-mode +- https://code.claude.com/docs/en/changelog +- https://code.claude.com/docs/en/commands +- https://code.claude.com/docs/en/model-config +- https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md +- https://docs.anthropic.com/en/docs/claude-code/slash-commands +- https://github.com/anthropics/claude-code/releases/tag/v2.1.139 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.144 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.152 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.153 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.154 +**ํ˜ธํ™˜ ๋ชจ๋ธ**: Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5 + +* [Claude How To](../) ๊ฐ€์ด๋“œ ์‹œ๋ฆฌ์ฆˆ์˜ ์ผ๋ถ€์ž…๋‹ˆ๋‹ค* diff --git a/ko/01-slash-commands/commit.md b/ko/01-slash-commands/commit.md new file mode 100644 index 00000000..e82fbe2e --- /dev/null +++ b/ko/01-slash-commands/commit.md @@ -0,0 +1,29 @@ +--- +allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*), Bash(git diff:*) +argument-hint: [message] +description: ์ปจํ…์ŠคํŠธ๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ git ์ปค๋ฐ‹ ์ƒ์„ฑ +--- + +## ์ปจํ…์ŠคํŠธ + +- ํ˜„์žฌ git ์ƒํƒœ: !`git status` +- ํ˜„์žฌ git diff: !`git diff HEAD` +- ํ˜„์žฌ ๋ธŒ๋žœ์น˜: !`git branch --show-current` +- ์ตœ๊ทผ ์ปค๋ฐ‹: !`git log --oneline -10` + +## ๋‹น์‹ ์˜ ์ž‘์—… + +์œ„ ๋ณ€๊ฒฝ ์‚ฌํ•ญ์„ ๋ฐ”ํƒ•์œผ๋กœ ๋‹จ์ผ git ์ปค๋ฐ‹์„ ์ƒ์„ฑํ•˜์„ธ์š”. + +์ธ์ˆ˜๋ฅผ ํ†ตํ•ด ๋ฉ”์‹œ์ง€๊ฐ€ ์ œ๊ณต๋œ ๊ฒฝ์šฐ, ํ•ด๋‹น ๋ฉ”์‹œ์ง€๋ฅผ ์‚ฌ์šฉํ•˜์„ธ์š”: $ARGUMENTS + +๊ทธ๋ ‡์ง€ ์•Š์€ ๊ฒฝ์šฐ, ๋ณ€๊ฒฝ ์‚ฌํ•ญ์„ ๋ถ„์„ํ•˜์—ฌ conventional commits ํ˜•์‹์— ๋งž๋Š” ์ ์ ˆํ•œ ์ปค๋ฐ‹ ๋ฉ”์‹œ์ง€๋ฅผ ์ƒ์„ฑํ•˜์„ธ์š”: +- `feat:` ์ƒˆ๋กœ์šด ๊ธฐ๋Šฅ์šฉ +- `fix:` ๋ฒ„๊ทธ ์ˆ˜์ •์šฉ +- `docs:` ๋ฌธ์„œ ๋ณ€๊ฒฝ์šฉ +- `refactor:` ์ฝ”๋“œ ๋ฆฌํŒฉํ† ๋ง์šฉ +- `test:` ํ…Œ์ŠคํŠธ ์ถ”๊ฐ€์šฉ +- `chore:` ์œ ์ง€๋ณด์ˆ˜ ์ž‘์—…์šฉ + +--- +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: April 9, 2026 diff --git a/ko/01-slash-commands/doc-refactor.md b/ko/01-slash-commands/doc-refactor.md new file mode 100644 index 00000000..ba6363d0 --- /dev/null +++ b/ko/01-slash-commands/doc-refactor.md @@ -0,0 +1,27 @@ +--- +name: ๋ฌธ์„œ ๋ฆฌํŒฉํ„ฐ๋ง +description: ๋ช…ํ™•์„ฑ๊ณผ ์ ‘๊ทผ์„ฑ์„ ์œ„ํ•ด ํ”„๋กœ์ ํŠธ ๋ฌธ์„œ๋ฅผ ์žฌ๊ตฌ์„ฑํ•ฉ๋‹ˆ๋‹ค +tags: ๋ฌธ์„œํ™”, ๋ฆฌํŒฉํ„ฐ๋ง, ์กฐ์งํ™” +--- + +# ๋ฌธ์„œ ๋ฆฌํŒฉํ„ฐ๋ง + +ํ”„๋กœ์ ํŠธ ์œ ํ˜•์— ๋งž์ถฐ ํ”„๋กœ์ ํŠธ ๋ฌธ์„œ ๊ตฌ์กฐ๋ฅผ ๋ฆฌํŒฉํ„ฐ๋งํ•ฉ๋‹ˆ๋‹ค: + +1. **ํ”„๋กœ์ ํŠธ ๋ถ„์„**: ์œ ํ˜•(๋ผ์ด๋ธŒ๋Ÿฌ๋ฆฌ/API/์›น ์•ฑ/CLI/๋งˆ์ดํฌ๋กœ์„œ๋น„์Šค), ์•„ํ‚คํ…์ฒ˜, ์‚ฌ์šฉ์ž ํŽ˜๋ฅด์†Œ๋‚˜ ์‹๋ณ„ +2. **๋ฌธ์„œ ์ค‘์•™ํ™”**: ๊ธฐ์ˆ  ๋ฌธ์„œ๋ฅผ `docs/`๋กœ ์ด๋™ํ•˜๊ณ  ์ ์ ˆํ•œ ์ƒํ˜ธ ์ฐธ์กฐ ์ถ”๊ฐ€ +3. **๋ฃจํŠธ README.md**: ๊ฐœ์š”, ๋น ๋ฅธ ์‹œ์ž‘, ๋ชจ๋“ˆ/์ปดํฌ๋„ŒํŠธ ์š”์•ฝ, ๋ผ์ด์„ ์Šค, ์—ฐ๋ฝ์ฒ˜๋ฅผ ํฌํ•จํ•œ ์ง„์ž…์ ์œผ๋กœ ๊ฐ„์†Œํ™” +4. **์ปดํฌ๋„ŒํŠธ ๋ฌธ์„œ**: ์„ค์ • ๋ฐ ํ…Œ์ŠคํŠธ ์ง€์นจ์ด ํฌํ•จ๋œ ๋ชจ๋“ˆ/ํŒจํ‚ค์ง€/์„œ๋น„์Šค ์ˆ˜์ค€ README ํŒŒ์ผ ์ถ”๊ฐ€ +5. **`docs/` ๊ตฌ์„ฑ**: ๊ด€๋ จ ์นดํ…Œ๊ณ ๋ฆฌ๋ณ„๋กœ ๊ตฌ์„ฑํ•ฉ๋‹ˆ๋‹ค: + - ์•„ํ‚คํ…์ฒ˜, API ์ฐธ์กฐ, ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค, ์„ค๊ณ„, ๋ฌธ์ œ ํ•ด๊ฒฐ, ๋ฐฐํฌ, ๊ธฐ์—ฌ (ํ”„๋กœ์ ํŠธ ์š”๊ตฌ์‚ฌํ•ญ์— ๋งž๊ฒŒ ์กฐ์ •) +6. **๊ฐ€์ด๋“œ ์ƒ์„ฑ** (ํ•ด๋‹นํ•˜๋Š” ํ•ญ๋ชฉ ์„ ํƒ): + - ์‚ฌ์šฉ์ž ๊ฐ€์ด๋“œ: ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜ ์ตœ์ข… ์‚ฌ์šฉ์ž ๋ฌธ์„œ + - API ๋ฌธ์„œ: API ์—”๋“œํฌ์ธํŠธ, ์ธ์ฆ, ์˜ˆ์‹œ + - ๊ฐœ๋ฐœ ๊ฐ€์ด๋“œ: ์„ค์ •, ํ…Œ์ŠคํŠธ, ๊ธฐ์—ฌ ์›Œํฌํ”Œ๋กœ + - ๋ฐฐํฌ ๊ฐ€์ด๋“œ: ์„œ๋น„์Šค/์•ฑ์˜ ํ”„๋กœ๋•์…˜ ๋ฐฐํฌ +7. **Mermaid ์‚ฌ์šฉ**: ๋ชจ๋“  ๋‹ค์ด์–ด๊ทธ๋žจ(์•„ํ‚คํ…์ฒ˜, ํ๋ฆ„, ์Šคํ‚ค๋งˆ)์— Mermaid ์‚ฌ์šฉ + +๋ฌธ์„œ๋Š” ๊ฐ„๊ฒฐํ•˜๊ณ , ์‰ฝ๊ฒŒ ํ›‘์–ด๋ณผ ์ˆ˜ ์žˆ์œผ๋ฉฐ, ํ”„๋กœ์ ํŠธ ์œ ํ˜•์— ๋”ฐ๋ผ ์ƒํ™ฉ์— ๋งž๋Š” ๋‚ด์šฉ์„ ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. + +--- +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: 2026๋…„ 4์›” 9์ผ diff --git a/ko/01-slash-commands/generate-api-docs.md b/ko/01-slash-commands/generate-api-docs.md new file mode 100644 index 00000000..952490e3 --- /dev/null +++ b/ko/01-slash-commands/generate-api-docs.md @@ -0,0 +1,22 @@ +--- +description: ์†Œ์Šค ์ฝ”๋“œ๋กœ๋ถ€ํ„ฐ ํฌ๊ด„์ ์ธ API ๋ฌธ์„œ๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. +--- + +# API ๋ฌธ์„œ ์ƒ์„ฑ๊ธฐ + +๋‹ค์Œ๊ณผ ๊ฐ™์€ ๋ฐฉ์‹์œผ๋กœ API ๋ฌธ์„œ๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค: + +1. `/src/api/`์˜ ๋ชจ๋“  ํŒŒ์ผ์„ ์Šค์บ”ํ•˜์—ฌ +2. ํ•จ์ˆ˜ ์‹œ๊ทธ๋‹ˆ์ฒ˜์™€ JSDoc ์ฃผ์„์„ ์ถ”์ถœํ•˜๊ณ  +3. ์—”๋“œํฌ์ธํŠธ/๋ชจ๋“ˆ๋ณ„๋กœ ์ •๋ฆฌํ•˜๋ฉฐ +4. ์˜ˆ์‹œ๋ฅผ ํฌํ•จํ•œ ๋งˆํฌ๋‹ค์šด์„ ์ƒ์„ฑํ•˜๊ณ  +5. ์š”์ฒญ/์‘๋‹ต ์Šคํ‚ค๋งˆ๋ฅผ ํฌํ•จํ•˜๋ฉฐ +6. ์˜ค๋ฅ˜ ๋ฌธ์„œ๋ฅผ ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค. + +์ถœ๋ ฅ ํ˜•์‹: +- `/docs/api.md`์— ๋งˆํฌ๋‹ค์šด ํŒŒ์ผ ์ƒ์„ฑ +- ๋ชจ๋“  ์—”๋“œํฌ์ธํŠธ์— ๋Œ€ํ•œ curl ์˜ˆ์‹œ ํฌํ•จ +- TypeScript ํƒ€์ž… ์ถ”๊ฐ€ + +--- +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: April 9, 2026 diff --git a/ko/01-slash-commands/optimize.md b/ko/01-slash-commands/optimize.md new file mode 100644 index 00000000..b196faf9 --- /dev/null +++ b/ko/01-slash-commands/optimize.md @@ -0,0 +1,22 @@ +--- +description: ์ฝ”๋“œ ์„ฑ๋Šฅ ๋ฌธ์ œ๋ฅผ ๋ถ„์„ํ•˜๊ณ  ์ตœ์ ํ™” ๋ฐฉ์•ˆ์„ ์ œ์•ˆํ•ฉ๋‹ˆ๋‹ค. +--- + +# ์ฝ”๋“œ ์ตœ์ ํ™” + +์ œ๊ณต๋œ ์ฝ”๋“œ์—์„œ ๋‹ค์Œ ๋ฌธ์ œ๋“ค์„ ์šฐ์„ ์ˆœ์œ„์— ๋”ฐ๋ผ ๊ฒ€ํ† ํ•˜์„ธ์š”: + +1. **์„ฑ๋Šฅ ๋ณ‘๋ชฉ ํ˜„์ƒ** - O(nยฒ) ์—ฐ์‚ฐ, ๋น„ํšจ์œจ์ ์ธ ๋ฃจํ”„ ์‹๋ณ„ +2. **๋ฉ”๋ชจ๋ฆฌ ๋ˆ„์ˆ˜** - ํ•ด์ œ๋˜์ง€ ์•Š์€ ๋ฆฌ์†Œ์Šค, ์ˆœํ™˜ ์ฐธ์กฐ ์ฐพ๊ธฐ +3. **์•Œ๊ณ ๋ฆฌ์ฆ˜ ๊ฐœ์„ ** - ๋” ๋‚˜์€ ์•Œ๊ณ ๋ฆฌ์ฆ˜ ๋˜๋Š” ์ž๋ฃŒ ๊ตฌ์กฐ ์ œ์•ˆ +4. **์บ์‹ฑ ๊ธฐํšŒ** - ๋ฐ˜๋ณต์ ์ธ ๊ณ„์‚ฐ ์‹๋ณ„ +5. **๋™์‹œ์„ฑ ๋ฌธ์ œ** - ๊ฒฝ์Ÿ ์กฐ๊ฑด ๋˜๋Š” ์Šค๋ ˆ๋”ฉ ๋ฌธ์ œ ์ฐพ๊ธฐ + +์‘๋‹ต์„ ๋‹ค์Œ ํ˜•์‹์œผ๋กœ ๊ตฌ์„ฑํ•˜์„ธ์š”: +- ๋ฌธ์ œ ์‹ฌ๊ฐ๋„ (์น˜๋ช…์ /๋†’์Œ/์ค‘๊ฐ„/๋‚ฎ์Œ) +- ์ฝ”๋“œ ๋‚ด ์œ„์น˜ +- ์„ค๋ช… +- ์ฝ”๋“œ ์˜ˆ์‹œ๋ฅผ ํฌํ•จํ•œ ๊ถŒ์žฅ ์ˆ˜์ • ์‚ฌํ•ญ + +--- +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: April 9, 2026 diff --git a/ko/01-slash-commands/pr-slash-command.png b/ko/01-slash-commands/pr-slash-command.png new file mode 100644 index 00000000..789e5c27 Binary files /dev/null and b/ko/01-slash-commands/pr-slash-command.png differ diff --git a/ko/01-slash-commands/pr.md b/ko/01-slash-commands/pr.md new file mode 100644 index 00000000..5f62d214 --- /dev/null +++ b/ko/01-slash-commands/pr.md @@ -0,0 +1,29 @@ +--- +description: ์ฝ”๋“œ ์ •๋ฆฌ, ๋ณ€๊ฒฝ์‚ฌํ•ญ ์Šคํ…Œ์ด์ง•, ํ’€ ๋ฆฌํ€˜์ŠคํŠธ ์ค€๋น„ +allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git diff:*), Bash(npm test:*), Bash(npm run lint:*) +--- + +# ํ’€ ๋ฆฌํ€˜์ŠคํŠธ ์ค€๋น„ ์ฒดํฌ๋ฆฌ์ŠคํŠธ + +PR์„ ์ƒ์„ฑํ•˜๊ธฐ ์ „์— ๋‹ค์Œ ๋‹จ๊ณ„๋ฅผ ์ˆ˜ํ–‰ํ•˜์‹ญ์‹œ์˜ค: + +1. ๋ฆฐํŒ… ์‹คํ–‰: `prettier --write .` +2. ํ…Œ์ŠคํŠธ ์‹คํ–‰: `npm test` +3. git diff ๊ฒ€ํ† : `git diff HEAD` +4. ๋ณ€๊ฒฝ์‚ฌํ•ญ ์Šคํ…Œ์ด์ง•: `git add .` +5. ์ปจ๋ฒค์…”๋„ ์ปค๋ฐ‹(conventional commits) ๊ทœ์น™์— ๋”ฐ๋ผ ์ปค๋ฐ‹ ๋ฉ”์‹œ์ง€ ์ž‘์„ฑ: + - `fix:` ๋ฒ„๊ทธ ์ˆ˜์ • + - `feat:` ์ƒˆ๋กœ์šด ๊ธฐ๋Šฅ ์ถ”๊ฐ€ + - `docs:` ๋ฌธ์„œ ์—…๋ฐ์ดํŠธ + - `refactor:` ์ฝ”๋“œ ๋ฆฌํŒฉํ† ๋ง + - `test:` ํ…Œ์ŠคํŠธ ์ถ”๊ฐ€ + - `chore:` ์œ ์ง€๋ณด์ˆ˜ ์ž‘์—… + +6. ๋‹ค์Œ ๋‚ด์šฉ์„ ํฌํ•จํ•˜์—ฌ PR ์š”์•ฝ ์ƒ์„ฑ: + - ๋ณ€๊ฒฝ ๋‚ด์šฉ + - ๋ณ€๊ฒฝ ์ด์œ  + - ์ˆ˜ํ–‰๋œ ํ…Œ์ŠคํŠธ + - ์ž ์žฌ์  ์˜ํ–ฅ + +--- +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: 2026๋…„ 4์›” 9์ผ diff --git a/ko/01-slash-commands/push-all.md b/ko/01-slash-commands/push-all.md new file mode 100644 index 00000000..2b11d1d5 --- /dev/null +++ b/ko/01-slash-commands/push-all.md @@ -0,0 +1,155 @@ +--- +description: ๋ชจ๋“  ๋ณ€๊ฒฝ ์‚ฌํ•ญ์„ ์Šคํ…Œ์ด์ง•ํ•˜๊ณ , ์ปค๋ฐ‹์„ ์ƒ์„ฑํ•˜๋ฉฐ, ์›๊ฒฉ ์ €์žฅ์†Œ๋กœ ํ‘ธ์‹œํ•ฉ๋‹ˆ๋‹ค (์ฃผ์˜ํ•ด์„œ ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค). +allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*), Bash(git push:*), Bash(git diff:*), Bash(git log:*), Bash(git pull:*) +--- + +# ๋ชจ๋“  ๊ฒƒ์„ ์ปค๋ฐ‹ํ•˜๊ณ  ํ‘ธ์‹œํ•˜๊ธฐ + +โš ๏ธ **์ฃผ์˜**: ๋ชจ๋“  ๋ณ€๊ฒฝ ์‚ฌํ•ญ์„ ์Šคํ…Œ์ด์ง•ํ•˜๊ณ , ์ปค๋ฐ‹ํ•˜๋ฉฐ, ์›๊ฒฉ ์ €์žฅ์†Œ๋กœ ํ‘ธ์‹œํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ๋ณ€๊ฒฝ ์‚ฌํ•ญ์ด ํ•จ๊ป˜ ์†ํ•œ๋‹ค๊ณ  ํ™•์‹ ํ•  ๋•Œ๋งŒ ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค. + +## ์›Œํฌํ”Œ๋กœ์šฐ + +### 1. ๋ณ€๊ฒฝ ์‚ฌํ•ญ ๋ถ„์„ +๋‹ค์Œ ๋ช…๋ น์–ด๋ฅผ ๋ณ‘๋ ฌ๋กœ ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค: +- `git status` - ์ˆ˜์ •/์ถ”๊ฐ€/์‚ญ์ œ/์ถ”์ ๋˜์ง€ ์•Š์€ ํŒŒ์ผ ํ‘œ์‹œ +- `git diff --stat` - ๋ณ€๊ฒฝ ํ†ต๊ณ„ ํ‘œ์‹œ +- `git log -1 --oneline` - ๋ฉ”์‹œ์ง€ ์Šคํƒ€์ผ์„ ์œ„ํ•œ ์ตœ๊ทผ ์ปค๋ฐ‹ ํ‘œ์‹œ + +### 2. ์•ˆ์ „์„ฑ ๊ฒ€์‚ฌ + +**โŒ ๋‹ค์Œ ์‚ฌํ•ญ์ด ๊ฐ์ง€๋˜๋ฉด ์ค‘๋‹จํ•˜๊ณ  ๊ฒฝ๊ณ ํ•˜์‹ญ์‹œ์˜ค:** +- ๋น„๋ฐ€ ์ •๋ณด: `.env*`, `*.key`, `*.pem`, `credentials.json`, `secrets.yaml`, `id_rsa`, `*.p12`, `*.pfx`, `*.cer` +- API ํ‚ค: ์‹ค์ œ ๊ฐ’์ด ํฌํ•จ๋œ ๋ชจ๋“  `*_API_KEY`, `*_SECRET`, `*_TOKEN` ๋ณ€์ˆ˜ ( `your-api-key`, `xxx`, `placeholder`์™€ ๊ฐ™์€ ํ”Œ๋ ˆ์ด์Šคํ™€๋” ์ œ์™ธ) +- ๋Œ€์šฉ๋Ÿ‰ ํŒŒ์ผ: Git LFS ์—†์ด `>10MB`์ธ ํŒŒ์ผ +- ๋นŒ๋“œ ์•„ํ‹ฐํŒฉํŠธ: `node_modules/`, `dist/`, `build/`, `__pycache__/`, `*.pyc`, `.venv/` +- ์ž„์‹œ ํŒŒ์ผ: `.DS_Store`, `thumbs.db`, `*.swp`, `*.tmp` + +**API ํ‚ค ์œ ํšจ์„ฑ ๊ฒ€์‚ฌ:** +์ˆ˜์ •๋œ ํŒŒ์ผ์—์„œ ๋‹ค์Œ๊ณผ ๊ฐ™์€ ํŒจํ„ด์„ ํ™•์ธํ•˜์‹ญ์‹œ์˜ค: +```bash +OPENAI_API_KEY=sk-proj-xxxxx # โŒ Real key detected! +AWS_SECRET_KEY=AKIA... # โŒ Real key detected! +STRIPE_API_KEY=sk_live_... # โŒ Real key detected! + +# โœ… Acceptable placeholders: +API_KEY=your-api-key-here +SECRET_KEY=placeholder +TOKEN=xxx +API_KEY= +SECRET=${YOUR_SECRET} +``` + +**โœ… ๋‹ค์Œ ์‚ฌํ•ญ์„ ํ™•์ธํ•˜์‹ญ์‹œ์˜ค:** +- `.gitignore`๊ฐ€ ์˜ฌ๋ฐ”๋ฅด๊ฒŒ ๊ตฌ์„ฑ๋˜์—ˆ๋Š”์ง€ +- ๋ณ‘ํ•ฉ ์ถฉ๋Œ์ด ์—†๋Š”์ง€ +- ์˜ฌ๋ฐ”๋ฅธ ๋ธŒ๋žœ์น˜์ธ์ง€ (main/master์ธ ๊ฒฝ์šฐ ๊ฒฝ๊ณ ) +- API ํ‚ค๊ฐ€ ํ”Œ๋ ˆ์ด์Šคํ™€๋”๋งŒ ํฌํ•จํ•˜๋Š”์ง€ + +### 3. ํ™•์ธ ์š”์ฒญ + +์š”์•ฝ์„ ์ œ์‹œํ•ฉ๋‹ˆ๋‹ค: +``` +๐Ÿ“Š Changes Summary: +- X files modified, Y added, Z deleted +- Total: +AAA insertions, -BBB deletions + +๐Ÿ”’ Safety: โœ… No secrets | โœ… No large files | โš ๏ธ [warnings] +๐ŸŒฟ Branch: [name] โ†’ origin/[name] + +I will: git add . โ†’ commit โ†’ push + +Type 'yes' to proceed or 'no' to cancel. +``` + +**์ง„ํ–‰ํ•˜๊ธฐ ์ „์— ๋ช…์‹œ์ ์ธ "yes"๋ฅผ ๊ธฐ๋‹ค๋ฆฌ์‹ญ์‹œ์˜ค.** + +### 4. ์‹คํ–‰ (ํ™•์ธ ํ›„) + +๋‹ค์Œ ๋ช…๋ น์–ด๋ฅผ ์ˆœ์ฐจ์ ์œผ๋กœ ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค: +```bash +git add . +git status # Verify staging +``` + +### 5. ์ปค๋ฐ‹ ๋ฉ”์‹œ์ง€ ์ƒ์„ฑ + +๋ณ€๊ฒฝ ์‚ฌํ•ญ์„ ๋ถ„์„ํ•˜๊ณ  ์ปจ๋ฒค์…”๋„ ์ปค๋ฐ‹์„ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค: + +**ํ˜•์‹:** +``` +[type]: Brief summary (max 72 characters) + +- Key change 1 +- Key change 2 +- Key change 3 +``` + +**์œ ํ˜•:** `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`, `build`, `ci` + +**์˜ˆ์‹œ:** +``` +docs: Update concept README files with comprehensive documentation + +- Add architecture diagrams and tables +- Include practical examples +- Expand best practices sections +``` + +### 6. ์ปค๋ฐ‹ ๋ฐ ํ‘ธ์‹œ + +```bash +git commit -m "$(cat <<'EOF' +[Generated commit message] +EOF +)" +git push # If fails: git pull --rebase && git push +git log -1 --oneline --decorate # Verify +``` + +### 7. ์„ฑ๊ณต ํ™•์ธ + +``` +โœ… Successfully pushed to remote! + +Commit: [hash] [message] +Branch: [branch] โ†’ origin/[branch] +Files changed: X (+insertions, -deletions) +``` + +## ์˜ค๋ฅ˜ ์ฒ˜๋ฆฌ + +- **git add ์‹คํŒจ**: ๊ถŒํ•œ, ์ž ๊ธด ํŒŒ์ผ, ์ €์žฅ์†Œ ์ดˆ๊ธฐํ™” ์—ฌ๋ถ€๋ฅผ ํ™•์ธํ•˜์‹ญ์‹œ์˜ค. +- **git commit ์‹คํŒจ**: pre-commit ํ›…์„ ์ˆ˜์ •ํ•˜๊ณ , git config (user.name/email)๋ฅผ ํ™•์ธํ•˜์‹ญ์‹œ์˜ค. +- **git push ์‹คํŒจ**: + - ๋…ผ-ํŒจ์ŠคํŠธํฌ์›Œ๋“œ(Non-fast-forward): `git pull --rebase && git push` + - ์›๊ฒฉ ๋ธŒ๋žœ์น˜ ์—†์Œ: `git push -u origin [branch]` + - ๋ณดํ˜ธ๋œ ๋ธŒ๋žœ์น˜: ๋Œ€์‹  PR ์›Œํฌํ”Œ๋กœ์šฐ๋ฅผ ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค. + +## ์‚ฌ์šฉ ์‹œ๊ธฐ + +โœ… **๊ถŒ์žฅ:** +- ์—ฌ๋Ÿฌ ํŒŒ์ผ์— ๊ฑธ์นœ ๋ฌธ์„œ ์—…๋ฐ์ดํŠธ +- ํ…Œ์ŠคํŠธ์™€ ๋ฌธ์„œ๊ฐ€ ํฌํ•จ๋œ ๊ธฐ๋Šฅ +- ์—ฌ๋Ÿฌ ํŒŒ์ผ์— ๊ฑธ์นœ ๋ฒ„๊ทธ ์ˆ˜์ • +- ํ”„๋กœ์ ํŠธ ์ „๋ฐ˜์˜ ํ˜•์‹ ์ง€์ •/๋ฆฌํŒฉํ† ๋ง +- ๊ตฌ์„ฑ ๋ณ€๊ฒฝ + +โŒ **ํ”ผํ•ด์•ผ ํ•  ๊ฒฝ์šฐ:** +- ๋ฌด์—‡์„ ์ปค๋ฐ‹ํ•˜๋Š”์ง€ ๋ถˆํ™•์‹คํ•œ ๊ฒฝ์šฐ +- ๋น„๋ฐ€ ์ •๋ณด/๋ฏผ๊ฐํ•œ ๋ฐ์ดํ„ฐ๊ฐ€ ํฌํ•จ๋œ ๊ฒฝ์šฐ +- ๊ฒ€ํ†  ์—†์ด ๋ณดํ˜ธ๋œ ๋ธŒ๋žœ์น˜์— ํ‘ธ์‹œํ•˜๋Š” ๊ฒฝ์šฐ +- ๋ณ‘ํ•ฉ ์ถฉ๋Œ์ด ์žˆ๋Š” ๊ฒฝ์šฐ +- ์„ธ๋ถ„ํ™”๋œ ์ปค๋ฐ‹ ํžˆ์Šคํ† ๋ฆฌ๋ฅผ ์›ํ•˜๋Š” ๊ฒฝ์šฐ +- pre-commit ํ›…์ด ์‹คํŒจํ•˜๋Š” ๊ฒฝ์šฐ + +## ๋Œ€์•ˆ + +์‚ฌ์šฉ์ž๊ฐ€ ๋” ๋งŽ์€ ์ œ์–ด๋ฅผ ์›ํ•  ๊ฒฝ์šฐ, ๋‹ค์Œ์„ ์ œ์•ˆํ•ฉ๋‹ˆ๋‹ค: +1. **์„ ํƒ์  ์Šคํ…Œ์ด์ง•**: ํŠน์ • ํŒŒ์ผ์„ ๊ฒ€ํ† /์Šคํ…Œ์ด์ง• +2. **๋Œ€ํ™”ํ˜• ์Šคํ…Œ์ด์ง•**: ํŒจ์น˜ ์„ ํƒ์„ ์œ„ํ•œ `git add -p` +3. **PR ์›Œํฌํ”Œ๋กœ์šฐ**: ๋ธŒ๋žœ์น˜ ์ƒ์„ฑ โ†’ ํ‘ธ์‹œ โ†’ PR (`/pr` ๋ช…๋ น ์‚ฌ์šฉ) + +**โš ๏ธ ๊ธฐ์–ตํ•˜์‹ญ์‹œ์˜ค**: ํ‘ธ์‹œํ•˜๊ธฐ ์ „์— ํ•ญ์ƒ ๋ณ€๊ฒฝ ์‚ฌํ•ญ์„ ๊ฒ€ํ† ํ•˜์‹ญ์‹œ์˜ค. ํ™•์‹ ์ด ์„œ์ง€ ์•Š์„ ๋•Œ๋Š” ๊ฐœ๋ณ„ git ๋ช…๋ น์„ ์‚ฌ์šฉํ•˜์—ฌ ๋” ๋งŽ์€ ์ œ์–ด๋ฅผ ํ™•๋ณดํ•˜์‹ญ์‹œ์˜ค. + +--- +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: 2026๋…„ 4์›” 9์ผ diff --git a/ko/01-slash-commands/setup-ci-cd.md b/ko/01-slash-commands/setup-ci-cd.md new file mode 100644 index 00000000..d0aef209 --- /dev/null +++ b/ko/01-slash-commands/setup-ci-cd.md @@ -0,0 +1,28 @@ +--- +name: CI/CD ํŒŒ์ดํ”„๋ผ์ธ ์„ค์ • +description: ํ’ˆ์งˆ ๋ณด์ฆ์„ ์œ„ํ•œ pre-commit hooks ๋ฐ GitHub Actions ๊ตฌํ˜„ +tags: ci-cd, devops, automation +--- + +# CI/CD ํŒŒ์ดํ”„๋ผ์ธ ์„ค์ • + +ํ”„๋กœ์ ํŠธ ์œ ํ˜•์— ๋งž์ถฐ ํฌ๊ด„์ ์ธ DevOps ํ’ˆ์งˆ ๊ฒŒ์ดํŠธ๋ฅผ ๊ตฌํ˜„ํ•ฉ๋‹ˆ๋‹ค: + +1. **ํ”„๋กœ์ ํŠธ ๋ถ„์„**: ์–ธ์–ด, ํ”„๋ ˆ์ž„์›Œํฌ, ๋นŒ๋“œ ์‹œ์Šคํ…œ ๋ฐ ๊ธฐ์กด ํˆด๋ง ๊ฐ์ง€ +2. ์–ธ์–ด๋ณ„ ๋„๊ตฌ๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ **pre-commit hooks ๊ตฌ์„ฑ**: + - ํฌ๋งคํŒ…: Prettier/Black/gofmt/rustfmt/etc. + - ๋ฆฐํŒ…: ESLint/Ruff/golangci-lint/Clippy/etc. + - ๋ณด์•ˆ: Bandit/gosec/cargo-audit/npm audit/etc. + - ํƒ€์ž… ๊ฒ€์‚ฌ: TypeScript/mypy/flow (ํ•ด๋‹นํ•˜๋Š” ๊ฒฝ์šฐ) + - ํ…Œ์ŠคํŠธ: ๊ด€๋ จ ํ…Œ์ŠคํŠธ ์Šค์œ„ํŠธ ์‹คํ–‰ +3. **GitHub Actions ์›Œํฌํ”Œ๋กœ ์ƒ์„ฑ** (.github/workflows/): + - push/PR ์‹œ pre-commit ๊ฒ€์‚ฌ ๋ฏธ๋Ÿฌ๋ง + - ๋‹ค์ค‘ ๋ฒ„์ „/ํ”Œ๋žซํผ ๋งคํŠธ๋ฆญ์Šค (ํ•ด๋‹นํ•˜๋Š” ๊ฒฝ์šฐ) + - ๋นŒ๋“œ ๋ฐ ํ…Œ์ŠคํŠธ ๊ฒ€์ฆ + - ๋ฐฐํฌ ๋‹จ๊ณ„ (ํ•„์š”ํ•œ ๊ฒฝ์šฐ) +4. **ํŒŒ์ดํ”„๋ผ์ธ ๊ฒ€์ฆ**: ๋กœ์ปฌ์—์„œ ํ…Œ์ŠคํŠธํ•˜๊ณ , ํ…Œ์ŠคํŠธ PR์„ ์ƒ์„ฑํ•˜์—ฌ ๋ชจ๋“  ๊ฒ€์‚ฌ๊ฐ€ ํ†ต๊ณผํ•˜๋Š”์ง€ ํ™•์ธ + +๋ฌด๋ฃŒ/์˜คํ”ˆ ์†Œ์Šค ๋„๊ตฌ๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. ๊ธฐ์กด ๊ตฌ์„ฑ์„ ์กด์ค‘ํ•ฉ๋‹ˆ๋‹ค. ๋น ๋ฅธ ์‹คํ–‰ ์†๋„๋ฅผ ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. + +--- +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: 2026๋…„ 4์›” 9์ผ diff --git a/ko/01-slash-commands/unit-test-expand.md b/ko/01-slash-commands/unit-test-expand.md new file mode 100644 index 00000000..6e68b5c2 --- /dev/null +++ b/ko/01-slash-commands/unit-test-expand.md @@ -0,0 +1,28 @@ +--- +name: Expand Unit Tests +description: ํ…Œ์ŠคํŠธ๋˜์ง€ ์•Š์€ ๋ถ„๊ธฐ ๋ฐ ์—ฃ์ง€ ์ผ€์ด์Šค๋ฅผ ๋Œ€์ƒ์œผ๋กœ ํ•˜์—ฌ ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€ ๋Š˜๋ฆฌ๊ธฐ +tags: testing, coverage, unit-tests +--- + +# ๋‹จ์œ„ ํ…Œ์ŠคํŠธ ํ™•์žฅ + +ํ”„๋กœ์ ํŠธ์˜ ํ…Œ์ŠคํŠธ ํ”„๋ ˆ์ž„์›Œํฌ์— ๋งž์ถฐ ๊ธฐ์กด ๋‹จ์œ„ ํ…Œ์ŠคํŠธ๋ฅผ ํ™•์žฅํ•ฉ๋‹ˆ๋‹ค: + +1. **์ปค๋ฒ„๋ฆฌ์ง€ ๋ถ„์„**: ์ปค๋ฒ„๋ฆฌ์ง€ ๋ณด๊ณ ์„œ๋ฅผ ์‹คํ–‰ํ•˜์—ฌ ํ…Œ์ŠคํŠธ๋˜์ง€ ์•Š์€ ๋ถ„๊ธฐ, ์—ฃ์ง€ ์ผ€์ด์Šค ๋ฐ ๋‚ฎ์€ ์ปค๋ฒ„๋ฆฌ์ง€ ์˜์—ญ ์‹๋ณ„ +2. **๋ˆ„๋ฝ๋œ ๋ถ€๋ถ„ ์‹๋ณ„**: ๋…ผ๋ฆฌ์  ๋ถ„๊ธฐ, ์˜ค๋ฅ˜ ๊ฒฝ๋กœ, ๊ฒฝ๊ณ„ ์กฐ๊ฑด, null/๋นˆ ์ž…๋ ฅ์— ๋Œ€ํ•ด ์ฝ”๋“œ ๊ฒ€ํ†  +3. **ํ…Œ์ŠคํŠธ ์ž‘์„ฑ**: ํ”„๋กœ์ ํŠธ์˜ ํ”„๋ ˆ์ž„์›Œํฌ๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ํ…Œ์ŠคํŠธ๋ฅผ ์ž‘์„ฑํ•ฉ๋‹ˆ๋‹ค: + - Jest/Vitest/Mocha (JavaScript/TypeScript) + - pytest/unittest (Python) + - Go testing/testify (Go) + - Rust test framework (Rust) +4. **ํŠน์ • ์‹œ๋‚˜๋ฆฌ์˜ค ๋Œ€์ƒ ์ง€์ •**: + - ์˜ค๋ฅ˜ ์ฒ˜๋ฆฌ ๋ฐ ์˜ˆ์™ธ + - ๊ฒฝ๊ณ„๊ฐ’ (์ตœ์†Œ/์ตœ๋Œ€, ๋นˆ ๊ฐ’, null) + - ์—ฃ์ง€ ์ผ€์ด์Šค ๋ฐ ์ฝ”๋„ˆ ์ผ€์ด์Šค + - ์ƒํƒœ ์ „ํ™˜ ๋ฐ ๋ถ€์ž‘์šฉ +5. **๊ฐœ์„  ์‚ฌํ•ญ ํ™•์ธ**: ์ปค๋ฒ„๋ฆฌ์ง€๋ฅผ ๋‹ค์‹œ ์‹คํ–‰ํ•˜์—ฌ ์ธก์ • ๊ฐ€๋Šฅํ•œ ์ฆ๊ฐ€ ํ™•์ธ + +์ƒˆ๋กœ์šด ํ…Œ์ŠคํŠธ ์ฝ”๋“œ ๋ธ”๋ก๋งŒ ์ œ์‹œํ•ฉ๋‹ˆ๋‹ค. ๊ธฐ์กด ํ…Œ์ŠคํŠธ ํŒจํ„ด ๋ฐ ๋ช…๋ช… ๊ทœ์น™์„ ๋”ฐ๋ฆ…๋‹ˆ๋‹ค. + +--- +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: 2026๋…„ 4์›” 9์ผ diff --git a/ko/02-memory/README.md b/ko/02-memory/README.md new file mode 100644 index 00000000..4c4b7bb4 --- /dev/null +++ b/ko/02-memory/README.md @@ -0,0 +1,1213 @@ + + + Claude How To + + +# ๋ฉ”๋ชจ๋ฆฌ ๊ฐ€์ด๋“œ + +๋ฉ”๋ชจ๋ฆฌ๋Š” Claude๊ฐ€ ์„ธ์…˜๊ณผ ๋Œ€ํ™” ์ „๋ฐ˜์— ๊ฑธ์ณ ์ปจํ…์ŠคํŠธ๋ฅผ ์œ ์ง€ํ•  ์ˆ˜ ์žˆ๋„๋ก ํ•ฉ๋‹ˆ๋‹ค. ์ด๋Š” claude.ai์˜ ์ž๋™ ํ•ฉ์„ฑ, ๊ทธ๋ฆฌ๊ณ  Claude Code์˜ ํŒŒ์ผ ์‹œ์Šคํ…œ ๊ธฐ๋ฐ˜ CLAUDE.md๋ผ๋Š” ๋‘ ๊ฐ€์ง€ ํ˜•ํƒœ๋กœ ์กด์žฌํ•ฉ๋‹ˆ๋‹ค. + +## ๊ฐœ์š” + +Claude Code์˜ ๋ฉ”๋ชจ๋ฆฌ๋Š” ์—ฌ๋Ÿฌ ์„ธ์…˜๊ณผ ๋Œ€ํ™”์— ๊ฑธ์ณ ์ง€์†์ ์ธ ์ปจํ…์ŠคํŠธ๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. ์ž„์‹œ ์ปจํ…์ŠคํŠธ ์ฐฝ๊ณผ ๋‹ฌ๋ฆฌ ๋ฉ”๋ชจ๋ฆฌ ํŒŒ์ผ์„ ์‚ฌ์šฉํ•˜๋ฉด ๋‹ค์Œ์„ ์ˆ˜ํ–‰ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +- ํŒ€ ์ „์ฒด์— ํ”„๋กœ์ ํŠธ ํ‘œ์ค€ ๊ณต์œ  +- ๊ฐœ์ธ ๊ฐœ๋ฐœ ํ™˜๊ฒฝ ์„ค์ • ์ €์žฅ +- ๋””๋ ‰ํ„ฐ๋ฆฌ๋ณ„ ๊ทœ์น™ ๋ฐ ๊ตฌ์„ฑ ์œ ์ง€ +- ์™ธ๋ถ€ ๋ฌธ์„œ ๊ฐ€์ ธ์˜ค๊ธฐ +- ํ”„๋กœ์ ํŠธ์˜ ์ผ๋ถ€๋กœ ๋ฉ”๋ชจ๋ฆฌ๋ฅผ ๋ฒ„์ „ ๊ด€๋ฆฌ + +๋ฉ”๋ชจ๋ฆฌ ์‹œ์Šคํ…œ์€ ์ „์—ญ ๊ฐœ์ธ ํ™˜๊ฒฝ ์„ค์ •๋ถ€ํ„ฐ ํŠน์ • ํ•˜์œ„ ๋””๋ ‰ํ„ฐ๋ฆฌ์— ์ด๋ฅด๊ธฐ๊นŒ์ง€ ์—ฌ๋Ÿฌ ์ˆ˜์ค€์—์„œ ์ž‘๋™ํ•˜์—ฌ, Claude๊ฐ€ ๋ฌด์—‡์„ ๊ธฐ์–ตํ•˜๊ณ  ํ•ด๋‹น ์ง€์‹์„ ์–ด๋–ป๊ฒŒ ์ ์šฉํ•˜๋Š”์ง€์— ๋Œ€ํ•œ ์„ธ๋ฐ€ํ•œ ์ œ์–ด๋ฅผ ๊ฐ€๋Šฅํ•˜๊ฒŒ ํ•ฉ๋‹ˆ๋‹ค. + +## ๋ฉ”๋ชจ๋ฆฌ ๋ช…๋ น์–ด ๋น ๋ฅธ ์ฐธ์กฐ + +| ๋ช…๋ น์–ด | ๋ชฉ์  | ์‚ฌ์šฉ๋ฒ• | ์‚ฌ์šฉ ์‹œ์  | +|---------|---------|-------|-------------| +| `/init` | ํ”„๋กœ์ ํŠธ ๋ฉ”๋ชจ๋ฆฌ ์ดˆ๊ธฐํ™” | `/init` | ์ƒˆ ํ”„๋กœ์ ํŠธ ์‹œ์ž‘, CLAUDE.md ์ฒซ ์„ค์ • ์‹œ | +| `/memory` | ํŽธ์ง‘๊ธฐ์—์„œ ๋ฉ”๋ชจ๋ฆฌ ํŒŒ์ผ ํŽธ์ง‘ | `/memory` | ๊ด‘๋ฒ”์œ„ํ•œ ์—…๋ฐ์ดํŠธ, ์žฌ๊ตฌ์„ฑ, ๋‚ด์šฉ ๊ฒ€ํ†  ์‹œ | +| `#` ์ ‘๋‘์‚ฌ | ~~๋น ๋ฅธ ํ•œ ์ค„ ๋ฉ”๋ชจ๋ฆฌ ์ถ”๊ฐ€~~ **์ค‘๋‹จ๋จ** | โ€” | ๋Œ€์‹  `/memory`๋ฅผ ์‚ฌ์šฉํ•˜๊ฑฐ๋‚˜ ๋Œ€ํ™”์‹์œผ๋กœ ์š”์ฒญ | +| `@path/to/file` | ์™ธ๋ถ€ ์ฝ˜ํ…์ธ  ๊ฐ€์ ธ์˜ค๊ธฐ | `@README.md` ๋˜๋Š” `@docs/api.md` | CLAUDE.md์—์„œ ๊ธฐ์กด ๋ฌธ์„œ๋ฅผ ์ฐธ์กฐํ•  ๋•Œ | + +## ๋น ๋ฅธ ์‹œ์ž‘: ๋ฉ”๋ชจ๋ฆฌ ์ดˆ๊ธฐํ™” + +### `/init` ๋ช…๋ น์–ด + +`/init` ๋ช…๋ น์–ด๋Š” Claude Code์—์„œ ํ”„๋กœ์ ํŠธ ๋ฉ”๋ชจ๋ฆฌ๋ฅผ ์„ค์ •ํ•˜๋Š” ๊ฐ€์žฅ ๋น ๋ฅธ ๋ฐฉ๋ฒ•์ž…๋‹ˆ๋‹ค. ์ด ๋ช…๋ น์–ด๋Š” ํ”„๋กœ์ ํŠธ์˜ ๊ธฐ๋ณธ ๋ฌธ์„œ๋ฅผ ํฌํ•จํ•˜๋Š” CLAUDE.md ํŒŒ์ผ์„ ์ดˆ๊ธฐํ™”ํ•ฉ๋‹ˆ๋‹ค. + +**์‚ฌ์šฉ๋ฒ•:** + +```bash +/init +``` + +**์ˆ˜ํ–‰ํ•˜๋Š” ์ž‘์—…:** + +- ํ”„๋กœ์ ํŠธ ๋‚ด์— ์ƒˆ CLAUDE.md ํŒŒ์ผ์„ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค (์ผ๋ฐ˜์ ์œผ๋กœ `./CLAUDE.md` ๋˜๋Š” `./.claude/CLAUDE.md`์— ์ƒ์„ฑ๋จ) +- ํ”„๋กœ์ ํŠธ ๊ทœ์น™ ๋ฐ ์ง€์นจ์„ ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค +- ์„ธ์…˜ ์ „๋ฐ˜์— ๊ฑธ์ณ ์ปจํ…์ŠคํŠธ ์ง€์†์„ฑ์„ ์œ„ํ•œ ๊ธฐ๋ฐ˜์„ ๋งˆ๋ จํ•ฉ๋‹ˆ๋‹ค +- ํ”„๋กœ์ ํŠธ ํ‘œ์ค€์„ ๋ฌธ์„œํ™”ํ•˜๊ธฐ ์œ„ํ•œ ํ…œํ”Œ๋ฆฟ ๊ตฌ์กฐ๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค + +**๊ฐ•ํ™”๋œ ๋Œ€ํ™”ํ˜• ๋ชจ๋“œ:** `CLAUDE_CODE_NEW_INIT=1`๋กœ ์„ค์ •ํ•˜์—ฌ ํ”„๋กœ์ ํŠธ ์„ค์ •์„ ๋‹จ๊ณ„๋ณ„๋กœ ์•ˆ๋‚ดํ•˜๋Š” ๋‹ค๋‹จ๊ณ„ ๋Œ€ํ™”ํ˜• ํ๋ฆ„์„ ํ™œ์„ฑํ™”ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +```bash +CLAUDE_CODE_NEW_INIT=1 claude +/init +``` + +**`/init` ์‚ฌ์šฉ ์‹œ์ :** + +- Claude Code๋กœ ์ƒˆ ํ”„๋กœ์ ํŠธ๋ฅผ ์‹œ์ž‘ํ•  ๋•Œ +- ํŒ€ ์ฝ”๋”ฉ ํ‘œ์ค€ ๋ฐ ๊ทœ์น™์„ ์„ค์ •ํ•  ๋•Œ +- ์ฝ”๋“œ๋ฒ ์ด์Šค ๊ตฌ์กฐ์— ๋Œ€ํ•œ ๋ฌธ์„œ๋ฅผ ์ž‘์„ฑํ•  ๋•Œ +- ํ˜‘์—… ๊ฐœ๋ฐœ์„ ์œ„ํ•œ ๋ฉ”๋ชจ๋ฆฌ ๊ณ„์ธต ๊ตฌ์กฐ๋ฅผ ์„ค์ •ํ•  ๋•Œ + +**์˜ˆ์‹œ ์›Œํฌํ”Œ๋กœ์šฐ:** + +```markdown +# In your project directory +/init + +# Claude creates CLAUDE.md with structure like: +# Project Configuration +## Project Overview +- Name: Your Project +- Tech Stack: [Your technologies] +- Team Size: [Number of developers] + +## Development Standards +- Code style preferences +- Testing requirements +- Git workflow conventions +``` + +### ๋น ๋ฅธ ๋ฉ”๋ชจ๋ฆฌ ์—…๋ฐ์ดํŠธ + +> **์ฐธ๊ณ **: ์ธ๋ผ์ธ ๋ฉ”๋ชจ๋ฆฌ๋ฅผ ์œ„ํ•œ `#` ๋‹จ์ถ•ํ‚ค๋Š” ์ค‘๋‹จ๋˜์—ˆ์Šต๋‹ˆ๋‹ค. `/memory`๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ๋ฉ”๋ชจ๋ฆฌ ํŒŒ์ผ์„ ์ง์ ‘ ํŽธ์ง‘ํ•˜๊ฑฐ๋‚˜, Claude์—๊ฒŒ ๋Œ€ํ™”์‹์œผ๋กœ ๋ฌด์–ธ๊ฐ€๋ฅผ ๊ธฐ์–ตํ•˜๋„๋ก ์š”์ฒญํ•˜์„ธ์š” (์˜ˆ: "์šฐ๋ฆฌ๋Š” ํ•ญ์ƒ TypeScript strict mode๋ฅผ ์‚ฌ์šฉํ•œ๋‹ค๋Š” ๊ฒƒ์„ ๊ธฐ์–ตํ•ด์ค˜"). + +๋ฉ”๋ชจ๋ฆฌ์— ์ •๋ณด๋ฅผ ์ถ”๊ฐ€ํ•˜๋Š” ๊ถŒ์žฅ ๋ฐฉ๋ฒ•์€ ๋‹ค์Œ๊ณผ ๊ฐ™์Šต๋‹ˆ๋‹ค. + +**์˜ต์…˜ 1: `/memory` ๋ช…๋ น์–ด ์‚ฌ์šฉ** + +```bash +/memory +``` + +์‹œ์Šคํ…œ ํŽธ์ง‘๊ธฐ์—์„œ ๋ฉ”๋ชจ๋ฆฌ ํŒŒ์ผ์„ ์—ด์–ด ์ง์ ‘ ํŽธ์ง‘ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +**์˜ต์…˜ 2: ๋Œ€ํ™”์‹์œผ๋กœ ์š”์ฒญ** + +``` +Remember that we always use TypeScript strict mode in this project. +Please add to memory: prefer async/await over promise chains. +``` + +Claude๋Š” ์š”์ฒญ์— ๋”ฐ๋ผ ์ ์ ˆํ•œ CLAUDE.md ํŒŒ์ผ์„ ์—…๋ฐ์ดํŠธํ•ฉ๋‹ˆ๋‹ค. + +**๊ณผ๊ฑฐ ์ฐธ์กฐ** (๋” ์ด์ƒ ์ž‘๋™ํ•˜์ง€ ์•Š์Œ): + +์ด์ „์—๋Š” `#` ์ ‘๋‘์‚ฌ ๋‹จ์ถ•ํ‚ค๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ์ธ๋ผ์ธ์œผ๋กœ ๊ทœ์น™์„ ์ถ”๊ฐ€ํ•  ์ˆ˜ ์žˆ์—ˆ์Šต๋‹ˆ๋‹ค. + +```markdown +# Always use TypeScript strict mode in this project โ† no longer works +``` + +์ด ํŒจํ„ด์— ์˜์กดํ–ˆ๋‹ค๋ฉด `/memory` ๋ช…๋ น์–ด ๋˜๋Š” ๋Œ€ํ™”์‹ ์š”์ฒญ์œผ๋กœ ์ „ํ™˜ํ•˜์‹ญ์‹œ์˜ค. + +### `/memory` ๋ช…๋ น์–ด + +`/memory` ๋ช…๋ น์–ด๋Š” Claude Code ์„ธ์…˜ ๋‚ด์—์„œ CLAUDE.md ๋ฉ”๋ชจ๋ฆฌ ํŒŒ์ผ์„ ์ง์ ‘ ํŽธ์ง‘ํ•  ์ˆ˜ ์žˆ๋„๋ก ํ•ฉ๋‹ˆ๋‹ค. ์ด ๋ช…๋ น์–ด๋Š” ์‹œ์Šคํ…œ ํŽธ์ง‘๊ธฐ์—์„œ ๋ฉ”๋ชจ๋ฆฌ ํŒŒ์ผ์„ ์—ด์–ด ํฌ๊ด„์ ์ธ ํŽธ์ง‘์„ ๊ฐ€๋Šฅํ•˜๊ฒŒ ํ•ฉ๋‹ˆ๋‹ค. + +**์‚ฌ์šฉ๋ฒ•:** + +```bash +/memory +``` + +**์ˆ˜ํ–‰ํ•˜๋Š” ์ž‘์—…:** + +- ์‹œ์Šคํ…œ์˜ ๊ธฐ๋ณธ ํŽธ์ง‘๊ธฐ์—์„œ ๋ฉ”๋ชจ๋ฆฌ ํŒŒ์ผ์„ ์—ฝ๋‹ˆ๋‹ค +- ๊ด‘๋ฒ”์œ„ํ•œ ์ถ”๊ฐ€, ์ˆ˜์ • ๋ฐ ์žฌ๊ตฌ์„ฑ์„ ํ—ˆ์šฉํ•ฉ๋‹ˆ๋‹ค +- ๊ณ„์ธต ๊ตฌ์กฐ ๋‚ด์˜ ๋ชจ๋“  ๋ฉ”๋ชจ๋ฆฌ ํŒŒ์ผ์— ์ง์ ‘ ์ ‘๊ทผ์„ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค +- ์„ธ์…˜ ์ „๋ฐ˜์— ๊ฑธ์ณ ์ง€์†์ ์ธ ์ปจํ…์ŠคํŠธ๋ฅผ ๊ด€๋ฆฌํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค + +**`/memory` ์‚ฌ์šฉ ์‹œ์ :** + +- ๊ธฐ์กด ๋ฉ”๋ชจ๋ฆฌ ์ฝ˜ํ…์ธ ๋ฅผ ๊ฒ€ํ† ํ•  ๋•Œ +- ํ”„๋กœ์ ํŠธ ํ‘œ์ค€์„ ๊ด‘๋ฒ”์œ„ํ•˜๊ฒŒ ์—…๋ฐ์ดํŠธํ•  ๋•Œ +- ๋ฉ”๋ชจ๋ฆฌ ๊ตฌ์กฐ๋ฅผ ์žฌ๊ตฌ์„ฑํ•  ๋•Œ +- ์ƒ์„ธํ•œ ๋ฌธ์„œ๋‚˜ ์ง€์นจ์„ ์ถ”๊ฐ€ํ•  ๋•Œ +- ํ”„๋กœ์ ํŠธ๊ฐ€ ๋ฐœ์ „ํ•จ์— ๋”ฐ๋ผ ๋ฉ”๋ชจ๋ฆฌ๋ฅผ ์œ ์ง€ ๋ฐ ์—…๋ฐ์ดํŠธํ•  ๋•Œ + +**๋น„๊ต: `/memory` vs `/init`** + +| ์ธก๋ฉด | `/memory` | `/init` | +|--------|-----------|---------| +| **๋ชฉ์ ** | ๊ธฐ์กด ๋ฉ”๋ชจ๋ฆฌ ํŒŒ์ผ ํŽธ์ง‘ | ์ƒˆ CLAUDE.md ์ดˆ๊ธฐํ™” | +| **์‚ฌ์šฉ ์‹œ์ ** | ํ”„๋กœ์ ํŠธ ์ปจํ…์ŠคํŠธ ์—…๋ฐ์ดํŠธ/์ˆ˜์ • | ์ƒˆ ํ”„๋กœ์ ํŠธ ์‹œ์ž‘ | +| **๋™์ž‘** | ํŽธ์ง‘๊ธฐ๋ฅผ ์—ด์–ด ๋ณ€๊ฒฝ | ์‹œ์ž‘ ํ…œํ”Œ๋ฆฟ ์ƒ์„ฑ | +| **์›Œํฌํ”Œ๋กœ์šฐ** | ์ง€์†์ ์ธ ์œ ์ง€๋ณด์ˆ˜ | ์ผํšŒ์„ฑ ์„ค์ • | + +**์˜ˆ์‹œ ์›Œํฌํ”Œ๋กœ์šฐ:** + +```markdown +# Open memory for editing +/memory + +# Claude presents options: +# 1. Managed Policy Memory +# 2. Project Memory (./CLAUDE.md) +# 3. User Memory (~/.claude/CLAUDE.md) +# 4. Local Project Memory + +# Choose option 2 (Project Memory) +# Your default editor opens with ./CLAUDE.md content + +# Make changes, save, and close editor +# Claude automatically reloads the updated memory +``` + +**๋ฉ”๋ชจ๋ฆฌ ๊ฐ€์ ธ์˜ค๊ธฐ ์‚ฌ์šฉ:** + +CLAUDE.md ํŒŒ์ผ์€ ์™ธ๋ถ€ ์ฝ˜ํ…์ธ ๋ฅผ ํฌํ•จํ•˜๊ธฐ ์œ„ํ•ด `@path/to/file` ๊ตฌ๋ฌธ์„ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค. + +```markdown +# Project Documentation +See @README.md for project overview +See @package.json for available npm commands +See @docs/architecture.md for system design + +# Import from home directory using absolute path +@~/.claude/my-project-instructions.md +``` + +**๊ฐ€์ ธ์˜ค๊ธฐ ๊ธฐ๋Šฅ:** + +- ์ƒ๋Œ€ ๋ฐ ์ ˆ๋Œ€ ๊ฒฝ๋กœ ๋ชจ๋‘ ์ง€์›๋ฉ๋‹ˆ๋‹ค (์˜ˆ: `@docs/api.md` ๋˜๋Š” `@~/.claude/my-project-instructions.md`) +- ์ตœ๋Œ€ ๊นŠ์ด 5๊นŒ์ง€ ์žฌ๊ท€์  ๊ฐ€์ ธ์˜ค๊ธฐ๊ฐ€ ์ง€์›๋ฉ๋‹ˆ๋‹ค +- ์™ธ๋ถ€ ์œ„์น˜์—์„œ ์ฒ˜์Œ ๊ฐ€์ ธ์˜ฌ ๊ฒฝ์šฐ ๋ณด์•ˆ์„ ์œ„ํ•ด ์Šน์ธ ๋Œ€ํ™” ์ƒ์ž๊ฐ€ ๋‚˜ํƒ€๋‚ฉ๋‹ˆ๋‹ค +- Markdown ์ฝ”๋“œ ์ŠคํŒฌ์ด๋‚˜ ์ฝ”๋“œ ๋ธ”๋ก ๋‚ด๋ถ€์—์„œ๋Š” ๊ฐ€์ ธ์˜ค๊ธฐ ์ง€์‹œ๋ฌธ์ด ํ‰๊ฐ€๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค (๋”ฐ๋ผ์„œ ์˜ˆ์‹œ์—์„œ ๋ฌธ์„œํ™”ํ•˜๋Š” ๊ฒƒ์ด ์•ˆ์ „ํ•ฉ๋‹ˆ๋‹ค) +- ๊ธฐ์กด ๋ฌธ์„œ๋ฅผ ์ฐธ์กฐํ•˜์—ฌ ์ค‘๋ณต์„ ํ”ผํ•˜๋Š” ๋ฐ ๋„์›€์ด ๋ฉ๋‹ˆ๋‹ค +- ์ฐธ์กฐ๋œ ์ฝ˜ํ…์ธ ๋ฅผ Claude์˜ ์ปจํ…์ŠคํŠธ์— ์ž๋™์œผ๋กœ ํฌํ•จํ•ฉ๋‹ˆ๋‹ค + +## ๋ฉ”๋ชจ๋ฆฌ ์•„ํ‚คํ…์ฒ˜ + +Claude Code์˜ ๋ฉ”๋ชจ๋ฆฌ๋Š” ๋‹ค์–‘ํ•œ ๋ฒ”์œ„๊ฐ€ ๋‹ค์–‘ํ•œ ๋ชฉ์ ์„ ์ˆ˜ํ–‰ํ•˜๋Š” ๊ณ„์ธต์  ์‹œ์Šคํ…œ์„ ๋”ฐ๋ฆ…๋‹ˆ๋‹ค. + +```mermaid +graph TB + A["Claude Session"] + B["User Input"] + C["Memory System"] + D["Memory Storage"] + + B -->|User provides info| C + C -->|Synthesizes every 24h| D + D -->|Loads automatically| A + A -->|Uses context| C +``` + +## Claude Code์˜ ๋ฉ”๋ชจ๋ฆฌ ๊ณ„์ธต ๊ตฌ์กฐ + +Claude Code๋Š” ๋‹ค๋‹จ๊ณ„ ๊ณ„์ธต์  ๋ฉ”๋ชจ๋ฆฌ ์‹œ์Šคํ…œ์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. Claude Code๊ฐ€ ์‹œ์ž‘๋  ๋•Œ ๋ฉ”๋ชจ๋ฆฌ ํŒŒ์ผ์ด ์ž๋™์œผ๋กœ ๋กœ๋“œ๋˜๋ฉฐ, ์ƒ์œ„ ์ˆ˜์ค€ ํŒŒ์ผ์ด ์šฐ์„  ์ˆœ์œ„๋ฅผ ๊ฐ–์Šต๋‹ˆ๋‹ค. + +**์ „์ฒด ๋ฉ”๋ชจ๋ฆฌ ๊ณ„์ธต ๊ตฌ์กฐ (์šฐ์„  ์ˆœ์œ„ ์ˆœ):** + +1. **๊ด€๋ฆฌ ์ •์ฑ…** - ์กฐ์ง ์ „์ฒด ์ง€์นจ + - macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md` + - Linux/WSL: `/etc/claude-code/CLAUDE.md` + - Windows: `C:\Program Files\ClaudeCode\CLAUDE.md` + +2. **๊ด€๋ฆฌ ๋“œ๋กญ์ธ** - ์•ŒํŒŒ๋ฒณ ์ˆœ์œผ๋กœ ๋ณ‘ํ•ฉ๋œ ์ •์ฑ… ํŒŒ์ผ (v2.1.83+) + - ๊ด€๋ฆฌ ์ •์ฑ… CLAUDE.md์™€ ํ•จ๊ป˜ ์žˆ๋Š” `managed-settings.d/` ๋””๋ ‰ํ„ฐ๋ฆฌ + - ๋ชจ๋“ˆ์‹ ์ •์ฑ… ๊ด€๋ฆฌ๋ฅผ ์œ„ํ•ด ํŒŒ์ผ์ด ์•ŒํŒŒ๋ฒณ ์ˆœ์œผ๋กœ ๋ณ‘ํ•ฉ๋ฉ๋‹ˆ๋‹ค + +3. **ํ”„๋กœ์ ํŠธ ๋ฉ”๋ชจ๋ฆฌ** - ํŒ€ ๊ณต์œ  ์ปจํ…์ŠคํŠธ (๋ฒ„์ „ ๊ด€๋ฆฌ๋จ) + - `./.claude/CLAUDE.md` ๋˜๋Š” `./CLAUDE.md` (์ €์žฅ์†Œ ๋ฃจํŠธ์—) + +4. **ํ”„๋กœ์ ํŠธ ๊ทœ์น™** - ๋ชจ๋“ˆ์‹, ์ฃผ์ œ๋ณ„ ํ”„๋กœ์ ํŠธ ์ง€์นจ + - `./.claude/rules/*.md` + +5. **์‚ฌ์šฉ์ž ๋ฉ”๋ชจ๋ฆฌ** - ๊ฐœ์ธ ํ™˜๊ฒฝ ์„ค์ • (๋ชจ๋“  ํ”„๋กœ์ ํŠธ) + - `~/.claude/CLAUDE.md` + +6. **์‚ฌ์šฉ์ž ์ˆ˜์ค€ ๊ทœ์น™** - ๊ฐœ์ธ ๊ทœ์น™ (๋ชจ๋“  ํ”„๋กœ์ ํŠธ) + - `~/.claude/rules/*.md` + +7. **๋กœ์ปฌ ํ”„๋กœ์ ํŠธ ๋ฉ”๋ชจ๋ฆฌ** - ๊ฐœ์ธ ํ”„๋กœ์ ํŠธ๋ณ„ ํ™˜๊ฒฝ ์„ค์ • + - `./CLAUDE.local.md` + +> **์ฐธ๊ณ **: `CLAUDE.local.md`๋Š” [๊ณต์‹ ๋ฌธ์„œ](https://code.claude.com/docs/en/memory)์—์„œ ์™„์ „ํžˆ ์ง€์›๋˜๊ณ  ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. ์ด๋Š” ๋ฒ„์ „ ์ œ์–ด์— ์ปค๋ฐ‹๋˜์ง€ ์•Š๋Š” ๊ฐœ์ธ ํ”„๋กœ์ ํŠธ๋ณ„ ํ™˜๊ฒฝ ์„ค์ •์„ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. `CLAUDE.local.md`๋ฅผ `.gitignore`์— ์ถ”๊ฐ€ํ•˜์„ธ์š”. + +8. **์ž๋™ ๋ฉ”๋ชจ๋ฆฌ** - Claude์˜ ์ž๋™ ๊ธฐ๋ก ๋ฐ ํ•™์Šต ๋‚ด์šฉ + - `~/.claude/projects//memory/` + +**๋ฉ”๋ชจ๋ฆฌ ๊ฒ€์ƒ‰ ๋™์ž‘:** + +Claude๋Š” ๋ฉ”๋ชจ๋ฆฌ ํŒŒ์ผ์„ ์ด ์ˆœ์„œ๋กœ ๊ฒ€์ƒ‰ํ•˜๋ฉฐ, ์•ž์„  ์œ„์น˜๊ฐ€ ์šฐ์„  ์ˆœ์œ„๋ฅผ ๊ฐ–์Šต๋‹ˆ๋‹ค. + +```mermaid +graph TD + A["Managed Policy
/Library/.../ClaudeCode/CLAUDE.md"] -->|highest priority| A2["Managed Drop-ins
managed-settings.d/"] + A2 --> B["Project Memory
./CLAUDE.md"] + B --> C["Project Rules
./.claude/rules/*.md"] + C --> D["User Memory
~/.claude/CLAUDE.md"] + D --> E["User Rules
~/.claude/rules/*.md"] + E --> F["Local Project Memory
./CLAUDE.local.md"] + F --> G["Auto Memory
~/.claude/projects/.../memory/"] + + B -->|imports| H["@docs/architecture.md"] + H -->|imports| I["@docs/api-standards.md"] + + style A fill:#fce4ec,stroke:#333,color:#333 + style A2 fill:#fce4ec,stroke:#333,color:#333 + style B fill:#e1f5fe,stroke:#333,color:#333 + style C fill:#e1f5fe,stroke:#333,color:#333 + style D fill:#f3e5f5,stroke:#333,color:#333 + style E fill:#f3e5f5,stroke:#333,color:#333 + style F fill:#e8f5e9,stroke:#333,color:#333 + style G fill:#fff3e0,stroke:#333,color:#333 + style H fill:#e1f5fe,stroke:#333,color:#333 + style I fill:#e1f5fe,stroke:#333,color:#333 +``` + +## `claudeMdExcludes`๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ CLAUDE.md ํŒŒ์ผ ์ œ์™ธํ•˜๊ธฐ + +๋Œ€๊ทœ๋ชจ ๋ชจ๋…ธ๋ ˆํฌ์—์„œ ์ผ๋ถ€ CLAUDE.md ํŒŒ์ผ์€ ํ˜„์žฌ ์ž‘์—…๊ณผ ๊ด€๋ จ์ด ์—†์„ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. `claudeMdExcludes` ์„ค์ •์€ ํŠน์ • CLAUDE.md ํŒŒ์ผ์„ ์ปจํ…์ŠคํŠธ์— ๋กœ๋“œํ•˜์ง€ ์•Š๋„๋ก ๊ฑด๋„ˆ๋›ธ ์ˆ˜ ์žˆ๊ฒŒ ํ•ฉ๋‹ˆ๋‹ค. + +```jsonc +// In ~/.claude/settings.json or .claude/settings.json +{ + "claudeMdExcludes": [ + "packages/legacy-app/CLAUDE.md", + "vendors/**/CLAUDE.md" + ] +} +``` + +ํŒจํ„ด์€ ํ”„๋กœ์ ํŠธ ๋ฃจํŠธ๋ฅผ ๊ธฐ์ค€์œผ๋กœ ํ•˜๋Š” ๊ฒฝ๋กœ์™€ ์ผ์น˜ํ•ฉ๋‹ˆ๋‹ค. ์ด๋Š” ํŠนํžˆ ๋‹ค์Œ ๊ฒฝ์šฐ์— ์œ ์šฉํ•ฉ๋‹ˆ๋‹ค. + +- ๋งŽ์€ ํ•˜์œ„ ํ”„๋กœ์ ํŠธ๊ฐ€ ์žˆ๋Š” ๋ชจ๋…ธ๋ ˆํฌ์—์„œ ์ผ๋ถ€๋งŒ ๊ด€๋ จ ์žˆ๋Š” ๊ฒฝ์šฐ +- ๊ณต๊ธ‰์—…์ฒด ๋˜๋Š” ํƒ€์‚ฌ CLAUDE.md ํŒŒ์ผ์ด ํฌํ•จ๋œ ์ €์žฅ์†Œ +- ์˜ค๋ž˜๋˜์—ˆ๊ฑฐ๋‚˜ ๊ด€๋ จ ์—†๋Š” ์ง€์นจ์„ ์ œ์™ธํ•˜์—ฌ Claude์˜ ์ปจํ…์ŠคํŠธ ์ฐฝ์—์„œ ๋…ธ์ด์ฆˆ ๊ฐ์†Œ + +## ์„ค์ • ํŒŒ์ผ ๊ณ„์ธต ๊ตฌ์กฐ + +Claude Code ์„ค์ •( `autoMemoryDirectory`, `claudeMdExcludes` ๋ฐ ๊ธฐํƒ€ ๊ตฌ์„ฑ ํฌํ•จ)์€ 5๋‹จ๊ณ„ ๊ณ„์ธต ๊ตฌ์กฐ์—์„œ ํ•ด๊ฒฐ๋˜๋ฉฐ, ์ƒ์œ„ ์ˆ˜์ค€์ด ์šฐ์„  ์ˆœ์œ„๋ฅผ ๊ฐ–์Šต๋‹ˆ๋‹ค. + +| ์ˆ˜์ค€ | ์œ„์น˜ | ๋ฒ”์œ„ | +|-------|----------|-------| +| 1 (์ตœ๊ณ ) | ๊ด€๋ฆฌ ์ •์ฑ… (์‹œ์Šคํ…œ ์ˆ˜์ค€) | ์กฐ์ง ์ „์ฒด ์ ์šฉ | +| 2 | `managed-settings.d/` (v2.1.83+) | ๋ชจ๋“ˆ์‹ ์ •์ฑ… ๋“œ๋กญ์ธ, ์•ŒํŒŒ๋ฒณ ์ˆœ์œผ๋กœ ๋ณ‘ํ•ฉ๋จ | +| 3 | `.claude/settings.local.json` | ๋กœ์ปฌ ์žฌ์ •์˜ (git-ignored) | +| 4 | `.claude/settings.json` | ํ”„๋กœ์ ํŠธ ์ˆ˜์ค€ (git์— ์ปค๋ฐ‹๋จ) | +| 5 (์ตœ์ €) | `~/.claude/settings.json` | ์‚ฌ์šฉ์ž ํ™˜๊ฒฝ ์„ค์ • | + +**ํ”Œ๋žซํผ๋ณ„ ๊ตฌ์„ฑ (v2.1.51+):** + +์„ค์ •์€ ๋‹ค์Œ์„ ํ†ตํ•ด์„œ๋„ ๊ตฌ์„ฑํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. +- **macOS**: ์†์„ฑ ๋ชฉ๋ก(plist) ํŒŒ์ผ +- **Windows**: Windows ๋ ˆ์ง€์ŠคํŠธ๋ฆฌ + +์ด๋Ÿฌํ•œ ํ”Œ๋žซํผ ๋„ค์ดํ‹ฐ๋ธŒ ๋ฉ”์ปค๋‹ˆ์ฆ˜์€ JSON ์„ค์ • ํŒŒ์ผ๊ณผ ํ•จ๊ป˜ ์ฝํžˆ๋ฉฐ ๋™์ผํ•œ ์šฐ์„  ์ˆœ์œ„ ๊ทœ์น™์„ ๋”ฐ๋ฆ…๋‹ˆ๋‹ค. + +> **์ฐธ๊ณ  (v2.1.119)**: `/config` ๋ณ€๊ฒฝ ์‚ฌํ•ญ์€ ์ด์ œ `~/.claude/settings.json`์— ์œ ์ง€๋ฉ๋‹ˆ๋‹ค. `/config`๋ฅผ ํ†ตํ•ด ์ž‘์„ฑ๋œ ๊ฐ’์€ ์œ„์—์„œ ์„ค๋ช…ํ•œ ์ผ๋ฐ˜์ ์ธ ์ •์ฑ…/๋กœ์ปฌ/ํ”„๋กœ์ ํŠธ ์šฐ์„  ์ˆœ์œ„ ์ฒด์ธ์— ์ฐธ์—ฌํ•˜๋ฉฐ, ๋” ์ด์ƒ ์„ธ์…˜ ์ „์šฉ์ด ์•„๋‹™๋‹ˆ๋‹ค. ๋Œ€ํ™”ํ˜• ํŽธ์ง‘์—๋Š” `/config`๋ฅผ ์‚ฌ์šฉํ•˜๊ณ , ์Šคํฌ๋ฆฝํŠธํ™”๋˜๊ฑฐ๋‚˜ ๊ด€๋ฆฌ๋˜๋Š” ๊ตฌ์„ฑ์—๋Š” `settings.json` ํŒŒ์ผ์„ ์ง์ ‘ ํŽธ์ง‘ํ•˜์„ธ์š”. + +### ๋ณด์กด ๋ฐ ์ •๋ฆฌ ์„ค์ • + +| ์„ค์ • | ์œ ํ˜• | ๊ธฐ๋ณธ๊ฐ’ | ์„ค๋ช… | +|---------|------|---------|-------------| +| `cleanupPeriodDays` | ์ •์ˆ˜ (์ผ) | 30 | ๋””์Šคํฌ ์•„ํ‹ฐํŒฉํŠธ ๋ณด์กด ๊ธฐ๊ฐ„. **v2.1.117๋ถ€ํ„ฐ**, ์ฒดํฌํฌ์ธํŠธ (`~/.claude/checkpoints/`), ์ž‘์—… (`~/.claude/tasks/`), ์…ธ ์Šค๋ƒ…์ƒท (`~/.claude/shell-snapshots/`), ๋ฐฑ์—… (`~/.claude/backups/`) ๋“ฑ 4๊ฐ€์ง€ ๋ชจ๋‘์— ์ ์šฉ๋ฉ๋‹ˆ๋‹ค. ๊ธฐ๊ฐ„๋ณด๋‹ค ์˜ค๋ž˜๋œ ํŒŒ์ผ์€ ์‹œ์ž‘ ์‹œ ์ •๋ฆฌ๋ฉ๋‹ˆ๋‹ค. | + +```jsonc +// ~/.claude/settings.json +{ + "cleanupPeriodDays": 14 +} +``` + +### ์†์„ฑ, ์Œ์„ฑ ๋ฐ PR URL ์„ค์ • + +| ์„ค์ • | ์œ ํ˜• | ์„ค๋ช… | +|---------|------|-------------| +| `attribution.commit` | ๋ถ€์šธ | Claude๊ฐ€ ์ƒ์„ฑํ•œ ์ปค๋ฐ‹์— `Co-Authored-By: Claude` ํŠธ๋ ˆ์ผ๋Ÿฌ๋ฅผ ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค. ๋” ์ด์ƒ ์‚ฌ์šฉ๋˜์ง€ ์•Š๋Š” `includeCoAuthoredBy` ํ”Œ๋ž˜๊ทธ๋ฅผ ๋Œ€์ฒดํ•ฉ๋‹ˆ๋‹ค. | +| `attribution.pr` | ๋ถ€์šธ | pull request ์„ค๋ช…์— Claude ์†์„ฑ์„ ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค. PR์— ๋Œ€ํ•œ ๋” ์ด์ƒ ์‚ฌ์šฉ๋˜์ง€ ์•Š๋Š” `includeCoAuthoredBy` ํ”Œ๋ž˜๊ทธ๋ฅผ ๋Œ€์ฒดํ•ฉ๋‹ˆ๋‹ค. | +| `attribution.sessionUrl` | ๋ถ€์šธ | ์›น ๋ฐ ์›๊ฒฉ ์ œ์–ด ์„ธ์…˜์—์„œ ์ƒ์„ฑ๋œ ์ปค๋ฐ‹ ๋ฐ PR์—์„œ claude.ai ์„ธ์…˜ ๋งํฌ๋ฅผ ์ƒ๋žตํ•ฉ๋‹ˆ๋‹ค (v2.1.183+). | +| `voice.enabled` | ๋ถ€์šธ | ํ‘ธ์‹œ ํˆฌ ํ† ํฌ ์Œ์„ฑ ๋ฐ›์•„์“ฐ๊ธฐ (`/voice`)๋ฅผ ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค. ๋” ์ด์ƒ ์‚ฌ์šฉ๋˜์ง€ ์•Š๋Š” `voiceEnabled` ํ”Œ๋ž˜๊ทธ๋ฅผ ๋Œ€์ฒดํ•ฉ๋‹ˆ๋‹ค. | +| `prUrlTemplate` | ๋ฌธ์ž์—ด | **v2.1.119์— ์ƒˆ๋กœ ์ถ”๊ฐ€๋จ.** ํ‘ธํ„ฐ PR ๋ฐฐ์ง€๋ฅผ ์œ„ํ•œ ์‚ฌ์šฉ์ž ์ง€์ • URL ํ…œํ”Œ๋ฆฟ; GitLab, Bitbucket ๋˜๋Š” ๋‚ด๋ถ€ ์ฝ”๋“œ ๊ฒ€ํ†  ํ”Œ๋žซํผ์— ์œ ์šฉํ•ฉ๋‹ˆ๋‹ค. `{{owner}}`, `{{repo}}`, `{{number}}` ํ”Œ๋ ˆ์ด์Šคํ™€๋”๋ฅผ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค. | + +```jsonc +// ~/.claude/settings.json +{ + "attribution": { + "commit": false, + "pr": true + }, + "voice": { + "enabled": true + }, + "prUrlTemplate": "https://gitlab.internal/{{owner}}/{{repo}}/-/merge_requests/{{number}}" +} +``` + +#### ๋” ์ด์ƒ ์‚ฌ์šฉ๋˜์ง€ ์•Š๋Š” ์„ค์ • ์ด๋ฆ„ + +๋‹ค์Œ ๋ ˆ๊ฑฐ์‹œ ์„ค์ • ํ‚ค๋Š” ์—ฌ์ „ํžˆ ์ž‘๋™ํ•˜์ง€๋งŒ ๋” ์ด์ƒ ์‚ฌ์šฉ๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ์œ„ ๋Œ€์ฒด ํ‚ค๋ฅผ ์„ ํ˜ธํ•˜์„ธ์š”. + +| ์‚ฌ์šฉ ์ค‘๋‹จ๋œ ํ‚ค | ๋Œ€์ฒด ํ‚ค | ์ฐธ๊ณ  | +|----------------|-------------|-------| +| `includeCoAuthoredBy` | `attribution.commit` / `attribution.pr` | ๊ธฐ์กด์˜ ๋‹จ์ผ ํ”Œ๋ž˜๊ทธ๊ฐ€ ๋ณ„๋„์˜ ์ปค๋ฐ‹ ๋ฐ PR ์Šค์œ„์น˜๋กœ ๋ถ„ํ• ๋˜์—ˆ์Šต๋‹ˆ๋‹ค. ์ด์ „ ์„ค์น˜ ์‚ฌ์šฉ์ž๋Š” ๋ ˆ๊ฑฐ์‹œ ํ‚ค๋ฅผ ์œ ์ง€ํ•  ์ˆ˜ ์žˆ์ง€๋งŒ, ์ƒˆ ํ”„๋กœ์ ํŠธ๋Š” ์ค‘์ฒฉ๋œ ํ˜•ํƒœ๋ฅผ ์‚ฌ์šฉํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. | +| `voiceEnabled` | `voice.enabled` | ํ–ฅํ›„ ์Œ์„ฑ ๊ด€๋ จ ์˜ต์…˜๊ณผ ํ•จ๊ป˜ `voice` ๋„ค์ž„์ŠคํŽ˜์ด์Šค ์•„๋ž˜์— ๊ทธ๋ฃนํ™”๋˜์—ˆ์Šต๋‹ˆ๋‹ค. | + +## ๋ชจ๋“ˆ์‹ ๊ทœ์น™ ์‹œ์Šคํ…œ + +`.claude/rules/` ๋””๋ ‰ํ„ฐ๋ฆฌ ๊ตฌ์กฐ๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ์ฒด๊ณ„์ ์ด๊ณ  ๊ฒฝ๋กœ๋ณ„ ๊ทœ์น™์„ ๋งŒ๋“œ์„ธ์š”. ๊ทœ์น™์€ ํ”„๋กœ์ ํŠธ ์ˆ˜์ค€๊ณผ ์‚ฌ์šฉ์ž ์ˆ˜์ค€ ๋ชจ๋‘์—์„œ ์ •์˜ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +``` +your-project/ +โ”œโ”€โ”€ .claude/ +โ”‚ โ”œโ”€โ”€ CLAUDE.md +โ”‚ โ””โ”€โ”€ rules/ +โ”‚ โ”œโ”€โ”€ code-style.md +โ”‚ โ”œโ”€โ”€ testing.md +โ”‚ โ”œโ”€โ”€ security.md +โ”‚ โ””โ”€โ”€ api/ # Subdirectories supported +โ”‚ โ”œโ”€โ”€ conventions.md +โ”‚ โ””โ”€โ”€ validation.md + +~/.claude/ +โ”œโ”€โ”€ CLAUDE.md +โ””โ”€โ”€ rules/ # User-level rules (all projects) + โ”œโ”€โ”€ personal-style.md + โ””โ”€โ”€ preferred-patterns.md +``` + +`rules/` ๋””๋ ‰ํ„ฐ๋ฆฌ ๋‚ด์—์„œ ํ•˜์œ„ ๋””๋ ‰ํ„ฐ๋ฆฌ๋ฅผ ํฌํ•จํ•˜์—ฌ ๊ทœ์น™์ด ์žฌ๊ท€์ ์œผ๋กœ ๊ฒ€์ƒ‰๋ฉ๋‹ˆ๋‹ค. `~/.claude/rules/`์˜ ์‚ฌ์šฉ์ž ์ˆ˜์ค€ ๊ทœ์น™์€ ํ”„๋กœ์ ํŠธ ์ˆ˜์ค€ ๊ทœ์น™๋ณด๋‹ค ๋จผ์ € ๋กœ๋“œ๋˜์–ด, ํ”„๋กœ์ ํŠธ๊ฐ€ ์žฌ์ •์˜ํ•  ์ˆ˜ ์žˆ๋Š” ๊ฐœ์ธ ๊ธฐ๋ณธ๊ฐ’์„ ํ—ˆ์šฉํ•ฉ๋‹ˆ๋‹ค. + +### YAML Frontmatter๋ฅผ ์‚ฌ์šฉํ•œ ๊ฒฝ๋กœ๋ณ„ ๊ทœ์น™ + +ํŠน์ • ํŒŒ์ผ ๊ฒฝ๋กœ์—๋งŒ ์ ์šฉ๋˜๋Š” ๊ทœ์น™์„ ์ •์˜ํ•ฉ๋‹ˆ๋‹ค. + +```markdown +--- +paths: src/api/**/*.ts +--- + +# API Development Rules + +- All API endpoints must include input validation +- Use Zod for schema validation +- Document all parameters and response types +- Include error handling for all operations +``` + +**Glob ํŒจํ„ด ์˜ˆ์‹œ:** + +- `**/*.ts` - ๋ชจ๋“  TypeScript ํŒŒ์ผ +- `src/**/*` - src/ ์•„๋ž˜์˜ ๋ชจ๋“  ํŒŒ์ผ +- `src/**/*.{ts,tsx}` - ์—ฌ๋Ÿฌ ํ™•์žฅ์ž +- `{src,lib}/**/*.ts, tests/**/*.test.ts` - ์—ฌ๋Ÿฌ ํŒจํ„ด + +### ํ•˜์œ„ ๋””๋ ‰ํ„ฐ๋ฆฌ ๋ฐ ์‹ฌ๋ณผ๋ฆญ ๋งํฌ + +`.claude/rules/`์˜ ๊ทœ์น™์€ ๋‘ ๊ฐ€์ง€ ์กฐ์ง ๊ธฐ๋Šฅ์„ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค. + +- **ํ•˜์œ„ ๋””๋ ‰ํ„ฐ๋ฆฌ**: ๊ทœ์น™์€ ์žฌ๊ท€์ ์œผ๋กœ ๊ฒ€์ƒ‰๋˜๋ฏ€๋กœ ์ฃผ์ œ ๊ธฐ๋ฐ˜ ํด๋”(์˜ˆ: `rules/api/`, `rules/testing/`, `rules/security/`)๋กœ ์ •๋ฆฌํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. +- **์‹ฌ๋ณผ๋ฆญ ๋งํฌ**: ์—ฌ๋Ÿฌ ํ”„๋กœ์ ํŠธ ๊ฐ„์— ๊ทœ์น™์„ ๊ณต์œ ํ•˜๊ธฐ ์œ„ํ•ด ์‹ฌ๋ณผ๋ฆญ ๋งํฌ๊ฐ€ ์ง€์›๋ฉ๋‹ˆ๋‹ค. ์˜ˆ๋ฅผ ๋“ค์–ด, ์ค‘์•™ ์œ„์น˜์—์„œ ๊ณต์œ  ๊ทœ์น™ ํŒŒ์ผ์„ ๊ฐ ํ”„๋กœ์ ํŠธ์˜ `.claude/rules/` ๋””๋ ‰ํ„ฐ๋ฆฌ์— ์‹ฌ๋ณผ๋ฆญ ๋งํฌํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +## ๋ฉ”๋ชจ๋ฆฌ ์œ„์น˜ ํ‘œ + +| ์œ„์น˜ | ๋ฒ”์œ„ | ์šฐ์„  ์ˆœ์œ„ | ๊ณต์œ  ์—ฌ๋ถ€ | ์ ‘๊ทผ ๋ฐฉ์‹ | ๊ฐ€์žฅ ์ ํ•ฉํ•œ ๊ฒฝ์šฐ | +|----------|-------|----------|--------|--------|----------| +| `/Library/Application Support/ClaudeCode/CLAUDE.md` (macOS) | ๊ด€๋ฆฌ ์ •์ฑ… | 1 (์ตœ๊ณ ) | ์กฐ์ง | ์‹œ์Šคํ…œ | ํšŒ์‚ฌ ์ „์ฒด ์ •์ฑ… | +| `/etc/claude-code/CLAUDE.md` (Linux/WSL) | ๊ด€๋ฆฌ ์ •์ฑ… | 1 (์ตœ๊ณ ) | ์กฐ์ง | ์‹œ์Šคํ…œ | ์กฐ์ง ํ‘œ์ค€ | +| `C:\Program Files\ClaudeCode\CLAUDE.md` (Windows) | ๊ด€๋ฆฌ ์ •์ฑ… | 1 (์ตœ๊ณ ) | ์กฐ์ง | ์‹œ์Šคํ…œ | ๊ธฐ์—… ์ง€์นจ | +| `managed-settings.d/*.md` (์ •์ฑ…๊ณผ ํ•จ๊ป˜) | ๊ด€๋ฆฌ ๋“œ๋กญ์ธ | 1.5 | ์กฐ์ง | ์‹œ์Šคํ…œ | ๋ชจ๋“ˆ์‹ ์ •์ฑ… ํŒŒ์ผ (v2.1.83+) | +| `./CLAUDE.md` ๋˜๋Š” `./.claude/CLAUDE.md` | ํ”„๋กœ์ ํŠธ ๋ฉ”๋ชจ๋ฆฌ | 2 | ํŒ€ | Git | ํŒ€ ํ‘œ์ค€, ๊ณต์œ  ์•„ํ‚คํ…์ฒ˜ | +| `./.claude/rules/*.md` | ํ”„๋กœ์ ํŠธ ๊ทœ์น™ | 3 | ํŒ€ | Git | ๊ฒฝ๋กœ๋ณ„, ๋ชจ๋“ˆ์‹ ๊ทœ์น™ | +| `~/.claude/CLAUDE.md` | ์‚ฌ์šฉ์ž ๋ฉ”๋ชจ๋ฆฌ | 4 | ๊ฐœ์ธ | ํŒŒ์ผ ์‹œ์Šคํ…œ | ๊ฐœ์ธ ํ™˜๊ฒฝ ์„ค์ • (๋ชจ๋“  ํ”„๋กœ์ ํŠธ) | +| `~/.claude/rules/*.md` | ์‚ฌ์šฉ์ž ๊ทœ์น™ | 5 | ๊ฐœ์ธ | ํŒŒ์ผ ์‹œ์Šคํ…œ | ๊ฐœ์ธ ๊ทœ์น™ (๋ชจ๋“  ํ”„๋กœ์ ํŠธ) | +| `./CLAUDE.local.md` | ๋กœ์ปฌ ํ”„๋กœ์ ํŠธ | 6 | ๊ฐœ์ธ | Git (๋ฌด์‹œ๋จ) | ๊ฐœ์ธ ํ”„๋กœ์ ํŠธ๋ณ„ ํ™˜๊ฒฝ ์„ค์ • | +| `~/.claude/projects//memory/` | ์ž๋™ ๋ฉ”๋ชจ๋ฆฌ | 7 (์ตœ์ €) | ๊ฐœ์ธ | ํŒŒ์ผ ์‹œ์Šคํ…œ | Claude์˜ ์ž๋™ ๊ธฐ๋ก ๋ฐ ํ•™์Šต ๋‚ด์šฉ | + +## ๋ฉ”๋ชจ๋ฆฌ ์—…๋ฐ์ดํŠธ ๋ผ์ดํ”„์‚ฌ์ดํด + +Claude Code ์„ธ์…˜์—์„œ ๋ฉ”๋ชจ๋ฆฌ ์—…๋ฐ์ดํŠธ๊ฐ€ ์–ด๋–ป๊ฒŒ ํ๋ฅด๋Š”์ง€ ๋ณด์—ฌ์ค๋‹ˆ๋‹ค. + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude Code + participant Editor as File System + participant Memory as CLAUDE.md + + User->>Claude: "Remember: use async/await" + Claude->>User: "Which memory file?" + User->>Claude: "Project memory" + Claude->>Editor: Open ~/.claude/settings.json + Claude->>Memory: Write to ./CLAUDE.md + Memory-->>Claude: File saved + Claude->>Claude: Load updated memory + Claude-->>User: "Memory saved!" +``` + +## ์ž๋™ ๋ฉ”๋ชจ๋ฆฌ + +์ž๋™ ๋ฉ”๋ชจ๋ฆฌ๋Š” Claude๊ฐ€ ํ”„๋กœ์ ํŠธ์™€ ์ž‘์—…ํ•˜๋ฉด์„œ ํ•™์Šต ๋‚ด์šฉ, ํŒจํ„ด ๋ฐ ํ†ต์ฐฐ๋ ฅ์„ ์ž๋™์œผ๋กœ ๊ธฐ๋กํ•˜๋Š” ์ง€์†์ ์ธ ๋””๋ ‰ํ„ฐ๋ฆฌ์ž…๋‹ˆ๋‹ค. ์‚ฌ์šฉ์ž๊ฐ€ ์ˆ˜๋™์œผ๋กœ ์ž‘์„ฑํ•˜๊ณ  ์œ ์ง€ ๊ด€๋ฆฌํ•˜๋Š” CLAUDE.md ํŒŒ์ผ๊ณผ ๋‹ฌ๋ฆฌ, ์ž๋™ ๋ฉ”๋ชจ๋ฆฌ๋Š” ์„ธ์…˜ ์ค‘์— Claude ์ž์ฒด์— ์˜ํ•ด ์ž‘์„ฑ๋ฉ๋‹ˆ๋‹ค. + +### ์ž๋™ ๋ฉ”๋ชจ๋ฆฌ ์ž‘๋™ ๋ฐฉ์‹ + +- **์œ„์น˜**: `~/.claude/projects//memory/` +- **์‹œ์ž‘์ **: `MEMORY.md`๋Š” ์ž๋™ ๋ฉ”๋ชจ๋ฆฌ ๋””๋ ‰ํ„ฐ๋ฆฌ์˜ ์ฃผ์š” ํŒŒ์ผ ์—ญํ• ์„ ํ•ฉ๋‹ˆ๋‹ค +- **์ฃผ์ œ ํŒŒ์ผ**: ํŠน์ • ์ฃผ์ œ์— ๋Œ€ํ•œ ์„ ํƒ์  ์ถ”๊ฐ€ ํŒŒ์ผ (์˜ˆ: `debugging.md`, `api-conventions.md`) +- **๋กœ๋“œ ๋™์ž‘**: ์„ธ์…˜ ์‹œ์ž‘ ์‹œ `MEMORY.md`์˜ ์ฒซ 200์ค„ (๋˜๋Š” ์ฒซ 25KB ์ค‘ ๋จผ์ € ๋„๋‹ฌํ•˜๋Š” ๊ฒƒ)์ด ์ปจํ…์ŠคํŠธ์— ๋กœ๋“œ๋ฉ๋‹ˆ๋‹ค. ์ฃผ์ œ ํŒŒ์ผ์€ ์‹œ์ž‘ ์‹œ๊ฐ€ ์•„๋‹ˆ๋ผ ํ•„์š”ํ•  ๋•Œ ๋กœ๋“œ๋ฉ๋‹ˆ๋‹ค. +- **์ฝ๊ธฐ/์“ฐ๊ธฐ**: Claude๋Š” ํŒจํ„ด๊ณผ ํ”„๋กœ์ ํŠธ๋ณ„ ์ง€์‹์„ ๋ฐœ๊ฒฌํ•จ์— ๋”ฐ๋ผ ์„ธ์…˜ ์ค‘์— ๋ฉ”๋ชจ๋ฆฌ ํŒŒ์ผ์„ ์ฝ๊ณ  ์”๋‹ˆ๋‹ค + +### ์ž๋™ ๋ฉ”๋ชจ๋ฆฌ ์•„ํ‚คํ…์ฒ˜ + +```mermaid +graph TD + A["Claude Session Starts"] --> B["Load MEMORY.md
(first 200 lines / 25KB)"] + B --> C["Session Active"] + C --> D["Claude discovers
patterns & insights"] + D --> E{"Write to
auto memory"} + E -->|General notes| F["MEMORY.md"] + E -->|Topic-specific| G["debugging.md"] + E -->|Topic-specific| H["api-conventions.md"] + C --> I["On-demand load
topic files"] + I --> C + + style A fill:#e1f5fe,stroke:#333,color:#333 + style B fill:#e1f5fe,stroke:#333,color:#333 + style C fill:#e8f5e9,stroke:#333,color:#333 + style D fill:#f3e5f5,stroke:#333,color:#333 + style E fill:#fff3e0,stroke:#333,color:#333 + style F fill:#fce4ec,stroke:#333,color:#333 + style G fill:#fce4ec,stroke:#333,color:#333 + style H fill:#fce4ec,stroke:#333,color:#333 + style I fill:#f3e5f5,stroke:#333,color:#333 +``` + +### ์ž๋™ ๋ฉ”๋ชจ๋ฆฌ ๋””๋ ‰ํ„ฐ๋ฆฌ ๊ตฌ์กฐ + +``` +~/.claude/projects//memory/ +โ”œโ”€โ”€ MEMORY.md # Entrypoint (first 200 lines / 25KB loaded at startup) +โ”œโ”€โ”€ debugging.md # Topic file (loaded on demand) +โ”œโ”€โ”€ api-conventions.md # Topic file (loaded on demand) +โ””โ”€โ”€ testing-patterns.md # Topic file (loaded on demand) +``` + +### ๋ฒ„์ „ ์š”๊ตฌ ์‚ฌํ•ญ + +์ž๋™ ๋ฉ”๋ชจ๋ฆฌ์—๋Š” **Claude Code v2.1.59 ์ด์ƒ**์ด ํ•„์š”ํ•ฉ๋‹ˆ๋‹ค. ์ด์ „ ๋ฒ„์ „์„ ์‚ฌ์šฉ ์ค‘์ด๋ผ๋ฉด ๋จผ์ € ์—…๊ทธ๋ ˆ์ด๋“œํ•˜์„ธ์š”. + +```bash +npm install -g @anthropic-ai/claude-code@latest +``` + +### ์‚ฌ์šฉ์ž ์ง€์ • ์ž๋™ ๋ฉ”๋ชจ๋ฆฌ ๋””๋ ‰ํ„ฐ๋ฆฌ + +๊ธฐ๋ณธ์ ์œผ๋กœ ์ž๋™ ๋ฉ”๋ชจ๋ฆฌ๋Š” `~/.claude/projects//memory/`์— ์ €์žฅ๋ฉ๋‹ˆ๋‹ค. `autoMemoryDirectory` ์„ค์ •( **v2.1.74๋ถ€ํ„ฐ ์‚ฌ์šฉ ๊ฐ€๋Šฅ**)์„ ์‚ฌ์šฉํ•˜์—ฌ ์ด ์œ„์น˜๋ฅผ ๋ณ€๊ฒฝํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +```jsonc +// In ~/.claude/settings.json or .claude/settings.local.json (user/local settings only) +{ + "autoMemoryDirectory": "/path/to/custom/memory/directory" +} +``` + +> **์ฐธ๊ณ **: `autoMemoryDirectory`๋Š” ํ”„๋กœ์ ํŠธ ๋˜๋Š” ๊ด€๋ฆฌ ์ •์ฑ… ์„ค์ •์ด ์•„๋‹Œ ์‚ฌ์šฉ์ž ์ˆ˜์ค€(`~/.claude/settings.json`) ๋˜๋Š” ๋กœ์ปฌ ์„ค์ •(`.claude/settings.local.json`)์—์„œ๋งŒ ์„ค์ •ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +์ด๋Š” ๋‹ค์Œ์„ ์›ํ•  ๋•Œ ์œ ์šฉํ•ฉ๋‹ˆ๋‹ค. + +- ์ž๋™ ๋ฉ”๋ชจ๋ฆฌ๋ฅผ ๊ณต์œ  ๋˜๋Š” ๋™๊ธฐํ™”๋œ ์œ„์น˜์— ์ €์žฅ +- ์ž๋™ ๋ฉ”๋ชจ๋ฆฌ๋ฅผ ๊ธฐ๋ณธ Claude ๊ตฌ์„ฑ ๋””๋ ‰ํ„ฐ๋ฆฌ์—์„œ ๋ถ„๋ฆฌ +- ๊ธฐ๋ณธ ๊ณ„์ธต ๊ตฌ์กฐ ์™ธ๋ถ€์˜ ํ”„๋กœ์ ํŠธ๋ณ„ ๊ฒฝ๋กœ ์‚ฌ์šฉ + +### ์›ŒํฌํŠธ๋ฆฌ ๋ฐ ์ €์žฅ์†Œ ๊ณต์œ  + +๋™์ผํ•œ Git ์ €์žฅ์†Œ ๋‚ด์˜ ๋ชจ๋“  ์›ŒํฌํŠธ๋ฆฌ ๋ฐ ํ•˜์œ„ ๋””๋ ‰ํ„ฐ๋ฆฌ๋Š” ๋‹จ์ผ ์ž๋™ ๋ฉ”๋ชจ๋ฆฌ ๋””๋ ‰ํ„ฐ๋ฆฌ๋ฅผ ๊ณต์œ ํ•ฉ๋‹ˆ๋‹ค. ์ด๋Š” ์›ŒํฌํŠธ๋ฆฌ ๊ฐ„์„ ์ „ํ™˜ํ•˜๊ฑฐ๋‚˜ ๋™์ผํ•œ ์ €์žฅ์†Œ์˜ ๋‹ค๋ฅธ ํ•˜์œ„ ๋””๋ ‰ํ„ฐ๋ฆฌ์—์„œ ์ž‘์—…ํ•  ๋•Œ ๋™์ผํ•œ ๋ฉ”๋ชจ๋ฆฌ ํŒŒ์ผ์„ ์ฝ๊ณ  ์“ด๋‹ค๋Š” ๊ฒƒ์„ ์˜๋ฏธํ•ฉ๋‹ˆ๋‹ค. + +### ์„œ๋ธŒ์—์ด์ „ํŠธ ๋ฉ”๋ชจ๋ฆฌ + +์„œ๋ธŒ์—์ด์ „ํŠธ(Task ๋˜๋Š” ๋ณ‘๋ ฌ ์‹คํ–‰๊ณผ ๊ฐ™์€ ๋„๊ตฌ๋ฅผ ํ†ตํ•ด ์ƒ์„ฑ๋จ)๋Š” ์ž์ฒด ๋ฉ”๋ชจ๋ฆฌ ์ปจํ…์ŠคํŠธ๋ฅผ ๊ฐ€์งˆ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์„œ๋ธŒ์—์ด์ „ํŠธ ์ •์˜์—์„œ ๋กœ๋“œํ•  ๋ฉ”๋ชจ๋ฆฌ ๋ฒ”์œ„๋ฅผ ์ง€์ •ํ•˜๋ ค๋ฉด `memory` ํ”„๋ก ํŠธ๋งคํ„ฐ ํ•„๋“œ๋ฅผ ์‚ฌ์šฉํ•˜์„ธ์š”. + +```yaml +memory: user # Load user-level memory only +memory: project # Load project-level memory only +memory: local # Load local memory only +``` + +์ด๋ฅผ ํ†ตํ•ด ์„œ๋ธŒ์—์ด์ „ํŠธ๋Š” ์ „์ฒด ๋ฉ”๋ชจ๋ฆฌ ๊ณ„์ธต ๊ตฌ์กฐ๋ฅผ ์ƒ์†ํ•˜๋Š” ๋Œ€์‹  ์ง‘์ค‘๋œ ์ปจํ…์ŠคํŠธ๋กœ ์ž‘๋™ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +> **์ฐธ๊ณ **: ์„œ๋ธŒ์—์ด์ „ํŠธ๋„ ์ž์ฒด ์ž๋™ ๋ฉ”๋ชจ๋ฆฌ๋ฅผ ์œ ์ง€ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์ž์„ธํ•œ ๋‚ด์šฉ์€ [๊ณต์‹ ์„œ๋ธŒ์—์ด์ „ํŠธ ๋ฉ”๋ชจ๋ฆฌ ๋ฌธ์„œ](https://code.claude.com/docs/en/sub-agents#enable-persistent-memory)๋ฅผ ์ฐธ์กฐํ•˜์„ธ์š”. + +### ์ž๋™ ๋ฉ”๋ชจ๋ฆฌ ์ œ์–ด + +์ž๋™ ๋ฉ”๋ชจ๋ฆฌ๋Š” `CLAUDE_CODE_DISABLE_AUTO_MEMORY` ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋ฅผ ํ†ตํ•ด ์ œ์–ดํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +| ๊ฐ’ | ๋™์ž‘ | +|-------|----------| +| `0` | ์ž๋™ ๋ฉ”๋ชจ๋ฆฌ **๊ฐ•์ œ ํ™œ์„ฑํ™”** | +| `1` | ์ž๋™ ๋ฉ”๋ชจ๋ฆฌ **๊ฐ•์ œ ๋น„ํ™œ์„ฑํ™”** | +| *(์„ค์ •๋˜์ง€ ์•Š์Œ)* | ๊ธฐ๋ณธ ๋™์ž‘ (์ž๋™ ๋ฉ”๋ชจ๋ฆฌ ํ™œ์„ฑํ™”๋จ) | + +```bash +# Disable auto memory for a session +CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude + +# Force auto memory on explicitly +CLAUDE_CODE_DISABLE_AUTO_MEMORY=0 claude +``` + +## `--add-dir`์„ ์‚ฌ์šฉํ•œ ์ถ”๊ฐ€ ๋””๋ ‰ํ„ฐ๋ฆฌ + +`--add-dir` ํ”Œ๋ž˜๊ทธ๋Š” Claude Code๊ฐ€ ํ˜„์žฌ ์ž‘์—… ๋””๋ ‰ํ„ฐ๋ฆฌ ์™ธ์˜ ์ถ”๊ฐ€ ๋””๋ ‰ํ„ฐ๋ฆฌ์—์„œ CLAUDE.md ํŒŒ์ผ์„ ๋กœ๋“œํ•  ์ˆ˜ ์žˆ๋„๋ก ํ•ฉ๋‹ˆ๋‹ค. ์ด๋Š” ๋‹ค๋ฅธ ๋””๋ ‰ํ„ฐ๋ฆฌ์˜ ์ปจํ…์ŠคํŠธ๊ฐ€ ๊ด€๋ จ ์žˆ๋Š” ๋ชจ๋…ธ๋ ˆํฌ ๋˜๋Š” ๋‹ค์ค‘ ํ”„๋กœ์ ํŠธ ์„ค์ •์— ์œ ์šฉํ•ฉ๋‹ˆ๋‹ค. + +์ด ๊ธฐ๋Šฅ์„ ํ™œ์„ฑํ™”ํ•˜๋ ค๋ฉด ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋ฅผ ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค. + +```bash +CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 +``` + +๊ทธ๋Ÿฐ ๋‹ค์Œ ๋‹ค์Œ ํ”Œ๋ž˜๊ทธ๋กœ Claude Code๋ฅผ ์‹œ์ž‘ํ•ฉ๋‹ˆ๋‹ค. + +```bash +claude --add-dir /path/to/other/project +``` + +Claude๋Š” ํ˜„์žฌ ์ž‘์—… ๋””๋ ‰ํ„ฐ๋ฆฌ์˜ ๋ฉ”๋ชจ๋ฆฌ ํŒŒ์ผ๊ณผ ํ•จ๊ป˜ ์ง€์ •๋œ ์ถ”๊ฐ€ ๋””๋ ‰ํ„ฐ๋ฆฌ์—์„œ CLAUDE.md๋ฅผ ๋กœ๋“œํ•ฉ๋‹ˆ๋‹ค. + +## ์‹ค์ œ ์˜ˆ์‹œ + +### ์˜ˆ์‹œ 1: ํ”„๋กœ์ ํŠธ ๋ฉ”๋ชจ๋ฆฌ ๊ตฌ์กฐ + +**ํŒŒ์ผ:** `./CLAUDE.md` + +```markdown +# Project Configuration + +## Project Overview +- **Name**: E-commerce Platform +- **Tech Stack**: Node.js, PostgreSQL, React 18, Docker +- **Team Size**: 5 developers +- **Deadline**: Q4 2025 + +## Architecture +@docs/architecture.md +@docs/api-standards.md +@docs/database-schema.md + +## Development Standards + +### Code Style +- Use Prettier for formatting +- Use ESLint with airbnb config +- Maximum line length: 100 characters +- Use 2-space indentation + +### Naming Conventions +- **Files**: kebab-case (user-controller.js) +- **Classes**: PascalCase (UserService) +- **Functions/Variables**: camelCase (getUserById) +- **Constants**: UPPER_SNAKE_CASE (API_BASE_URL) +- **Database Tables**: snake_case (user_accounts) + +### Git Workflow +- Branch names: `feature/description` or `fix/description` +- Commit messages: Follow conventional commits +- PR required before merge +- All CI/CD checks must pass +- Minimum 1 approval required + +### Testing Requirements +- Minimum 80% code coverage +- All critical paths must have tests +- Use Jest for unit tests +- Use Cypress for E2E tests +- Test filenames: `*.test.ts` or `*.spec.ts` + +### API Standards +- RESTful endpoints only +- JSON request/response +- Use HTTP status codes correctly +- Version API endpoints: `/api/v1/` +- Document all endpoints with examples + +### Database +- Use migrations for schema changes +- Never hardcode credentials +- Use connection pooling +- Enable query logging in development +- Regular backups required + +### Deployment +- Docker-based deployment +- Kubernetes orchestration +- Blue-green deployment strategy +- Automatic rollback on failure +- Database migrations run before deploy + +## Common Commands + +| Command | Purpose | +|---------|---------| +| `npm run dev` | Start development server | +| `npm test` | Run test suite | +| `npm run lint` | Check code style | +| `npm run build` | Build for production | +| `npm run migrate` | Run database migrations | + +## Team Contacts +- Tech Lead: Sarah Chen (@sarah.chen) +- Product Manager: Mike Johnson (@mike.j) +- DevOps: Alex Kim (@alex.k) + +## Known Issues & Workarounds +- PostgreSQL connection pooling limited to 20 during peak hours +- Workaround: Implement query queuing +- Safari 14 compatibility issues with async generators +- Workaround: Use Babel transpiler + +## Related Projects +- Analytics Dashboard: `/projects/analytics` +- Mobile App: `/projects/mobile` +- Admin Panel: `/projects/admin` +``` + +### ์˜ˆ์‹œ 2: ๋””๋ ‰ํ„ฐ๋ฆฌ๋ณ„ ๋ฉ”๋ชจ๋ฆฌ + +**ํŒŒ์ผ:** `./src/api/CLAUDE.md` + +````markdown +# API ๋ชจ๋“ˆ ํ‘œ์ค€ + +์ด ํŒŒ์ผ์€ /src/api/ ๋‚ด์˜ ๋ชจ๋“  ๊ฒƒ์— ๋Œ€ํ•ด ๋ฃจํŠธ CLAUDE.md๋ฅผ ์žฌ์ •์˜ํ•ฉ๋‹ˆ๋‹ค. + +## API-Specific Standards + +### Request Validation +- Use Zod for schema validation +- Always validate input +- Return 400 with validation errors +- Include field-level error details + +### Authentication +- All endpoints require JWT token +- Token in Authorization header +- Token expires after 24 hours +- Implement refresh token mechanism + +### Response Format + +All responses must follow this structure: + +```json +{ + "success": true, + "data": { /* actual data */ }, + "timestamp": "2025-11-06T10:30:00Z", + "version": "1.0" +} +``` + +Error responses: +```json +{ + "success": false, + "error": { + "code": "VALIDATION_ERROR", + "message": "User message", + "details": { /* field errors */ } + }, + "timestamp": "2025-11-06T10:30:00Z" +} +``` + +### Pagination +- Use cursor-based pagination (not offset) +- Include `hasMore` boolean +- Limit max page size to 100 +- Default page size: 20 + +### Rate Limiting +- 1000 requests per hour for authenticated users +- 100 requests per hour for public endpoints +- Return 429 when exceeded +- Include retry-after header + +### Caching +- Use Redis for session caching +- Cache duration: 5 minutes default +- Invalidate on write operations +- Tag cache keys with resource type +```` + +### ์˜ˆ์‹œ 3: ๊ฐœ์ธ ๋ฉ”๋ชจ๋ฆฌ + +**ํŒŒ์ผ:** `~/.claude/CLAUDE.md` + +```markdown +# ๋‚˜์˜ ๊ฐœ๋ฐœ ํ™˜๊ฒฝ ์„ค์ • + +## ๋‚˜์— ๋Œ€ํ•ด +- **๊ฒฝํ—˜ ์ˆ˜์ค€**: 8๋…„ ํ’€์Šคํƒ ๊ฐœ๋ฐœ +- **์„ ํ˜ธ ์–ธ์–ด**: TypeScript, Python +- **์ปค๋ฎค๋‹ˆ์ผ€์ด์…˜ ์Šคํƒ€์ผ**: ์˜ˆ์‹œ์™€ ํ•จ๊ป˜ ์ง์ ‘์  +- **ํ•™์Šต ์Šคํƒ€์ผ**: ์ฝ”๋“œ์™€ ํ•จ๊ป˜ ์‹œ๊ฐ์  ๋‹ค์ด์–ด๊ทธ๋žจ + +## ์ฝ”๋“œ ํ™˜๊ฒฝ ์„ค์ • + +### ์˜ค๋ฅ˜ ์ฒ˜๋ฆฌ +๋ช…์‹œ์ ์ธ try-catch ๋ธ”๋ก๊ณผ ์˜๋ฏธ ์žˆ๋Š” ์˜ค๋ฅ˜ ๋ฉ”์‹œ์ง€๋ฅผ ์‚ฌ์šฉํ•œ ์˜ค๋ฅ˜ ์ฒ˜๋ฆฌ๋ฅผ ์„ ํ˜ธํ•ฉ๋‹ˆ๋‹ค. +์ผ๋ฐ˜์ ์ธ ์˜ค๋ฅ˜๋ฅผ ํ”ผํ•ฉ๋‹ˆ๋‹ค. ๋””๋ฒ„๊น…์„ ์œ„ํ•ด ํ•ญ์ƒ ์˜ค๋ฅ˜๋ฅผ ๊ธฐ๋กํ•ฉ๋‹ˆ๋‹ค. + +### ์ฃผ์„ +๋ฌด์—‡์ด ์•„๋‹ˆ๋ผ WHY์— ๋Œ€ํ•ด ์ฃผ์„์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. ์ฝ”๋“œ๋Š” ์ž์ฒด ๋ฌธ์„œํ™”๋˜์–ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. +์ฃผ์„์€ ๋น„์ฆˆ๋‹ˆ์Šค ๋กœ์ง ๋˜๋Š” ๋ช…ํ™•ํ•˜์ง€ ์•Š์€ ๊ฒฐ์ •์„ ์„ค๋ช…ํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. + +### ํ…Œ์ŠคํŠธ +TDD(ํ…Œ์ŠคํŠธ ์ฃผ๋„ ๊ฐœ๋ฐœ)๋ฅผ ์„ ํ˜ธํ•ฉ๋‹ˆ๋‹ค. +ํ…Œ์ŠคํŠธ๋ฅผ ๋จผ์ € ์ž‘์„ฑํ•˜๊ณ  ๊ตฌํ˜„์„ ๋‚˜์ค‘์— ํ•ฉ๋‹ˆ๋‹ค. +๊ตฌํ˜„ ์„ธ๋ถ€ ์‚ฌํ•ญ์ด ์•„๋‹Œ ๋™์ž‘์— ์ดˆ์ ์„ ๋งž์ถฅ๋‹ˆ๋‹ค. + +### ์•„ํ‚คํ…์ฒ˜ +๋ชจ๋“ˆ์‹, ๋Š์Šจํ•˜๊ฒŒ ๊ฒฐํ•ฉ๋œ ์„ค๊ณ„๋ฅผ ์„ ํ˜ธํ•ฉ๋‹ˆ๋‹ค. +ํ…Œ์ŠคํŠธ ๊ฐ€๋Šฅ์„ฑ์„ ์œ„ํ•ด ์˜์กด์„ฑ ์ฃผ์ž…์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +๊ด€์‹ฌ์‚ฌ๋ฅผ ๋ถ„๋ฆฌํ•ฉ๋‹ˆ๋‹ค (์ปจํŠธ๋กค๋Ÿฌ, ์„œ๋น„์Šค, ์ €์žฅ์†Œ). + +## ๋””๋ฒ„๊น… ํ™˜๊ฒฝ ์„ค์ • +- `[DEBUG]` ์ ‘๋‘์‚ฌ์™€ ํ•จ๊ป˜ console.log ์‚ฌ์šฉ +- ์ปจํ…์ŠคํŠธ ํฌํ•จ: ํ•จ์ˆ˜ ์ด๋ฆ„, ๊ด€๋ จ ๋ณ€์ˆ˜ +- ๊ฐ€๋Šฅํ•œ ๊ฒฝ์šฐ ์Šคํƒ ํŠธ๋ ˆ์ด์Šค ์‚ฌ์šฉ +- ๋กœ๊ทธ์— ํ•ญ์ƒ ํƒ€์ž„์Šคํƒฌํ”„ ํฌํ•จ + +## ์ปค๋ฎค๋‹ˆ์ผ€์ด์…˜ +- ๋‹ค์ด์–ด๊ทธ๋žจ์œผ๋กœ ๋ณต์žกํ•œ ๊ฐœ๋… ์„ค๋ช… +- ์ด๋ก  ์„ค๋ช… ์ „์— ๊ตฌ์ฒด์ ์ธ ์˜ˆ์‹œ ๋ณด์—ฌ์ฃผ๊ธฐ +- ์ด์ „/์ดํ›„ ์ฝ”๋“œ ์Šค๋‹ˆํŽซ ํฌํ•จ +- ๋งˆ์ง€๋ง‰์— ์ฃผ์š” ์š”์•ฝ ์ œ๊ณต + +## ํ”„๋กœ์ ํŠธ ๊ตฌ์„ฑ +๋‚ด ํ”„๋กœ์ ํŠธ๋Š” ๋‹ค์Œ๊ณผ ๊ฐ™์ด ๊ตฌ์„ฑํ•ฉ๋‹ˆ๋‹ค. + + project/ + โ”œโ”€โ”€ src/ + โ”‚ โ”œโ”€โ”€ api/ + โ”‚ โ”œโ”€โ”€ services/ + โ”‚ โ”œโ”€โ”€ models/ + โ”‚ โ””โ”€โ”€ utils/ + โ”œโ”€โ”€ tests/ + โ”œโ”€โ”€ docs/ + โ””โ”€โ”€ docker/ + +## ๋„๊ตฌ +- **IDE**: vim ํ‚ค ๋ฐ”์ธ๋”ฉ์ด ์žˆ๋Š” VS Code +- **ํ„ฐ๋ฏธ๋„**: Oh-My-Zsh๊ฐ€ ์žˆ๋Š” Zsh +- **ํ˜•์‹**: Prettier (100์ž ์ค„ ๊ธธ์ด) +- **๋ฆฐํ„ฐ**: airbnb config๊ฐ€ ์žˆ๋Š” ESLint +- **ํ…Œ์ŠคํŠธ ํ”„๋ ˆ์ž„์›Œํฌ**: React Testing Library๊ฐ€ ์žˆ๋Š” Jest +``` + +_๋‚˜์˜ ํ…Œ์ŠคํŠธ_ +Claude์—๊ฒŒ ์ƒˆ ๊ทœ์น™์„ ์ €์žฅํ•˜๋ผ๊ณ  ์š”์ฒญ + +![Ask Claude to save a new rule](memory-ask-claude.png) +์–ด๋–ค `Claude.md` ํŒŒ์ผ๋„ ์—†์—ˆ๊ธฐ ๋•Œ๋ฌธ์— Claude๋Š” ๊ทœ์น™์„ ์ €์žฅํ•˜์ง€ ์•Š์•˜์Šต๋‹ˆ๋‹ค. ๊ทธ๋Ÿฐ ๋‹ค์Œ Claude์—๊ฒŒ ์œ„์น˜๋ฅผ ํ™•์ธํ•ด ๋‹ฌ๋ผ๊ณ  ์š”์ฒญํ–ˆ์Šต๋‹ˆ๋‹ค. + +![Ask Claude to save a new rule](memory-saved.png) + +### ์˜ˆ์‹œ 4: ์„ธ์…˜ ์ค‘ ๋ฉ”๋ชจ๋ฆฌ ์—…๋ฐ์ดํŠธ + +ํ™œ์„ฑ Claude Code ์„ธ์…˜ ์ค‘์— ๋ฉ”๋ชจ๋ฆฌ์— ์ƒˆ ๊ทœ์น™์„ ์ถ”๊ฐ€ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์ด๋ฅผ ์ˆ˜ํ–‰ํ•˜๋Š” ๋‘ ๊ฐ€์ง€ ๋ฐฉ๋ฒ•์ด ์žˆ์Šต๋‹ˆ๋‹ค. + +#### ๋ฐฉ๋ฒ• 1: ์ง์ ‘ ์š”์ฒญ + +```markdown +User: Remember that I prefer using React hooks instead of class components + for all new components. + +Claude: I'm adding that to your memory. Which memory file should this go in? + 1. Project memory (./CLAUDE.md) + 2. Personal memory (~/.claude/CLAUDE.md) + +User: Project memory + +Claude: โœ… Memory saved! + +Added to ./CLAUDE.md: +--- + +### Component Development +- Use functional components with React Hooks +- Prefer hooks over class components +- Custom hooks for reusable logic +- Use useCallback for event handlers +- Use useMemo for expensive computations +``` + +#### ๋ฐฉ๋ฒ• 2: "# new rule into memory" ํŒจํ„ด ์‚ฌ์šฉ + +"# new rule into memory" ๋ช…์‹œ์  ํŒจํ„ด์„ ์‚ฌ์šฉํ•˜์—ฌ ๋ฉ”๋ชจ๋ฆฌ ์—…๋ฐ์ดํŠธ๋ฅผ ํŠธ๋ฆฌ๊ฑฐํ•  ์ˆ˜๋„ ์žˆ์Šต๋‹ˆ๋‹ค. + +```markdown +User: # new rule into memory + Always validate user input with Zod schemas before processing. + +Claude: I'm saving this rule to memory. Which memory file should I use? + 1. Project memory (./CLAUDE.md) + 2. Personal memory (~/.claude/CLAUDE.md) + +User: Project memory + +Claude: โœ… Memory saved! + +Added to ./CLAUDE.md: +--- + +### Input Validation +- Always validate user input with Zod schemas before processing +- Define schemas at the top of each API handler file +- Return 400 status with validation errors +``` + +#### ๋ฉ”๋ชจ๋ฆฌ ์ถ”๊ฐ€๋ฅผ ์œ„ํ•œ ํŒ + +- ๊ทœ์น™์„ ๊ตฌ์ฒด์ ์ด๊ณ  ์‹คํ–‰ ๊ฐ€๋Šฅํ•˜๊ฒŒ ๋งŒ๋“œ์„ธ์š” +- ๊ด€๋ จ ๊ทœ์น™์„ ์„น์…˜ ํ—ค๋” ์•„๋ž˜์— ํ•จ๊ป˜ ๊ทธ๋ฃนํ™”ํ•˜์„ธ์š” +- ์ฝ˜ํ…์ธ ๋ฅผ ์ค‘๋ณตํ•˜์ง€ ๋ง๊ณ  ๊ธฐ์กด ์„น์…˜์„ ์—…๋ฐ์ดํŠธํ•˜์„ธ์š” +- ์ ์ ˆํ•œ ๋ฉ”๋ชจ๋ฆฌ ๋ฒ”์œ„(ํ”„๋กœ์ ํŠธ vs. ๊ฐœ์ธ)๋ฅผ ์„ ํƒํ•˜์„ธ์š” + +## ๋ฉ”๋ชจ๋ฆฌ ๊ธฐ๋Šฅ ๋น„๊ต + +| ๊ธฐ๋Šฅ | Claude ์›น/๋ฐ์Šคํฌํ†ฑ | Claude Code (CLAUDE.md) | +|---------|-------------------|------------------------| +| ์ž๋™ ํ•ฉ์„ฑ | โœ… 24์‹œ๊ฐ„๋งˆ๋‹ค | โœ… ์ž๋™ ๋ฉ”๋ชจ๋ฆฌ | +| ๊ต์ฐจ ํ”„๋กœ์ ํŠธ | โœ… ๊ณต์œ  ํ”„๋กœ์ ํŠธ | โŒ ํ”„๋กœ์ ํŠธ๋ณ„ | +| ํŒ€ ์ ‘๊ทผ | โœ… ๊ณต์œ  ํ”„๋กœ์ ํŠธ | โœ… Git ์ถ”์  | +| ๊ฒ€์ƒ‰ ๊ฐ€๋Šฅ | โœ… ๋‚ด์žฅ | โœ… `/memory`๋ฅผ ํ†ตํ•ด | +| ํŽธ์ง‘ ๊ฐ€๋Šฅ | โœ… ์ฑ„ํŒ… ๋‚ด | โœ… ์ง์ ‘ ํŒŒ์ผ ํŽธ์ง‘ | +| ๊ฐ€์ ธ์˜ค๊ธฐ/๋‚ด๋ณด๋‚ด๊ธฐ | โœ… ์˜ˆ | โœ… ๋ณต์‚ฌ/๋ถ™์—ฌ๋„ฃ๊ธฐ | +| ์˜๊ตฌ์  | โœ… 24์‹œ๊ฐ„ ์ด์ƒ | โœ… ๋ฌด๊ธฐํ•œ | + +### Claude ์›น/๋ฐ์Šคํฌํ†ฑ์˜ ๋ฉ”๋ชจ๋ฆฌ + +#### ๋ฉ”๋ชจ๋ฆฌ ํ•ฉ์„ฑ ํƒ€์ž„๋ผ์ธ + +```mermaid +graph LR + A["Day 1: User
Conversations"] -->|24 hours| B["Day 2: Memory
Synthesis"] + B -->|Automatic| C["Memory Updated
Summarized"] + C -->|Loaded in| D["Day 2-N:
New Conversations"] + D -->|Add to| E["Memory"] + E -->|24 hours later| F["Memory Refreshed"] +``` + +**๋ฉ”๋ชจ๋ฆฌ ์š”์•ฝ ์˜ˆ์‹œ:** + +```markdown +## Claude's Memory of User + +### Professional Background +- Senior full-stack developer with 8 years experience +- Focus on TypeScript/Node.js backends and React frontends +- Active open source contributor +- Interested in AI and machine learning + +### Project Context +- Currently building e-commerce platform +- Tech stack: Node.js, PostgreSQL, React 18, Docker +- Working with team of 5 developers +- Using CI/CD and blue-green deployments + +### Communication Preferences +- Prefers direct, concise explanations +- Likes visual diagrams and examples +- Appreciates code snippets +- Explains business logic in comments + +### Current Goals +- Improve API performance +- Increase test coverage to 90% +- Implement caching strategy +- Document architecture +``` + +## ๋ชจ๋ฒ” ์‚ฌ๋ก€ + +### ํ•ด์•ผ ํ•  ์ผ - ํฌํ•จํ•  ๋‚ด์šฉ + +- **๊ตฌ์ฒด์ ์ด๊ณ  ์ƒ์„ธํ•˜๊ฒŒ**: ๋ชจํ˜ธํ•œ ์ง€์นจ ๋Œ€์‹  ๋ช…ํ™•ํ•˜๊ณ  ์ƒ์„ธํ•œ ์ง€์นจ์„ ์‚ฌ์šฉํ•˜์„ธ์š”. + - โœ… ์ข‹์Œ: "๋ชจ๋“  JavaScript ํŒŒ์ผ์— 2์นธ ๋“ค์—ฌ์“ฐ๊ธฐ๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค." + - โŒ ํ”ผํ•ด์•ผ ํ•  ๊ฒƒ: "๋ชจ๋ฒ” ์‚ฌ๋ก€๋ฅผ ๋”ฐ๋ฆ…๋‹ˆ๋‹ค." + +- **์ฒด๊ณ„์ ์œผ๋กœ ์œ ์ง€**: ๋ช…ํ™•ํ•œ ๋งˆํฌ๋‹ค์šด ์„น์…˜๊ณผ ์ œ๋ชฉ์œผ๋กœ ๋ฉ”๋ชจ๋ฆฌ ํŒŒ์ผ์„ ๊ตฌ์„ฑํ•˜์„ธ์š”. + +- **์ ์ ˆํ•œ ๊ณ„์ธต ์ˆ˜์ค€ ์‚ฌ์šฉ**: + - **๊ด€๋ฆฌ ์ •์ฑ…**: ํšŒ์‚ฌ ์ „์ฒด ์ •์ฑ…, ๋ณด์•ˆ ํ‘œ์ค€, ๊ทœ์ • ์ค€์ˆ˜ ์š”๊ตฌ ์‚ฌํ•ญ + - **ํ”„๋กœ์ ํŠธ ๋ฉ”๋ชจ๋ฆฌ**: ํŒ€ ํ‘œ์ค€, ์•„ํ‚คํ…์ฒ˜, ์ฝ”๋”ฉ ๊ทœ์น™ (git์— ์ปค๋ฐ‹) + - **์‚ฌ์šฉ์ž ๋ฉ”๋ชจ๋ฆฌ**: ๊ฐœ์ธ ํ™˜๊ฒฝ ์„ค์ •, ์ปค๋ฎค๋‹ˆ์ผ€์ด์…˜ ์Šคํƒ€์ผ, ๋„๊ตฌ ์„ ํƒ + - **๋””๋ ‰ํ„ฐ๋ฆฌ ๋ฉ”๋ชจ๋ฆฌ**: ๋ชจ๋“ˆ๋ณ„ ๊ทœ์น™ ๋ฐ ์žฌ์ •์˜ + +- **๊ฐ€์ ธ์˜ค๊ธฐ ํ™œ์šฉ**: `@path/to/file` ๊ตฌ๋ฌธ์„ ์‚ฌ์šฉํ•˜์—ฌ ๊ธฐ์กด ๋ฌธ์„œ๋ฅผ ์ฐธ์กฐํ•˜์„ธ์š”. + - ์ตœ๋Œ€ 5๋‹จ๊ณ„์˜ ์žฌ๊ท€์  ์ค‘์ฒฉ์„ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค. + - ๋ฉ”๋ชจ๋ฆฌ ํŒŒ์ผ ๊ฐ„์˜ ์ค‘๋ณต์„ ํ”ผํ•ฉ๋‹ˆ๋‹ค. + - ์˜ˆ: `See @README.md for project overview` + +- **์ž์ฃผ ์‚ฌ์šฉํ•˜๋Š” ๋ช…๋ น์–ด ๋ฌธ์„œํ™”**: ์‹œ๊ฐ„์„ ์ ˆ์•ฝํ•˜๊ธฐ ์œ„ํ•ด ๋ฐ˜๋ณต์ ์œผ๋กœ ์‚ฌ์šฉํ•˜๋Š” ๋ช…๋ น์–ด๋ฅผ ํฌํ•จํ•˜์„ธ์š”. + +- **ํ”„๋กœ์ ํŠธ ๋ฉ”๋ชจ๋ฆฌ ๋ฒ„์ „ ๊ด€๋ฆฌ**: ํŒ€์˜ ์ด์ ์„ ์œ„ํ•ด ํ”„๋กœ์ ํŠธ ์ˆ˜์ค€ CLAUDE.md ํŒŒ์ผ์„ git์— ์ปค๋ฐ‹ํ•˜์„ธ์š”. + +- **์ •๊ธฐ์ ์œผ๋กœ ๊ฒ€ํ† **: ํ”„๋กœ์ ํŠธ๊ฐ€ ๋ฐœ์ „ํ•˜๊ณ  ์š”๊ตฌ ์‚ฌํ•ญ์ด ๋ณ€๊ฒฝ๋จ์— ๋”ฐ๋ผ ๋ฉ”๋ชจ๋ฆฌ๋ฅผ ์ •๊ธฐ์ ์œผ๋กœ ์—…๋ฐ์ดํŠธํ•˜์„ธ์š”. + +- **๊ตฌ์ฒด์ ์ธ ์˜ˆ์‹œ ์ œ๊ณต**: ์ฝ”๋“œ ์Šค๋‹ˆํŽซ ๋ฐ ํŠน์ • ์‹œ๋‚˜๋ฆฌ์˜ค๋ฅผ ํฌํ•จํ•˜์„ธ์š”. + +### ํ•˜์ง€ ๋ง์•„์•ผ ํ•  ์ผ - ํ”ผํ•ด์•ผ ํ•  ๋‚ด์šฉ + +- **๋น„๋ฐ€ ์ €์žฅ ๊ธˆ์ง€**: API ํ‚ค, ๋น„๋ฐ€๋ฒˆํ˜ธ, ํ† ํฐ ๋˜๋Š” ์ž๊ฒฉ ์ฆ๋ช…์„ ์ ˆ๋Œ€ ํฌํ•จํ•˜์ง€ ๋งˆ์„ธ์š”. + +- **๋ฏผ๊ฐํ•œ ๋ฐ์ดํ„ฐ ํฌํ•จ ๊ธˆ์ง€**: ๊ฐœ์ธ ์‹๋ณ„ ์ •๋ณด(PII), ๊ฐœ์ธ ์ •๋ณด ๋˜๋Š” ๋…์  ๊ธฐ๋ฐ€์„ ํฌํ•จํ•˜์ง€ ๋งˆ์„ธ์š”. + +- **์ฝ˜ํ…์ธ  ์ค‘๋ณต ๊ธˆ์ง€**: ๋Œ€์‹  ๊ฐ€์ ธ์˜ค๊ธฐ (`@path`)๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ๊ธฐ์กด ๋ฌธ์„œ๋ฅผ ์ฐธ์กฐํ•˜์„ธ์š”. + +- **๋ชจํ˜ธํ•œ ํ‘œํ˜„ ๊ธˆ์ง€**: "๋ชจ๋ฒ” ์‚ฌ๋ก€๋ฅผ ๋”ฐ๋ฆ…๋‹ˆ๋‹ค" ๋˜๋Š” "์ข‹์€ ์ฝ”๋“œ๋ฅผ ์ž‘์„ฑํ•ฉ๋‹ˆ๋‹ค"์™€ ๊ฐ™์€ ์ผ๋ฐ˜์ ์ธ ์ง„์ˆ ์„ ํ”ผํ•˜์„ธ์š”. + +- **๋„ˆ๋ฌด ๊ธธ๊ฒŒ ๋งŒ๋“ค์ง€ ๋งˆ์„ธ์š”**: ๊ฐœ๋ณ„ ๋ฉ”๋ชจ๋ฆฌ ํŒŒ์ผ์€ ์ง‘์ค‘์ ์ด๊ณ  500์ค„ ๋ฏธ๋งŒ์œผ๋กœ ์œ ์ง€ํ•˜์„ธ์š”. + +- **๊ณผ๋„ํ•œ ์ •๋ฆฌ ๊ธˆ์ง€**: ๊ณ„์ธต ๊ตฌ์กฐ๋ฅผ ์ „๋žต์ ์œผ๋กœ ์‚ฌ์šฉํ•˜๊ณ  ๊ณผ๋„ํ•œ ํ•˜์œ„ ๋””๋ ‰ํ„ฐ๋ฆฌ ์žฌ์ •์˜๋ฅผ ๋งŒ๋“ค์ง€ ๋งˆ์„ธ์š”. + +- **์—…๋ฐ์ดํŠธ๋ฅผ ์žŠ์ง€ ๋งˆ์„ธ์š”**: ์˜ค๋ž˜๋œ ๋ฉ”๋ชจ๋ฆฌ๋Š” ํ˜ผ๋ž€๊ณผ ์‹œ๋Œ€์— ๋’ค๋–จ์–ด์ง„ ๊ด€ํ–‰์„ ์ดˆ๋ž˜ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +- **์ค‘์ฒฉ ์ œํ•œ ์ดˆ๊ณผ ๊ธˆ์ง€**: ๋ฉ”๋ชจ๋ฆฌ ๊ฐ€์ ธ์˜ค๊ธฐ๋Š” ์ตœ๋Œ€ 5๋‹จ๊ณ„์˜ ์ค‘์ฒฉ์„ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค. + +### ๋ฉ”๋ชจ๋ฆฌ ๊ด€๋ฆฌ ํŒ + +**์˜ฌ๋ฐ”๋ฅธ ๋ฉ”๋ชจ๋ฆฌ ์ˆ˜์ค€ ์„ ํƒ:** + +| ์‚ฌ์šฉ ์‚ฌ๋ก€ | ๋ฉ”๋ชจ๋ฆฌ ์ˆ˜์ค€ | ์ด์œ  | +|----------|-------------|-----------| +| ํšŒ์‚ฌ ๋ณด์•ˆ ์ •์ฑ… | ๊ด€๋ฆฌ ์ •์ฑ… | ์กฐ์ง ์ „์ฒด์˜ ๋ชจ๋“  ํ”„๋กœ์ ํŠธ์— ์ ์šฉ๋จ | +| ํŒ€ ์ฝ”๋“œ ์Šคํƒ€์ผ ๊ฐ€์ด๋“œ | ํ”„๋กœ์ ํŠธ | Git์„ ํ†ตํ•ด ํŒ€๊ณผ ๊ณต์œ ๋จ | +| ์„ ํ˜ธํ•˜๋Š” ํŽธ์ง‘๊ธฐ ๋‹จ์ถ•ํ‚ค | ์‚ฌ์šฉ์ž | ๊ฐœ์ธ ํ™˜๊ฒฝ ์„ค์ •, ๊ณต์œ ๋˜์ง€ ์•Š์Œ | +| API ๋ชจ๋“ˆ ํ‘œ์ค€ | ๋””๋ ‰ํ„ฐ๋ฆฌ | ํ•ด๋‹น ๋ชจ๋“ˆ์—๋งŒ ํ•ด๋‹น | + +**๋น ๋ฅธ ์—…๋ฐ์ดํŠธ ์›Œํฌํ”Œ๋กœ์šฐ:** + +1. ๋‹จ์ผ ๊ทœ์น™์˜ ๊ฒฝ์šฐ: `/memory`๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ํŽธ์ง‘๊ธฐ๋ฅผ ์—ด๊ฑฐ๋‚˜ ๋Œ€ํ™”์‹์œผ๋กœ ์š”์ฒญํ•˜์„ธ์š”. +2. ์—ฌ๋Ÿฌ ๋ณ€๊ฒฝ ์‚ฌํ•ญ์˜ ๊ฒฝ์šฐ: `/memory`๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ํŽธ์ง‘๊ธฐ๋ฅผ ์—ด์„ธ์š”. +3. ์ดˆ๊ธฐ ์„ค์ •์˜ ๊ฒฝ์šฐ: `/init`์„ ์‚ฌ์šฉํ•˜์—ฌ ํ…œํ”Œ๋ฆฟ์„ ๋งŒ๋“œ์„ธ์š”. + +**๊ฐ€์ ธ์˜ค๊ธฐ ๋ชจ๋ฒ” ์‚ฌ๋ก€:** + +```markdown +# Good: Reference existing docs +@README.md +@docs/architecture.md +@package.json + +# Avoid: Copying content that exists elsewhere +# Instead of copying README content into CLAUDE.md, just import it +``` + +## ์„ค์น˜ ์ง€์นจ + +### ํ”„๋กœ์ ํŠธ ๋ฉ”๋ชจ๋ฆฌ ์„ค์ • + +#### ๋ฐฉ๋ฒ• 1: `/init` ๋ช…๋ น์–ด ์‚ฌ์šฉ (๊ถŒ์žฅ) + +ํ”„๋กœ์ ํŠธ ๋ฉ”๋ชจ๋ฆฌ๋ฅผ ์„ค์ •ํ•˜๋Š” ๊ฐ€์žฅ ๋น ๋ฅธ ๋ฐฉ๋ฒ•์ž…๋‹ˆ๋‹ค. + +1. **ํ”„๋กœ์ ํŠธ ๋””๋ ‰ํ„ฐ๋ฆฌ๋กœ ์ด๋™:** + ```bash + cd /path/to/your/project + ``` + +2. **Claude Code์—์„œ init ๋ช…๋ น ์‹คํ–‰:** + ```bash + /init + ``` + +3. **Claude๋Š” ํ…œํ”Œ๋ฆฟ ๊ตฌ์กฐ๋กœ CLAUDE.md๋ฅผ ์ƒ์„ฑํ•˜๊ณ  ์ฑ„์›๋‹ˆ๋‹ค.** + +4. **์ƒ์„ฑ๋œ ํŒŒ์ผ์„ ํ”„๋กœ์ ํŠธ ์š”๊ตฌ ์‚ฌํ•ญ์— ๋งž๊ฒŒ ์‚ฌ์šฉ์ž ์ง€์ •ํ•ฉ๋‹ˆ๋‹ค.** + +5. **git์— ์ปค๋ฐ‹:** + ```bash + git add CLAUDE.md + git commit -m "Initialize project memory with /init" + ``` + +#### ๋ฐฉ๋ฒ• 2: ์ˆ˜๋™ ์ƒ์„ฑ + +์ˆ˜๋™ ์„ค์ •์„ ์„ ํ˜ธํ•˜๋Š” ๊ฒฝ์šฐ: + +1. **ํ”„๋กœ์ ํŠธ ๋ฃจํŠธ์— CLAUDE.md ์ƒ์„ฑ:** + ```bash + cd /path/to/your/project + touch CLAUDE.md + ``` + +2. **ํ”„๋กœ์ ํŠธ ํ‘œ์ค€ ์ถ”๊ฐ€:** + ```bash + cat > CLAUDE.md << 'EOF' + # Project Configuration + + ## Project Overview + - **Name**: Your Project Name + - **Tech Stack**: List your technologies + - **Team Size**: Number of developers + + ## Development Standards + - Your coding standards + - Naming conventions + - Testing requirements + EOF + ``` + +3. **git์— ์ปค๋ฐ‹:** + ```bash + git add CLAUDE.md + git commit -m "Add project memory configuration" + ``` + +#### ๋ฐฉ๋ฒ• 3: `#`๋ฅผ ์‚ฌ์šฉํ•œ ๋น ๋ฅธ ์—…๋ฐ์ดํŠธ + +CLAUDE.md๊ฐ€ ์กด์žฌํ•˜๋ฉด ๋Œ€ํ™” ์ค‘์— ๋น ๋ฅด๊ฒŒ ๊ทœ์น™์„ ์ถ”๊ฐ€ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +```markdown +# Use semantic versioning for all releases + +# Always run tests before committing + +# Prefer composition over inheritance +``` + +Claude๋Š” ์–ด๋–ค ๋ฉ”๋ชจ๋ฆฌ ํŒŒ์ผ์„ ์—…๋ฐ์ดํŠธํ• ์ง€ ์„ ํƒํ•˜๋ผ๋Š” ๋ฉ”์‹œ์ง€๋ฅผ ํ‘œ์‹œํ•ฉ๋‹ˆ๋‹ค. + +### ๊ฐœ์ธ ๋ฉ”๋ชจ๋ฆฌ ์„ค์ • + +1. **`~/.claude` ๋””๋ ‰ํ„ฐ๋ฆฌ ์ƒ์„ฑ:** + ```bash + mkdir -p ~/.claude + ``` + +2. **๊ฐœ์ธ CLAUDE.md ์ƒ์„ฑ:** + ```bash + touch ~/.claude/CLAUDE.md + ``` + +3. **ํ™˜๊ฒฝ ์„ค์ • ์ถ”๊ฐ€:** + ```bash + cat > ~/.claude/CLAUDE.md << 'EOF' + # My Development Preferences + + ## About Me + - Experience Level: [Your level] + - Preferred Languages: [Your languages] + - Communication Style: [Your style] + + ## Code Preferences + - [Your preferences] + EOF + ``` + +### ๋””๋ ‰ํ„ฐ๋ฆฌ๋ณ„ ๋ฉ”๋ชจ๋ฆฌ ์„ค์ • + +1. **ํŠน์ • ๋””๋ ‰ํ„ฐ๋ฆฌ์— ๋Œ€ํ•œ ๋ฉ”๋ชจ๋ฆฌ ์ƒ์„ฑ:** + ```bash + mkdir -p /path/to/directory/.claude + touch /path/to/directory/CLAUDE.md + ``` + +2. **๋””๋ ‰ํ„ฐ๋ฆฌ๋ณ„ ๊ทœ์น™ ์ถ”๊ฐ€:** + ```bash + cat > /path/to/directory/CLAUDE.md << 'EOF' + # [Directory Name] Standards + + This file overrides root CLAUDE.md for this directory. + + ## [Specific Standards] + EOF + ``` + +3. **๋ฒ„์ „ ์ œ์–ด์— ์ปค๋ฐ‹:** + ```bash + git add /path/to/directory/CLAUDE.md + git commit -m "Add [directory] memory configuration" + ``` + +### ์„ค์ • ํ™•์ธ + +1. **๋ฉ”๋ชจ๋ฆฌ ์œ„์น˜ ํ™•์ธ:** + ```bash + # Project root memory + ls -la ./CLAUDE.md + + # Personal memory + ls -la ~/.claude/CLAUDE.md + ``` + +2. **Claude Code๋Š” ์„ธ์…˜ ์‹œ์ž‘ ์‹œ ์ด๋Ÿฌํ•œ ํŒŒ์ผ์„ ์ž๋™์œผ๋กœ ๋กœ๋“œํ•ฉ๋‹ˆ๋‹ค.** + +3. **ํ”„๋กœ์ ํŠธ์—์„œ ์ƒˆ ์„ธ์…˜์„ ์‹œ์ž‘ํ•˜์—ฌ Claude Code๋กœ ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค.** + +## ๊ณต์‹ ๋ฌธ์„œ + +๊ฐ€์žฅ ์ตœ์‹  ์ •๋ณด๋Š” Claude Code ๊ณต์‹ ๋ฌธ์„œ๋ฅผ ์ฐธ์กฐํ•˜์„ธ์š”. + +- **[๋ฉ”๋ชจ๋ฆฌ ๋ฌธ์„œ](https://code.claude.com/docs/en/memory)** - ์ „์ฒด ๋ฉ”๋ชจ๋ฆฌ ์‹œ์Šคํ…œ ์ฐธ์กฐ +- **[์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด ์ฐธ์กฐ](https://code.claude.com/docs/en/interactive-mode)** - `/init` ๋ฐ `/memory`๋ฅผ ํฌํ•จํ•œ ๋ชจ๋“  ๋‚ด์žฅ ๋ช…๋ น์–ด +- **[CLI ์ฐธ์กฐ](https://code.claude.com/docs/en/cli-reference)** - ๋ช…๋ น์ค„ ์ธํ„ฐํŽ˜์ด์Šค ๋ฌธ์„œ + +### ๊ณต์‹ ๋ฌธ์„œ์˜ ์ฃผ์š” ๊ธฐ์ˆ  ์„ธ๋ถ€ ์ •๋ณด + +**๋ฉ”๋ชจ๋ฆฌ ๋กœ๋”ฉ:** + +- ๋ชจ๋“  ๋ฉ”๋ชจ๋ฆฌ ํŒŒ์ผ์€ Claude Code๊ฐ€ ์‹œ์ž‘๋  ๋•Œ ์ž๋™์œผ๋กœ ๋กœ๋“œ๋ฉ๋‹ˆ๋‹ค. +- Claude๋Š” ํ˜„์žฌ ์ž‘์—… ๋””๋ ‰ํ„ฐ๋ฆฌ์—์„œ ์œ„๋กœ ์˜ฌ๋ผ๊ฐ€ CLAUDE.md ํŒŒ์ผ์„ ๊ฒ€์ƒ‰ํ•ฉ๋‹ˆ๋‹ค. +- ํ•˜์œ„ ํŠธ๋ฆฌ ํŒŒ์ผ์€ ํ•ด๋‹น ๋””๋ ‰ํ„ฐ๋ฆฌ์— ์ ‘๊ทผํ•  ๋•Œ ๋ฌธ๋งฅ์ ์œผ๋กœ ๊ฒ€์ƒ‰๋˜๊ณ  ๋กœ๋“œ๋ฉ๋‹ˆ๋‹ค. + +**๊ฐ€์ ธ์˜ค๊ธฐ ๊ตฌ๋ฌธ:** + +- `@path/to/file`์„ ์‚ฌ์šฉํ•˜์—ฌ ์™ธ๋ถ€ ์ฝ˜ํ…์ธ ๋ฅผ ํฌํ•จํ•ฉ๋‹ˆ๋‹ค (์˜ˆ: `@~/.claude/my-project-instructions.md`). +- ์ƒ๋Œ€ ๋ฐ ์ ˆ๋Œ€ ๊ฒฝ๋กœ ๋ชจ๋‘ ์ง€์›๋ฉ๋‹ˆ๋‹ค. +- ์ตœ๋Œ€ 5๋‹จ๊ณ„์˜ ์žฌ๊ท€์  ๊ฐ€์ ธ์˜ค๊ธฐ๊ฐ€ ์ง€์›๋ฉ๋‹ˆ๋‹ค. +- ์™ธ๋ถ€์—์„œ ์ฒ˜์Œ ๊ฐ€์ ธ์˜ฌ ๊ฒฝ์šฐ ์Šน์ธ ๋Œ€ํ™” ์ƒ์ž๊ฐ€ ๋‚˜ํƒ€๋‚ฉ๋‹ˆ๋‹ค. +- Markdown ์ฝ”๋“œ ์ŠคํŒฌ์ด๋‚˜ ์ฝ”๋“œ ๋ธ”๋ก ๋‚ด๋ถ€์—์„œ๋Š” ํ‰๊ฐ€๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. +- ์ฐธ์กฐ๋œ ์ฝ˜ํ…์ธ ๋ฅผ Claude์˜ ์ปจํ…์ŠคํŠธ์— ์ž๋™์œผ๋กœ ํฌํ•จํ•ฉ๋‹ˆ๋‹ค. + +**๋ฉ”๋ชจ๋ฆฌ ๊ณ„์ธต ์šฐ์„  ์ˆœ์œ„:** + +1. ๊ด€๋ฆฌ ์ •์ฑ… (๊ฐ€์žฅ ๋†’์€ ์šฐ์„  ์ˆœ์œ„) +2. ๊ด€๋ฆฌ ๋“œ๋กญ์ธ (`managed-settings.d/`, v2.1.83+) +3. ํ”„๋กœ์ ํŠธ ๋ฉ”๋ชจ๋ฆฌ +4. ํ”„๋กœ์ ํŠธ ๊ทœ์น™ (`.claude/rules/`) +5. ์‚ฌ์šฉ์ž ๋ฉ”๋ชจ๋ฆฌ +6. ์‚ฌ์šฉ์ž ์ˆ˜์ค€ ๊ทœ์น™ (`~/.claude/rules/`) +7. ๋กœ์ปฌ ํ”„๋กœ์ ํŠธ ๋ฉ”๋ชจ๋ฆฌ +8. ์ž๋™ ๋ฉ”๋ชจ๋ฆฌ (๊ฐ€์žฅ ๋‚ฎ์€ ์šฐ์„  ์ˆœ์œ„) + +## ๊ด€๋ จ ๊ฐœ๋… ๋งํฌ + +### ํ†ตํ•ฉ ์ง€์  +- [MCP ํ”„๋กœํ† ์ฝœ](../05-mcp/) - ๋ฉ”๋ชจ๋ฆฌ์™€ ํ•จ๊ป˜ ์‹ค์‹œ๊ฐ„ ๋ฐ์ดํ„ฐ ์ ‘๊ทผ +- [์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด](../01-slash-commands/) - ์„ธ์…˜๋ณ„ ๋‹จ์ถ•ํ‚ค +- [์Šคํ‚ฌ](../03-skills/) - ๋ฉ”๋ชจ๋ฆฌ ์ปจํ…์ŠคํŠธ๋ฅผ ์‚ฌ์šฉํ•œ ์ž๋™ํ™”๋œ ์›Œํฌํ”Œ๋กœ์šฐ + +### ๊ด€๋ จ Claude ๊ธฐ๋Šฅ +- [Claude ์›น ๋ฉ”๋ชจ๋ฆฌ](https://claude.ai) - ์ž๋™ ํ•ฉ์„ฑ +- [๊ณต์‹ ๋ฉ”๋ชจ๋ฆฌ ๋ฌธ์„œ](https://code.claude.com/docs/en/memory) - Anthropic ๋ฌธ์„œ + +--- +**๋งˆ์ง€๋ง‰ ์—…๋ฐ์ดํŠธ**: 2026๋…„ 6์›” 24์ผ +**Claude Code ๋ฒ„์ „**: 2.1.187 +**์ถœ์ฒ˜**: +- https://code.claude.com/docs/en/memory +- https://code.claude.com/docs/en/settings +- https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md +- https://docs.anthropic.com/en/docs/claude-code/settings +- https://code.claude.com/docs/en/cli-reference +- https://github.com/anthropics/claude-code/releases/tag/v2.1.117 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.144 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.145 +**ํ˜ธํ™˜ ๋ชจ๋ธ**: Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5 diff --git a/ko/02-memory/directory-api-CLAUDE.md b/ko/02-memory/directory-api-CLAUDE.md new file mode 100644 index 00000000..4af77ea6 --- /dev/null +++ b/ko/02-memory/directory-api-CLAUDE.md @@ -0,0 +1,64 @@ +# API ๋ชจ๋“ˆ ํ‘œ์ค€ + +์ด ํŒŒ์ผ์€ /src/api/ ๋‚ด์˜ ๋ชจ๋“  ํ•ญ๋ชฉ์— ๋Œ€ํ•ด ๋ฃจํŠธ CLAUDE.md๋ฅผ ์žฌ์ •์˜ํ•ฉ๋‹ˆ๋‹ค. + +## API ํŠน์ • ํ‘œ์ค€ + +### ์š”์ฒญ ์œ ํšจ์„ฑ ๊ฒ€์‚ฌ +- ์Šคํ‚ค๋งˆ ์œ ํšจ์„ฑ ๊ฒ€์‚ฌ์— Zod ์‚ฌ์šฉ +- ํ•ญ์ƒ ์ž…๋ ฅ ์œ ํšจ์„ฑ ๊ฒ€์‚ฌ +- ์œ ํšจ์„ฑ ๊ฒ€์‚ฌ ์˜ค๋ฅ˜์™€ ํ•จ๊ป˜ 400 ๋ฐ˜ํ™˜ +- ํ•„๋“œ ์ˆ˜์ค€ ์˜ค๋ฅ˜ ์„ธ๋ถ€ ์ •๋ณด ํฌํ•จ + +### ์ธ์ฆ +- ๋ชจ๋“  ์—”๋“œํฌ์ธํŠธ๋Š” JWT ํ† ํฐ ํ•„์š” +- Authorization ํ—ค๋”์— ํ† ํฐ ํฌํ•จ +- ํ† ํฐ์€ 24์‹œ๊ฐ„ ํ›„ ๋งŒ๋ฃŒ +- ๋ฆฌํ”„๋ ˆ์‹œ ํ† ํฐ ๋ฉ”์ปค๋‹ˆ์ฆ˜ ๊ตฌํ˜„ + +### ์‘๋‹ต ํ˜•์‹ + +๋ชจ๋“  ์‘๋‹ต์€ ๋‹ค์Œ ๊ตฌ์กฐ๋ฅผ ๋”ฐ๋ผ์•ผ ํ•ฉ๋‹ˆ๋‹ค: + +```json +{ + "success": true, + "data": { /* actual data */ }, + "timestamp": "2025-11-06T10:30:00Z", + "version": "1.0" +} +``` + +์˜ค๋ฅ˜ ์‘๋‹ต: +```json +{ + "success": false, + "error": { + "code": "VALIDATION_ERROR", + "message": "User message", + "details": { /* field errors */ } + }, + "timestamp": "2025-11-06T10:30:00Z" +} +``` + +### ํŽ˜์ด์ง€๋„ค์ด์…˜ +- ์ปค์„œ ๊ธฐ๋ฐ˜ ํŽ˜์ด์ง€๋„ค์ด์…˜ ์‚ฌ์šฉ (์˜คํ”„์…‹ ๋ฐฉ์‹ ์•„๋‹˜) +- `hasMore` ๋ถˆ๋ฆฌ์–ธ ํฌํ•จ +- ์ตœ๋Œ€ ํŽ˜์ด์ง€ ํฌ๊ธฐ๋ฅผ 100์œผ๋กœ ์ œํ•œ +- ๊ธฐ๋ณธ ํŽ˜์ด์ง€ ํฌ๊ธฐ: 20 + +### ์†๋„ ์ œํ•œ +- ์ธ์ฆ๋œ ์‚ฌ์šฉ์ž๋Š” ์‹œ๊ฐ„๋‹น 1000 ์š”์ฒญ +- ๊ณต๊ฐœ ์—”๋“œํฌ์ธํŠธ๋Š” ์‹œ๊ฐ„๋‹น 100 ์š”์ฒญ +- ์ดˆ๊ณผ ์‹œ 429 ๋ฐ˜ํ™˜ +- retry-after ํ—ค๋” ํฌํ•จ + +### ์บ์‹ฑ +- ์„ธ์…˜ ์บ์‹ฑ์— Redis ์‚ฌ์šฉ +- ์บ์‹œ ์ง€์† ์‹œ๊ฐ„: ๊ธฐ๋ณธ 5๋ถ„ +- ์“ฐ๊ธฐ ์ž‘์—… ์‹œ ๋ฌดํšจํ™” +- ๋ฆฌ์†Œ์Šค ์œ ํ˜•์œผ๋กœ ์บ์‹œ ํ‚ค ํƒœ๊ทธ ์ง€์ • + +--- +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: 2026๋…„ 4์›” 9์ผ diff --git a/ko/02-memory/memory-ask-claude.png b/ko/02-memory/memory-ask-claude.png new file mode 100644 index 00000000..b2022276 Binary files /dev/null and b/ko/02-memory/memory-ask-claude.png differ diff --git a/ko/02-memory/memory-saved.png b/ko/02-memory/memory-saved.png new file mode 100644 index 00000000..1c16eb74 Binary files /dev/null and b/ko/02-memory/memory-saved.png differ diff --git a/ko/02-memory/personal-CLAUDE.md b/ko/02-memory/personal-CLAUDE.md new file mode 100644 index 00000000..f79f46d1 --- /dev/null +++ b/ko/02-memory/personal-CLAUDE.md @@ -0,0 +1,63 @@ +# ์ €์˜ ๊ฐœ๋ฐœ ์„ ํ˜ธ ์‚ฌํ•ญ + +## ์ €์— ๋Œ€ํ•˜์—ฌ +- **๊ฒฝํ—˜ ์ˆ˜์ค€**: 8๋…„ ํ’€์Šคํƒ ๊ฐœ๋ฐœ +- **์„ ํ˜ธ ์–ธ์–ด**: TypeScript, Python +- **์†Œํ†ต ๋ฐฉ์‹**: ์˜ˆ์‹œ๋ฅผ ํ†ตํ•œ ์ง์ ‘์ ์ธ ๋ฐฉ์‹ +- **ํ•™์Šต ๋ฐฉ์‹**: ์ฝ”๋“œ๋ฅผ ํฌํ•จํ•œ ์‹œ๊ฐ์  ๋‹ค์ด์–ด๊ทธ๋žจ + +## ์ฝ”๋“œ ์„ ํ˜ธ ์‚ฌํ•ญ + +### ์˜ค๋ฅ˜ ์ฒ˜๋ฆฌ +์ €๋Š” try-catch ๋ธ”๋ก๊ณผ ์˜๋ฏธ ์žˆ๋Š” ์˜ค๋ฅ˜ ๋ฉ”์‹œ์ง€๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ๋ช…์‹œ์ ์œผ๋กœ ์˜ค๋ฅ˜๋ฅผ ์ฒ˜๋ฆฌํ•˜๋Š” ๊ฒƒ์„ ์„ ํ˜ธํ•ฉ๋‹ˆ๋‹ค. +์ผ๋ฐ˜์ ์ธ ์˜ค๋ฅ˜๋Š” ํ”ผํ•˜์„ธ์š”. ๋””๋ฒ„๊น…์„ ์œ„ํ•ด ํ•ญ์ƒ ์˜ค๋ฅ˜๋ฅผ ๋กœ๊น…ํ•˜์„ธ์š”. + +### ์ฃผ์„ +์ฃผ์„์€ '๋ฌด์—‡'์ด ์•„๋‹Œ '์™œ'๋ฅผ ์„ค๋ช…ํ•˜๋Š” ๋ฐ ์‚ฌ์šฉํ•˜์„ธ์š”. ์ฝ”๋“œ๋Š” ์ž์ฒด์ ์œผ๋กœ ๋ฌธ์„œํ™”๋˜์–ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. +์ฃผ์„์€ ๋น„์ฆˆ๋‹ˆ์Šค ๋กœ์ง์ด๋‚˜ ๋ช…ํ™•ํ•˜์ง€ ์•Š์€ ๊ฒฐ์ •์„ ์„ค๋ช…ํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. + +### ํ…Œ์ŠคํŠธ +์ €๋Š” TDD (ํ…Œ์ŠคํŠธ ์ฃผ๋„ ๊ฐœ๋ฐœ)๋ฅผ ์„ ํ˜ธํ•ฉ๋‹ˆ๋‹ค. +๊ตฌํ˜„ ์ „์— ํ…Œ์ŠคํŠธ๋ฅผ ๋จผ์ € ์ž‘์„ฑํ•˜์„ธ์š”. +๊ตฌํ˜„ ์„ธ๋ถ€ ์‚ฌํ•ญ๋ณด๋‹ค๋Š” ๋™์ž‘์— ์ดˆ์ ์„ ๋งž์ถ”์„ธ์š”. + +### ์•„ํ‚คํ…์ฒ˜ +์ €๋Š” ๋ชจ๋“ˆํ™”๋˜๊ณ  ๋Š์Šจํ•˜๊ฒŒ ๊ฒฐํ•ฉ๋œ ์„ค๊ณ„๋ฅผ ์„ ํ˜ธํ•ฉ๋‹ˆ๋‹ค. +ํ…Œ์ŠคํŠธ ์šฉ์ด์„ฑ์„ ์œ„ํ•ด ์˜์กด์„ฑ ์ฃผ์ž…์„ ์‚ฌ์šฉํ•˜์„ธ์š”. +๊ด€์‹ฌ์‚ฌ๋ฅผ ๋ถ„๋ฆฌํ•˜์„ธ์š” (Controllers, Services, Repositories). + +## ๋””๋ฒ„๊น… ์„ ํ˜ธ ์‚ฌํ•ญ +- `[DEBUG]` ์ ‘๋‘์‚ฌ์™€ ํ•จ๊ป˜ console.log ์‚ฌ์šฉ +- ์ปจํ…์ŠคํŠธ ํฌํ•จ: ํ•จ์ˆ˜ ์ด๋ฆ„, ๊ด€๋ จ ๋ณ€์ˆ˜ +- ๊ฐ€๋Šฅํ•œ ๊ฒฝ์šฐ ์Šคํƒ ํŠธ๋ ˆ์ด์Šค ์‚ฌ์šฉ +- ๋กœ๊ทธ์— ํ•ญ์ƒ ํƒ€์ž„์Šคํƒฌํ”„ ํฌํ•จ + +## ์†Œํ†ต +- ๋ณต์žกํ•œ ๊ฐœ๋…์€ ๋‹ค์ด์–ด๊ทธ๋žจ์œผ๋กœ ์„ค๋ช… +- ์ด๋ก  ์„ค๋ช… ์ „์— ๊ตฌ์ฒด์ ์ธ ์˜ˆ์‹œ ์ œ์‹œ +- ๋ณ€๊ฒฝ ์ „/ํ›„ ์ฝ”๋“œ ์Šค๋‹ˆํŽซ ํฌํ•จ +- ๋งˆ์ง€๋ง‰์— ํ•ต์‹ฌ ์š”์•ฝ + +## ํ”„๋กœ์ ํŠธ ๊ตฌ์„ฑ +์ €๋Š” ํ”„๋กœ์ ํŠธ๋ฅผ ๋‹ค์Œ๊ณผ ๊ฐ™์ด ๊ตฌ์„ฑํ•ฉ๋‹ˆ๋‹ค: +``` +project/ + โ”œโ”€โ”€ src/ + โ”‚ โ”œโ”€โ”€ api/ + โ”‚ โ”œโ”€โ”€ services/ + โ”‚ โ”œโ”€โ”€ models/ + โ”‚ โ””โ”€โ”€ utils/ + โ”œโ”€โ”€ tests/ + โ”œโ”€โ”€ docs/ + โ””โ”€โ”€ docker/ +``` + +## ๋„๊ตฌ +- **IDE**: vim ํ‚ค ๋ฐ”์ธ๋”ฉ์ด ์žˆ๋Š” VS Code +- **ํ„ฐ๋ฏธ๋„**: Oh-My-Zsh๊ฐ€ ์žˆ๋Š” Zsh +- **ํฌ๋งทํ„ฐ**: Prettier (100์ž ์ค„ ๊ธธ์ด) +- **๋ฆฐํ„ฐ**: airbnb config๊ฐ€ ์žˆ๋Š” ESLint +- **ํ…Œ์ŠคํŠธ ํ”„๋ ˆ์ž„์›Œํฌ**: React Testing Library๊ฐ€ ์žˆ๋Š” Jest + +--- +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: April 9, 2026 diff --git a/ko/02-memory/project-CLAUDE.md b/ko/02-memory/project-CLAUDE.md new file mode 100644 index 00000000..d7b86838 --- /dev/null +++ b/ko/02-memory/project-CLAUDE.md @@ -0,0 +1,91 @@ +# ํ”„๋กœ์ ํŠธ ๊ตฌ์„ฑ + +## ํ”„๋กœ์ ํŠธ ๊ฐœ์š” +- **์ด๋ฆ„**: E-commerce Platform +- **๊ธฐ์ˆ  ์Šคํƒ**: Node.js, PostgreSQL, React 18, Docker +- **ํŒ€ ๊ทœ๋ชจ**: 5 developers +- **๋งˆ๊ฐ์ผ**: Q4 2025 + +## ์•„ํ‚คํ…์ฒ˜ +@docs/architecture.md +@docs/api-standards.md +@docs/database-schema.md + +## ๊ฐœ๋ฐœ ํ‘œ์ค€ + +### ์ฝ”๋“œ ์Šคํƒ€์ผ +- ํฌ๋งทํŒ…์„ ์œ„ํ•ด Prettier ์‚ฌ์šฉ +- airbnb ์„ค์ •์„ ์‚ฌ์šฉํ•˜์—ฌ ESLint ์‚ฌ์šฉ +- ์ตœ๋Œ€ ์ค„ ๊ธธ์ด: 100์ž +- 2์นธ ๋“ค์—ฌ์“ฐ๊ธฐ ์‚ฌ์šฉ + +### ๋ช…๋ช… ๊ทœ์น™ +- **ํŒŒ์ผ**: kebab-case (user-controller.js) +- **ํด๋ž˜์Šค**: PascalCase (UserService) +- **ํ•จ์ˆ˜/๋ณ€์ˆ˜**: camelCase (getUserById) +- **์ƒ์ˆ˜**: UPPER_SNAKE_CASE (API_BASE_URL) +- **๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ํ…Œ์ด๋ธ”**: snake_case (user_accounts) + +### Git ์›Œํฌํ”Œ๋กœ์šฐ +- ๋ธŒ๋žœ์น˜ ์ด๋ฆ„: `feature/description` ๋˜๋Š” `fix/description` +- ์ปค๋ฐ‹ ๋ฉ”์‹œ์ง€: ์ปจ๋ฒค์…”๋„ ์ปค๋ฐ‹ ๊ทœ์น™ ์ค€์ˆ˜ +- ๋ณ‘ํ•ฉ ์ „ PR(Pull Request) ํ•„์ˆ˜ +- ๋ชจ๋“  CI/CD ๊ฒ€์‚ฌ ํ†ต๊ณผ ํ•„์ˆ˜ +- ์ตœ์†Œ 1๋ช… ์Šน์ธ ํ•„์ˆ˜ + +### ํ…Œ์ŠคํŠธ ์š”๊ตฌ ์‚ฌํ•ญ +- ์ตœ์†Œ 80% ์ฝ”๋“œ ์ปค๋ฒ„๋ฆฌ์ง€ +- ๋ชจ๋“  ์ค‘์š” ๊ฒฝ๋กœ์— ํ…Œ์ŠคํŠธ ํ•„์ˆ˜ +- ๋‹จ์œ„ ํ…Œ์ŠคํŠธ๋ฅผ ์œ„ํ•ด Jest ์‚ฌ์šฉ +- E2E(End-to-End) ํ…Œ์ŠคํŠธ๋ฅผ ์œ„ํ•ด Cypress ์‚ฌ์šฉ +- ํ…Œ์ŠคํŠธ ํŒŒ์ผ๋ช…: `*.test.ts` ๋˜๋Š” `*.spec.ts` + +### API ํ‘œ์ค€ +- RESTful ์—”๋“œํฌ์ธํŠธ๋งŒ ์‚ฌ์šฉ +- JSON ์š”์ฒญ/์‘๋‹ต +- HTTP ์ƒํƒœ ์ฝ”๋“œ ์˜ฌ๋ฐ”๋ฅด๊ฒŒ ์‚ฌ์šฉ +- API ์—”๋“œํฌ์ธํŠธ ๋ฒ„์ „ ๊ด€๋ฆฌ: `/api/v1/` +- ๋ชจ๋“  ์—”๋“œํฌ์ธํŠธ์— ์˜ˆ์‹œ์™€ ํ•จ๊ป˜ ๋ฌธ์„œํ™” + +### ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค +- ์Šคํ‚ค๋งˆ ๋ณ€๊ฒฝ์„ ์œ„ํ•ด ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ ์‚ฌ์šฉ +- ์ธ์ฆ ์ •๋ณด๋ฅผ ํ•˜๋“œ์ฝ”๋”ฉํ•˜์ง€ ๋ง ๊ฒƒ +- ์—ฐ๊ฒฐ ํ’€๋ง ์‚ฌ์šฉ +- ๊ฐœ๋ฐœ ํ™˜๊ฒฝ์—์„œ ์ฟผ๋ฆฌ ๋กœ๊น… ํ™œ์„ฑํ™” +- ์ •๊ธฐ์ ์ธ ๋ฐฑ์—… ํ•„์ˆ˜ + +### ๋ฐฐํฌ +- Docker ๊ธฐ๋ฐ˜ ๋ฐฐํฌ +- Kubernetes ์˜ค์ผ€์ŠคํŠธ๋ ˆ์ด์…˜ +- ๋ธ”๋ฃจ-๊ทธ๋ฆฐ ๋ฐฐํฌ ์ „๋žต +- ์‹คํŒจ ์‹œ ์ž๋™ ๋กค๋ฐฑ +- ๋ฐฐํฌ ์ „ ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ ์‹คํ–‰ + +## ์ผ๋ฐ˜ ๋ช…๋ น์–ด + +| ๋ช…๋ น์–ด | ๋ชฉ์  | +|---------|---------| +| `npm run dev` | ๊ฐœ๋ฐœ ์„œ๋ฒ„ ์‹œ์ž‘ | +| `npm test` | ํ…Œ์ŠคํŠธ ์Šค์œ„ํŠธ ์‹คํ–‰ | +| `npm run lint` | ์ฝ”๋“œ ์Šคํƒ€์ผ ๊ฒ€์‚ฌ | +| `npm run build` | ํ”„๋กœ๋•์…˜ ๋นŒ๋“œ | +| `npm run migrate` | ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ ์‹คํ–‰ | + +## ํŒ€ ์—ฐ๋ฝ์ฒ˜ +- ๊ธฐ์ˆ  ๋ฆฌ๋“œ: Sarah Chen (@sarah.chen) +- ์ œํ’ˆ ๊ด€๋ฆฌ์ž: Mike Johnson (@mike.j) +- ๋ฐ๋ธŒ์˜ต์Šค: Alex Kim (@alex.k) + +## ์•Œ๋ ค์ง„ ๋ฌธ์ œ ๋ฐ ํ•ด๊ฒฐ ๋ฐฉ๋ฒ• +- ํ”ผํฌ ์‹œ๊ฐ„ ๋™์•ˆ PostgreSQL ์—ฐ๊ฒฐ ํ’€์ด 20๊ฐœ๋กœ ์ œํ•œ๋จ +- ํ•ด๊ฒฐ ๋ฐฉ๋ฒ•: ์ฟผ๋ฆฌ ํ์ž‰ ๊ตฌํ˜„ +- Safari 14์˜ ๋น„๋™๊ธฐ ์ œ๋„ˆ๋ ˆ์ดํ„ฐ ํ˜ธํ™˜์„ฑ ๋ฌธ์ œ +- ํ•ด๊ฒฐ ๋ฐฉ๋ฒ•: Babel ํŠธ๋žœ์ŠคํŒŒ์ผ๋Ÿฌ ์‚ฌ์šฉ + +## ๊ด€๋ จ ํ”„๋กœ์ ํŠธ +- ๋ถ„์„ ๋Œ€์‹œ๋ณด๋“œ: `/projects/analytics` +- ๋ชจ๋ฐ”์ผ ์•ฑ: `/projects/mobile` +- ๊ด€๋ฆฌ์ž ํŒจ๋„: `/projects/admin` + +--- +**๋งˆ์ง€๋ง‰ ์—…๋ฐ์ดํŠธ**: April 9, 2026 diff --git a/ko/03-skills/.gitignore b/ko/03-skills/.gitignore new file mode 100644 index 00000000..28820ae0 --- /dev/null +++ b/ko/03-skills/.gitignore @@ -0,0 +1,5 @@ +# Local skill testing +.claude/ + +# Blog post outputs +blog-posts/ diff --git a/ko/03-skills/README.md b/ko/03-skills/README.md new file mode 100644 index 00000000..8ab11440 --- /dev/null +++ b/ko/03-skills/README.md @@ -0,0 +1,887 @@ + + + Claude How To + + +# ์—์ด์ „ํŠธ ์Šคํ‚ฌ ๊ฐ€์ด๋“œ + +์—์ด์ „ํŠธ ์Šคํ‚ฌ์€ Claude์˜ ๊ธฐ๋Šฅ์„ ํ™•์žฅํ•˜๋Š” ์žฌ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ํŒŒ์ผ ์‹œ์Šคํ…œ ๊ธฐ๋ฐ˜์˜ ๊ธฐ๋Šฅ์ž…๋‹ˆ๋‹ค. ์ด ๊ธฐ๋Šฅ์€ ๋„๋ฉ”์ธ๋ณ„ ์ „๋ฌธ ์ง€์‹, ์›Œํฌํ”Œ๋กœ ๋ฐ ๋ชจ๋ฒ” ์‚ฌ๋ก€๋ฅผ Claude๊ฐ€ ๊ด€๋ จ์„ฑ์ด ์žˆ์„ ๋•Œ ์ž๋™์œผ๋กœ ์‚ฌ์šฉํ•˜๋Š” ๋ฐœ๊ฒฌ ๊ฐ€๋Šฅํ•œ ๊ตฌ์„ฑ ์š”์†Œ๋กœ ํŒจํ‚ค์ง•ํ•ฉ๋‹ˆ๋‹ค. + +## ๊ฐœ์š” + +**์—์ด์ „ํŠธ ์Šคํ‚ฌ**์€ ๋ฒ”์šฉ ์—์ด์ „ํŠธ๋ฅผ ์ „๋ฌธ๊ฐ€๋กœ ๋ณ€ํ™”์‹œํ‚ค๋Š” ๋ชจ๋“ˆ์‹ ๊ธฐ๋Šฅ์ž…๋‹ˆ๋‹ค. ํ”„๋กฌํ”„ํŠธ(์ผํšŒ์„ฑ ์ž‘์—…์„ ์œ„ํ•œ ๋Œ€ํ™” ์ˆ˜์ค€์˜ ์ง€์นจ)์™€ ๋‹ฌ๋ฆฌ, ์Šคํ‚ฌ์€ ์˜จ๋””๋งจ๋“œ๋กœ ๋กœ๋“œ๋˜๋ฉฐ ์—ฌ๋Ÿฌ ๋Œ€ํ™”์— ๊ฑธ์ณ ๋™์ผํ•œ ์ง€์นจ์„ ๋ฐ˜๋ณต์ ์œผ๋กœ ์ œ๊ณตํ•  ํ•„์š”๊ฐ€ ์—†์Šต๋‹ˆ๋‹ค. + +### ์ฃผ์š” ์ด์  + +- **Claude ์ „๋ฌธํ™”**: ๋„๋ฉ”์ธ๋ณ„ ์ž‘์—…์— ๋งž์ถฐ ๊ธฐ๋Šฅ ์กฐ์ • +- **๋ฐ˜๋ณต ๊ฐ์†Œ**: ํ•œ ๋ฒˆ ์ƒ์„ฑํ•˜๋ฉด ์—ฌ๋Ÿฌ ๋Œ€ํ™”์—์„œ ์ž๋™์œผ๋กœ ์‚ฌ์šฉ +- **๊ธฐ๋Šฅ ๊ตฌ์„ฑ**: ์Šคํ‚ฌ์„ ๊ฒฐํ•ฉํ•˜์—ฌ ๋ณต์žกํ•œ ์›Œํฌํ”Œ๋กœ ๊ตฌ์ถ• +- **์›Œํฌํ”Œ๋กœ ํ™•์žฅ**: ์—ฌ๋Ÿฌ ํ”„๋กœ์ ํŠธ ๋ฐ ํŒ€์—์„œ ์Šคํ‚ฌ ์žฌ์‚ฌ์šฉ +- **ํ’ˆ์งˆ ์œ ์ง€**: ๋ชจ๋ฒ” ์‚ฌ๋ก€๋ฅผ ์›Œํฌํ”Œ๋กœ์— ์ง์ ‘ ๋‚ด์žฅ + +์Šคํ‚ฌ์€ ์—ฌ๋Ÿฌ AI ๋„๊ตฌ์—์„œ ์ž‘๋™ํ•˜๋Š” [Agent Skills](https://agentskills.io) ๊ณต๊ฐœ ํ‘œ์ค€์„ ๋”ฐ๋ฆ…๋‹ˆ๋‹ค. Claude Code๋Š” ํ˜ธ์ถœ ์ œ์–ด, ์„œ๋ธŒ์—์ด์ „ํŠธ ์‹คํ–‰ ๋ฐ ๋™์  ์ปจํ…์ŠคํŠธ ์ฃผ์ž…๊ณผ ๊ฐ™์€ ์ถ”๊ฐ€ ๊ธฐ๋Šฅ์œผ๋กœ ํ‘œ์ค€์„ ํ™•์žฅํ•ฉ๋‹ˆ๋‹ค. + +> **์ฐธ๊ณ **: ์‚ฌ์šฉ์ž ์ง€์ • ์Šฌ๋ž˜์‹œ ๋ช…๋ น์€ ์Šคํ‚ฌ์— ๋ณ‘ํ•ฉ๋˜์—ˆ์Šต๋‹ˆ๋‹ค. `.claude/commands/` ํŒŒ์ผ์€ ์—ฌ์ „ํžˆ ์ž‘๋™ํ•˜๋ฉฐ ๋™์ผํ•œ ํ”„๋ก ํŠธ๋งคํ„ฐ ํ•„๋“œ๋ฅผ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค. ์ƒˆ๋กœ์šด ๊ฐœ๋ฐœ์—๋Š” ์Šคํ‚ฌ ์‚ฌ์šฉ์„ ๊ถŒ์žฅํ•ฉ๋‹ˆ๋‹ค. ๋‘ ๊ฐ€์ง€๊ฐ€ ๋™์ผํ•œ ๊ฒฝ๋กœ์— ์กด์žฌํ•˜๋Š” ๊ฒฝ์šฐ(์˜ˆ: `.claude/commands/review.md` ๋ฐ `.claude/skills/review/SKILL.md`), ์Šคํ‚ฌ์ด ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. + +## ์Šคํ‚ฌ ์ž‘๋™ ๋ฐฉ์‹: ์ ์ง„์  ๊ณต๊ฐœ + +์Šคํ‚ฌ์€ **์ ์ง„์  ๊ณต๊ฐœ** ์•„ํ‚คํ…์ฒ˜๋ฅผ ํ™œ์šฉํ•ฉ๋‹ˆ๋‹ค. Claude๋Š” ์ปจํ…์ŠคํŠธ๋ฅผ ๋ฏธ๋ฆฌ ์†Œ๋น„ํ•˜๋Š” ๋Œ€์‹  ํ•„์š”ํ•  ๋•Œ ๋‹จ๊ณ„์ ์œผ๋กœ ์ •๋ณด๋ฅผ ๋กœ๋“œํ•ฉ๋‹ˆ๋‹ค. ์ด๋ฅผ ํ†ตํ•ด ๋ฌด์ œํ•œ ํ™•์žฅ์„ฑ์„ ์œ ์ง€ํ•˜๋ฉด์„œ ํšจ์œจ์ ์ธ ์ปจํ…์ŠคํŠธ ๊ด€๋ฆฌ๊ฐ€ ๊ฐ€๋Šฅํ•ฉ๋‹ˆ๋‹ค. + +### ์„ธ ๊ฐ€์ง€ ๋กœ๋”ฉ ์ˆ˜์ค€ + +```mermaid +graph TB + subgraph "Level 1: Metadata (Always Loaded)" + A["YAML Frontmatter"] + A1["~100 tokens per skill"] + A2["name + description"] + end + + subgraph "Level 2: Instructions (When Triggered)" + B["SKILL.md Body"] + B1["Under 5k tokens"] + B2["Workflows & guidance"] + end + + subgraph "Level 3: Resources (As Needed)" + C["Bundled Files"] + C1["Effectively unlimited"] + C2["Scripts, templates, docs"] + end + + A --> B + B --> C +``` + +| Level | When Loaded | Token Cost | Content | +|-------|------------|------------|---------| +| **Level 1: Metadata** | ํ•ญ์ƒ (์‹œ์ž‘ ์‹œ) | ์Šคํ‚ฌ๋‹น ~100 ํ† ํฐ | YAML ํ”„๋ก ํŠธ๋งคํ„ฐ์˜ `name` ๋ฐ `description` | +| **Level 2: Instructions** | ์Šคํ‚ฌ์ด ํŠธ๋ฆฌ๊ฑฐ๋  ๋•Œ | 5k ํ† ํฐ ๋ฏธ๋งŒ | ์ง€์นจ ๋ฐ ๊ฐ€์ด๋“œ๋ฅผ ํฌํ•จํ•˜๋Š” SKILL.md ๋ณธ๋ฌธ | +| **Level 3+: Resources** | ํ•„์š”์— ๋”ฐ๋ผ | ์‚ฌ์‹ค์ƒ ๋ฌด์ œํ•œ | ๋‚ด์šฉ์„ ์ปจํ…์ŠคํŠธ์— ๋กœ๋“œํ•˜์ง€ ์•Š๊ณ  bash๋ฅผ ํ†ตํ•ด ์‹คํ–‰๋˜๋Š” ๋ฒˆ๋“ค ํŒŒ์ผ | + +์ด๋Š” ์ปจํ…์ŠคํŠธ ํŽ˜๋„ํ‹ฐ ์—†์ด ๋งŽ์€ ์Šคํ‚ฌ์„ ์„ค์น˜ํ•  ์ˆ˜ ์žˆ์Œ์„ ์˜๋ฏธํ•ฉ๋‹ˆ๋‹ค. Claude๋Š” ์‹ค์ œ๋กœ ํŠธ๋ฆฌ๊ฑฐ๋  ๋•Œ๊นŒ์ง€ ๊ฐ ์Šคํ‚ฌ์ด ์กด์žฌํ•œ๋‹ค๋Š” ๊ฒƒ๊ณผ ์–ธ์ œ ์‚ฌ์šฉํ•ด์•ผ ํ•˜๋Š”์ง€๋งŒ ์•Œ๊ณ  ์žˆ์Šต๋‹ˆ๋‹ค. + +## ์Šคํ‚ฌ ๋กœ๋”ฉ ํ”„๋กœ์„ธ์Šค + +```mermaid +sequenceDiagram + participant User + participant Claude + participant System + participant SkillInst as Skill Instructions + participant SkillRes as Skill Resources + + User->>Claude: "Review this code for security issues" + Claude->>System: Check available skills (metadata) + System-->>Claude: Skill descriptions loaded at startup + Claude->>Claude: Match request to skill description + Claude->>SkillInst: Read code-review-specialist/SKILL.md + SkillInst-->>Claude: Level 2: Instructions loaded + Claude->>Claude: Determine: Need templates? + Claude->>SkillRes: Read templates/checklist.md + SkillRes-->>Claude: Level 3: Template loaded + Claude->>Claude: Execute skill instructions + Claude->>User: Comprehensive code review +``` + +## ์Šคํ‚ฌ ์œ ํ˜• ๋ฐ ์œ„์น˜ + +| Type | Location | Scope | Shared | Best For | +|------|----------|-------|--------|----------| +| **Enterprise** | ๊ด€๋ฆฌ ์„ค์ • | ๋ชจ๋“  ์กฐ์ง ์‚ฌ์šฉ์ž | ์˜ˆ | ์กฐ์ง ์ „์ฒด ํ‘œ์ค€ | +| **Personal** | `~/.claude/skills//SKILL.md` | ๊ฐœ๋ณ„ | ์•„๋‹ˆ์š” | ๊ฐœ์ธ ์›Œํฌํ”Œ๋กœ | +| **Project** | `.claude/skills//SKILL.md` | ํŒ€ | ์˜ˆ (git์„ ํ†ตํ•ด) | ํŒ€ ํ‘œ์ค€ | +| **Plugin** | `/skills//SKILL.md` | ํ™œ์„ฑํ™”๋œ ๊ฒฝ์šฐ | ๋‹ค๋ฆ„ | ํ”Œ๋Ÿฌ๊ทธ์ธ๊ณผ ๋ฒˆ๋“ค๋จ | + +์Šคํ‚ฌ์ด ์—ฌ๋Ÿฌ ์ˆ˜์ค€์—์„œ ๋™์ผํ•œ ์ด๋ฆ„์„ ๊ณต์œ ํ•˜๋Š” ๊ฒฝ์šฐ, ์šฐ์„ ์ˆœ์œ„๊ฐ€ ๋†’์€ ์œ„์น˜๊ฐ€ ์ด๊น๋‹ˆ๋‹ค: **์—”ํ„ฐํ”„๋ผ์ด์ฆˆ > ๊ฐœ์ธ > ํ”„๋กœ์ ํŠธ**. ํ”Œ๋Ÿฌ๊ทธ์ธ ์Šคํ‚ฌ์€ `plugin-name:skill-name` ๋„ค์ž„์ŠคํŽ˜์ด์Šค๋ฅผ ์‚ฌ์šฉํ•˜๋ฏ€๋กœ ์ถฉ๋Œํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. + +> **์„œ๋ธŒ์—์ด์ „ํŠธ ์Šคํ‚ฌ ๊ฒ€์ƒ‰ (v2.1.133+)**: ์„œ๋ธŒ์—์ด์ „ํŠธ๋Š” ์ด์ œ ์ฃผ์š” ์„ธ์…˜๊ณผ ๋™์ผํ•œ ๋ฐฉ์‹์œผ๋กœ Skill ๋„๊ตฌ๋ฅผ ํ†ตํ•ด ํ”„๋กœ์ ํŠธ, ์‚ฌ์šฉ์ž ๋ฐ ํ”Œ๋Ÿฌ๊ทธ์ธ ์Šคํ‚ฌ์„ ๊ฒ€์ƒ‰ํ•ฉ๋‹ˆ๋‹ค. ์ด์ „ ๋ฒ„์ „์€ ์„œ๋ธŒ์—์ด์ „ํŠธ๋ฅผ ์ž์ฒด ๋‚ด์žฅ๋œ ์„ธํŠธ๋กœ ์ œํ•œํ•˜์—ฌ ์Šคํ‚ฌ+์„œ๋ธŒ์—์ด์ „ํŠธ ์›Œํฌํ”Œ๋กœ๊ฐ€ ์กฐ์šฉํžˆ ์ €ํ•˜๋˜์—ˆ์ง€๋งŒ, v2.1.133๋ถ€ํ„ฐ๋Š” ๋™์ผํ•œ ์Šคํ‚ฌ ์นดํƒˆ๋กœ๊ทธ๊ฐ€ ๋‘˜ ๋‹ค์—๊ฒŒ ํ‘œ์‹œ๋ฉ๋‹ˆ๋‹ค. + +### ์ž๋™ ๊ฒ€์ƒ‰ + +**์ค‘์ฒฉ ๋””๋ ‰ํ„ฐ๋ฆฌ**: ํ•˜์œ„ ๋””๋ ‰ํ„ฐ๋ฆฌ์—์„œ ํŒŒ์ผ ์ž‘์—…์„ ํ•  ๋•Œ, Claude Code๋Š” ์ค‘์ฒฉ๋œ `.claude/skills/` ๋””๋ ‰ํ„ฐ๋ฆฌ์—์„œ ์Šคํ‚ฌ์„ ์ž๋™์œผ๋กœ ๊ฒ€์ƒ‰ํ•ฉ๋‹ˆ๋‹ค. ์˜ˆ๋ฅผ ๋“ค์–ด, `packages/frontend/`์˜ ํŒŒ์ผ์„ ํŽธ์ง‘ํ•˜๋Š” ๊ฒฝ์šฐ, Claude Code๋Š” `packages/frontend/.claude/skills/`์—์„œ๋„ ์Šคํ‚ฌ์„ ์ฐพ์Šต๋‹ˆ๋‹ค. ์ด๋Š” ํŒจํ‚ค์ง€๋งˆ๋‹ค ์ž์ฒด ์Šคํ‚ฌ์„ ๊ฐ–๋Š” ๋ชจ๋…ธ๋ ˆํฌ ์„ค์ •์— ์œ ์šฉํ•ฉ๋‹ˆ๋‹ค. v2.1.178๋ถ€ํ„ฐ ์ค‘์ฒฉ๋œ `.claude/skills/` ๋””๋ ‰ํ„ฐ๋ฆฌ์—์„œ ์Šคํ‚ฌ ์ด๋ฆ„์ด ์ถฉ๋Œํ•˜๋Š” ๊ฒฝ์šฐ, **ํ˜„์žฌ ์ž‘์—… ๋””๋ ‰ํ„ฐ๋ฆฌ์—์„œ ๊ฐ€์žฅ ๊ฐ€๊นŒ์šด** ๋””๋ ‰ํ„ฐ๋ฆฌ๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ์ฆ‰, ํŒจํ‚ค์ง€ ์ˆ˜์ค€ ์Šคํ‚ฌ์ด ๋™์ผํ•œ ์ด๋ฆ„์˜ ๋ฆฌํฌ์ง€ํ† ๋ฆฌ ๋ฃจํŠธ ์Šคํ‚ฌ์„ ์žฌ์ •์˜ํ•ฉ๋‹ˆ๋‹ค. + +**`--add-dir` ๋””๋ ‰ํ„ฐ๋ฆฌ**: `--add-dir`์„ ํ†ตํ•ด ์ถ”๊ฐ€๋œ ๋””๋ ‰ํ„ฐ๋ฆฌ์˜ ์Šคํ‚ฌ์€ ๋ผ์ด๋ธŒ ๋ณ€๊ฒฝ ๊ฐ์ง€์™€ ํ•จ๊ป˜ ์ž๋™์œผ๋กœ ๋กœ๋“œ๋ฉ๋‹ˆ๋‹ค. ํ•ด๋‹น ๋””๋ ‰ํ„ฐ๋ฆฌ์˜ ์Šคํ‚ฌ ํŒŒ์ผ์— ๋Œ€ํ•œ ๋ชจ๋“  ํŽธ์ง‘ ๋‚ด์šฉ์€ Claude Code๋ฅผ ๋‹ค์‹œ ์‹œ์ž‘ํ•  ํ•„์š” ์—†์ด ์ฆ‰์‹œ ์ ์šฉ๋ฉ๋‹ˆ๋‹ค. + +**์Šคํ‚ฌ ์žฌ๋กœ๋“œ**: `/reload-skills` ๋ช…๋ น(v2.1.152์— ์ถ”๊ฐ€๋จ)์€ ์„ธ์…˜์„ ๋‹ค์‹œ ์‹œ์ž‘ํ•˜์ง€ ์•Š๊ณ  ๋ชจ๋“  ์Šคํ‚ฌ ๋””๋ ‰ํ„ฐ๋ฆฌ๋ฅผ ๋‹ค์‹œ ์Šค์บ”ํ•ฉ๋‹ˆ๋‹ค. ์ด๋Š” ๋ผ์ด๋ธŒ ๊ฐ์ง€๋กœ ๊ฐ์ง€๋˜์ง€ ์•Š์€ ์Šคํ‚ฌ์„ ์ถ”๊ฐ€ํ•˜๊ฑฐ๋‚˜ ํŽธ์ง‘ํ•œ ํ›„์— ์œ ์šฉํ•ฉ๋‹ˆ๋‹ค. `SessionStart` ํ›…์€ `reloadSkills: true`๋ฅผ ๋ฐ˜ํ™˜ํ•˜์—ฌ ๋™์ผํ•œ ์žฌ์Šค์บ”์„ ํŠธ๋ฆฌ๊ฑฐํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค([Hooks](../06-hooks/README.md) ์ฐธ์กฐ). + +**์„ค๋ช… ์˜ˆ์‚ฐ**: ์Šคํ‚ฌ ์„ค๋ช…(๋ ˆ๋ฒจ 1 ๋ฉ”ํƒ€๋ฐ์ดํ„ฐ)์€ **์ปจํ…์ŠคํŠธ ์ฐฝ์˜ 1%**(๋Œ€์ฒด: **8,000์ž**)๋กœ ์ œํ•œ๋ฉ๋‹ˆ๋‹ค. ๋งŽ์€ ์Šคํ‚ฌ์ด ์„ค์น˜๋œ ๊ฒฝ์šฐ ์„ค๋ช…์ด ๋‹จ์ถ•๋  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ๋ชจ๋“  ์Šคํ‚ฌ ์ด๋ฆ„์€ ํ•ญ์ƒ ํฌํ•จ๋˜์ง€๋งŒ, ์„ค๋ช…์€ ์˜ˆ์‚ฐ์— ๋งž๊ฒŒ ์ž˜๋ฆฝ๋‹ˆ๋‹ค. ์„ค๋ช…์—์„œ ํ•ต์‹ฌ ์‚ฌ์šฉ ์‚ฌ๋ก€๋ฅผ ์ „๋ฉด์— ๋ฐฐ์น˜ํ•˜์‹ญ์‹œ์˜ค. `SLASH_COMMAND_TOOL_CHAR_BUDGET` ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ์˜ˆ์‚ฐ์„ ์žฌ์ •์˜ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +## ์‚ฌ์šฉ์ž ์ง€์ • ์Šคํ‚ฌ ์ƒ์„ฑ + +### ๊ธฐ๋ณธ ๋””๋ ‰ํ„ฐ๋ฆฌ ๊ตฌ์กฐ + +``` +my-skill/ +โ”œโ”€โ”€ SKILL.md # Main instructions (required) +โ”œโ”€โ”€ template.md # Template for Claude to fill in +โ”œโ”€โ”€ examples/ +โ”‚ โ””โ”€โ”€ sample.md # Example output showing expected format +โ””โ”€โ”€ scripts/ + โ””โ”€โ”€ validate.sh # Script Claude can execute +``` + +### SKILL.md ํ˜•์‹ + +```yaml +--- +name: your-skill-name +description: ์ด ์Šคํ‚ฌ์ด ๋ฌด์—‡์„ ํ•˜๊ณ  ์–ธ์ œ ์‚ฌ์šฉํ•ด์•ผ ํ•˜๋Š”์ง€์— ๋Œ€ํ•œ ๊ฐ„๋žตํ•œ ์„ค๋ช… +--- + +# ๋‹น์‹ ์˜ ์Šคํ‚ฌ ์ด๋ฆ„ + +## ์ง€์นจ +Claude์—๊ฒŒ ๋ช…ํ™•ํ•˜๊ณ  ๋‹จ๊ณ„๋ณ„ ์ง€์นจ์„ ์ œ๊ณตํ•˜์„ธ์š”. + +## ์˜ˆ์‹œ +์ด ์Šคํ‚ฌ์„ ์‚ฌ์šฉํ•˜๋Š” ๊ตฌ์ฒด์ ์ธ ์˜ˆ์‹œ๋ฅผ ๋ณด์—ฌ์ฃผ์„ธ์š”. +``` + +### ํ•„์ˆ˜ ํ•„๋“œ + +- **name**: ์†Œ๋ฌธ์ž, ์ˆซ์ž, ํ•˜์ดํ”ˆ๋งŒ ์‚ฌ์šฉ (์ตœ๋Œ€ 64์ž). "anthropic" ๋˜๋Š” "claude"๋ฅผ ํฌํ•จํ•  ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค. +- **description**: ์Šคํ‚ฌ์ด ๋ฌด์—‡์„ ํ•˜๋Š”์ง€ ๊ทธ๋ฆฌ๊ณ  ์–ธ์ œ ์‚ฌ์šฉํ•ด์•ผ ํ•˜๋Š”์ง€ (์ตœ๋Œ€ 1024์ž). ์ด๋Š” Claude๊ฐ€ ์Šคํ‚ฌ์„ ์–ธ์ œ ํ™œ์„ฑํ™”ํ• ์ง€ ์•„๋Š” ๋ฐ ์ค‘์š”ํ•ฉ๋‹ˆ๋‹ค. + +### ์„ ํƒ์  ํ”„๋ก ํŠธ๋งคํ„ฐ ํ•„๋“œ + +```yaml +--- +name: my-skill +description: ์ด ์Šคํ‚ฌ์ด ๋ฌด์—‡์„ ํ•˜๊ณ  ์–ธ์ œ ์‚ฌ์šฉํ•ด์•ผ ํ•˜๋Š”์ง€ +argument-hint: "[filename] [format]" # ์ž๋™ ์™„์„ฑ ํžŒํŠธ +disable-model-invocation: true # ์‚ฌ์šฉ์ž๋งŒ ํ˜ธ์ถœ ๊ฐ€๋Šฅ +user-invocable: false # ์Šฌ๋ž˜์‹œ ๋ฉ”๋‰ด์—์„œ ์ˆจ๊น€ +allowed-tools: Read, Grep, Glob # ๋„๊ตฌ ์ ‘๊ทผ ์ œํ•œ +disallowed-tools: Write, Edit # ํ™œ์„ฑ ์ƒํƒœ์ผ ๋•Œ ํŠน์ • ๋„๊ตฌ ์ œ๊ฑฐ (v2.1.152) +model: opus # ์‚ฌ์šฉํ•  ํŠน์ • ๋ชจ๋ธ +effort: high # ๋…ธ๋ ฅ ์ˆ˜์ค€ ์žฌ์ •์˜ (low, medium, high, xhigh, max) +context: fork # ๊ฒฉ๋ฆฌ๋œ ์„œ๋ธŒ์—์ด์ „ํŠธ์—์„œ ์‹คํ–‰ +agent: Explore # ์ปจํ…์ŠคํŠธ๊ฐ€ fork์ผ ๋•Œ ์—์ด์ „ํŠธ ์œ ํ˜• +shell: bash # ๋ช…๋ น์„ ์œ„ํ•œ ์…ธ: bash (๊ธฐ๋ณธ๊ฐ’) ๋˜๋Š” powershell +hooks: # ์Šคํ‚ฌ ๋ฒ”์œ„ ํ›… + PreToolUse: + - matcher: "Bash" + hooks: + - type: command + command: "./scripts/validate.sh" +paths: "src/api/**/*.ts" # ์Šคํ‚ฌ ํ™œ์„ฑํ™” ์‹œ๊ธฐ๋ฅผ ์ œํ•œํ•˜๋Š” ์ „์—ญ ํŒจํ„ด +--- +``` + +| Field | Description | +|-------|-------------| +| `name` | ์†Œ๋ฌธ์ž, ์ˆซ์ž, ํ•˜์ดํ”ˆ๋งŒ ์‚ฌ์šฉ (์ตœ๋Œ€ 64์ž). "anthropic" ๋˜๋Š” "claude"๋ฅผ ํฌํ•จํ•  ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค. | +| `description` | ์Šคํ‚ฌ์ด ๋ฌด์—‡์„ ํ•˜๊ณ  ์–ธ์ œ ์‚ฌ์šฉํ•ด์•ผ ํ•˜๋Š”์ง€ (์ตœ๋Œ€ 1024์ž). ์ž๋™ ํ˜ธ์ถœ ๋งค์นญ์— ์ค‘์š”ํ•ฉ๋‹ˆ๋‹ค. | +| `argument-hint` | `/` ์ž๋™ ์™„์„ฑ ๋ฉ”๋‰ด์— ํ‘œ์‹œ๋˜๋Š” ํžŒํŠธ (์˜ˆ: `"[filename] [format]"`). | +| `disable-model-invocation` | `true` = ์‚ฌ์šฉ์ž๋งŒ `/name`์„ ํ†ตํ•ด ํ˜ธ์ถœํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. Claude๋Š” ์ž๋™ ํ˜ธ์ถœํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. | +| `user-invocable` | `false` = `/` ๋ฉ”๋‰ด์—์„œ ์ˆจ๊ฒจ์ง‘๋‹ˆ๋‹ค. Claude๋งŒ ์ž๋™์œผ๋กœ ํ˜ธ์ถœํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. | +| `allowed-tools` | ์Šคํ‚ฌ์ด ๊ถŒํ•œ ํ”„๋กฌํ”„ํŠธ ์—†์ด ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ๋Š” ๋„๊ตฌ๋“ค์˜ ์‰ผํ‘œ๋กœ ๊ตฌ๋ถ„๋œ ๋ชฉ๋ก. | +| `disallowed-tools` | ์Šคํ‚ฌ์ด ํ™œ์„ฑ ์ƒํƒœ์ผ ๋•Œ ์ œ๊ฑฐํ•  ๋„๊ตฌ๋“ค์˜ ์‰ผํ‘œ๋กœ ๊ตฌ๋ถ„๋œ ๋ชฉ๋ก (`allowed-tools`๋ฅผ ๋ณด์™„ํ•ฉ๋‹ˆ๋‹ค). v2.1.152์— ์ถ”๊ฐ€๋จ. | +| `model` | ์Šคํ‚ฌ์ด ํ™œ์„ฑ ์ƒํƒœ์ผ ๋•Œ ๋ชจ๋ธ ์žฌ์ •์˜ (์˜ˆ: `opus`, `sonnet`). | +| `effort` | ์Šคํ‚ฌ์ด ํ™œ์„ฑ ์ƒํƒœ์ผ ๋•Œ ๋…ธ๋ ฅ ์ˆ˜์ค€ ์žฌ์ •์˜: `low`, `medium`, `high`, `xhigh` ๋˜๋Š” `max`. ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ์ˆ˜์ค€์€ ๋ชจ๋ธ์— ๋”ฐ๋ผ ๋‹ค๋ฆ…๋‹ˆ๋‹ค. Opus 4.8์˜ ๊ธฐ๋ณธ ๋…ธ๋ ฅ ์ˆ˜์ค€์€ `high`์ด๋ฉฐ (Opus 4.7์—์„œ๋Š” `xhigh`). | +| `context` | `fork`๋Š” ์Šคํ‚ฌ์„ ์ž์ฒด ์ปจํ…์ŠคํŠธ ์ฐฝ์„ ๊ฐ€์ง„ ํฌํฌ๋œ ์„œ๋ธŒ์—์ด์ „ํŠธ ์ปจํ…์ŠคํŠธ์—์„œ ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค. | +| `agent` | `context: fork`์ผ ๋•Œ ์„œ๋ธŒ์—์ด์ „ํŠธ ์œ ํ˜• (์˜ˆ: `Explore`, `Plan`, `general-purpose`). | +| `shell` | `` !`command` `` ๋Œ€์ฒด ๋ฐ ์Šคํฌ๋ฆฝํŠธ์— ์‚ฌ์šฉ๋˜๋Š” ์…ธ: `bash` (๊ธฐ๋ณธ๊ฐ’) ๋˜๋Š” `powershell`. | +| `hooks` | ์ด ์Šคํ‚ฌ์˜ ์ˆ˜๋ช… ์ฃผ๊ธฐ์— ๋ฒ”์œ„๊ฐ€ ์ง€์ •๋œ ํ›… (๊ธ€๋กœ๋ฒŒ ํ›…๊ณผ ๋™์ผํ•œ ํ˜•์‹). | +| `paths` | ์Šคํ‚ฌ์ด ์ž๋™์œผ๋กœ ํ™œ์„ฑํ™”๋˜๋Š” ์‹œ๊ธฐ๋ฅผ ์ œํ•œํ•˜๋Š” ์ „์—ญ ํŒจํ„ด. ์‰ผํ‘œ๋กœ ๊ตฌ๋ถ„๋œ ๋ฌธ์ž์—ด ๋˜๋Š” YAML ๋ชฉ๋ก. ๊ฒฝ๋กœ๋ณ„ ๊ทœ์น™๊ณผ ๋™์ผํ•œ ํ˜•์‹. | + +## ์Šคํ‚ฌ ์ฝ˜ํ…์ธ  ์œ ํ˜• + +์Šคํ‚ฌ์€ ๋‘ ๊ฐ€์ง€ ์œ ํ˜•์˜ ์ฝ˜ํ…์ธ ๋ฅผ ํฌํ•จํ•  ์ˆ˜ ์žˆ์œผ๋ฉฐ, ๊ฐ ์œ ํ˜•์€ ๋‹ค๋ฅธ ๋ชฉ์ ์— ์ ํ•ฉํ•ฉ๋‹ˆ๋‹ค. + +### ์ฐธ์กฐ ์ฝ˜ํ…์ธ  + +Claude๊ฐ€ ํ˜„์žฌ ์ž‘์—…์— ์ ์šฉํ•˜๋Š” ์ง€์‹(๊ทœ์•ฝ, ํŒจํ„ด, ์Šคํƒ€์ผ ๊ฐ€์ด๋“œ, ๋„๋ฉ”์ธ ์ง€์‹)์„ ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€ํ™” ์ปจํ…์ŠคํŠธ์™€ ํ•จ๊ป˜ ์ธ๋ผ์ธ์œผ๋กœ ์‹คํ–‰๋ฉ๋‹ˆ๋‹ค. + +```yaml +--- +name: api-conventions +description: ์ด ์ฝ”๋“œ๋ฒ ์ด์Šค๋ฅผ ์œ„ํ•œ API ๋””์ž์ธ ํŒจํ„ด +--- + +API ์—”๋“œํฌ์ธํŠธ๋ฅผ ์ž‘์„ฑํ•  ๋•Œ: +- RESTful ๋ช…๋ช… ๊ทœ์น™ ์‚ฌ์šฉ +- ์ผ๊ด€๋œ ์˜ค๋ฅ˜ ํ˜•์‹ ๋ฐ˜ํ™˜ +- ์š”์ฒญ ์œ ํšจ์„ฑ ๊ฒ€์‚ฌ ํฌํ•จ +``` + +### ์ž‘์—… ์ฝ˜ํ…์ธ  + +ํŠน์ • ์ž‘์—…์— ๋Œ€ํ•œ ๋‹จ๊ณ„๋ณ„ ์ง€์นจ. ์ข…์ข… `/skill-name`์œผ๋กœ ์ง์ ‘ ํ˜ธ์ถœ๋ฉ๋‹ˆ๋‹ค. + +```yaml +--- +name: deploy +description: ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜์„ ํ”„๋กœ๋•์…˜์— ๋ฐฐํฌํ•ฉ๋‹ˆ๋‹ค. +context: fork +disable-model-invocation: true +--- + +์• ํ”Œ๋ฆฌ์ผ€์ด์…˜ ๋ฐฐํฌ: +1. ํ…Œ์ŠคํŠธ ์Šค์œ„ํŠธ ์‹คํ–‰ +2. ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜ ๋นŒ๋“œ +3. ๋ฐฐํฌ ๋Œ€์ƒ์— ํ‘ธ์‹œ +``` + +## ์Šคํ‚ฌ ํ˜ธ์ถœ ์ œ์–ด + +๊ธฐ๋ณธ์ ์œผ๋กœ ์‚ฌ์šฉ์ž(๋‹น์‹ )์™€ Claude ๋ชจ๋‘ ๋ชจ๋“  ์Šคํ‚ฌ์„ ํ˜ธ์ถœํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ๋‘ ๊ฐ€์ง€ ํ”„๋ก ํŠธ๋งคํ„ฐ ํ•„๋“œ๊ฐ€ ์„ธ ๊ฐ€์ง€ ํ˜ธ์ถœ ๋ชจ๋“œ๋ฅผ ์ œ์–ดํ•ฉ๋‹ˆ๋‹ค. + +| Frontmatter | ๋‹น์‹ ์€ ํ˜ธ์ถœํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค | Claude๋Š” ํ˜ธ์ถœํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค | +|---|---|---| +| (๊ธฐ๋ณธ๊ฐ’) | ์˜ˆ | ์˜ˆ | +| `disable-model-invocation: true` | ์˜ˆ | ์•„๋‹ˆ์š” | +| `user-invocable: false` | ์•„๋‹ˆ์š” | ์˜ˆ | + +**๋ถ€์ž‘์šฉ์ด ์žˆ๋Š” ์›Œํฌํ”Œ๋กœ์—๋Š” `disable-model-invocation: true`๋ฅผ ์‚ฌ์šฉํ•˜์„ธ์š”**: `/commit`, `/deploy`, `/send-slack-message`. Claude๊ฐ€ ์ฝ”๋“œ๊ฐ€ ์ค€๋น„๋œ ๊ฒƒ์ฒ˜๋Ÿผ ๋ณด์—ฌ์„œ ๋ฐฐํฌ๋ฅผ ๊ฒฐ์ •ํ•˜๋Š” ๊ฒƒ์„ ์›์น˜ ์•Š์„ ๊ฒƒ์ž…๋‹ˆ๋‹ค. + +**๋ช…๋ น์œผ๋กœ ์‹คํ–‰ํ•  ์ˆ˜ ์—†๋Š” ๋ฐฐ๊ฒฝ ์ง€์‹์—๋Š” `user-invocable: false`๋ฅผ ์‚ฌ์šฉํ•˜์„ธ์š”**. `legacy-system-context` ์Šคํ‚ฌ์€ ์ด์ „ ์‹œ์Šคํ…œ์ด ์–ด๋–ป๊ฒŒ ์ž‘๋™ํ•˜๋Š”์ง€ ์„ค๋ช…ํ•ฉ๋‹ˆ๋‹ค. ์ด๋Š” Claude์—๊ฒŒ๋Š” ์œ ์šฉํ•˜์ง€๋งŒ ์‚ฌ์šฉ์ž์—๊ฒŒ๋Š” ์˜๋ฏธ ์žˆ๋Š” ์ž‘์—…์ด ์•„๋‹™๋‹ˆ๋‹ค. + +## ๋ฌธ์ž์—ด ๋Œ€์ฒด + +์Šคํ‚ฌ์€ ์Šคํ‚ฌ ์ฝ˜ํ…์ธ ๊ฐ€ Claude์— ๋„๋‹ฌํ•˜๊ธฐ ์ „์— ํ•ด๊ฒฐ๋˜๋Š” ๋™์  ๊ฐ’์„ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค. + +| Variable | Description | +|----------|-------------| +| `$ARGUMENTS` | ์Šคํ‚ฌ ํ˜ธ์ถœ ์‹œ ์ „๋‹ฌ๋œ ๋ชจ๋“  ์ธ์ˆ˜ | +| `$ARGUMENTS[N]` ๋˜๋Š” `$N` | ์ธ๋ฑ์Šค(0๋ถ€ํ„ฐ ์‹œ์ž‘)๋กœ ํŠน์ • ์ธ์ˆ˜์— ์ ‘๊ทผ | +| `${CLAUDE_SESSION_ID}` | ํ˜„์žฌ ์„ธ์…˜ ID | +| `${CLAUDE_SKILL_DIR}` | ์Šคํ‚ฌ์˜ SKILL.md ํŒŒ์ผ์ด ํฌํ•จ๋œ ๋””๋ ‰ํ„ฐ๋ฆฌ | +| `${CLAUDE_EFFORT}` | ํ˜„์žฌ ๋…ธ๋ ฅ ์ˆ˜์ค€ (`low`, `medium`, `high`, `xhigh` ๋˜๋Š” `max`). ์Šคํ‚ฌ ๋™์ž‘ ๋ถ„๊ธฐ์— ์œ ์šฉํ•ฉ๋‹ˆ๋‹ค: ์˜ˆ: `[ "${CLAUDE_EFFORT}" = "max" ] && deep_analysis` (v2.1.120+) | +| `` !`command` `` | ๋™์  ์ปจํ…์ŠคํŠธ ์ฃผ์ž… โ€” ์…ธ ๋ช…๋ น์„ ์‹คํ–‰ํ•˜๊ณ  ์ถœ๋ ฅ์„ ์ธ๋ผ์ธํ•ฉ๋‹ˆ๋‹ค. | + +**์˜ˆ์‹œ:** + +```yaml +--- +name: fix-issue +description: GitHub ์ด์Šˆ ์ˆ˜์ • +--- + +์ฝ”๋”ฉ ํ‘œ์ค€์— ๋”ฐ๋ผ GitHub ์ด์Šˆ $ARGUMENTS๋ฅผ ์ˆ˜์ •ํ•ฉ๋‹ˆ๋‹ค. +1. ์ด์Šˆ ์„ค๋ช… ์ฝ๊ธฐ +2. ์ˆ˜์ • ์‚ฌํ•ญ ๊ตฌํ˜„ +3. ํ…Œ์ŠคํŠธ ์ž‘์„ฑ +4. ์ปค๋ฐ‹ ์ƒ์„ฑ +``` + +`/fix-issue 123`์„ ์‹คํ–‰ํ•˜๋ฉด `$ARGUMENTS`๊ฐ€ `123`์œผ๋กœ ๋Œ€์ฒด๋ฉ๋‹ˆ๋‹ค. + +## ๋™์  ์ปจํ…์ŠคํŠธ ์ฃผ์ž… + +`` !`command` `` ๊ตฌ๋ฌธ์€ ์Šคํ‚ฌ ์ฝ˜ํ…์ธ ๊ฐ€ Claude๋กœ ์ „์†ก๋˜๊ธฐ ์ „์— ์…ธ ๋ช…๋ น์„ ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค. + +```yaml +--- +name: pr-summary +description: ํ’€ ๋ฆฌํ€˜์ŠคํŠธ์˜ ๋ณ€๊ฒฝ ์‚ฌํ•ญ ์š”์•ฝ +context: fork +agent: Explore +--- + +## ํ’€ ๋ฆฌํ€˜์ŠคํŠธ ์ปจํ…์ŠคํŠธ +- PR diff: !`gh pr diff` +- PR comments: !`gh pr view --comments` +- Changed files: !`gh pr diff --name-only` + +## ๋‹น์‹ ์˜ ์ž‘์—… +์ด ํ’€ ๋ฆฌํ€˜์ŠคํŠธ๋ฅผ ์š”์•ฝํ•˜์„ธ์š”... +``` + +๋ช…๋ น์€ ์ฆ‰์‹œ ์‹คํ–‰๋˜๋ฉฐ, Claude๋Š” ์ตœ์ข… ์ถœ๋ ฅ๋งŒ ๋ด…๋‹ˆ๋‹ค. ๊ธฐ๋ณธ์ ์œผ๋กœ ๋ช…๋ น์€ `bash`์—์„œ ์‹คํ–‰๋ฉ๋‹ˆ๋‹ค. `shell: powershell`์„ ํ”„๋ก ํŠธ๋งคํ„ฐ์— ์„ค์ •ํ•˜์—ฌ ๋Œ€์‹  PowerShell์„ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +## ์„œ๋ธŒ์—์ด์ „ํŠธ์—์„œ ์Šคํ‚ฌ ์‹คํ–‰ + +์Šคํ‚ฌ์„ ๊ฒฉ๋ฆฌ๋œ ์„œ๋ธŒ์—์ด์ „ํŠธ ์ปจํ…์ŠคํŠธ์—์„œ ์‹คํ–‰ํ•˜๋ ค๋ฉด `context: fork`๋ฅผ ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค. ์Šคํ‚ฌ ์ฝ˜ํ…์ธ ๋Š” ์ „์šฉ ์„œ๋ธŒ์—์ด์ „ํŠธ์˜ ์ž‘์—…์ด ๋˜๋ฉฐ, ์ž์ฒด ์ปจํ…์ŠคํŠธ ์ฐฝ์„ ๊ฐ€์ ธ ๋ฉ”์ธ ๋Œ€ํ™”๋ฅผ ๊น”๋”ํ•˜๊ฒŒ ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. + +> **v2.1.145 ์ˆ˜์ •**: `context: fork`๋ฅผ ์‚ฌ์šฉํ•˜๋Š” ์Šคํ‚ฌ์€ ์ด์ „์— ๋“œ๋ฌธ ๊ฒฝ์šฐ์— ๋ฌดํ•œ ์žฌํ˜ธ์ถœ ๋ฃจํ”„๋ฅผ ์œ ๋ฐœํ•  ์ˆ˜ ์žˆ์—ˆ์Šต๋‹ˆ๋‹ค. ํฌํ‚น ์Šคํ‚ฌ์„ ์ž‘์„ฑํ•˜๊ฑฐ๋‚˜ ์˜์กดํ•˜๋Š” ๊ฒฝ์šฐ v2.1.145 ์ด์ƒ์œผ๋กœ ์—…๊ทธ๋ ˆ์ด๋“œํ•˜์‹ญ์‹œ์˜ค. + +`agent` ํ•„๋“œ๋Š” ์‚ฌ์šฉํ•  ์—์ด์ „ํŠธ ์œ ํ˜•์„ ์ง€์ •ํ•ฉ๋‹ˆ๋‹ค. + +| Agent Type | Best For | +|---|---| +| `Explore` | ์ฝ๊ธฐ ์ „์šฉ ์—ฐ๊ตฌ, ์ฝ”๋“œ๋ฒ ์ด์Šค ๋ถ„์„ | +| `Plan` | ๊ตฌํ˜„ ๊ณ„ํš ์ƒ์„ฑ | +| `general-purpose` | ๋ชจ๋“  ๋„๊ตฌ๊ฐ€ ํ•„์š”ํ•œ ๊ด‘๋ฒ”์œ„ํ•œ ์ž‘์—… | +| Custom agents | ๊ตฌ์„ฑ์— ์ •์˜๋œ ์ „๋ฌธ ์—์ด์ „ํŠธ | + +**์˜ˆ์‹œ ํ”„๋ก ํŠธ๋งคํ„ฐ:** + +```yaml +--- +context: fork +agent: Explore +--- +``` + +**์ „์ฒด ์Šคํ‚ฌ ์˜ˆ์‹œ:** + +```yaml +--- +name: deep-research +description: ์ฃผ์ œ๋ฅผ ์ฒ ์ €ํžˆ ์—ฐ๊ตฌํ•ฉ๋‹ˆ๋‹ค. +context: fork +agent: Explore +--- + +$ARGUMENTS๋ฅผ ์ฒ ์ €ํžˆ ์—ฐ๊ตฌํ•˜์„ธ์š”: +1. Glob๊ณผ Grep์„ ์‚ฌ์šฉํ•˜์—ฌ ๊ด€๋ จ ํŒŒ์ผ ์ฐพ๊ธฐ +2. ์ฝ”๋“œ ์ฝ๊ณ  ๋ถ„์„ํ•˜๊ธฐ +3. ํŠน์ • ํŒŒ์ผ ์ฐธ์กฐ์™€ ํ•จ๊ป˜ ๊ฒฐ๊ณผ ์š”์•ฝํ•˜๊ธฐ +``` + +## ์‹ค์ œ ์˜ˆ์‹œ + +### ์˜ˆ์‹œ 1: ์ฝ”๋“œ ๊ฒ€ํ†  ์Šคํ‚ฌ + +**๋””๋ ‰ํ„ฐ๋ฆฌ ๊ตฌ์กฐ:** + +``` +~/.claude/skills/code-review-specialist/ +โ”œโ”€โ”€ SKILL.md +โ”œโ”€โ”€ templates/ +โ”‚ โ”œโ”€โ”€ review-checklist.md +โ”‚ โ””โ”€โ”€ finding-template.md +โ””โ”€โ”€ scripts/ + โ”œโ”€โ”€ analyze-metrics.py + โ””โ”€โ”€ compare-complexity.py +``` + +**ํŒŒ์ผ:** `~/.claude/skills/code-review-specialist/SKILL.md` + +```yaml +--- +name: code-review-specialist +description: ๋ณด์•ˆ, ์„ฑ๋Šฅ, ํ’ˆ์งˆ ๋ถ„์„์„ ํฌํ•จํ•˜๋Š” ์ข…ํ•ฉ ์ฝ”๋“œ ๊ฒ€ํ† . ์‚ฌ์šฉ์ž๊ฐ€ ์ฝ”๋“œ ๊ฒ€ํ† , ์ฝ”๋“œ ํ’ˆ์งˆ ๋ถ„์„, ํ’€ ๋ฆฌํ€˜์ŠคํŠธ ํ‰๊ฐ€๋ฅผ ์š”์ฒญํ•˜๊ฑฐ๋‚˜ ์ฝ”๋“œ ๊ฒ€ํ† , ๋ณด์•ˆ ๋ถ„์„, ์„ฑ๋Šฅ ์ตœ์ ํ™”๋ฅผ ์–ธ๊ธ‰ํ•  ๋•Œ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +--- + +# ์ฝ”๋“œ ๊ฒ€ํ†  ์Šคํ‚ฌ + +์ด ์Šคํ‚ฌ์€ ๋‹ค์Œ์„ ์ค‘์‹ฌ์œผ๋กœ ํ•œ ์ข…ํ•ฉ์ ์ธ ์ฝ”๋“œ ๊ฒ€ํ†  ๊ธฐ๋Šฅ์„ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค: + +1. **๋ณด์•ˆ ๋ถ„์„** + - ์ธ์ฆ/๊ถŒํ•œ ๋ถ€์—ฌ ๋ฌธ์ œ + - ๋ฐ์ดํ„ฐ ๋…ธ์ถœ ์œ„ํ—˜ + - ์ธ์ ์…˜ ์ทจ์•ฝ์„ฑ + - ์•”ํ˜ธํ™” ์•ฝ์  + +2. **์„ฑ๋Šฅ ๊ฒ€ํ† ** + - ์•Œ๊ณ ๋ฆฌ์ฆ˜ ํšจ์œจ์„ฑ (๋น… O ๋ถ„์„) + - ๋ฉ”๋ชจ๋ฆฌ ์ตœ์ ํ™” + - ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ์ฟผ๋ฆฌ ์ตœ์ ํ™” + - ์บ์‹ฑ ๊ธฐํšŒ + +3. **์ฝ”๋“œ ํ’ˆ์งˆ** + - SOLID ์›์น™ + - ๋””์ž์ธ ํŒจํ„ด + - ๋ช…๋ช… ๊ทœ์น™ + - ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€ + +4. **์œ ์ง€ ๋ณด์ˆ˜์„ฑ** + - ์ฝ”๋“œ ๊ฐ€๋…์„ฑ + - ํ•จ์ˆ˜ ํฌ๊ธฐ (50์ค„ ๋ฏธ๋งŒ์ด์–ด์•ผ ํ•จ) + - ์ˆœํ™˜ ๋ณต์žก๋„ + - ํƒ€์ž… ์•ˆ์ „์„ฑ + +## ๊ฒ€ํ†  ํ…œํ”Œ๋ฆฟ + +๊ฒ€ํ† ๋œ ๊ฐ ์ฝ”๋“œ์— ๋Œ€ํ•ด ๋‹ค์Œ์„ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค: + +### ์š”์•ฝ +- ์ „์ฒด ํ’ˆ์งˆ ํ‰๊ฐ€ (1-5) +- ์ฃผ์š” ๋ฐœ๊ฒฌ ๊ฐœ์ˆ˜ +- ๊ถŒ์žฅ ์šฐ์„ ์ˆœ์œ„ ์˜์—ญ + +### ์‹ฌ๊ฐํ•œ ๋ฌธ์ œ (์žˆ๋Š” ๊ฒฝ์šฐ) +- **์ด์Šˆ**: ๋ช…ํ™•ํ•œ ์„ค๋ช… +- **์œ„์น˜**: ํŒŒ์ผ ๋ฐ ์ค„ ๋ฒˆํ˜ธ +- **์˜ํ–ฅ**: ์ด๊ฒƒ์ด ์ค‘์š”ํ•œ ์ด์œ  +- **์‹ฌ๊ฐ๋„**: ์‹ฌ๊ฐ/๋†’์Œ/์ค‘๊ฐ„ +- **์ˆ˜์ •**: ์ฝ”๋“œ ์˜ˆ์‹œ + +์ž์„ธํ•œ ์ฒดํฌ๋ฆฌ์ŠคํŠธ๋Š” [templates/review-checklist.md](templates/review-checklist.md)๋ฅผ ์ฐธ์กฐํ•˜์„ธ์š”. +``` + +### ์˜ˆ์‹œ 2: ์ฝ”๋“œ๋ฒ ์ด์Šค ์‹œ๊ฐํ™” ์Šคํ‚ฌ + +๋Œ€ํ™”ํ˜• HTML ์‹œ๊ฐํ™”๋ฅผ ์ƒ์„ฑํ•˜๋Š” ์Šคํ‚ฌ์ž…๋‹ˆ๋‹ค. + +**๋””๋ ‰ํ„ฐ๋ฆฌ ๊ตฌ์กฐ:** + +``` +~/.claude/skills/codebase-visualizer/ +โ”œโ”€โ”€ SKILL.md +โ””โ”€โ”€ scripts/ + โ””โ”€โ”€ visualize.py +``` + +**ํŒŒ์ผ:** `~/.claude/skills/codebase-visualizer/SKILL.md` + +````yaml +--- +name: codebase-visualizer +description: ์ฝ”๋“œ๋ฒ ์ด์Šค์˜ ๋Œ€ํ™”ํ˜• ์ ‘์ด์‹ ํŠธ๋ฆฌ ์‹œ๊ฐํ™”๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. ์ƒˆ๋กœ์šด ๋ฆฌํฌ์ง€ํ† ๋ฆฌ๋ฅผ ํƒ์ƒ‰ํ•˜๊ฑฐ๋‚˜, ํ”„๋กœ์ ํŠธ ๊ตฌ์กฐ๋ฅผ ์ดํ•ดํ•˜๊ฑฐ๋‚˜, ํฐ ํŒŒ์ผ์„ ์‹๋ณ„ํ•  ๋•Œ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +allowed-tools: Bash(python *) +--- + +# ์ฝ”๋“œ๋ฒ ์ด์Šค ์‹œ๊ฐํ™” ๋„๊ตฌ + +ํ”„๋กœ์ ํŠธ์˜ ํŒŒ์ผ ๊ตฌ์กฐ๋ฅผ ๋ณด์—ฌ์ฃผ๋Š” ๋Œ€ํ™”ํ˜• HTML ํŠธ๋ฆฌ ๋ทฐ๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. + +## ์‚ฌ์šฉ๋ฒ• + +ํ”„๋กœ์ ํŠธ ๋ฃจํŠธ์—์„œ ์‹œ๊ฐํ™” ์Šคํฌ๋ฆฝํŠธ๋ฅผ ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค: + +```bash +python ~/.claude/skills/codebase-visualizer/scripts/visualize.py . +``` + +์ด๋ ‡๊ฒŒ ํ•˜๋ฉด `codebase-map.html`์ด ์ƒ์„ฑ๋˜๊ณ  ๊ธฐ๋ณธ ๋ธŒ๋ผ์šฐ์ €์—์„œ ์—ด๋ฆฝ๋‹ˆ๋‹ค. + +## ์‹œ๊ฐํ™”๊ฐ€ ๋ณด์—ฌ์ฃผ๋Š” ๊ฒƒ + +- **์ ‘์ด์‹ ๋””๋ ‰ํ„ฐ๋ฆฌ**: ํด๋”๋ฅผ ํด๋ฆญํ•˜์—ฌ ํ™•์žฅ/์ถ•์†Œ +- **ํŒŒ์ผ ํฌ๊ธฐ**: ๊ฐ ํŒŒ์ผ ์˜†์— ํ‘œ์‹œ๋จ +- **์ƒ‰์ƒ**: ๋‹ค๋ฅธ ํŒŒ์ผ ์œ ํ˜•์— ๋Œ€ํ•œ ๋‹ค๋ฅธ ์ƒ‰์ƒ +- **๋””๋ ‰ํ„ฐ๋ฆฌ ์ด๊ณ„**: ๊ฐ ํด๋”์˜ ์ด ํฌ๊ธฐ๋ฅผ ํ‘œ์‹œ +```` + +๋ฒˆ๋“ค๋กœ ์ œ๊ณต๋˜๋Š” Python ์Šคํฌ๋ฆฝํŠธ๊ฐ€ ๋Œ€๋ถ€๋ถ„์˜ ์ž‘์—…์„ ์ˆ˜ํ–‰ํ•˜๊ณ  Claude๋Š” ์˜ค์ผ€์ŠคํŠธ๋ ˆ์ด์…˜์„ ์ฒ˜๋ฆฌํ•ฉ๋‹ˆ๋‹ค. + +### ์˜ˆ์‹œ 3: ๋ฐฐํฌ ์Šคํ‚ฌ (์‚ฌ์šฉ์ž ํ˜ธ์ถœ ์ „์šฉ) + +```yaml +--- +name: deploy +description: ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜์„ ํ”„๋กœ๋•์…˜์— ๋ฐฐํฌํ•ฉ๋‹ˆ๋‹ค. +disable-model-invocation: true +allowed-tools: Bash(npm *), Bash(git *) +--- + +$ARGUMENTS๋ฅผ ํ”„๋กœ๋•์…˜์— ๋ฐฐํฌํ•ฉ๋‹ˆ๋‹ค: + +1. ํ…Œ์ŠคํŠธ ์Šค์œ„ํŠธ ์‹คํ–‰: `npm test` +2. ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜ ๋นŒ๋“œ: `npm run build` +3. ๋ฐฐํฌ ๋Œ€์ƒ์— ํ‘ธ์‹œ +4. ๋ฐฐํฌ ์„ฑ๊ณต ํ™•์ธ +5. ๋ฐฐํฌ ์ƒํƒœ ๋ณด๊ณ  +``` + +### ์˜ˆ์‹œ 4: ๋ธŒ๋žœ๋“œ ๋ณด์ด์Šค ์Šคํ‚ฌ (๋ฐฐ๊ฒฝ ์ง€์‹) + +```yaml +--- +name: brand-voice +description: ๋ชจ๋“  ์ปค๋ฎค๋‹ˆ์ผ€์ด์…˜์ด ๋ธŒ๋žœ๋“œ ๋ณด์ด์Šค ๋ฐ ํ†ค ๊ฐ€์ด๋“œ๋ผ์ธ๊ณผ ์ผ์น˜ํ•˜๋„๋ก ๋ณด์žฅํ•ฉ๋‹ˆ๋‹ค. ๋งˆ์ผ€ํŒ… ์ž๋ฃŒ, ๊ณ ๊ฐ ์ปค๋ฎค๋‹ˆ์ผ€์ด์…˜ ๋˜๋Š” ๋Œ€์ค‘ ๊ณต๊ฐœ ์ฝ˜ํ…์ธ ๋ฅผ ์ž‘์„ฑํ•  ๋•Œ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +user-invocable: false +--- + +## ํ†ค ์•ค ๋งค๋„ˆ +- **์นœ๊ทผํ•˜์ง€๋งŒ ์ „๋ฌธ์ ** - ํŽธ์•ˆํ•˜์ง€๋งŒ ์บ์ฃผ์–ผํ•˜์ง€ ์•Š์Œ +- **๋ช…ํ™•ํ•˜๊ณ  ๊ฐ„๊ฒฐํ•จ** - ์ „๋ฌธ ์šฉ์–ด ํ”ผํ•˜๊ธฐ +- **์ž์‹ ๊ฐ ์žˆ๋Š”** - ์šฐ๋ฆฌ๊ฐ€ ๋ฌด์—‡์„ ํ•˜๋Š”์ง€ ์•Œ๊ณ  ์žˆ์Œ +- **๊ณต๊ฐํ•˜๋Š”** - ์‚ฌ์šฉ์ž ์š”๊ตฌ ์ดํ•ด + +## ๊ธ€์“ฐ๊ธฐ ๊ฐ€์ด๋“œ๋ผ์ธ +- ๋…์ž๋ฅผ ์ง€์นญํ•  ๋•Œ "๋‹น์‹ " ์‚ฌ์šฉ +- ๋Šฅ๋™ํƒœ ์‚ฌ์šฉ +- ๋ฌธ์žฅ์„ 20๋‹จ์–ด ๋ฏธ๋งŒ์œผ๋กœ ์œ ์ง€ +- ๊ฐ€์น˜ ์ œ์•ˆ์œผ๋กœ ์‹œ์ž‘ + +ํ…œํ”Œ๋ฆฟ์€ [templates/](templates/)๋ฅผ ์ฐธ์กฐํ•˜์„ธ์š”. +``` + +### ์˜ˆ์‹œ 5: CLAUDE.md ์ƒ์„ฑ๊ธฐ ์Šคํ‚ฌ + +```yaml +--- +name: claude-md +description: ์ตœ์ ์˜ AI ์—์ด์ „ํŠธ ์˜จ๋ณด๋”ฉ์„ ์œ„ํ•œ ๋ชจ๋ฒ” ์‚ฌ๋ก€์— ๋”ฐ๋ผ CLAUDE.md ํŒŒ์ผ์„ ์ƒ์„ฑํ•˜๊ฑฐ๋‚˜ ์—…๋ฐ์ดํŠธํ•ฉ๋‹ˆ๋‹ค. ์‚ฌ์šฉ์ž๊ฐ€ CLAUDE.md, ํ”„๋กœ์ ํŠธ ๋ฌธ์„œ ๋˜๋Š” AI ์˜จ๋ณด๋”ฉ์„ ์–ธ๊ธ‰ํ•  ๋•Œ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +--- + +## ํ•ต์‹ฌ ์›์น™ + +**LLM์€ ์ƒํƒœ ๋น„์ €์žฅ์ž…๋‹ˆ๋‹ค**: CLAUDE.md๋Š” ๋ชจ๋“  ๋Œ€ํ™”์— ์ž๋™์œผ๋กœ ํฌํ•จ๋˜๋Š” ์œ ์ผํ•œ ํŒŒ์ผ์ž…๋‹ˆ๋‹ค. + +### ํ™ฉ๊ธˆ๋ฅ  + +1. **์ ์„์ˆ˜๋ก ์ข‹๋‹ค**: 300์ค„ ๋ฏธ๋งŒ (์ด์ƒ์ ์œผ๋กœ๋Š” 100์ค„ ๋ฏธ๋งŒ) ์œ ์ง€ +2. **๋ฒ”์šฉ์„ฑ**: ๋ชจ๋“  ์„ธ์…˜์— ๊ด€๋ จ๋œ ์ •๋ณด๋งŒ ํฌํ•จ +3. **Claude๋ฅผ ๋ฆฐํ„ฐ๋กœ ์‚ฌ์šฉํ•˜์ง€ ๋งˆ์„ธ์š”**: ๋Œ€์‹  ๊ฒฐ์ •๋ก ์  ๋„๊ตฌ ์‚ฌ์šฉ +4. **์ ˆ๋Œ€ ์ž๋™ ์ƒ์„ฑํ•˜์ง€ ๋งˆ์„ธ์š”**: ์‹ ์ค‘ํ•˜๊ฒŒ ์ˆ˜๋™์œผ๋กœ ์ž‘์„ฑ + +## ํ•„์ˆ˜ ์„น์…˜ + +- **ํ”„๋กœ์ ํŠธ ์ด๋ฆ„**: ํ•œ ์ค„ ์š”์•ฝ +- **๊ธฐ์ˆ  ์Šคํƒ**: ๊ธฐ๋ณธ ์–ธ์–ด, ํ”„๋ ˆ์ž„์›Œํฌ, ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค +- **๊ฐœ๋ฐœ ๋ช…๋ น**: ์„ค์น˜, ํ…Œ์ŠคํŠธ, ๋นŒ๋“œ ๋ช…๋ น +- **์ค‘์š” ๊ทœ์น™**: ๋ช…๋ฐฑํ•˜์ง€ ์•Š๊ณ  ์˜ํ–ฅ๋ ฅ์ด ํฐ ๊ทœ์น™๋งŒ +- **์•Œ๋ ค์ง„ ๋ฌธ์ œ / ํ•จ์ •**: ๊ฐœ๋ฐœ์ž๋ฅผ ํ˜ผ๋ž€์Šค๋Ÿฝ๊ฒŒ ํ•˜๋Š” ๊ฒƒ๋“ค +``` + +### ์˜ˆ์‹œ 6: ์Šคํฌ๋ฆฝํŠธ๊ฐ€ ์žˆ๋Š” ๋ฆฌํŒฉํ† ๋ง ์Šคํ‚ฌ + +**๋””๋ ‰ํ„ฐ๋ฆฌ ๊ตฌ์กฐ:** + +``` +refactor/ +โ”œโ”€โ”€ SKILL.md +โ”œโ”€โ”€ references/ +โ”‚ โ”œโ”€โ”€ code-smells.md +โ”‚ โ””โ”€โ”€ refactoring-catalog.md +โ”œโ”€โ”€ templates/ +โ”‚ โ””โ”€โ”€ refactoring-plan.md +โ””โ”€โ”€ scripts/ + โ”œโ”€โ”€ analyze-complexity.py + โ””โ”€โ”€ detect-smells.py +``` + +**ํŒŒ์ผ:** `refactor/SKILL.md` + +```yaml +--- +name: code-refactor +description: ๋งˆํ‹ด ํŒŒ์šธ๋Ÿฌ์˜ ๋ฐฉ๋ฒ•๋ก ์— ๊ธฐ๋ฐ˜ํ•œ ์ฒด๊ณ„์ ์ธ ์ฝ”๋“œ ๋ฆฌํŒฉํ† ๋ง. ์‚ฌ์šฉ์ž๊ฐ€ ์ฝ”๋“œ ๋ฆฌํŒฉํ† ๋ง, ์ฝ”๋“œ ๊ตฌ์กฐ ๊ฐœ์„ , ๊ธฐ์ˆ  ๋ถ€์ฑ„ ๊ฐ์†Œ ๋˜๋Š” ์ฝ”๋“œ ์Šค๋ฉœ ์ œ๊ฑฐ๋ฅผ ์š”์ฒญํ•  ๋•Œ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +--- + +# ์ฝ”๋“œ ๋ฆฌํŒฉํ† ๋ง ์Šคํ‚ฌ + +ํ…Œ์ŠคํŠธ๋ฅผ ๊ธฐ๋ฐ˜์œผ๋กœ ํ•œ ์•ˆ์ „ํ•˜๊ณ  ์ ์ง„์ ์ธ ๋ณ€๊ฒฝ์„ ๊ฐ•์กฐํ•˜๋Š” ๋‹จ๊ณ„๋ณ„ ์ ‘๊ทผ ๋ฐฉ์‹. + +## ์›Œํฌํ”Œ๋กœ + +1๋‹จ๊ณ„: ์—ฐ๊ตฌ ๋ฐ ๋ถ„์„ โ†’ 2๋‹จ๊ณ„: ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€ ํ‰๊ฐ€ โ†’ +3๋‹จ๊ณ„: ์ฝ”๋“œ ์Šค๋ฉœ ์‹๋ณ„ โ†’ 4๋‹จ๊ณ„: ๋ฆฌํŒฉํ† ๋ง ๊ณ„ํš ์ƒ์„ฑ โ†’ +5๋‹จ๊ณ„: ์ ์ง„์  ๊ตฌํ˜„ โ†’ 6๋‹จ๊ณ„: ๊ฒ€ํ†  ๋ฐ ๋ฐ˜๋ณต + +## ํ•ต์‹ฌ ์›์น™ + +1. **๋™์ž‘ ๋ณด์กด**: ์™ธ๋ถ€ ๋™์ž‘์€ ๋ณ€๊ฒฝ๋˜์ง€ ์•Š๊ณ  ์œ ์ง€๋˜์–ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. +2. **์ž‘์€ ๋‹จ๊ณ„**: ์ž‘๊ณ  ํ…Œ์ŠคํŠธ ๊ฐ€๋Šฅํ•œ ๋ณ€๊ฒฝ์„ ์ˆ˜ํ–‰ํ•ฉ๋‹ˆ๋‹ค. +3. **ํ…Œ์ŠคํŠธ ์ฃผ๋„**: ํ…Œ์ŠคํŠธ๋Š” ์•ˆ์ „๋ง์ž…๋‹ˆ๋‹ค. +4. **์ง€์†์ **: ๋ฆฌํŒฉํ† ๋ง์€ ์ผํšŒ์„ฑ ์ด๋ฒคํŠธ๊ฐ€ ์•„๋‹ˆ๋ผ ์ง€์†์ ์ธ ๊ณผ์ •์ž…๋‹ˆ๋‹ค. + +์ฝ”๋“œ ์Šค๋ฉœ ์นดํƒˆ๋กœ๊ทธ๋Š” [references/code-smells.md](references/code-smells.md)๋ฅผ ์ฐธ์กฐํ•˜์„ธ์š”. +๋ฆฌํŒฉํ† ๋ง ๊ธฐ๋ฒ•์€ [references/refactoring-catalog.md](references/refactoring-catalog.md)๋ฅผ ์ฐธ์กฐํ•˜์„ธ์š”. +``` + +## ๋ณด์กฐ ํŒŒ์ผ + +์Šคํ‚ฌ์€ `SKILL.md` ์™ธ์—๋„ ๋””๋ ‰ํ„ฐ๋ฆฌ์— ์—ฌ๋Ÿฌ ํŒŒ์ผ์„ ํฌํ•จํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์ด๋Ÿฌํ•œ ๋ณด์กฐ ํŒŒ์ผ(ํ…œํ”Œ๋ฆฟ, ์˜ˆ์ œ, ์Šคํฌ๋ฆฝํŠธ, ์ฐธ์กฐ ๋ฌธ์„œ)์„ ํ†ตํ•ด ์ฃผ์š” ์Šคํ‚ฌ ํŒŒ์ผ์— ์ง‘์ค‘ํ•˜๋ฉด์„œ Claude๊ฐ€ ํ•„์š”ํ•  ๋•Œ ๋กœ๋“œํ•  ์ถ”๊ฐ€ ๋ฆฌ์†Œ์Šค๋ฅผ ์ œ๊ณตํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +``` +my-skill/ +โ”œโ”€โ”€ SKILL.md # ์ฃผ์š” ์ง€์นจ (ํ•„์ˆ˜, 500์ค„ ๋ฏธ๋งŒ์œผ๋กœ ์œ ์ง€) +โ”œโ”€โ”€ templates/ # Claude๊ฐ€ ์ฑ„์šธ ํ…œํ”Œ๋ฆฟ +โ”‚ โ””โ”€โ”€ output-format.md +โ”œโ”€โ”€ examples/ # ์˜ˆ์ƒ ํ˜•์‹์„ ๋ณด์—ฌ์ฃผ๋Š” ์˜ˆ์‹œ ์ถœ๋ ฅ +โ”‚ โ””โ”€โ”€ sample-output.md +โ”œโ”€โ”€ references/ # ๋„๋ฉ”์ธ ์ง€์‹ ๋ฐ ์‚ฌ์–‘ +โ”‚ โ””โ”€โ”€ api-spec.md +โ””โ”€โ”€ scripts/ # Claude๊ฐ€ ์‹คํ–‰ํ•  ์ˆ˜ ์žˆ๋Š” ์Šคํฌ๋ฆฝํŠธ + โ””โ”€โ”€ validate.sh +``` + +๋ณด์กฐ ํŒŒ์ผ์— ๋Œ€ํ•œ ์ง€์นจ: + +- `SKILL.md`๋Š” **500์ค„** ๋ฏธ๋งŒ์œผ๋กœ ์œ ์ง€ํ•˜์‹ญ์‹œ์˜ค. ์ƒ์„ธํ•œ ์ฐธ์กฐ ์ž๋ฃŒ, ํฐ ์˜ˆ์‹œ ๋ฐ ์‚ฌ์–‘์€ ๋ณ„๋„์˜ ํŒŒ์ผ๋กœ ์ด๋™์‹œํ‚ค์‹ญ์‹œ์˜ค. +- **์ƒ๋Œ€ ๊ฒฝ๋กœ**๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ `SKILL.md`์—์„œ ์ถ”๊ฐ€ ํŒŒ์ผ์„ ์ฐธ์กฐํ•˜์‹ญ์‹œ์˜ค (์˜ˆ: `[API reference](references/api-spec.md)`). +- ๋ณด์กฐ ํŒŒ์ผ์€ ๋ ˆ๋ฒจ 3(ํ•„์š”ํ•  ๋•Œ)์—์„œ ๋กœ๋“œ๋˜๋ฏ€๋กœ Claude๊ฐ€ ์‹ค์ œ๋กœ ์ฝ์„ ๋•Œ๊นŒ์ง€ ์ปจํ…์ŠคํŠธ๋ฅผ ์†Œ๋น„ํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. + +## ์Šคํ‚ฌ ๊ด€๋ฆฌ + +### ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ์Šคํ‚ฌ ๋ณด๊ธฐ + +Claude์—๊ฒŒ ์ง์ ‘ ๋ฌผ์–ด๋ณด์„ธ์š”: +``` +What Skills are available? +``` + +๋˜๋Š” ํŒŒ์ผ ์‹œ์Šคํ…œ์—์„œ ํ™•์ธํ•˜์„ธ์š”: +```bash +# ๊ฐœ์ธ ์Šคํ‚ฌ ๋‚˜์—ด +ls ~/.claude/skills/ + +# ํ”„๋กœ์ ํŠธ ์Šคํ‚ฌ ๋‚˜์—ด +ls .claude/skills/ +``` + +> **ํŒ (v2.1.121+)**: ๋งŽ์€ ์Šคํ‚ฌ์ด ์„ค์น˜๋œ ๊ฒฝ์šฐ `/skills` ๋Œ€ํ™”ํ˜• ๋ฉ”๋‰ด์—์„œ ํ•„ํ„ฐ๋งํ•˜๋ ค๋ฉด ์ž…๋ ฅํ•˜์„ธ์š”. + +### ์Šคํ‚ฌ ํ…Œ์ŠคํŠธ + +๋‘ ๊ฐ€์ง€ ํ…Œ์ŠคํŠธ ๋ฐฉ๋ฒ•: + +**Claude๊ฐ€ ์ž๋™์œผ๋กœ ํ˜ธ์ถœํ•˜๋„๋ก ํ—ˆ์šฉ**ํ•˜์—ฌ ์„ค๋ช…๊ณผ ์ผ์น˜ํ•˜๋Š” ๋‚ด์šฉ์„ ์š”์ฒญํ•˜์„ธ์š”: +``` +Can you help me review this code for security issues? +``` + +**๋˜๋Š” ์Šคํ‚ฌ ์ด๋ฆ„์œผ๋กœ ์ง์ ‘ ํ˜ธ์ถœํ•˜์„ธ์š”**: +``` +/code-review-specialist src/auth/login.ts +``` + +> **์ฐธ๊ณ **: ์ด ๋กœ์ปฌ ์Šคํ‚ฌ์€ `code-review-specialist`๋กœ ์„ค์น˜๋˜์–ด ๋‚ด์žฅ `/code-review` ๋ช…๋ น(Claude Code v2.1.146์—์„œ `/simplify`์—์„œ ์ด๋ฆ„ ๋ณ€๊ฒฝ๋จ)๊ณผ ์ถฉ๋Œํ•˜์ง€ **์•Š์Šต๋‹ˆ๋‹ค**. ๋Œ€์‹  `~/.claude/skills/code-review/`์— ๋ณต์‚ฌํ•˜๋ฉด ๋‚ด์žฅ ์Šคํ‚ฌ์„ ๊ฐ€๋ฆฌ๊ฒŒ ๋˜๋ฏ€๋กœ, ์ถฉ๋Œ์„ ํ”ผํ•˜๋ ค๋ฉด `-specialist` ์ ‘๋ฏธ์‚ฌ๋ฅผ ์œ ์ง€ํ•˜์‹ญ์‹œ์˜ค. + +### ์Šคํ‚ฌ ์—…๋ฐ์ดํŠธ + +`SKILL.md` ํŒŒ์ผ์„ ์ง์ ‘ ํŽธ์ง‘ํ•˜์„ธ์š”. ๋ณ€๊ฒฝ ์‚ฌํ•ญ์€ ๋‹ค์Œ Claude Code ์‹œ์ž‘ ์‹œ ์ ์šฉ๋ฉ๋‹ˆ๋‹ค. + +```bash +# ๊ฐœ์ธ ์Šคํ‚ฌ +code ~/.claude/skills/my-skill/SKILL.md + +# ํ”„๋กœ์ ํŠธ ์Šคํ‚ฌ +code .claude/skills/my-skill/SKILL.md +``` + +### Claude์˜ ์Šคํ‚ฌ ์ ‘๊ทผ ์ œํ•œ + +Claude๊ฐ€ ํ˜ธ์ถœํ•  ์ˆ˜ ์žˆ๋Š” ์Šคํ‚ฌ์„ ์ œ์–ดํ•˜๋Š” ์„ธ ๊ฐ€์ง€ ๋ฐฉ๋ฒ•: + +`/permissions`์—์„œ **๋ชจ๋“  ์Šคํ‚ฌ ๋น„ํ™œ์„ฑํ™”**: +``` +# ๊ฑฐ๋ถ€ ๊ทœ์น™์— ์ถ”๊ฐ€: +Skill +``` + +**ํŠน์ • ์Šคํ‚ฌ ํ—ˆ์šฉ ๋˜๋Š” ๊ฑฐ๋ถ€**: +``` +# ํŠน์ • ์Šคํ‚ฌ๋งŒ ํ—ˆ์šฉ +Skill(commit) +Skill(review-pr *) + +# ํŠน์ • ์Šคํ‚ฌ ๊ฑฐ๋ถ€ +Skill(deploy *) +``` + +๊ฐœ๋ณ„ ์Šคํ‚ฌ์˜ ํ”„๋ก ํŠธ๋งคํ„ฐ์— `disable-model-invocation: true`๋ฅผ ์ถ”๊ฐ€ํ•˜์—ฌ **๊ฐœ๋ณ„ ์Šคํ‚ฌ ์ˆจ๊ธฐ๊ธฐ**. + +### ์Šคํ‚ฌ ์žฌ์ •์˜ ๋™์ž‘ ์ œ์–ด (`skillOverrides`) + +ํ”„๋กœ์ ํŠธ ์Šคํ‚ฌ๊ณผ ์‚ฌ์šฉ์ž ์Šคํ‚ฌ์ด ๋™์ผํ•œ ์ด๋ฆ„์„ ๊ณต์œ ํ•  ๋•Œ, ๊ธฐ๋ณธ์ ์œผ๋กœ ํ”„๋กœ์ ํŠธ๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. `skillOverrides` ์„ค์ •(v2.1.129+)์„ ํ†ตํ•ด ์ด๋ฅผ ์กฐ์ •ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. `~/.claude/settings.json` ๋˜๋Š” ํ”„๋กœ์ ํŠธ `.claude/settings.json`์— ์ถ”๊ฐ€ํ•˜์„ธ์š”: + +```json +{ + "skillOverrides": "name-only" +} +``` + +ํ—ˆ์šฉ๋˜๋Š” ๊ฐ’: + +| Value | Behavior | +|-------|----------| +| `"on"` (๊ธฐ๋ณธ๊ฐ’) | ์ €์žฅ์†Œ ์Šคํ‚ฌ์€ ๋™์ผํ•œ ์ด๋ฆ„์˜ ์‚ฌ์šฉ์ž ์Šคํ‚ฌ์„ ์žฌ์ •์˜ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. | +| `"off"` | ์žฌ์ •์˜๋ฅผ ์™„์ „ํžˆ ๋น„ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค. ์‚ฌ์šฉ์ž ์Šคํ‚ฌ์ด ํ•ญ์ƒ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. | +| `"name-only"` | ์Šคํ‚ฌ ์ด๋ฆ„๋งŒ์œผ๋กœ ์žฌ์ •์˜๋ฅผ ์ผ์น˜์‹œํ‚ต๋‹ˆ๋‹ค (์„ค๋ช…/์†Œ์Šค ๋ฌด์‹œ). | +| `"user-invocable-only"` | ์‚ฌ์šฉ์ž ํ˜ธ์ถœ ๊ฐ€๋Šฅ ์Šคํ‚ฌ๋งŒ ์žฌ์ •์˜ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ๋ชจ๋ธ ํ˜ธ์ถœ ์Šคํ‚ฌ์€ ํ•ญ์ƒ ์›๋ž˜ ์œ„์น˜์—์„œ ๊ฐ€์ ธ์˜ต๋‹ˆ๋‹ค. | + +ํŒ€ ์ •์ฑ…์ด "์‚ฌ์šฉ์ž ์ •์˜ ์Šคํ‚ฌ์ด ํ•ญ์ƒ ์šฐ์„ ํ•ด์•ผ ํ•œ๋‹ค" (`"off"`)๊ฑฐ๋‚˜ "์ข์€ ์ด๋ฆ„ ๊ธฐ๋ฐ˜ ์žฌ์ •์˜๋งŒ ํ—ˆ์šฉํ•ด์•ผ ํ•œ๋‹ค" (`"name-only"`)๊ณ  ํ•  ๋•Œ ์œ ์šฉํ•ฉ๋‹ˆ๋‹ค. + +## ๋ชจ๋ฒ” ์‚ฌ๋ก€ + +### 1. ์„ค๋ช…์„ ๊ตฌ์ฒด์ ์œผ๋กœ ์ž‘์„ฑํ•˜๊ธฐ + +- **๋‚˜์œ ์˜ˆ (๋ชจํ˜ธํ•จ)**: "๋ฌธ์„œ ์ž‘์„ฑ์— ๋„์›€์ด ๋ฉ๋‹ˆ๋‹ค." +- **์ข‹์€ ์˜ˆ (๊ตฌ์ฒด์ )**: "PDF ํŒŒ์ผ์—์„œ ํ…์ŠคํŠธ์™€ ํ…Œ์ด๋ธ”์„ ์ถ”์ถœํ•˜๊ณ , ์–‘์‹์„ ์ฑ„์šฐ๊ณ , ๋ฌธ์„œ๋ฅผ ๋ณ‘ํ•ฉํ•ฉ๋‹ˆ๋‹ค. PDF ํŒŒ์ผ ์ž‘์—… ์‹œ ๋˜๋Š” ์‚ฌ์šฉ์ž๊ฐ€ PDF, ์–‘์‹ ๋˜๋Š” ๋ฌธ์„œ ์ถ”์ถœ์„ ์–ธ๊ธ‰ํ•  ๋•Œ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค." + +### 2. ์Šคํ‚ฌ์˜ ์ดˆ์  ์œ ์ง€ + +- ํ•˜๋‚˜์˜ ์Šคํ‚ฌ = ํ•˜๋‚˜์˜ ๊ธฐ๋Šฅ +- โœ… "PDF ์–‘์‹ ์ฑ„์šฐ๊ธฐ" +- โŒ "๋ฌธ์„œ ์ฒ˜๋ฆฌ" (๋„ˆ๋ฌด ๊ด‘๋ฒ”์œ„ํ•จ) + +### 3. ํŠธ๋ฆฌ๊ฑฐ ์šฉ์–ด ํฌํ•จ + +์‚ฌ์šฉ์ž ์š”์ฒญ๊ณผ ์ผ์น˜ํ•˜๋Š” ํ‚ค์›Œ๋“œ๋ฅผ ์„ค๋ช…์— ์ถ”๊ฐ€ํ•˜์„ธ์š”: +```yaml +description: Excel ์Šคํ”„๋ ˆ๋“œ์‹œํŠธ๋ฅผ ๋ถ„์„ํ•˜๊ณ , ํ”ผ๋ฒ— ํ…Œ์ด๋ธ”์„ ์ƒ์„ฑํ•˜๊ณ , ์ฐจํŠธ๋ฅผ ๋งŒ๋“ญ๋‹ˆ๋‹ค. Excel ํŒŒ์ผ, ์Šคํ”„๋ ˆ๋“œ์‹œํŠธ ๋˜๋Š” .xlsx ํŒŒ์ผ๋กœ ์ž‘์—…ํ•  ๋•Œ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +``` + +### 4. SKILL.md๋ฅผ 500์ค„ ๋ฏธ๋งŒ์œผ๋กœ ์œ ์ง€ + +์ž์„ธํ•œ ์ฐธ์กฐ ์ž๋ฃŒ๋Š” Claude๊ฐ€ ํ•„์š”ํ•  ๋•Œ ๋กœ๋“œํ•˜๋Š” ๋ณ„๋„์˜ ํŒŒ์ผ๋กœ ์ด๋™์‹œํ‚ค์‹ญ์‹œ์˜ค. + +### 5. ๋ณด์กฐ ํŒŒ์ผ ์ฐธ์กฐ + +```markdown +## ์ถ”๊ฐ€ ์ž๋ฃŒ + +- ์ „์ฒด API ์„ธ๋ถ€ ์ •๋ณด๋Š” [reference.md](reference.md)๋ฅผ ์ฐธ์กฐํ•˜์„ธ์š”. +- ์‚ฌ์šฉ ์˜ˆ์‹œ๋Š” [examples.md](examples.md)๋ฅผ ์ฐธ์กฐํ•˜์„ธ์š”. +``` + +### ํ•ด์•ผ ํ•  ์ผ + +- ๋ช…ํ™•ํ•˜๊ณ  ์„ค๋ช…์ ์ธ ์ด๋ฆ„ ์‚ฌ์šฉ +- ํฌ๊ด„์ ์ธ ์ง€์นจ ํฌํ•จ +- ๊ตฌ์ฒด์ ์ธ ์˜ˆ์‹œ ์ถ”๊ฐ€ +- ๊ด€๋ จ ์Šคํฌ๋ฆฝํŠธ ๋ฐ ํ…œํ”Œ๋ฆฟ ํŒจํ‚ค์ง• +- ์‹ค์ œ ์‹œ๋‚˜๋ฆฌ์˜ค๋กœ ํ…Œ์ŠคํŠธ +- ์˜์กด์„ฑ ๋ฌธ์„œํ™” + +### ํ•˜์ง€ ๋ง์•„์•ผ ํ•  ์ผ + +- ์ผํšŒ์„ฑ ์ž‘์—…์„ ์œ„ํ•œ ์Šคํ‚ฌ ์ƒ์„ฑ ๊ธˆ์ง€ +- ๊ธฐ์กด ๊ธฐ๋Šฅ ์ค‘๋ณต ๊ธˆ์ง€ +- ์Šคํ‚ฌ์„ ๋„ˆ๋ฌด ๊ด‘๋ฒ”์œ„ํ•˜๊ฒŒ ๋งŒ๋“ค์ง€ ๋ง ๊ฒƒ +- ์„ค๋ช… ํ•„๋“œ๋ฅผ ๊ฑด๋„ˆ๋›ฐ์ง€ ๋ง ๊ฒƒ +- ๊ฐ์‚ฌ ์—†์ด ์‹ ๋ขฐํ•  ์ˆ˜ ์—†๋Š” ์ถœ์ฒ˜์˜ ์Šคํ‚ฌ ์„ค์น˜ ๊ธˆ์ง€ + +## ๋ฌธ์ œ ํ•ด๊ฒฐ + +### ๋น ๋ฅธ ์ฐธ์กฐ + +| Issue | Solution | +|-------|----------| +| Claude๊ฐ€ ์Šคํ‚ฌ์„ ์‚ฌ์šฉํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. | ํŠธ๋ฆฌ๊ฑฐ ์šฉ์–ด๋ฅผ ํฌํ•จํ•˜์—ฌ ์„ค๋ช…์„ ๋” ๊ตฌ์ฒด์ ์œผ๋กœ ๋งŒ๋“œ์„ธ์š”. | +| ์Šคํ‚ฌ ํŒŒ์ผ์„ ์ฐพ์„ ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค. | ๊ฒฝ๋กœ ํ™•์ธ: `~/.claude/skills/name/SKILL.md` | +| YAML ์˜ค๋ฅ˜ | `---` ๋งˆ์ปค, ๋“ค์—ฌ์“ฐ๊ธฐ, ํƒญ ์—†์Œ ํ™•์ธ | +| ์Šคํ‚ฌ ์ถฉ๋Œ | ์„ค๋ช…์— ๋ช…ํ™•ํžˆ ๋‹ค๋ฅธ ํŠธ๋ฆฌ๊ฑฐ ์šฉ์–ด ์‚ฌ์šฉ | +| ์Šคํฌ๋ฆฝํŠธ๊ฐ€ ์‹คํ–‰๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. | ๊ถŒํ•œ ํ™•์ธ: `chmod +x scripts/*.py` | +| Claude๊ฐ€ ๋ชจ๋“  ์Šคํ‚ฌ์„ ์ธ์‹ํ•˜์ง€ ๋ชปํ•ฉ๋‹ˆ๋‹ค. | ์Šคํ‚ฌ์ด ๋„ˆ๋ฌด ๋งŽ์Šต๋‹ˆ๋‹ค; ๊ฒฝ๊ณ ๋Š” `/context`๋ฅผ ํ™•์ธํ•˜์„ธ์š”. | + +### ์Šคํ‚ฌ์ด ํŠธ๋ฆฌ๊ฑฐ๋˜์ง€ ์•Š์Œ + +Claude๊ฐ€ ์˜ˆ์ƒ๋Œ€๋กœ ์Šคํ‚ฌ์„ ์‚ฌ์šฉํ•˜์ง€ ์•Š๋Š” ๊ฒฝ์šฐ: + +1. ์„ค๋ช…์— ์‚ฌ์šฉ์ž๊ฐ€ ์ž์—ฐ์Šค๋Ÿฝ๊ฒŒ ๋งํ•  ํ‚ค์›Œ๋“œ๊ฐ€ ํฌํ•จ๋˜์–ด ์žˆ๋Š”์ง€ ํ™•์ธํ•˜์„ธ์š”. +2. "What skills are available?"์ด๋ผ๊ณ  ๋ฌผ์—ˆ์„ ๋•Œ ์Šคํ‚ฌ์ด ๋‚˜ํƒ€๋‚˜๋Š”์ง€ ํ™•์ธํ•˜์„ธ์š”. +3. ์„ค๋ช…๊ณผ ์ผ์น˜ํ•˜๋„๋ก ์š”์ฒญ์„ ๋‹ค์‹œ ์ž‘์„ฑํ•ด ๋ณด์„ธ์š”. +4. `/skill-name`์œผ๋กœ ์ง์ ‘ ํ˜ธ์ถœํ•˜์—ฌ ํ…Œ์ŠคํŠธํ•˜์„ธ์š”. + +### ์Šคํ‚ฌ์ด ๋„ˆ๋ฌด ์ž์ฃผ ํŠธ๋ฆฌ๊ฑฐ๋จ + +Claude๊ฐ€ ์›ํ•˜์ง€ ์•Š์„ ๋•Œ ์Šคํ‚ฌ์„ ์‚ฌ์šฉํ•˜๋Š” ๊ฒฝ์šฐ: + +1. ์„ค๋ช…์„ ๋” ๊ตฌ์ฒด์ ์œผ๋กœ ๋งŒ๋“œ์„ธ์š”. +2. ์ˆ˜๋™ ํ˜ธ์ถœ ์ „์šฉ์œผ๋กœ `disable-model-invocation: true`๋ฅผ ์ถ”๊ฐ€ํ•˜์„ธ์š”. + +### Claude๊ฐ€ ๋ชจ๋“  ์Šคํ‚ฌ์„ ์ธ์‹ํ•˜์ง€ ๋ชปํ•จ + +์Šคํ‚ฌ ์„ค๋ช…์€ **์ปจํ…์ŠคํŠธ ์ฐฝ์˜ 1%**(๋Œ€์ฒด: **8,000์ž**)๋กœ ๋กœ๋“œ๋ฉ๋‹ˆ๋‹ค. ๊ฐ ํ•ญ๋ชฉ์€ ์˜ˆ์‚ฐ์— ๊ด€๊ณ„์—†์ด 250์ž๋กœ ์ œํ•œ๋ฉ๋‹ˆ๋‹ค. ์ œ์™ธ๋œ ์Šคํ‚ฌ์— ๋Œ€ํ•œ ๊ฒฝ๊ณ ๋Š” `/context`๋ฅผ ์‹คํ–‰ํ•˜์—ฌ ํ™•์ธํ•˜์„ธ์š”. `SLASH_COMMAND_TOOL_CHAR_BUDGET` ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ์˜ˆ์‚ฐ์„ ์žฌ์ •์˜ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +## ๋ณด์•ˆ ๊ณ ๋ ค ์‚ฌํ•ญ + +**์‹ ๋ขฐํ•  ์ˆ˜ ์žˆ๋Š” ์†Œ์Šค์˜ ์Šคํ‚ฌ๋งŒ ์‚ฌ์šฉํ•˜์„ธ์š”.** ์Šคํ‚ฌ์€ ์ง€์นจ๊ณผ ์ฝ”๋“œ๋ฅผ ํ†ตํ•ด Claude์— ๊ธฐ๋Šฅ์„ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. ์•…์˜์ ์ธ ์Šคํ‚ฌ์€ Claude์—๊ฒŒ ๋„๊ตฌ๋ฅผ ํ˜ธ์ถœํ•˜๊ฑฐ๋‚˜ ์ฝ”๋“œ๋ฅผ ํ•ด๋กœ์šด ๋ฐฉ์‹์œผ๋กœ ์‹คํ–‰ํ•˜๋„๋ก ์ง€์‹œํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +**์ฃผ์š” ๋ณด์•ˆ ๊ณ ๋ ค ์‚ฌํ•ญ:** + +- **์ฒ ์ €ํžˆ ๊ฐ์‚ฌ**: ์Šคํ‚ฌ ๋””๋ ‰ํ„ฐ๋ฆฌ์˜ ๋ชจ๋“  ํŒŒ์ผ์„ ๊ฒ€ํ† ํ•˜์„ธ์š”. +- **์™ธ๋ถ€ ์†Œ์Šค๋Š” ์œ„ํ—˜**: ์™ธ๋ถ€ URL์—์„œ ๊ฐ€์ ธ์˜ค๋Š” ์Šคํ‚ฌ์€ ์†์ƒ๋  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. +- **๋„๊ตฌ ์˜ค์šฉ**: ์•…์˜์ ์ธ ์Šคํ‚ฌ์€ ๋„๊ตฌ๋ฅผ ํ•ด๋กœ์šด ๋ฐฉ์‹์œผ๋กœ ํ˜ธ์ถœํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. +- **์†Œํ”„ํŠธ์›จ์–ด ์„ค์น˜์ฒ˜๋Ÿผ ์ทจ๊ธ‰**: ์‹ ๋ขฐํ•  ์ˆ˜ ์žˆ๋Š” ์ถœ์ฒ˜์˜ ์Šคํ‚ฌ๋งŒ ์‚ฌ์šฉํ•˜์„ธ์š”. + +### ์Šคํ‚ฌ์—์„œ ์…ธ ๋Œ€์ฒด ๋น„ํ™œ์„ฑํ™” + +์Šคํ‚ฌ์€ `` !`command` `` ๊ตฌ๋ฌธ์„ ์ง€์›ํ•˜์—ฌ Claude๊ฐ€ ์ด๋ฅผ ๋ณด๊ธฐ ์ „์— ์…ธ ๋ช…๋ น์˜ ์ถœ๋ ฅ์„ ํ”„๋กฌํ”„ํŠธ์— ์ฃผ์ž…ํ•ฉ๋‹ˆ๋‹ค. ๋ณด์•ˆ์— ๋ฏผ๊ฐํ•œ ํ™˜๊ฒฝ(๊ณต์œ  ์—”ํ„ฐํ”„๋ผ์ด์ฆˆ ๋ฐฐํฌ, ์ž ๊ธด CI ๋Ÿฌ๋„ˆ)์—์„œ๋Š” `disableSkillShellExecution` ์„ค์ •์„ ํ†ตํ•ด ์ด ๋Œ€์ฒด๋ฅผ ์™„์ „ํžˆ ๋น„ํ™œ์„ฑํ™”ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค(**v2.1.91**์— ์ถ”๊ฐ€๋จ). + +```jsonc +// ~/.claude/settings.json ๋˜๋Š” ๊ด€๋ฆฌ ์ •์ฑ… +{ + "disableSkillShellExecution": true +} +``` + +`disableSkillShellExecution`์ด `true`์ธ ๊ฒฝ์šฐ, ์Šคํ‚ฌ์˜ ๋ชจ๋“  `` !`command` `` ๋งˆ์ปค๋Š” ์‹คํ–‰๋˜์ง€ ์•Š๊ณ  ๋ฆฌํ„ฐ๋Ÿด ํ…์ŠคํŠธ๋กœ ๋‚จ์Šต๋‹ˆ๋‹ค. ์ด๋Š” ์Šคํ‚ฌ ์ž์ฒด๋ฅผ ๋น„ํ™œ์„ฑํ™”ํ•˜์ง€ ์•Š๊ณ  ์Šคํ‚ฌ ์ˆ˜์ค€ ์…ธ ์ฃผ์ž… ๊ณต๊ฒฉ ํ‘œ๋ฉด์„ ์ œ๊ฑฐํ•ฉ๋‹ˆ๋‹ค. ์‹ฌ์ธต ๋ฐฉ์–ด๋ฅผ ์œ„ํ•ด `allowedTools` ํ—ˆ์šฉ ๋ชฉ๋ก๊ณผ ํ•จ๊ป˜ ์‚ฌ์šฉํ•˜๋Š” ๊ฒƒ์„ ๊ณ ๋ คํ•ด ๋ณด์„ธ์š”. + +### ๋ฒˆ๋“ค ์Šคํ‚ฌ ์ˆจ๊ธฐ๊ธฐ (`disableBundledSkills`) + +`disableBundledSkills` ์„ค์ •(**v2.1.169**์— ์ถ”๊ฐ€๋จ)์€ Claude Code์™€ ํ•จ๊ป˜ ์ œ๊ณต๋˜๋Š” ๋ฒˆ๋“ค ์Šคํ‚ฌ, ์›Œํฌํ”Œ๋กœ ๋ฐ ๋ช…๋ น์„ ๋ชจ๋ธ์—์„œ ์ˆจ๊น๋‹ˆ๋‹ค. ํŠน์ • ํ”„๋กœ์ ํŠธ์— ๋‚ด์žฅ ์Šคํ‚ฌ์ด ๋ถˆํ•„์š”ํ•˜๊ฑฐ๋‚˜ ๋ชจ๋ธ์˜ ์Šคํ‚ฌ ํ‘œ๋ฉด์„ ์ค„์ด๊ณ  ์‹ถ์„ ๋•Œ ์‚ฌ์šฉํ•˜์„ธ์š”. + +```jsonc +// ~/.claude/settings.json ๋˜๋Š” ํ”„๋กœ์ ํŠธ .claude/settings.json +{ + "disableBundledSkills": true +} +``` + +๋™๋“ฑํ•œ ํ™˜๊ฒฝ ๋ณ€์ˆ˜ ํ˜•์‹์€ ๋‹ค์Œ๊ณผ ๊ฐ™์Šต๋‹ˆ๋‹ค: + +```bash +export CLAUDE_CODE_DISABLE_BUNDLED_SKILLS=1 +``` + +## ์Šคํ‚ฌ ๋Œ€ ๋‹ค๋ฅธ ๊ธฐ๋Šฅ + +| Feature | Invocation | Best For | +|---------|------------|----------| +| **Skills** | ์ž๋™ ๋˜๋Š” `/name` | ์žฌ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ์ „๋ฌธ ์ง€์‹, ์›Œํฌํ”Œ๋กœ | +| **Slash Commands** | ์‚ฌ์šฉ์ž ์‹œ์ž‘ `/name` | ๋น ๋ฅธ ๋‹จ์ถ•ํ‚ค (์Šคํ‚ฌ์— ๋ณ‘ํ•ฉ๋จ) | +| **Subagents** | ์ž๋™ ์œ„์ž„ | ๊ฒฉ๋ฆฌ๋œ ์ž‘์—… ์‹คํ–‰ | +| **Memory (CLAUDE.md)** | ํ•ญ์ƒ ๋กœ๋“œ๋จ | ์ง€์†์ ์ธ ํ”„๋กœ์ ํŠธ ์ปจํ…์ŠคํŠธ | +| **MCP** | ์‹ค์‹œ๊ฐ„ | ์™ธ๋ถ€ ๋ฐ์ดํ„ฐ/์„œ๋น„์Šค ์ ‘๊ทผ | +| **Hooks** | ์ด๋ฒคํŠธ ๊ธฐ๋ฐ˜ | ์ž๋™ํ™”๋œ ๋ถ€์ž‘์šฉ | + +## ๋ฒˆ๋“ค ์Šคํ‚ฌ + +Claude Code๋Š” ์„ค์น˜ ์—†์ด ํ•ญ์ƒ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ๋Š” 9๊ฐ€์ง€ ๋‚ด์žฅ ์Šคํ‚ฌ๊ณผ ํ•จ๊ป˜ ์ œ๊ณต๋ฉ๋‹ˆ๋‹ค. + +| Skill | Description | +|-------|-------------| +| `/batch ` | git ์ž‘์—… ํŠธ๋ฆฌ๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ์ฝ”๋“œ๋ฒ ์ด์Šค ์ „๋ฐ˜์— ๊ฑธ์ณ ๋Œ€๊ทœ๋ชจ ๋ณ‘๋ ฌ ๋ณ€๊ฒฝ์„ ์กฐ์œจํ•ฉ๋‹ˆ๋‹ค. | +| `/claude-api` | Claude API/SDK ์ฐธ์กฐ๋ฅผ ๋กœ๋“œํ•ฉ๋‹ˆ๋‹ค. `anthropic`/`@anthropic-ai/sdk` ๊ฐ€์ ธ์˜ค๊ธฐ ์‹œ ์ž๋™ ํ™œ์„ฑํ™”๋ฉ๋‹ˆ๋‹ค. | +| `/debug [description]` | ๋””๋ฒ„๊ทธ ๋กœ๊ทธ๋ฅผ ์ฝ์–ด ํ˜„์žฌ ์„ธ์…˜์„ ๋ฌธ์ œ ํ•ด๊ฒฐํ•ฉ๋‹ˆ๋‹ค. | +| `/fewer-permission-prompts` | ๋Œ€๋ณธ์„ ์Šค์บ”ํ•˜๊ณ  ์ผ๋ฐ˜์ ์ธ ์ฝ๊ธฐ ์ „์šฉ ๋„๊ตฌ์— ๋Œ€ํ•œ ์šฐ์„ ์ˆœ์œ„ ์ง€์ •๋œ ํ—ˆ์šฉ ๋ชฉ๋ก์„ ์ œ์•ˆํ•ฉ๋‹ˆ๋‹ค. | +| `/loop [interval] ` | ์ง€์ •๋œ ๊ฐ„๊ฒฉ์œผ๋กœ ํ”„๋กฌํ”„ํŠธ๋ฅผ ๋ฐ˜๋ณต ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค (์˜ˆ: `/loop 5m check the deploy`). | +| `/run` *(v2.1.145+)* | ์ด ํ”„๋กœ์ ํŠธ์˜ ์•ฑ์„ ์‹คํ–‰ํ•˜์—ฌ ๋ณ€๊ฒฝ ์‚ฌํ•ญ์ด ์‹คํ–‰๋˜๋Š”์ง€ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. ํ”„๋กœ์ ํŠธ ์Šคํ‚ฌ์„ ์ฐพ๊ณ , ๊ทธ๋ ‡์ง€ ์•Š์œผ๋ฉด ํ”„๋กœ์ ํŠธ ์œ ํ˜•๋ณ„ ๋‚ด์žฅ ํŒจํ„ด์œผ๋กœ ํด๋ฐฑํ•ฉ๋‹ˆ๋‹ค. | +| `/run-skill-generator` *(v2.1.145+)* | ํ”„๋กœ์ ํŠธ๋ณ„ ์Šคํ‚ฌ์„ ์ƒ์„ฑํ•˜์—ฌ `/run`/`/verify`๊ฐ€ ํŠน์ • ํ”„๋กœ์ ํŠธ๋ฅผ ์ฒ˜๋ฆฌํ•˜๋Š” ๋ฐฉ๋ฒ•์„ ํ•™์Šต์‹œํ‚ต๋‹ˆ๋‹ค. | +| `/code-review [effort]` | ์„ ํƒํ•œ ๋…ธ๋ ฅ ์ˆ˜์ค€์—์„œ ํ˜„์žฌ diff์˜ ์ •ํ™•์„ฑ ๋ฒ„๊ทธ๋ฅผ ๊ฒ€ํ† ํ•ฉ๋‹ˆ๋‹ค (์˜ˆ: `/code-review high`). `--comment`๋ฅผ ์ „๋‹ฌํ•˜์—ฌ ๋ฐœ๊ฒฌ ์‚ฌํ•ญ์„ ์ธ๋ผ์ธ PR ๋Œ“๊ธ€๋กœ ๊ฒŒ์‹œํ•ฉ๋‹ˆ๋‹ค. v2.1.146์—์„œ `/simplify`์—์„œ ์ด๋ฆ„ ๋ณ€๊ฒฝ๋จ. | +| `/verify` *(v2.1.145+)* | ์•ฑ์„ ๋นŒ๋“œ, ์‹คํ–‰ ๋ฐ ๊ด€์ฐฐํ•˜์—ฌ ์ˆ˜์ • ์‚ฌํ•ญ์ด (ํ…Œ์ŠคํŠธ ํ†ต๊ณผ๋ฟ๋งŒ ์•„๋‹ˆ๋ผ) ์ž‘๋™ํ•˜๋Š”์ง€ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. | + +์ด ์Šคํ‚ฌ๋“ค์€ ์ฆ‰์‹œ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์œผ๋ฉฐ ์„ค์น˜ํ•˜๊ฑฐ๋‚˜ ๊ตฌ์„ฑํ•  ํ•„์š”๊ฐ€ ์—†์Šต๋‹ˆ๋‹ค. ์ด ์Šคํ‚ฌ๋“ค๋„ ์‚ฌ์šฉ์ž ์ง€์ • ์Šคํ‚ฌ๊ณผ ๋™์ผํ•œ SKILL.md ํ˜•์‹์„ ๋”ฐ๋ฆ…๋‹ˆ๋‹ค. + +## ์Šคํ‚ฌ ๊ณต์œ  + +### ํ”„๋กœ์ ํŠธ ์Šคํ‚ฌ (ํŒ€ ๊ณต์œ ) + +1. `.claude/skills/`์— ์Šคํ‚ฌ ์ƒ์„ฑ +2. git์— ์ปค๋ฐ‹ +3. ํŒ€์›๋“ค์ด ๋ณ€๊ฒฝ ์‚ฌํ•ญ ํ’€ โ€” ์Šคํ‚ฌ ์ฆ‰์‹œ ์‚ฌ์šฉ ๊ฐ€๋Šฅ + +### ๊ฐœ์ธ ์Šคํ‚ฌ + +```bash +# ๊ฐœ์ธ ๋””๋ ‰ํ„ฐ๋ฆฌ๋กœ ๋ณต์‚ฌ +cp -r my-skill ~/.claude/skills/ + +# ์Šคํฌ๋ฆฝํŠธ ์‹คํ–‰ ๊ฐ€๋Šฅํ•˜๊ฒŒ ๋งŒ๋“ค๊ธฐ +chmod +x ~/.claude/skills/my-skill/scripts/*.py +``` + +### ํ”Œ๋Ÿฌ๊ทธ์ธ ๋ฐฐํฌ + +๋” ๋„“์€ ๋ฐฐํฌ๋ฅผ ์œ„ํ•ด ํ”Œ๋Ÿฌ๊ทธ์ธ์˜ `skills/` ๋””๋ ‰ํ„ฐ๋ฆฌ์— ์Šคํ‚ฌ์„ ํŒจํ‚ค์ง•ํ•˜์„ธ์š”. + +## ๋” ๋‚˜์•„๊ฐ€๊ธฐ: ์Šคํ‚ฌ ์ปฌ๋ ‰์…˜ ๋ฐ ์Šคํ‚ฌ ๊ด€๋ฆฌ์ž + +์Šคํ‚ฌ์„ ์ง„์ง€ํ•˜๊ฒŒ ๊ตฌ์ถ•ํ•˜๊ธฐ ์‹œ์ž‘ํ•˜๋ฉด ๋‘ ๊ฐ€์ง€๊ฐ€ ํ•„์ˆ˜์ ์ด ๋ฉ๋‹ˆ๋‹ค: ๊ฒ€์ฆ๋œ ์Šคํ‚ฌ ๋ผ์ด๋ธŒ๋Ÿฌ๋ฆฌ์™€ ์ด๋ฅผ ๊ด€๋ฆฌํ•˜๋Š” ๋„๊ตฌ์ž…๋‹ˆ๋‹ค. + +**[luongnv89/skills](https://github.com/luongnv89/skills)** โ€” ๊ฑฐ์˜ ๋ชจ๋“  ํ”„๋กœ์ ํŠธ์—์„œ ๋งค์ผ ์‚ฌ์šฉํ•˜๋Š” ์Šคํ‚ฌ ์ปฌ๋ ‰์…˜์ž…๋‹ˆ๋‹ค. `logo-designer` (์˜จ๋”ํ”Œ๋ผ์ด ํ”„๋กœ์ ํŠธ ๋กœ๊ณ  ์ƒ์„ฑ) ๋ฐ `ollama-optimizer` (ํ•˜๋“œ์›จ์–ด์— ๋งž๊ฒŒ ๋กœ์ปฌ LLM ์„ฑ๋Šฅ ํŠœ๋‹)๊ฐ€ ์ฃผ์š” ํŠน์ง•์ž…๋‹ˆ๋‹ค. ์ฆ‰์‹œ ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ์Šคํ‚ฌ์„ ์›ํ•œ๋‹ค๋ฉด ํ›Œ๋ฅญํ•œ ์‹œ์ž‘์ ์ž…๋‹ˆ๋‹ค. + +**[luongnv89/asm](https://github.com/luongnv89/asm)** โ€” ์—์ด์ „ํŠธ ์Šคํ‚ฌ ๊ด€๋ฆฌ์ž์ž…๋‹ˆ๋‹ค. ์Šคํ‚ฌ ๊ฐœ๋ฐœ, ์ค‘๋ณต ๊ฐ์ง€ ๋ฐ ํ…Œ์ŠคํŠธ๋ฅผ ์ฒ˜๋ฆฌํ•ฉ๋‹ˆ๋‹ค. `asm link` ๋ช…๋ น์„ ์‚ฌ์šฉํ•˜๋ฉด ํŒŒ์ผ์„ ๋ณต์‚ฌํ•  ํ•„์š” ์—†์ด ์–ด๋–ค ํ”„๋กœ์ ํŠธ์—์„œ๋“  ์Šคํ‚ฌ์„ ํ…Œ์ŠคํŠธํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์ด๋Š” ์—ฌ๋Ÿฌ ์Šคํ‚ฌ์„ ๊ฐ€์งˆ ๋•Œ ํ•„์ˆ˜์ ์ž…๋‹ˆ๋‹ค. + +## ์ถ”๊ฐ€ ์ž๋ฃŒ + +- [๊ณต์‹ ์Šคํ‚ฌ ๋ฌธ์„œ](https://code.claude.com/docs/en/skills) +- [์—์ด์ „ํŠธ ์Šคํ‚ฌ ์•„ํ‚คํ…์ฒ˜ ๋ธ”๋กœ๊ทธ](https://claude.com/blog/equipping-agents-for-the-real-world-with-agent-skills) +- [์Šคํ‚ฌ ์ €์žฅ์†Œ](https://github.com/luongnv89/skills) - ์ฆ‰์‹œ ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ์Šคํ‚ฌ ์ปฌ๋ ‰์…˜ +- [์Šฌ๋ž˜์‹œ ๋ช…๋ น ๊ฐ€์ด๋“œ](../01-slash-commands/) - ์‚ฌ์šฉ์ž ์‹œ์ž‘ ๋‹จ์ถ•ํ‚ค +- [์„œ๋ธŒ์—์ด์ „ํŠธ ๊ฐ€์ด๋“œ](../04-subagents/) - ์œ„์ž„๋œ AI ์—์ด์ „ํŠธ +- [๋ฉ”๋ชจ๋ฆฌ ๊ฐ€์ด๋“œ](../02-memory/) - ์ง€์†์ ์ธ ์ปจํ…์ŠคํŠธ +- [MCP (๋ชจ๋ธ ์ปจํ…์ŠคํŠธ ํ”„๋กœํ† ์ฝœ)](../05-mcp/) - ์‹ค์‹œ๊ฐ„ ์™ธ๋ถ€ ๋ฐ์ดํ„ฐ +- [ํ›… ๊ฐ€์ด๋“œ](../06-hooks/) - ์ด๋ฒคํŠธ ๊ธฐ๋ฐ˜ ์ž๋™ํ™” + +--- +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: 2026๋…„ 6์›” 17์ผ +**Claude Code ๋ฒ„์ „**: 2.1.179 +**์ถœ์ฒ˜**: +- https://code.claude.com/docs/en/skills +- https://code.claude.com/docs/en/settings +- https://code.claude.com/docs/en/changelog +- https://code.claude.com/docs/en/commands +- https://github.com/anthropics/claude-code/releases/tag/v2.1.152 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.154 +**ํ˜ธํ™˜ ๋ชจ๋ธ**: Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5 diff --git a/ko/03-skills/blog-draft/SKILL.md b/ko/03-skills/blog-draft/SKILL.md new file mode 100644 index 00000000..e9dae7a9 --- /dev/null +++ b/ko/03-skills/blog-draft/SKILL.md @@ -0,0 +1,272 @@ +name: blog-draft +description: ์•„์ด๋””์–ด์™€ ์ž๋ฃŒ๋ฅผ ๋ฐ”ํƒ•์œผ๋กœ ๋ธ”๋กœ๊ทธ ๊ฒŒ์‹œ๋ฌผ์„ ์ž‘์„ฑํ•ฉ๋‹ˆ๋‹ค. ์‚ฌ์šฉ์ž๊ฐ€ ๋ธ”๋กœ๊ทธ ๊ฒŒ์‹œ๋ฌผ์„ ์ž‘์„ฑํ•˜๊ฑฐ๋‚˜, ์—ฐ๊ตฌ๋ฅผ ํ†ตํ•ด ์ฝ˜ํ…์ธ ๋ฅผ ๋งŒ๋“ค๊ฑฐ๋‚˜, ๊ธฐ์‚ฌ๋ฅผ ์ดˆ์•ˆํ•  ๋•Œ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. ์—ฐ๊ตฌ, ๋ธŒ๋ ˆ์ธ์Šคํ† ๋ฐ, ๊ฐœ์š” ์ž‘์„ฑ, ๋ฒ„์ „ ๊ด€๋ฆฌ๋ฅผ ํ†ตํ•œ ๋ฐ˜๋ณต์ ์ธ ์ดˆ์•ˆ ์ž‘์„ฑ์„ ์•ˆ๋‚ดํ•ฉ๋‹ˆ๋‹ค. + +## ์‚ฌ์šฉ์ž ์ž…๋ ฅ + +```text +$ARGUMENTS +``` + +๊ณ„์† ์ง„ํ–‰ํ•˜๊ธฐ ์ „์— ์‚ฌ์šฉ์ž ์ž…๋ ฅ์„ **๋ฐ˜๋“œ์‹œ** ๊ณ ๋ คํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. ์‚ฌ์šฉ์ž๋Š” ๋‹ค์Œ์„ ์ œ๊ณตํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค: +- **์•„์ด๋””์–ด/์ฃผ์ œ**: ๋ธ”๋กœ๊ทธ ๊ฒŒ์‹œ๋ฌผ์˜ ์ฃผ์š” ๊ฐœ๋… ๋˜๋Š” ํ…Œ๋งˆ +- **์ž๋ฃŒ**: ์—ฐ๊ตฌ๋ฅผ ์œ„ํ•œ URL, ํŒŒ์ผ ๋˜๋Š” ์ฐธ๊ณ  ์ž๋ฃŒ (์„ ํƒ ์‚ฌํ•ญ์ด์ง€๋งŒ ๊ถŒ์žฅ๋จ) +- **๋Œ€์ƒ ๋…์ž**: ๋ธ”๋กœ๊ทธ ๊ฒŒ์‹œ๋ฌผ์ด ๋ˆ„๊ตฌ๋ฅผ ์œ„ํ•œ ๊ฒƒ์ธ์ง€ (์„ ํƒ ์‚ฌํ•ญ) +- **์–ด์กฐ/์Šคํƒ€์ผ**: ๊ณต์‹์ , ๋น„๊ณต์‹์ , ๊ธฐ์ˆ ์  ๋“ฑ (์„ ํƒ ์‚ฌํ•ญ) + +**์ค‘์š”**: ์‚ฌ์šฉ์ž๊ฐ€ **๊ธฐ์กด ๋ธ”๋กœ๊ทธ ๊ฒŒ์‹œ๋ฌผ**์— ๋Œ€ํ•œ ์—…๋ฐ์ดํŠธ๋ฅผ ์š”์ฒญํ•˜๋Š” ๊ฒฝ์šฐ, 0-8๋‹จ๊ณ„๋ฅผ ๊ฑด๋„ˆ๋›ฐ๊ณ  **9๋‹จ๊ณ„**๋ถ€ํ„ฐ ๋ฐ”๋กœ ์‹œ์ž‘ํ•˜์„ธ์š”. ๋จผ์ € ๊ธฐ์กด ์ดˆ์•ˆ ํŒŒ์ผ์„ ์ฝ์€ ๋‹ค์Œ, ๋ฐ˜๋ณต ํ”„๋กœ์„ธ์Šค๋ฅผ ์ง„ํ–‰ํ•˜์„ธ์š”. + +## ์‹คํ–‰ ํ๋ฆ„ + +๋‹ค์Œ ๋‹จ๊ณ„๋ฅผ ์ˆœ์„œ๋Œ€๋กœ ๋”ฐ๋ฅด์„ธ์š”. **๋ช…์‹œ๋œ ์‚ฌ์šฉ์ž ์Šน์ธ ์—†์ด๋Š” ๋‹จ๊ณ„๋ฅผ ๊ฑด๋„ˆ๋›ฐ๊ฑฐ๋‚˜ ๋‹ค์Œ์œผ๋กœ ์ง„ํ–‰ํ•˜์ง€ ๋งˆ์„ธ์š”.** + +### 0๋‹จ๊ณ„: ํ”„๋กœ์ ํŠธ ํด๋” ์ƒ์„ฑ + +1. ๋‹ค์Œ ํ˜•์‹์œผ๋กœ ํด๋” ์ด๋ฆ„์„ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค: `YYYY-MM-DD-short-topic-name` + - ์˜ค๋Š˜ ๋‚ ์งœ๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + - ์ฃผ์ œ์—์„œ ์งง๊ณ  URL ์นœํ™”์ ์ธ ์Šฌ๋Ÿฌ๊ทธ๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค (์†Œ๋ฌธ์ž, ํ•˜์ดํ”ˆ, ์ตœ๋Œ€ 5๋‹จ์–ด). + +2. ํด๋” ๊ตฌ์กฐ๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค: + ``` + blog-posts/ + โ””โ”€โ”€ YYYY-MM-DD-short-topic-name/ + โ””โ”€โ”€ resources/ + ``` + +3. ๊ณ„์† ์ง„ํ–‰ํ•˜๊ธฐ ์ „์— ์‚ฌ์šฉ์ž์—๊ฒŒ ํด๋” ์ƒ์„ฑ์„ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. + +### 1๋‹จ๊ณ„: ์—ฐ๊ตฌ ๋ฐ ์ž๋ฃŒ ์ˆ˜์ง‘ + +1. ๋ธ”๋กœ๊ทธ ๊ฒŒ์‹œ๋ฌผ ๋””๋ ‰ํ„ฐ๋ฆฌ์— `resources/` ํ•˜์œ„ ํด๋”๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. + +2. ์ œ๊ณต๋œ ๊ฐ ์ž๋ฃŒ์— ๋Œ€ํ•ด: + - **URL**: ์ฃผ์š” ์ •๋ณด๋ฅผ ๊ฐ€์ ธ์™€ `resources/`์— ๋งˆํฌ๋‹ค์šด ํŒŒ์ผ๋กœ ์ €์žฅํ•ฉ๋‹ˆ๋‹ค. + - **ํŒŒ์ผ**: `resources/`์—์„œ ์ฝ๊ณ  ์š”์•ฝํ•ฉ๋‹ˆ๋‹ค. + - **์ฃผ์ œ**: ์›น ๊ฒ€์ƒ‰์„ ์‚ฌ์šฉํ•˜์—ฌ ์ตœ์‹  ์ •๋ณด๋ฅผ ์ˆ˜์ง‘ํ•ฉ๋‹ˆ๋‹ค. + +3. ๊ฐ ์ž๋ฃŒ์— ๋Œ€ํ•ด `resources/`์— ์š”์•ฝ ํŒŒ์ผ์„ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค: + - `resources/source-1-[short-name].md` + - `resources/source-2-[short-name].md` + - etc. + +4. ๊ฐ ์š”์•ฝ์—๋Š” ๋‹ค์Œ ๋‚ด์šฉ์ด ํฌํ•จ๋˜์–ด์•ผ ํ•ฉ๋‹ˆ๋‹ค: + ```markdown + # Source: [Title/URL] + + ## Key Points + - Point 1 + - Point 2 + + ## Relevant Quotes/Data + - Quote or statistic 1 + - Quote or statistic 2 + + ## How This Relates to Topic + Brief explanation of relevance + ``` + +5. ์‚ฌ์šฉ์ž์—๊ฒŒ ์—ฐ๊ตฌ ์š”์•ฝ์„ ์ œ์‹œํ•ฉ๋‹ˆ๋‹ค. + +### 2๋‹จ๊ณ„: ๋ธŒ๋ ˆ์ธ์Šคํ† ๋ฐ ๋ฐ ๋ช…ํ™•ํ™” + +1. ์•„์ด๋””์–ด์™€ ์—ฐ๊ตฌ๋œ ์ž๋ฃŒ๋ฅผ ๋ฐ”ํƒ•์œผ๋กœ ๋‹ค์Œ์„ ์ œ์‹œํ•ฉ๋‹ˆ๋‹ค: + - ์—ฐ๊ตฌ์—์„œ ํŒŒ์•…๋œ **์ฃผ์š” ํ…Œ๋งˆ** + - ๋ธ”๋กœ๊ทธ ๊ฒŒ์‹œ๋ฌผ์— ๋Œ€ํ•œ **์ž ์žฌ์  ๊ด€์ ** + - ๋‹ค๋ฃจ์–ด์•ผ ํ•  **ํ•ต์‹ฌ ์š”์ ** + - ๋ช…ํ™•ํ™”๊ฐ€ ํ•„์š”ํ•œ ์ •๋ณด์˜ **๊ณต๋ฐฑ** + +2. ๋ช…ํ™•ํ™” ์งˆ๋ฌธ์„ ํ•ฉ๋‹ˆ๋‹ค: + - ๋…์ž๋“ค์ด ์–ป์–ด๊ฐ€๊ธธ ๋ฐ”๋ผ๋Š” ์ฃผ์š” ๋ฉ”์‹œ์ง€๋Š” ๋ฌด์—‡์ธ๊ฐ€์š”? + - ์—ฐ๊ตฌ์—์„œ ๊ฐ•์กฐํ•˜๊ณ  ์‹ถ์€ ํŠน์ • ์š”์ ์ด ์žˆ๋‚˜์š”? + - ๋ชฉํ‘œ ๊ธธ์ด๋Š” ์–ผ๋งˆ์ธ๊ฐ€์š”? (์งง์Œ: 500-800๋‹จ์–ด, ์ค‘๊ฐ„: 1000-1500๋‹จ์–ด, ๊น€: 2000๋‹จ์–ด ์ด์ƒ) + - ์ œ์™ธํ•˜๊ณ  ์‹ถ์€ ์š”์ ์ด ์žˆ๋‚˜์š”? + +3. **์ง„ํ–‰ํ•˜๊ธฐ ์ „์— ์‚ฌ์šฉ์ž ์‘๋‹ต์„ ๊ธฐ๋‹ค๋ฆฝ๋‹ˆ๋‹ค.** + +### 3๋‹จ๊ณ„: ๊ฐœ์š” ์ œ์•ˆ + +1. ๋‹ค์Œ์„ ํฌํ•จํ•˜๋Š” ๊ตฌ์กฐํ™”๋œ ๊ฐœ์š”๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค: + + ```markdown + # Blog Post Outline: [Title] + + ## Meta Information + - **Target Audience**: [who] + - **Tone**: [style] + - **Target Length**: [word count] + - **Main Takeaway**: [key message] + + ## Proposed Structure + + ### Hook/Introduction + - Opening hook idea + - Context setting + - Thesis statement + + ### Section 1: [Title] + - Key point A + - Key point B + - Supporting evidence from [source] + + ### Section 2: [Title] + - Key point A + - Key point B + + [Continue for all sections...] + + ### Conclusion + - Summary of key points + - Call to action or final thought + + ## Sources to Cite + - Source 1 + - Source 2 + ``` + +2. ์‚ฌ์šฉ์ž์—๊ฒŒ ๊ฐœ์š”๋ฅผ ์ œ์‹œํ•˜๊ณ  **์Šน์ธ ๋˜๋Š” ์ˆ˜์ • ์š”์ฒญ ์—ฌ๋ถ€๋ฅผ ๋ฌป์Šต๋‹ˆ๋‹ค.** + +### 4๋‹จ๊ณ„: ์Šน์ธ๋œ ๊ฐœ์š” ์ €์žฅ + +1. ์‚ฌ์šฉ์ž๊ฐ€ ๊ฐœ์š”๋ฅผ ์Šน์ธํ•˜๋ฉด, ๋ธ”๋กœ๊ทธ ๊ฒŒ์‹œ๋ฌผ ํด๋”์— `OUTLINE.md`๋กœ ์ €์žฅํ•ฉ๋‹ˆ๋‹ค. + +2. ๊ฐœ์š”๊ฐ€ ์ €์žฅ๋˜์—ˆ๋Š”์ง€ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. + +### 5๋‹จ๊ณ„: ๊ฐœ์š” ์ปค๋ฐ‹ (git ์ €์žฅ์†Œ์ธ ๊ฒฝ์šฐ) + +1. ํ˜„์žฌ ๋””๋ ‰ํ„ฐ๋ฆฌ๊ฐ€ git ์ €์žฅ์†Œ์ธ์ง€ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. + +2. ๊ทธ๋ ‡๋‹ค๋ฉด: + - ์ƒˆ ํŒŒ์ผ๋“ค์„ ์Šคํ…Œ์ด์ง•ํ•ฉ๋‹ˆ๋‹ค: ๋ธ”๋กœ๊ทธ ๊ฒŒ์‹œ๋ฌผ ํด๋”, resources, OUTLINE.md + - Create commit with message: `docs: Add outline for blog post - [topic-name]` + - ์›๊ฒฉ ์ €์žฅ์†Œ์— ํ‘ธ์‹œํ•ฉ๋‹ˆ๋‹ค. + +3. git ์ €์žฅ์†Œ๊ฐ€ ์•„๋‹ˆ๋ผ๋ฉด, ์ด ๋‹จ๊ณ„๋ฅผ ๊ฑด๋„ˆ๋›ฐ๊ณ  ์‚ฌ์šฉ์ž์—๊ฒŒ ์•Œ๋ฆฝ๋‹ˆ๋‹ค. + +### 6๋‹จ๊ณ„: ์ดˆ์•ˆ ์ž‘์„ฑ + +1. ์Šน์ธ๋œ ๊ฐœ์š”๋ฅผ ๋ฐ”ํƒ•์œผ๋กœ ๋ธ”๋กœ๊ทธ ๊ฒŒ์‹œ๋ฌผ ์ดˆ์•ˆ ์ „์ฒด๋ฅผ ์ž‘์„ฑํ•ฉ๋‹ˆ๋‹ค. + +2. OUTLINE.md์˜ ๊ตฌ์กฐ๋ฅผ ์ •ํ™•ํžˆ ๋”ฐ๋ฆ…๋‹ˆ๋‹ค. + +3. ๋‹ค์Œ์„ ํฌํ•จํ•ฉ๋‹ˆ๋‹ค: + - ํ›„ํฌ๋ฅผ ํฌํ•จํ•œ ๋งค๋ ฅ์ ์ธ ์„œ๋ก  + - ๋ช…ํ™•ํ•œ ์„น์…˜ ํ—ค๋” + - ์—ฐ๊ตฌ ์ž๋ฃŒ๋กœ๋ถ€ํ„ฐ์˜ ๋’ท๋ฐ›์นจํ•˜๋Š” ์ฆ๊ฑฐ ๋ฐ ์˜ˆ์‹œ + - ์„น์…˜ ๊ฐ„์˜ ๋ถ€๋“œ๋Ÿฌ์šด ์ „ํ™˜ + - ์ฃผ์š” ๋ฉ”์‹œ์ง€๊ฐ€ ๋‹ด๊ธด ๊ฐ•๋ ฅํ•œ ๊ฒฐ๋ก  + - **์ธ์šฉ**: ๋ชจ๋“  ๋น„๊ต, ํ†ต๊ณ„, ๋ฐ์ดํ„ฐ ํฌ์ธํŠธ ๋ฐ ์‚ฌ์‹ค์  ์ฃผ์žฅ์€ ์›๋ณธ ์ถœ์ฒ˜๋ฅผ **๋ฐ˜๋“œ์‹œ** ์ธ์šฉํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. + +4. ์ดˆ์•ˆ์„ ๋ธ”๋กœ๊ทธ ๊ฒŒ์‹œ๋ฌผ ํด๋”์— `draft-v0.1.md`๋กœ ์ €์žฅํ•ฉ๋‹ˆ๋‹ค. + +5. ํ˜•์‹: + ```markdown + # [Blog Post Title] + + *[Optional: subtitle or tagline]* + + [Full content with inline citations...] + + --- + + ## References + - [1] Source 1 Title - URL or Citation + - [2] Source 2 Title - URL or Citation + - [3] Source 3 Title - URL or Citation + ``` + +6. **์ธ์šฉ ์š”๊ตฌ ์‚ฌํ•ญ**: + - ๋ชจ๋“  ๋ฐ์ดํ„ฐ ํฌ์ธํŠธ, ํ†ต๊ณ„ ๋˜๋Š” ๋น„๊ต๋Š” ์ธ๋ผ์ธ ์ธ์šฉ์„ **๋ฐ˜๋“œ์‹œ** ํฌํ•จํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. + - ๋ฒˆํ˜ธ๊ฐ€ ๋งค๊ฒจ์ง„ ์ฐธ์กฐ [1], [2] ๋“ฑ์„ ์‚ฌ์šฉํ•˜๊ฑฐ๋‚˜ ์ด๋ฆ„์ด ์ง€์ •๋œ ์ธ์šฉ [Source Name]์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + - ์ธ์šฉ์„ ๋งˆ์ง€๋ง‰์˜ ์ฐธ์กฐ ์„น์…˜์— ์—ฐ๊ฒฐํ•ฉ๋‹ˆ๋‹ค. + - Example: "Studies show that 65% of developers prefer TypeScript [1]" + - Example: "React outperforms Vue in rendering speed by 20% [React Benchmarks 2024]" + +### 7๋‹จ๊ณ„: ์ดˆ์•ˆ ์ปค๋ฐ‹ (git ์ €์žฅ์†Œ์ธ ๊ฒฝ์šฐ) + +1. git ์ €์žฅ์†Œ์ธ์ง€ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. + +2. ๊ทธ๋ ‡๋‹ค๋ฉด: + - ์ดˆ์•ˆ ํŒŒ์ผ์„ ์Šคํ…Œ์ด์ง•ํ•ฉ๋‹ˆ๋‹ค. + - Create commit with message: `docs: Add draft v0.1 for blog post - [topic-name]` + - ์›๊ฒฉ ์ €์žฅ์†Œ์— ํ‘ธ์‹œํ•ฉ๋‹ˆ๋‹ค. + +3. git ์ €์žฅ์†Œ๊ฐ€ ์•„๋‹ˆ๋ผ๋ฉด, ๊ฑด๋„ˆ๋›ฐ๊ณ  ์‚ฌ์šฉ์ž์—๊ฒŒ ์•Œ๋ฆฝ๋‹ˆ๋‹ค. + +### 8๋‹จ๊ณ„: ๊ฒ€ํ† ๋ฅผ ์œ„ํ•œ ์ดˆ์•ˆ ์ œ์‹œ + +1. ์ดˆ์•ˆ ๋‚ด์šฉ์„ ์‚ฌ์šฉ์ž์—๊ฒŒ ์ œ์‹œํ•ฉ๋‹ˆ๋‹ค. + +2. ํ”ผ๋“œ๋ฐฑ์„ ์š”์ฒญํ•ฉ๋‹ˆ๋‹ค: + - ์ „๋ฐ˜์ ์ธ ์ธ์ƒ์€ ์–ด๋–ค๊ฐ€์š”? + - ํ™•์žฅ ๋˜๋Š” ์ถ•์†Œ๊ฐ€ ํ•„์š”ํ•œ ์„น์…˜์ด ์žˆ๋‚˜์š”? + - ์–ด์กฐ ์กฐ์ •์ด ํ•„์š”ํ•œ๊ฐ€์š”? + - ๋ˆ„๋ฝ๋œ ์ •๋ณด๊ฐ€ ์žˆ๋‚˜์š”? + - ํŠน์ • ํŽธ์ง‘ ๋˜๋Š” ์žฌ์ž‘์„ฑ์ด ํ•„์š”ํ•œ๊ฐ€์š”? + +3. **์‚ฌ์šฉ์ž ์‘๋‹ต์„ ๊ธฐ๋‹ค๋ฆฝ๋‹ˆ๋‹ค.** + +### 9๋‹จ๊ณ„: ๋ฐ˜๋ณต ๋˜๋Š” ์ตœ์ข…ํ™” + +**์‚ฌ์šฉ์ž๊ฐ€ ๋ณ€๊ฒฝ์„ ์š”์ฒญํ•˜๋Š” ๊ฒฝ์šฐ:** +1. ์š”์ฒญ๋œ ๋ชจ๋“  ์ˆ˜์ •์„ ๊ธฐ๋กํ•ฉ๋‹ˆ๋‹ค. +2. ๋‹ค์Œ ์กฐ์ • ์‚ฌํ•ญ๊ณผ ํ•จ๊ป˜ 6๋‹จ๊ณ„๋กœ ๋Œ์•„๊ฐ‘๋‹ˆ๋‹ค: + - ๋ฒ„์ „ ๋ฒˆํ˜ธ๋ฅผ ์ฆ๊ฐ€์‹œํ‚ต๋‹ˆ๋‹ค (v0.2, v0.3 ๋“ฑ). + - ๋ชจ๋“  ํ”ผ๋“œ๋ฐฑ์„ ๋ฐ˜์˜ํ•ฉ๋‹ˆ๋‹ค. + - `draft-v[X.Y].md`๋กœ ์ €์žฅํ•ฉ๋‹ˆ๋‹ค. + - 7-8๋‹จ๊ณ„๋ฅผ ๋ฐ˜๋ณตํ•ฉ๋‹ˆ๋‹ค. + +**์‚ฌ์šฉ์ž๊ฐ€ ์Šน์ธํ•˜๋Š” ๊ฒฝ์šฐ:** +1. ์ตœ์ข… ์ดˆ์•ˆ ๋ฒ„์ „์„ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. +2. ์‚ฌ์šฉ์ž๊ฐ€ ์š”์ฒญํ•˜๋Š” ๊ฒฝ์šฐ ์„ ํƒ์ ์œผ๋กœ `final.md`๋กœ ์ด๋ฆ„์„ ๋ณ€๊ฒฝํ•ฉ๋‹ˆ๋‹ค. +3. ๋ธ”๋กœ๊ทธ ๊ฒŒ์‹œ๋ฌผ ์ƒ์„ฑ ๊ณผ์ •์„ ์š”์•ฝํ•ฉ๋‹ˆ๋‹ค: + - ์ƒ์„ฑ๋œ ์ด ๋ฒ„์ „ ์ˆ˜ + - ๋ฒ„์ „ ๊ฐ„์˜ ์ฃผ์š” ๋ณ€๊ฒฝ ์‚ฌํ•ญ + - ์ตœ์ข… ๋‹จ์–ด ์ˆ˜ + - ์ƒ์„ฑ๋œ ํŒŒ์ผ + +## ๋ฒ„์ „ ์ถ”์  + +๋ชจ๋“  ์ดˆ์•ˆ์€ ์ ์ง„์ ์ธ ๋ฒ„์ „ ๊ด€๋ฆฌ๋ฅผ ํ†ตํ•ด ๋ณด์กด๋ฉ๋‹ˆ๋‹ค: +- `draft-v0.1.md` - ์ดˆ๊ธฐ ์ดˆ์•ˆ +- `draft-v0.2.md` - 1์ฐจ ํ”ผ๋“œ๋ฐฑ ํ›„ +- `draft-v0.3.md` - 2์ฐจ ํ”ผ๋“œ๋ฐฑ ํ›„ +- ๋“ฑ + +์ด๋Š” ๋ธ”๋กœ๊ทธ ๊ฒŒ์‹œ๋ฌผ์˜ ์ง„ํ™”๋ฅผ ์ถ”์ ํ•˜๊ณ  ํ•„์š”ํ•œ ๊ฒฝ์šฐ ๋˜๋Œ๋ฆด ์ˆ˜ ์žˆ๊ฒŒ ํ•ฉ๋‹ˆ๋‹ค. + +## ์ถœ๋ ฅ ํŒŒ์ผ ๊ตฌ์กฐ + +``` +blog-posts/ +โ””โ”€โ”€ YYYY-MM-DD-topic-name/ + โ”œโ”€โ”€ resources/ + โ”‚ โ”œโ”€โ”€ source-1-name.md + โ”‚ โ”œโ”€โ”€ source-2-name.md + โ”‚ โ””โ”€โ”€ ... + โ”œโ”€โ”€ OUTLINE.md + โ”œโ”€โ”€ draft-v0.1.md + โ”œโ”€โ”€ draft-v0.2.md (if iterations) + โ””โ”€โ”€ draft-v0.3.md (if more iterations) +``` + +## ํ’ˆ์งˆ ํ–ฅ์ƒ์„ ์œ„ํ•œ ํŒ + +- **ํ›„ํฌ**: ์งˆ๋ฌธ, ๋†€๋ผ์šด ์‚ฌ์‹ค ๋˜๋Š” ๊ณต๊ฐํ•  ์ˆ˜ ์žˆ๋Š” ์‹œ๋‚˜๋ฆฌ์˜ค๋กœ ์‹œ์ž‘ํ•ฉ๋‹ˆ๋‹ค. +- **ํ๋ฆ„**: ๊ฐ ๋‹จ๋ฝ์€ ๋‹ค์Œ ๋‹จ๋ฝ๊ณผ ์—ฐ๊ฒฐ๋˜์–ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. +- **์ฆ๊ฑฐ**: ์—ฐ๊ตฌ ์ž๋ฃŒ์˜ ๋ฐ์ดํ„ฐ๋กœ ์ฃผ์žฅ์„ ๋’ท๋ฐ›์นจํ•ฉ๋‹ˆ๋‹ค. +- **์ธ์šฉ**: ๋‹ค์Œ์˜ ๊ฒฝ์šฐ ์ถœ์ฒ˜๋ฅผ **ํ•ญ์ƒ** ์ธ์šฉํ•ฉ๋‹ˆ๋‹ค: + - ๋ชจ๋“  ํ†ต๊ณ„ ๋ฐ ๋ฐ์ดํ„ฐ ํฌ์ธํŠธ (์˜ˆ: "[์ถœ์ฒ˜]์— ๋”ฐ๋ฅด๋ฉด, 75%์˜ ...") + - ์ œํ’ˆ, ์„œ๋น„์Šค ๋˜๋Š” ์ ‘๊ทผ ๋ฐฉ์‹ ๊ฐ„์˜ ๋น„๊ต (์˜ˆ: "X๋Š” Y๋ณด๋‹ค 2๋ฐฐ ๋น ๋ฅด๊ฒŒ ์ž‘๋™ํ•ฉ๋‹ˆ๋‹ค [์ถœ์ฒ˜]") + - ์‹œ์žฅ ๋™ํ–ฅ, ์—ฐ๊ตฌ ๊ฒฐ๊ณผ ๋˜๋Š” ๋ฒค์น˜๋งˆํฌ์— ๋Œ€ํ•œ ์‚ฌ์‹ค์  ์ฃผ์žฅ + - [Source Name] ๋˜๋Š” [Author, Year] ํ˜•์‹์œผ๋กœ ์ธ๋ผ์ธ ์ธ์šฉ์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +- **์–ด์กฐ**: ์ „์ฒด์ ์œผ๋กœ ์ผ๊ด€๋œ ์–ด์กฐ๋ฅผ ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. +- **๊ธธ์ด**: ๋ชฉํ‘œ ๋‹จ์–ด ์ˆ˜๋ฅผ ์ค€์ˆ˜ํ•ฉ๋‹ˆ๋‹ค. +- **๊ฐ€๋…์„ฑ**: ์งง์€ ๋‹จ๋ฝ, ์ ์ ˆํ•œ ๊ฒฝ์šฐ ๊ธ€๋จธ๋ฆฌ ๊ธฐํ˜ธ๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +- **CTA**: ๋ช…ํ™•ํ•œ ํ–‰๋™ ์œ ๋„ ๋˜๋Š” ์ƒ๊ฐํ•  ๊ฑฐ๋ฆฌ๋ฅผ ์ œ๊ณตํ•˜๋Š” ์งˆ๋ฌธ์œผ๋กœ ๋๋ƒ…๋‹ˆ๋‹ค. + +## ์ฐธ๊ณ  ์‚ฌํ•ญ + +- ๋ช…์‹œ๋œ ์ฒดํฌํฌ์ธํŠธ์—์„œ ํ•ญ์ƒ ์‚ฌ์šฉ์ž ์Šน์ธ์„ ๊ธฐ๋‹ค๋ฆฝ๋‹ˆ๋‹ค. +- ๊ธฐ๋ก์„ ์œ„ํ•ด ๋ชจ๋“  ์ดˆ์•ˆ ๋ฒ„์ „์„ ๋ณด์กดํ•ฉ๋‹ˆ๋‹ค. +- URL์ด ์ œ๊ณต๋  ๋•Œ ์ตœ์‹  ์ •๋ณด๋ฅผ ์œ„ํ•ด ์›น ๊ฒ€์ƒ‰์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +- ์ž๋ฃŒ๊ฐ€ ๋ถˆ์ถฉ๋ถ„ํ•œ ๊ฒฝ์šฐ, ์‚ฌ์šฉ์ž์—๊ฒŒ ๋” ๋งŽ์€ ์ž๋ฃŒ๋ฅผ ์š”์ฒญํ•˜๊ฑฐ๋‚˜ ์ถ”๊ฐ€ ์—ฐ๊ตฌ๋ฅผ ์ œ์•ˆํ•ฉ๋‹ˆ๋‹ค. +- ๋Œ€์ƒ ๋…์ž (๊ธฐ์ˆ ์ , ์ผ๋ฐ˜์ , ๋น„์ฆˆ๋‹ˆ์Šค ๋“ฑ)์— ๋”ฐ๋ผ ์–ด์กฐ๋ฅผ ์กฐ์ •ํ•ฉ๋‹ˆ๋‹ค. diff --git a/ko/03-skills/blog-draft/templates/draft-template.md b/ko/03-skills/blog-draft/templates/draft-template.md new file mode 100644 index 00000000..3e6382e7 --- /dev/null +++ b/ko/03-skills/blog-draft/templates/draft-template.md @@ -0,0 +1,67 @@ +# [๋ธ”๋กœ๊ทธ ๊ฒŒ์‹œ๋ฌผ ์ œ๋ชฉ] + +*[๋ถ€์ œ๋ชฉ ๋˜๋Š” ํƒœ๊ทธ๋ผ์ธ - ์„ ํƒ ์‚ฌํ•ญ]* + +**[์ž‘์„ฑ์ž ์ด๋ฆ„]** | [๋‚ ์งœ] + +--- + +[์‹œ์ž‘ ๋ฌธ๊ตฌ - ์ฆ‰์‹œ ๋…์ž์˜ ์ฃผ์˜๋ฅผ ์‚ฌ๋กœ์žก์œผ์„ธ์š”] + +[๋งฅ๋ฝ ๋ฐ ๋ฐฐ๊ฒฝ - ์™œ ์ด๊ฒƒ์ด ์ค‘์š”ํ•œ๊ฐ€] + +[๋…ผ์ง€ - ์ด ๊ฒŒ์‹œ๋ฌผ์—์„œ ๋‹ค๋ฃฐ ๋‚ด์šฉ] + +--- + +## [์„น์…˜ 1 ์ œ๋ชฉ] + +[๋ช…ํ™•ํ•˜๊ณ  ํฅ๋ฏธ๋กœ์šด ์‚ฐ๋ฌธ์œผ๋กœ ๋œ ์„น์…˜ ๋‚ด์šฉ] + +[์š”์ ์„ ๋’ท๋ฐ›์นจํ•˜๋Š” ์ฆ๊ฑฐ, ์˜ˆ์‹œ ๋˜๋Š” ๋ฐ์ดํ„ฐ๋ฅผ ํฌํ•จํ•˜์„ธ์š”] + +> "์—ฐ๊ตฌ์—์„œ ๋ฐœ์ทŒํ•œ ๊ด€๋ จ ์ธ์šฉ๋ฌธ" - ์ถœ์ฒ˜ + +[๋‹ค์Œ ์„น์…˜์œผ๋กœ์˜ ์ „ํ™˜] + +--- + +## [์„น์…˜ 2 ์ œ๋ชฉ] + +[์ฃผ์š” ๋‚ด์šฉ์„ ๊ณ„์† ์ง„ํ–‰ํ•˜์„ธ์š”] + +**์ฃผ์š” ์š”์ :** [์ค‘์š”ํ•œ ๋‚ด์šฉ์„ ๊ตต๊ฒŒ ํ‘œ์‹œํ•˜๊ฑฐ๋‚˜ ๊ฐ•์กฐ ์ƒ์ž์— ๋„ฃ์–ด ๊ฐ•์กฐํ•˜์„ธ์š”] + +[๋” ๋งŽ์€ ๋ณด์กฐ ๋‚ด์šฉ] + +--- + +## [์„น์…˜ 3 ์ œ๋ชฉ] + +[ํ•„์š”์— ๋”ฐ๋ผ ์ถ”๊ฐ€ ์„น์…˜] + +### ํ•˜์œ„ ์„น์…˜ (ํ•„์š”ํ•œ ๊ฒฝ์šฐ) + +[ํ•˜์œ„ ์„น์…˜ ๋‚ด์šฉ] + +--- + +## ๊ฒฐ๋ก  + +[๋‹ค๋ฃฌ ํ•ต์‹ฌ ๋‚ด์šฉ์„ ์š”์•ฝํ•˜์„ธ์š”] + +[์ฃผ์š” ์š”์ ์„ ๋‹ค์‹œ ๊ฐ•์กฐํ•˜์„ธ์š”] + +[ํ–‰๋™ ์œ ๋„ ๋˜๋Š” ์ƒ๊ฐํ•  ๊ฑฐ๋ฆฌ๋ฅผ ์ œ๊ณตํ•˜๋Š” ๋งˆ์ง€๋ง‰ ์ง„์ˆ ] + +--- + +## ์ฐธ๊ณ  ๋ฌธํ—Œ + +1. [์ถœ์ฒ˜ ์ œ๋ชฉ](#) +2. [์ถœ์ฒ˜ ์ œ๋ชฉ](#) +3. [์ถœ์ฒ˜ ์ œ๋ชฉ](#) + +--- + +*[์„ ํƒ ์‚ฌํ•ญ: ์ž‘์„ฑ์ž ์•ฝ๋ ฅ ๋˜๋Š” ๊ด€๋ จ ๊ฒŒ์‹œ๋ฌผ ์ œ์•ˆ]* diff --git a/ko/03-skills/blog-draft/templates/outline-template.md b/ko/03-skills/blog-draft/templates/outline-template.md new file mode 100644 index 00000000..7ea14d5b --- /dev/null +++ b/ko/03-skills/blog-draft/templates/outline-template.md @@ -0,0 +1,97 @@ +# ๋ธ”๋กœ๊ทธ ๊ฒŒ์‹œ๋ฌผ ๊ฐœ์š”: [Title] + +## ๋ฉ”ํƒ€ ์ •๋ณด + +| ์†์„ฑ | ๊ฐ’ | +|-----------|-------| +| **๋Œ€์ƒ ๋…์ž** | [๋ˆ„๊ตฌ๋ฅผ ์œ„ํ•œ ๊ฒƒ์ธ๊ฐ€?] | +| **์–ด์กฐ** | [๊ณต์‹์ /๋น„๊ณต์‹์ /์ „๋ฌธ์ /๋Œ€ํ™”์ ] | +| **๋ชฉํ‘œ ๊ธธ์ด** | [๋‹จ์–ด ์ˆ˜ ๋ฒ”์œ„] | +| **์ฃผ์š” ์‹œ์‚ฌ์ ** | [ํ•œ ๋ฌธ์žฅ: ๋…์ž๋“ค์ด ๋ฌด์—‡์„ ๊ธฐ์–ตํ•ด์•ผ ํ•˜๋Š”๊ฐ€?] | +| **ํ‚ค์›Œ๋“œ** | [๊ด€๋ จ SEO ํ‚ค์›Œ๋“œ] | + +--- + +## ์ œ์•ˆ๋œ ๊ตฌ์„ฑ + +### 1. ์„œ๋ก  / ํ›„ํฌ + +**์‹œ์ž‘ ํ›„ํฌ ์˜ต์…˜:** +- [ ] ๋…์ž์˜ ๊ณต๊ฐ์„ ์–ป๋Š” ์งˆ๋ฌธ +- [ ] ๋†€๋ผ์šด ํ†ต๊ณ„ ๋˜๋Š” ์‚ฌ์‹ค +- [ ] ์งง์€ ์ด์•ผ๊ธฐ ๋˜๋Š” ์‹œ๋‚˜๋ฆฌ์˜ค +- [ ] ๋Œ€๋‹ดํ•œ ์ง„์ˆ  + +**๋งฅ๋ฝ ์„ค์ •:** +- ํ•„์š”ํ•œ ๋ฐฐ๊ฒฝ ์ •๋ณด +- ์ด ์ฃผ์ œ๊ฐ€ ์ง€๊ธˆ ์™œ ์ค‘์š”ํ•œ๊ฐ€ + +**๋…ผ์ง€ ์ง„์ˆ :** +- ๊ฒŒ์‹œ๋ฌผ์ด ๋‹ค๋ฃฐ ๋‚ด์šฉ์„ ๋ช…ํ™•ํ•˜๊ฒŒ ์ง„์ˆ  + +--- + +### 2. [์„น์…˜ ์ œ๋ชฉ] + +**์ฃผ์š” ์š”์ :** +- ์š”์  A: [์„ค๋ช…] +- ์š”์  B: [์„ค๋ช…] + +**๋’ท๋ฐ›์นจํ•˜๋Š” ์ฆ๊ฑฐ:** +- [์ถœ์ฒ˜]์—์„œ: [๊ด€๋ จ ๋ฐ์ดํ„ฐ/์ธ์šฉ] + +**๋‹ค์Œ ์„น์…˜์œผ๋กœ์˜ ์ „ํ™˜:** +- [์ด๊ฒƒ์ด ๋‹ค์Œ์— ์ด์–ด์งˆ ๋‚ด์šฉ๊ณผ ์–ด๋–ป๊ฒŒ ์—ฐ๊ฒฐ๋˜๋Š”๊ฐ€] + +--- + +### 3. [์„น์…˜ ์ œ๋ชฉ] + +**์ฃผ์š” ์š”์ :** +- ์š”์  A: [์„ค๋ช…] +- ์š”์  B: [์„ค๋ช…] + +**๋’ท๋ฐ›์นจํ•˜๋Š” ์ฆ๊ฑฐ:** +- [์ถœ์ฒ˜]์—์„œ: [๊ด€๋ จ ๋ฐ์ดํ„ฐ/์ธ์šฉ] + +**๋‹ค์Œ ์„น์…˜์œผ๋กœ์˜ ์ „ํ™˜:** +- [์ด๊ฒƒ์ด ๋‹ค์Œ์— ์ด์–ด์งˆ ๋‚ด์šฉ๊ณผ ์–ด๋–ป๊ฒŒ ์—ฐ๊ฒฐ๋˜๋Š”๊ฐ€] + +--- + +### 4. [์„น์…˜ ์ œ๋ชฉ] (ํ•„์š”์— ๋”ฐ๋ผ ์„น์…˜ ์ถ”๊ฐ€) + +**์ฃผ์š” ์š”์ :** +- ์š”์  A: [์„ค๋ช…] +- ์š”์  B: [์„ค๋ช…] + +**๋’ท๋ฐ›์นจํ•˜๋Š” ์ฆ๊ฑฐ:** +- [์ถœ์ฒ˜]์—์„œ: [๊ด€๋ จ ๋ฐ์ดํ„ฐ/์ธ์šฉ] + +--- + +### 5. ๊ฒฐ๋ก  + +**์ฃผ์š” ์š”์  ์š”์•ฝ:** +- ์š”์  1 ์š”์•ฝ +- ์š”์  2 ์š”์•ฝ +- ์š”์  3 ์š”์•ฝ + +**์ตœ์ข… ์ƒ๊ฐ / ํ–‰๋™ ์ด‰๊ตฌ:** +- [๋…์ž๋“ค์€ ๋‹ค์Œ์— ๋ฌด์—‡์„ ํ•˜๊ฑฐ๋‚˜ ์ƒ๊ฐํ•ด์•ผ ํ• ๊นŒ์š”?] + +--- + +## ์ธ์šฉํ•  ์ถœ์ฒ˜ + +1. [์ถœ์ฒ˜ ์ด๋ฆ„](#) - ์‚ฌ์šฉ ๋ชฉ์ : [์–ด๋–ค ์ •๋ณด] +2. [์ถœ์ฒ˜ ์ด๋ฆ„](#) - ์‚ฌ์šฉ ๋ชฉ์ : [์–ด๋–ค ์ •๋ณด] +3. [์ถœ์ฒ˜ ์ด๋ฆ„](#) - ์‚ฌ์šฉ ๋ชฉ์ : [์–ด๋–ค ์ •๋ณด] + +--- + +## ์ดˆ์•ˆ ์ž‘์„ฑ ์ฐธ๊ณ  ์‚ฌํ•ญ + +- [ํŠน์ • ์š”๊ตฌ ์‚ฌํ•ญ ๋˜๋Š” ์ œ์•ฝ ์‚ฌํ•ญ] +- [๊ฐ•์กฐํ•  ์‚ฌํ•ญ] +- [ํ”ผํ•ด์•ผ ํ•  ์‚ฌํ•ญ] diff --git a/ko/03-skills/brand-voice/SKILL.md b/ko/03-skills/brand-voice/SKILL.md new file mode 100644 index 00000000..19f93633 --- /dev/null +++ b/ko/03-skills/brand-voice/SKILL.md @@ -0,0 +1,72 @@ +--- +name: brand-voice-consistency +description: ๋ชจ๋“  ์ปค๋ฎค๋‹ˆ์ผ€์ด์…˜์ด ๋ธŒ๋žœ๋“œ ๋ณด์ด์Šค ๋ฐ ํ†ค ๊ฐ€์ด๋“œ๋ผ์ธ๊ณผ ์ผ์น˜ํ•˜๋„๋ก ํ•ฉ๋‹ˆ๋‹ค. ๋งˆ์ผ€ํŒ… ๋ฌธ๊ตฌ, ๊ณ ๊ฐ ์ปค๋ฎค๋‹ˆ์ผ€์ด์…˜, ๋Œ€์™ธ ๊ณต๊ฐœ ์ฝ˜ํ…์ธ ๋ฅผ ์ œ์ž‘ํ•  ๋•Œ ๋˜๋Š” ์‚ฌ์šฉ์ž๊ฐ€ ๋ธŒ๋žœ๋“œ ๋ณด์ด์Šค, ํ†ค, ๊ธ€์“ฐ๊ธฐ ์Šคํƒ€์ผ์„ ์–ธ๊ธ‰ํ•  ๋•Œ ์‚ฌ์šฉํ•˜์„ธ์š”. +--- + +# ๋ธŒ๋žœ๋“œ ๋ณด์ด์Šค ์Šคํ‚ฌ + +## ๊ฐœ์š” +์ด ์Šคํ‚ฌ์€ ๋ชจ๋“  ์ปค๋ฎค๋‹ˆ์ผ€์ด์…˜์ด ์ผ๊ด€๋œ ๋ธŒ๋žœ๋“œ ๋ณด์ด์Šค, ํ†ค ๋ฐ ๋ฉ”์‹œ์ง€๋ฅผ ์œ ์ง€ํ•˜๋„๋ก ๋ณด์žฅํ•ฉ๋‹ˆ๋‹ค. + +## ๋ธŒ๋žœ๋“œ ์•„์ด๋ดํ‹ฐํ‹ฐ + +### ๋ฏธ์…˜ +AI๋ฅผ ํ™œ์šฉํ•˜์—ฌ ํŒ€์˜ ๊ฐœ๋ฐœ ์›Œํฌํ”Œ๋กœ์šฐ ์ž๋™ํ™”๋ฅผ ๋•์Šต๋‹ˆ๋‹ค. + +### ๊ฐ€์น˜ +- **๊ฐ„๊ฒฐ์„ฑ**: ๋ณต์žกํ•œ ๊ฒƒ์„ ๊ฐ„๋‹จํ•˜๊ฒŒ ๋งŒ๋“ญ๋‹ˆ๋‹ค. +- **์‹ ๋ขฐ์„ฑ**: ๊ฒฌ๊ณ ํ•œ ์‹คํ–‰ +- **์—ญ๋Ÿ‰ ๊ฐ•ํ™”**: ์ธ๊ฐ„์˜ ์ฐฝ์˜์„ฑ์„ ๋ฐœํœ˜ํ•˜๋„๋ก ์ง€์›ํ•ฉ๋‹ˆ๋‹ค. + +### ํ†ค ์•ค ๋งค๋„ˆ +- **์นœ๊ทผํ•˜์ง€๋งŒ ์ „๋ฌธ์ ์ธ** - ๊ฒฉ์‹ ์—†์ง€ ์•Š์œผ๋ฉด์„œ๋„ ๋‹ค๊ฐ€๊ฐ€๊ธฐ ์‰ฌ์šด +- **๋ช…ํ™•ํ•˜๊ณ  ๊ฐ„๊ฒฐํ•œ** - ์ „๋ฌธ ์šฉ์–ด๋ฅผ ํ”ผํ•˜๊ณ  ๊ธฐ์ˆ  ๊ฐœ๋…์„ ๊ฐ„๋‹จํ•˜๊ฒŒ ์„ค๋ช…ํ•ฉ๋‹ˆ๋‹ค. +- **์ž์‹ ๊ฐ ์žˆ๋Š”** - ์šฐ๋ฆฌ๊ฐ€ ๋ฌด์—‡์„ ํ•˜๊ณ  ์žˆ๋Š”์ง€ ์•Œ๊ณ  ์žˆ์Šต๋‹ˆ๋‹ค. +- **๊ณต๊ฐ์ ์ธ** - ์‚ฌ์šฉ์ž ์š”๊ตฌ์‚ฌํ•ญ๊ณผ ๋ฌธ์ œ์ ์„ ์ดํ•ดํ•ฉ๋‹ˆ๋‹ค. + +## ๊ธ€์“ฐ๊ธฐ ๊ฐ€์ด๋“œ๋ผ์ธ + +### ์ง€์ผœ์•ผ ํ•  ์‚ฌํ•ญ โœ… +- ๋…์ž๋ฅผ ์–ธ๊ธ‰ํ•  ๋•Œ "you"๋ฅผ ์‚ฌ์šฉํ•˜์„ธ์š”. +- ๋Šฅ๋™ํƒœ๋ฅผ ์‚ฌ์šฉํ•˜์„ธ์š”: "Claude generates reports" (Claude๋Š” ๋ณด๊ณ ์„œ๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค.) (์ˆ˜๋™ํƒœ: "Reports are generated by Claude" (๋ณด๊ณ ์„œ๋Š” Claude์— ์˜ํ•ด ์ƒ์„ฑ๋ฉ๋‹ˆ๋‹ค.) ์•„๋‹˜) +- ๊ฐ€์น˜ ์ œ์•ˆ์œผ๋กœ ์‹œ์ž‘ํ•˜์„ธ์š”. +- ๊ตฌ์ฒด์ ์ธ ์˜ˆ์‹œ๋ฅผ ์‚ฌ์šฉํ•˜์„ธ์š”. +- ๋ฌธ์žฅ์€ 20๋‹จ์–ด ๋ฏธ๋งŒ์œผ๋กœ ์œ ์ง€ํ•˜์„ธ์š”. +- ๋ช…ํ™•์„ฑ์„ ์œ„ํ•ด ๋ชฉ๋ก์„ ์‚ฌ์šฉํ•˜์„ธ์š”. +- ์ฝœํˆฌ์•ก์…˜(CTA)์„ ํฌํ•จํ•˜์„ธ์š”. + +### ํ”ผํ•ด์•ผ ํ•  ์‚ฌํ•ญ โŒ +- ๊ธฐ์—… ์ „๋ฌธ ์šฉ์–ด๋ฅผ ์‚ฌ์šฉํ•˜์ง€ ๋งˆ์„ธ์š”. +- ๊น”๋ณด๊ฑฐ๋‚˜ ์ง€๋‚˜์น˜๊ฒŒ ๋‹จ์ˆœํ™”ํ•˜์ง€ ๋งˆ์„ธ์š”. +- "we believe" ๋˜๋Š” "we think"์™€ ๊ฐ™์€ ํ‘œํ˜„์„ ์‚ฌ์šฉํ•˜์ง€ ๋งˆ์„ธ์š”. +- ๊ฐ•์กฐ๋ฅผ ์œ„ํ•œ ๊ฒฝ์šฐ๋ฅผ ์ œ์™ธํ•˜๊ณ ๋Š” ๋ชจ๋“  ๊ธ€์ž๋ฅผ ๋Œ€๋ฌธ์ž๋กœ ์‚ฌ์šฉํ•˜์ง€ ๋งˆ์„ธ์š”. +- ๊ธด ํ…์ŠคํŠธ ๋ฉ์–ด๋ฆฌ๋ฅผ ๋งŒ๋“ค์ง€ ๋งˆ์„ธ์š”. +- ๊ธฐ์ˆ ์  ์ง€์‹์„ ๊ฐ€์ •ํ•˜์ง€ ๋งˆ์„ธ์š”. + +## ์–ดํœ˜ + +### โœ… ๊ถŒ์žฅ ์šฉ์–ด +- Claude ("the Claude AI" ์•„๋‹˜) +- ์ฝ”๋“œ ์ƒ์„ฑ ("auto-coding" ์•„๋‹˜) +- ์—์ด์ „ํŠธ ("bot" ์•„๋‹˜) +- ๊ฐ„์†Œํ™” ("revolutionize" ์•„๋‹˜) +- ํ†ตํ•ฉ ("synergize" ์•„๋‹˜) + +### โŒ ํ”ผํ•ด์•ผ ํ•  ์šฉ์–ด +- "Cutting-edge" (๊ณผ์šฉ๋จ) +- "Game-changer" (๋ชจํ˜ธํ•จ) +- "Leverage" (๊ธฐ์—…์šฉ์–ด) +- "Utilize" ("use"๋ฅผ ์‚ฌ์šฉ) +- "Paradigm shift" (๋ถˆ๋ถ„๋ช…ํ•จ) + +## ์˜ˆ์‹œ + +### โœ… ์ข‹์€ ์˜ˆ์‹œ +"Claude automates your code review process. Instead of manually checking each PR, Claude reviews security, performance, and qualityโ€”saving your team hours every week." + +ํšจ๊ณผ์ ์ธ ์ด์œ : ๋ช…ํ™•ํ•œ ๊ฐ€์น˜, ๊ตฌ์ฒด์ ์ธ ์ด์ , ํ–‰๋™ ์ง€ํ–ฅ์  + +### โŒ ๋‚˜์œ ์˜ˆ์‹œ +"Claude leverages cutting-edge AI to provide comprehensive software development solutions." + +ํšจ๊ณผ์ ์ด์ง€ ์•Š์€ ์ด์œ : ๋ชจํ˜ธํ•จ, ๊ธฐ์—… ์ „๋ฌธ ์šฉ์–ด, ๊ตฌ์ฒด์ ์ธ ๊ฐ€์น˜ ์—†์Œ diff --git a/ko/03-skills/brand-voice/templates/email-template.txt b/ko/03-skills/brand-voice/templates/email-template.txt new file mode 100644 index 00000000..741294d6 --- /dev/null +++ b/ko/03-skills/brand-voice/templates/email-template.txt @@ -0,0 +1,14 @@ +Subject: [Clear, benefit-driven subject] + +Hi [Name], + +[Opening: What's the value for them] + +[Body: How it works / What they'll get] + +[Specific example or benefit] + +[Call to action: Clear next step] + +Best regards, +[Name] diff --git a/ko/03-skills/brand-voice/templates/social-post-template.txt b/ko/03-skills/brand-voice/templates/social-post-template.txt new file mode 100644 index 00000000..97fafbaa --- /dev/null +++ b/ko/03-skills/brand-voice/templates/social-post-template.txt @@ -0,0 +1,4 @@ +[Hook: Grab attention in first line] +[2-3 lines: Value or interesting fact] +[Call to action: Link, question, or engagement] +[Emoji: 1-2 max for visual interest] diff --git a/ko/03-skills/brand-voice/tone-examples.md b/ko/03-skills/brand-voice/tone-examples.md new file mode 100644 index 00000000..6e42eaf8 --- /dev/null +++ b/ko/03-skills/brand-voice/tone-examples.md @@ -0,0 +1,13 @@ +# ๋ธŒ๋žœ๋“œ ๋ณด์ด์Šค ํ†ค ์˜ˆ์‹œ + +## ํฅ๋ฏธ๋กœ์šด ๋ฐœํ‘œ +"์ฝ”๋“œ ๊ฒ€ํ†  ์‹œ๊ฐ„์„ ์ฃผ๋‹น 8์‹œ๊ฐ„ ์ ˆ์•ฝํ•˜์„ธ์š”. Claude๊ฐ€ PR์„ ์ž๋™์œผ๋กœ ๊ฒ€ํ† ํ•ฉ๋‹ˆ๋‹ค." + +## ๊ณต๊ฐํ•˜๋Š” ์ง€์› +"๋ฐฐํฌ๊ฐ€ ์ŠคํŠธ๋ ˆ์Šค๊ฐ€ ๋  ์ˆ˜ ์žˆ๋‹ค๋Š” ๊ฒƒ์„ ์ž˜ ์•Œ๊ณ  ์žˆ์Šต๋‹ˆ๋‹ค. Claude๊ฐ€ ํ…Œ์ŠคํŠธ๋ฅผ ์ฒ˜๋ฆฌํ•˜์—ฌ ๊ฑฑ์ •ํ•  ํ•„์š”๊ฐ€ ์—†์Šต๋‹ˆ๋‹ค." + +## ์ž์‹ ๊ฐ ์žˆ๋Š” ์ œํ’ˆ ๊ธฐ๋Šฅ +"Claude๋Š” ๋‹จ์ˆœํžˆ ์ฝ”๋“œ๋ฅผ ์ œ์•ˆํ•˜๋Š” ๊ฒƒ์„ ๋„˜์–ด์„ญ๋‹ˆ๋‹ค. ์•„ํ‚คํ…์ฒ˜๋ฅผ ์ดํ•ดํ•˜๊ณ  ์ผ๊ด€์„ฑ์„ ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค." + +## ๊ต์œก์šฉ ๋ธ”๋กœ๊ทธ ๊ฒŒ์‹œ๋ฌผ +"์—์ด์ „ํŠธ๊ฐ€ ์ฝ”๋“œ ๊ฒ€ํ†  ์›Œํฌํ”Œ๋กœ์šฐ๋ฅผ ์–ด๋–ป๊ฒŒ ๊ฐœ์„ ํ•˜๋Š”์ง€ ์•Œ์•„๋ด…์‹œ๋‹ค. ๋‹ค์Œ์€ ์šฐ๋ฆฌ๊ฐ€ ๋ฐฐ์šด ๋‚ด์šฉ์ž…๋‹ˆ๋‹ค..." diff --git a/ko/03-skills/claude-md/SKILL.md b/ko/03-skills/claude-md/SKILL.md new file mode 100644 index 00000000..f8873c33 --- /dev/null +++ b/ko/03-skills/claude-md/SKILL.md @@ -0,0 +1,211 @@ +--- +name: claude-md +description: ์ตœ์ ์˜ AI ์—์ด์ „ํŠธ ์˜จ๋ณด๋”ฉ์„ ์œ„ํ•œ ๋ฒ ์ŠคํŠธ ํ”„๋ž™ํ‹ฐ์Šค์— ๋”ฐ๋ผ CLAUDE.md ํŒŒ์ผ์„ ์ƒ์„ฑํ•˜๊ฑฐ๋‚˜ ์—…๋ฐ์ดํŠธํ•ฉ๋‹ˆ๋‹ค. +--- + +## ์‚ฌ์šฉ์ž ์ž…๋ ฅ + +```text +$ARGUMENTS +``` + +์ง„ํ–‰ํ•˜๊ธฐ ์ „์— ์‚ฌ์šฉ์ž ์ž…๋ ฅ์„ **๋ฐ˜๋“œ์‹œ** ๊ณ ๋ คํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค (๋น„์–ด ์žˆ์ง€ ์•Š์€ ๊ฒฝ์šฐ). ์‚ฌ์šฉ์ž๋Š” ๋‹ค์Œ์„ ์ง€์ •ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค: +- `create` - ์ฒ˜์Œ๋ถ€ํ„ฐ ์ƒˆ๋กœ์šด CLAUDE.md ์ƒ์„ฑ +- `update` - ๊ธฐ์กด CLAUDE.md ๊ฐœ์„  +- `audit` - ํ˜„์žฌ CLAUDE.md์˜ ํ’ˆ์งˆ ๋ถ„์„ ๋ฐ ๋ณด๊ณ  +- ์ƒ์„ฑ/์—…๋ฐ์ดํŠธํ•  ํŠน์ • ๊ฒฝ๋กœ (์˜ˆ: ๋””๋ ‰ํ† ๋ฆฌ๋ณ„ ์ง€์นจ์„ ์œ„ํ•œ `src/api/CLAUDE.md`) + +## ํ•ต์‹ฌ ์›์น™ + +**LLM์€ ์ƒํƒœ๋ฅผ ๊ธฐ์–ตํ•˜์ง€ ๋ชปํ•ฉ๋‹ˆ๋‹ค(Stateless)**: CLAUDE.md๋Š” ๋ชจ๋“  ๋Œ€ํ™”์— ์ž๋™์œผ๋กœ ํฌํ•จ๋˜๋Š” ์œ ์ผํ•œ ํŒŒ์ผ์ž…๋‹ˆ๋‹ค. ์ด๋Š” AI ์—์ด์ „ํŠธ๊ฐ€ ์—ฌ๋Ÿฌ๋ถ„์˜ ์ฝ”๋“œ๋ฒ ์ด์Šค์— ํˆฌ์ž…๋  ๋•Œ ๊ฐ€์žฅ ๋จผ์ € ์ฝ๋Š” ํ•ต์‹ฌ ์˜จ๋ณด๋”ฉ ๋ฌธ์„œ ์—ญํ• ์„ ํ•ฉ๋‹ˆ๋‹ค. + +### ํ™ฉ๊ธˆ๋ฅ  + +1. **๋‹จ์ˆœํ•œ ๊ฒƒ์ด ๋” ์ข‹์Šต๋‹ˆ๋‹ค**: ์ตœ์ฒจ๋‹จ LLM์€ ํ•œ ๋ฒˆ์— ์•ฝ 150~200๊ฐœ์˜ ์ง€์นจ์„ ๋”ฐ๋ฅผ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. Claude Code์˜ ์‹œ์Šคํ…œ ํ”„๋กฌํ”„ํŠธ๊ฐ€ ์ด๋ฏธ ์•ฝ 50๊ฐœ๋ฅผ ์‚ฌ์šฉํ•˜๊ณ  ์žˆ์Šต๋‹ˆ๋‹ค. ์—ฌ๋Ÿฌ๋ถ„์˜ CLAUDE.md๋Š” ๊ฐ€์žฅ ํ•ต์‹ฌ์ ์ธ ๋‚ด์šฉ์— ์ง‘์ค‘ํ•˜๊ณ  ๊ฐ„๊ฒฐํ•˜๊ฒŒ ์œ ์ง€ํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. + +2. **๋ณดํŽธ์  ์ ์šฉ ๊ฐ€๋Šฅ์„ฑ**: ๋ชจ๋“  ์„ธ์…˜์— ๊ด€๋ จ์ด ์žˆ๋Š” ์ •๋ณด๋งŒ ํฌํ•จํ•˜์„ธ์š”. ํŠน์ • ์ž‘์—…์—๋งŒ ํ•ด๋‹นํ•˜๋Š” ์ง€์นจ์€ ๋ณ„๋„์˜ ํŒŒ์ผ๋กœ ๋ถ„๋ฆฌํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. + +3. **Claude๋ฅผ ๋ฆฐํ„ฐ(Linter)๋กœ ์“ฐ์ง€ ๋งˆ์„ธ์š”**: ์Šคํƒ€์ผ ๊ฐ€์ด๋“œ๋ผ์ธ์€ ์ปจํ…์ŠคํŠธ๋ฅผ ๋น„๋Œ€ํ™”์‹œํ‚ค๊ณ  ์ง€์นจ ์ค€์ˆ˜ ๋Šฅ๋ ฅ์„ ๋–จ์–ด๋œจ๋ฆฝ๋‹ˆ๋‹ค. ๋Œ€์‹  ๊ฒฐ์ •๋ก ์ ์ธ ๋„๊ตฌ(prettier, eslint ๋“ฑ)๋ฅผ ์‚ฌ์šฉํ•˜์„ธ์š”. + +4. **์ ˆ๋Œ€ ์ž๋™ ์ƒ์„ฑํ•˜์ง€ ๋งˆ์„ธ์š”**: CLAUDE.md๋Š” AI ํ™œ์šฉ ํšจ์œจ์„ ๊ทน๋Œ€ํ™”ํ•˜๋Š” ๊ฐ€์žฅ ๊ฐ•๋ ฅํ•œ ๋ ˆ๋ฒ„๋ฆฌ์ง€ ํฌ์ธํŠธ์ž…๋‹ˆ๋‹ค. ์‹ ์ค‘ํ•˜๊ฒŒ ๊ณ ๋ฏผํ•˜์—ฌ ์ˆ˜๋™์œผ๋กœ ์ž‘์„ฑํ•˜์„ธ์š”. + +## ์‹คํ–‰ ํ๋ฆ„ + +### 1. ํ”„๋กœ์ ํŠธ ๋ถ„์„ + +๋จผ์ €, ํ˜„์žฌ ํ”„๋กœ์ ํŠธ ์ƒํƒœ๋ฅผ ๋ถ„์„ํ•ฉ๋‹ˆ๋‹ค: + +1. ๊ธฐ์กด CLAUDE.md ํŒŒ์ผ์ด ์žˆ๋Š”์ง€ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค: + - ๋ฃจํŠธ ๋ ˆ๋ฒจ: `./CLAUDE.md` or `.claude/CLAUDE.md` + - ๋””๋ ‰ํ† ๋ฆฌ ํŠน์ •: `**/CLAUDE.md` + - ๊ธ€๋กœ๋ฒŒ ์‚ฌ์šฉ์ž ์„ค์ •: `~/.claude/CLAUDE.md` + +2. ํ”„๋กœ์ ํŠธ ๊ตฌ์กฐ๋ฅผ ํŒŒ์•…ํ•ฉ๋‹ˆ๋‹ค: + - ๊ธฐ์ˆ  ์Šคํƒ (์–ธ์–ด, ํ”„๋ ˆ์ž„์›Œํฌ) + - ํ”„๋กœ์ ํŠธ ์œ ํ˜• (๋ชจ๋…ธ๋ ˆํฌ, ๋‹จ์ผ ์•ฑ, ๋ผ์ด๋ธŒ๋Ÿฌ๋ฆฌ) + - ๊ฐœ๋ฐœ ๋„๊ตฌ (ํŒจํ‚ค์ง€ ๋งค๋‹ˆ์ €, ๋นŒ๋“œ ์‹œ์Šคํ…œ, ํ…Œ์ŠคํŠธ ๋Ÿฌ๋„ˆ) + +3. ๊ธฐ์กด ๋ฌธ์„œ๋ฅผ ๊ฒ€ํ† ํ•ฉ๋‹ˆ๋‹ค: + - README.md + - CONTRIBUTING.md + - package.json, pyproject.toml, Cargo.toml ๋“ฑ + +### 2. ์ฝ˜ํ…์ธ  ์ „๋žต (WHAT, WHY, HOW) + +CLAUDE.md๋ฅผ ๋‹ค์Œ ์„ธ ๊ฐ€์ง€ ์ฐจ์›์„ ์ค‘์‹ฌ์œผ๋กœ ๊ตฌ์„ฑํ•˜์„ธ์š”: + +#### WHAT - ๊ธฐ์ˆ  ๋ฐ ๊ตฌ์กฐ +- ๊ธฐ์ˆ  ์Šคํƒ ๊ฐœ์š” +- ํ”„๋กœ์ ํŠธ ๊ตฌ์กฐ (ํŠนํžˆ ๋ชจ๋…ธ๋ ˆํฌ์—์„œ ์ค‘์š”) +- ํ•ต์‹ฌ ๋””๋ ‰ํ† ๋ฆฌ ๋ฐ ๊ฐ๊ฐ์˜ ๋ชฉ์  + + +#### WHY - ๋ชฉ์  ๋ฐ ๋งฅ๋ฝ +- ํ”„๋กœ์ ํŠธ๊ฐ€ ํ•˜๋Š” ์ผ +- ํŠน์ • ์•„ํ‚คํ…์ฒ˜ ๊ฒฐ์ •์„ ๋‚ด๋ฆฐ ์ด์œ  +- ๊ฐ ์ฃผ์š” ์ปดํฌ๋„ŒํŠธ์˜ ์—ญํ•  + +#### HOW - ์›Œํฌํ”Œ๋กœ์šฐ ๋ฐ ๊ด€๋ก€ +- ๊ฐœ๋ฐœ ์›Œํฌํ”Œ๋กœ์šฐ (bun vs node, pip vs uv ๋“ฑ) +- ํ…Œ์ŠคํŠธ ์ ˆ์ฐจ ๋ฐ ๋ช…๋ น์–ด +- ๊ฒ€์ฆ ๋ฐ ๋นŒ๋“œ ๋ฐฉ๋ฒ• +- ์น˜๋ช…์ ์ธ '์ฃผ์˜ ์‚ฌํ•ญ(gotchas)' ๋˜๋Š” ์ง๊ด€์ ์ด์ง€ ์•Š์€ ์š”๊ตฌ์‚ฌํ•ญ + +### 3. ์ ์ง„์  ๊ณต๊ฐœ ์ „๋žต (Progressive Disclosure) + +ํ”„๋กœ์ ํŠธ ๊ทœ๋ชจ๊ฐ€ ํฐ ๊ฒฝ์šฐ, `agent_docs/` ํด๋”๋ฅผ ๋งŒ๋“œ๋Š” ๊ฒƒ์„ ๊ถŒ์žฅํ•ฉ๋‹ˆ๋‹ค: + +``` +agent_docs/ + |- building_the_project.md + |- running_tests.md + |- code_conventions.md + |- architecture_decisions.md +``` + +CLAUDE.md ์•ˆ์—์„œ๋Š” ๋‹ค์Œ๊ณผ ๊ฐ™์€ ์ง€์นจ์œผ๋กœ ์ด ํŒŒ์ผ๋“ค์„ ์ฐธ์กฐํ•˜์„ธ์š”: +```markdown +For detailed build instructions, refer to `agent_docs/building_the_project.md` +``` + +**์ค‘์š”**: ์˜ค๋ž˜๋œ ์ปจํ…์ŠคํŠธ๊ฐ€ ์ฃผ์ž…๋˜๋Š” ๊ฒƒ์„ ๋ฐฉ์ง€ํ•˜๊ธฐ ์œ„ํ•ด ์ฝ”๋“œ ์Šค๋‹ˆํŽซ(์กฐ๊ฐ)์„ ๋ณต์‚ฌํ•ด ๋ถ™์—ฌ๋„ฃ๋Š” ๋Œ€์‹  `ํŒŒ์ผ๋ช…:์ค„๋ฒˆํ˜ธ(file:line)` ์ฐธ์กฐ๋ฅผ ์‚ฌ์šฉํ•˜์„ธ์š”. + +### 4. ํ’ˆ์งˆ ์ œ์•ฝ ์กฐ๊ฑด + +CLAUDE.md๋ฅผ ์ƒ์„ฑํ•˜๊ฑฐ๋‚˜ ์—…๋ฐ์ดํŠธํ•  ๋•Œ: + +1. **๋ชฉํ‘œ ๊ธธ์ด**: 300์ค„ ๋ฏธ๋งŒ (์ด์ƒ์ ์œผ๋กœ๋Š” 100์ค„ ๋ฏธ๋งŒ) +2. **์Šคํƒ€์ผ ๊ทœ์น™ ๋ฐฐ์ œ**: ๋ฆฐํŒ…/ํฌ๋งทํŒ… ์ง€์นจ์€ ๋ชจ๋‘ ์ œ๊ฑฐ +3. **์ž‘์—… ํŠน์ • ์ง€์นจ ๋ฐฐ์ œ**: ๋ณ„๋„์˜ ํŒŒ์ผ๋กœ ์ด๋™ +4. **์ฝ”๋“œ ์Šค๋‹ˆํŽซ ๋ฐฐ์ œ**: ๋Œ€์‹  ํŒŒ์ผ ์ฐธ์กฐ๋ฅผ ์‚ฌ์šฉ +5. **์ฝ”๋“œ ์Šค๋‹ˆํŽซ ๋ฐฐ์ œ**: package.json์ด๋‚˜ README์— ์žˆ๋Š” ๋‚ด์šฉ์„ ๋ฐ˜๋ณตํ•˜์ง€ ๋ง ๊ฒƒ + +### 5. ํ•„์ˆ˜ ์„น์…˜ + +์ž˜ ๊ตฌ์กฐํ™”๋œ CLAUDE.md์—๋Š” ๋‹ค์Œ ๋‚ด์šฉ์ด ํฌํ•จ๋˜์–ด์•ผ ํ•ฉ๋‹ˆ๋‹ค: + +```markdown +# ํ”„๋กœ์ ํŠธ ์ด๋ฆ„ + +ํ•œ ์ค„์งœ๋ฆฌ ์งง์€ ์„ค๋ช…. + +## ๊ธฐ์ˆ  ์Šคํƒ +- ์ฃผ์š” ์–ธ์–ด ๋ฐ ๋ฒ„์ „ +- ํ•ต์‹ฌ ํ”„๋ ˆ์ž„์›Œํฌ/๋ผ์ด๋ธŒ๋Ÿฌ๋ฆฌ +- ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค/์Šคํ† ๋ฆฌ์ง€ (์žˆ๋Š” ๊ฒฝ์šฐ) + +## ํ”„๋กœ์ ํŠธ ๊ตฌ์กฐ +[๋ชจ๋…ธ๋ ˆํฌ ๋˜๋Š” ๋ณต์žกํ•œ ๊ตฌ์กฐ์ธ ๊ฒฝ์šฐ์—๋งŒ ์ž‘์„ฑ] +- `apps/` - ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜ ์ง„์ž…์  +- `packages/` - ๊ณต์œ  ๋ผ์ด๋ธŒ๋Ÿฌ๋ฆฌ + +## ๊ฐœ๋ฐœ ๋ช…๋ น์–ด +- ํŒจํ‚ค์ง€ ์„ค์น˜: `๋ช…๋ น์–ด` +- ํ…Œ์ŠคํŠธ ์‹คํ–‰: `๋ช…๋ น์–ด` +- ํ”„๋กœ์ ํŠธ ๋นŒ๋“œ: `๋ช…๋ น์–ด` + +## ํ•ต์‹ฌ ๊ด€๋ก€ +[์ง๊ด€์ ์ด์ง€ ์•Š๊ณ  ์˜ํ–ฅ๋ ฅ์ด ํฐ ๊ด€๋ก€๋งŒ ์ž‘์„ฑ] +- ๊ด€๋ก€ 1๊ณผ ์งง์€ ์„ค๋ช… +- ๊ด€๋ก€ 2๊ณผ ์งง์€ ์„ค๋ช… + +## ์•Œ๋ ค์ง„ ๋ฌธ์ œ / ์ฃผ์˜ ์‚ฌํ•ญ (Gotchas) +[๊ฐœ๋ฐœ์ž๋“ค์ด ์ง€์†์ ์œผ๋กœ ์‹ค์ˆ˜๋ฅผ ๋ฒ”ํ•˜๋Š” ๋ถ€๋ถ„๋“ค] +- ๋ฌธ์ œ 1 +- ๋ฌธ์ œ 2 +``` + +### 6. ํ”ผํ•ด์•ผ ํ•  ์•ˆํ‹ฐ ํŒจํ„ด + +**๋‹ค์Œ์„ ์ ˆ๋Œ€ ํฌํ•จํ•˜์ง€ ๋งˆ์„ธ์š”:** +- ์ฝ”๋“œ ์Šคํƒ€์ผ ๊ฐ€์ด๋“œ๋ผ์ธ (๋ฆฐํ„ฐ ์‚ฌ์šฉํ•˜๊ธฐ) +- Claude ์‚ฌ์šฉ๋ฒ•์— ๋Œ€ํ•œ ๋ฌธ์„œ +- ๋ป”ํ•˜๊ณ  ๋‹น์—ฐํ•œ ํŒจํ„ด์— ๋Œ€ํ•œ ๊ธด ์„ค๋ช… +- ๋ณต์‚ฌ ๋ถ™์—ฌ๋„ฃ๊ธฐ ๋œ ์ฝ”๋“œ ์˜ˆ์‹œ +- ์ œ๋„ค๋ฆญํ•œ ๋ฒ ์ŠคํŠธ ํ”„๋ž™ํ‹ฐ์Šค ("๊นจ๋—ํ•œ ์ฝ”๋“œ๋ฅผ ์ž‘์„ฑํ•  ๊ฒƒ" ๋“ฑ) +- ํŠน์ • ์ž‘์—…๋งŒ์„ ์œ„ํ•œ ์ง€์นจ +- ์ž๋™ ์ƒ์„ฑ๋œ ์ฝ˜ํ…์ธ  +- ๊ด‘๋ฒ”์œ„ํ•œ TODO ๋ฆฌ์ŠคํŠธ + +### 7. ๊ฒ€์ฆ ์ฒดํฌ๋ฆฌ์ŠคํŠธ + +์ตœ์ข… ํ™•์ •ํ•˜๊ธฐ ์ „์— ํ™•์ธํ•˜์„ธ์š”: +- [ ] 300์ค„ ๋ฏธ๋งŒ์ธ๊ฐ€? (100์ค„ ๋ฏธ๋งŒ ๊ถŒ์žฅ) +- [ ] ๋ชจ๋“  ์ค„์ด ๋ชจ๋“  ์„ธ์…˜์— ๋ณดํŽธ์ ์œผ๋กœ ์ ์šฉ๋˜๋Š”๊ฐ€? +- [ ] ์Šคํƒ€์ผ/ํฌ๋งทํŒ… ๊ทœ์น™์ด ์—†๋Š”๊ฐ€? +- [ ] ์ฝ”๋“œ ์Šค๋‹ˆํŽซ์ด ์—†๋Š”๊ฐ€? (ํŒŒ์ผ ์ฐธ์กฐ ์‚ฌ์šฉ) +- [ ] ๋ช…๋ น์–ด๋“ค์ด ์‹ค์ œ๋กœ ์ž‘๋™ํ•˜๋Š”์ง€ ๊ฒ€์ฆ๋˜์—ˆ๋Š”๊ฐ€? +- [ ] ๋ณต์žกํ•œ ํ”„๋กœ์ ํŠธ์˜ ๊ฒฝ์šฐ ์ ์ง„์  ๊ณต๊ฐœ ์ „๋žต์„ ์‚ฌ์šฉํ–ˆ๋Š”๊ฐ€? +- [ ] ์น˜๋ช…์ ์ธ ์ฃผ์˜ ์‚ฌํ•ญ๋“ค์ด ๋ฌธ์„œํ™”๋˜์—ˆ๋Š”๊ฐ€? +- [ ] README.md์™€ ์ค‘๋ณต๋˜๋Š” ๋‚ด์šฉ์ด ์—†๋Š”๊ฐ€? + +## ์ถœ๋ ฅ ํ˜•์‹ + +### `create` ๋˜๋Š” ๊ธฐ๋ณธ๊ฐ’์˜ ๊ฒฝ์šฐ: + +1. ํ”„๋กœ์ ํŠธ๋ฅผ ๋ถ„์„ํ•ฉ๋‹ˆ๋‹ค. +2. ์œ„ ๊ตฌ์กฐ์— ๋”ฐ๋ผ CLAUDE.md ์ดˆ์•ˆ์„ ์ž‘์„ฑํ•ฉ๋‹ˆ๋‹ค. +3. ๊ฒ€ํ† ๋ฅผ ์œ„ํ•ด ์ดˆ์•ˆ์„ ์ œ์‹œํ•ฉ๋‹ˆ๋‹ค. +4. ์Šน์ธ ํ›„ ์ ์ ˆํ•œ ์œ„์น˜์— ํŒŒ์ผ๋กœ ๊ธฐ๋กํ•ฉ๋‹ˆ๋‹ค. + +### `update` ์ธ ๊ฒฝ์šฐ: +1. ๊ธฐ์กด CLAUDE.md๋ฅผ ์ฝ์Šต๋‹ˆ๋‹ค. +2. ๋ฒ ์ŠคํŠธ ํ”„๋ž™ํ‹ฐ์Šค๋ฅผ ๊ธฐ์ค€์œผ๋กœ ์ ๊ฒ€(Audit)ํ•ฉ๋‹ˆ๋‹ค. +3. ๋‹ค์Œ ์‚ฌํ•ญ์„ ์‹๋ณ„ํ•ฉ๋‹ˆ๋‹ค: + - ์ œ๊ฑฐํ•  ์ฝ˜ํ…์ธ  (์Šคํƒ€์ผ ๊ทœ์น™, ์ฝ”๋“œ ์Šค๋‹ˆํŽซ, ํŠน์ • ์ž‘์—…์šฉ ์ง€์นจ) + - ์••์ถ•ํ•  ์ฝ˜ํ…์ธ  + - ๋ˆ„๋ฝ๋œ ํ•„์ˆ˜ ์ •๋ณด +4. ๊ฒ€ํ† ๋ฅผ ์œ„ํ•ด ๋ณ€๊ฒฝ ์‚ฌํ•ญ์„ ์ œ์‹œํ•ฉ๋‹ˆ๋‹ค. +5. ์Šน์ธ ํ›„ ๋ณ€๊ฒฝ ์‚ฌํ•ญ์„ ์ ์šฉํ•ฉ๋‹ˆ๋‹ค. + +### `audit`์ธ ๊ฒฝ์šฐ: +1. ๊ธฐ์กด CLAUDE.md๋ฅผ ์ฝ์Šต๋‹ˆ๋‹ค. +2. ๋‹ค์Œ ๋‚ด์šฉ์ด ํฌํ•จ๋œ ๋ณด๊ณ ์„œ๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค: + - ํ˜„์žฌ ์ค„ ์ˆ˜ vs ๋ชฉํ‘œ ์ค„ ์ˆ˜ + - ๋ณดํŽธ์ ์œผ๋กœ ์ ์šฉ ๊ฐ€๋Šฅํ•œ ์ฝ˜ํ…์ธ ์˜ ๋น„์œจ + - ๋ฐœ๊ฒฌ๋œ ์•ˆํ‹ฐ ํŒจํ„ด ๋ชฉ๋ก + - ๊ฐœ์„ ์„ ์œ„ํ•œ ๊ถŒ์žฅ ์‚ฌํ•ญ +3. ํŒŒ์ผ์„ ์ˆ˜์ •ํ•˜์ง€ ์•Š๊ณ , ์˜ค์ง ๋ณด๊ณ ๋งŒ ์ˆ˜ํ–‰ํ•ฉ๋‹ˆ๋‹ค. + + +## AGENTS.md ์ฒ˜๋ฆฌ + +์‚ฌ์šฉ์ž๊ฐ€ AGENTS.md ์ƒ์„ฑ/์—…๋ฐ์ดํŠธ๋ฅผ ์š”์ฒญํ•˜๋Š” ๊ฒฝ์šฐ: + +AGENTS.md๋Š” ํŠนํ™”๋œ ์—์ด์ „ํŠธ์˜ ํ–‰๋™์„ ์ •์˜ํ•˜๋Š” ๋ฐ ์‚ฌ์šฉ๋ฉ๋‹ˆ๋‹ค. ํ”„๋กœ์ ํŠธ์˜ ์ „๋ฐ˜์ ์ธ ๋งฅ๋ฝ์„ ๋‹ค๋ฃจ๋Š” CLAUDE.md์™€ ๋‹ฌ๋ฆฌ, AGENTS.md๋Š” ๋‹ค์Œ์„ ์ •์˜ํ•ฉ๋‹ˆ๋‹ค: +- ์ปค์Šคํ…€ ์—์ด์ „ํŠธ์˜ ์—ญํ•  ๋ฐ ๊ธฐ๋Šฅ +- ์—์ด์ „ํŠธ ์ „์šฉ ์ง€์นจ ๋ฐ ์ œ์•ฝ ์กฐ๊ฑด +- ๋ฉ€ํ‹ฐ ์—์ด์ „ํŠธ ์‹œ๋‚˜๋ฆฌ์˜ค๋ฅผ ์œ„ํ•œ ์›Œํฌํ”Œ๋กœ์šฐ ์ •์˜ + +์œ ์‚ฌํ•œ ์›์น™์„ ์ ์šฉํ•ฉ๋‹ˆ๋‹ค: +- ํ•ต์‹ฌ์— ์ง‘์ค‘ํ•˜๊ณ  ๊ฐ„๊ฒฐํ•˜๊ฒŒ ์œ ์ง€ํ•  ๊ฒƒ +- ์ ์ง„์  ๊ณต๊ฐœ ์ „๋žต์„ ์‚ฌ์šฉํ•  ๊ฒƒ +- ์ฝ˜ํ…์ธ ๋ฅผ ์ง์ ‘ ์ž„๋ฒ ๋”ฉ(ํฌํ•จ)ํ•˜๋Š” ๋Œ€์‹  ์™ธ๋ถ€ ๋ฌธ์„œ๋ฅผ ์ฐธ์กฐํ•  ๊ฒƒ + +## ์ฐธ๊ณ  ์‚ฌํ•ญ + +- ๋ช…๋ น์–ด๋ฅผ ํฌํ•จํ•˜๊ธฐ ์ „์— ํ•ญ์ƒ ์‹ค์ œ๋กœ ์ž‘๋™ํ•˜๋Š”์ง€ ๊ฒ€์ฆํ•˜์„ธ์š”. +- ํ™•์‹คํ•˜์ง€ ์•Š์„ ๋•Œ๋Š” ์ œ์™ธํ•˜์„ธ์š”. ์ ์„์ˆ˜๋ก ์ข‹์Šต๋‹ˆ๋‹ค. +- ์‹œ์Šคํ…œ ๋ฆฌ๋งˆ์ธ๋”๋Š” Claude์—๊ฒŒ CLAUDE.md๊ฐ€ "๊ด€๋ จ์ด ์žˆ์„ ์ˆ˜๋„ ์žˆ๊ณ  ์—†์„ ์ˆ˜๋„ ์žˆ๋‹ค"๊ณ  ์•Œ๋ ค์ค๋‹ˆ๋‹ค. ๋…ธ์ด์ฆˆ(๋ถˆํ•„์š”ํ•œ ์ •๋ณด)๊ฐ€ ๋งŽ์•„์งˆ์ˆ˜๋ก AI๊ฐ€ ์ด๋ฅผ ๋ฌด์‹œํ•  ํ™•๋ฅ ์ด ๋†’์•„์ง‘๋‹ˆ๋‹ค. +- ๋ชจ๋…ธ๋ ˆํฌ๋Š” ๋ช…ํ™•ํ•œ WHAT/WHY/HOW ๊ตฌ์กฐ๋ฅผ ๊ฐ€์งˆ ๋•Œ ๊ฐ€์žฅ ํฐ ์ด์ ์„ ์–ป์Šต๋‹ˆ๋‹ค. +- ๋””๋ ‰ํ† ๋ฆฌ ํŠน์ • CLAUDE.md ํŒŒ์ผ์€ ํ›จ์”ฌ ๋” ํ•ต์‹ฌ์—๋งŒ ์ง‘์ค‘ํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. diff --git a/ko/03-skills/code-review-specialist/SKILL.md b/ko/03-skills/code-review-specialist/SKILL.md new file mode 100644 index 00000000..85ee7afe --- /dev/null +++ b/ko/03-skills/code-review-specialist/SKILL.md @@ -0,0 +1,78 @@ +name: code-review-specialist +description: ๋ณด์•ˆ, ์„ฑ๋Šฅ ๋ฐ ํ’ˆ์งˆ ๋ถ„์„์„ ํฌํ•จํ•˜๋Š” ํฌ๊ด„์ ์ธ ์ฝ”๋“œ ๊ฒ€ํ† . ์‚ฌ์šฉ์ž๊ฐ€ ์ฝ”๋“œ ๊ฒ€ํ† , ์ฝ”๋“œ ํ’ˆ์งˆ ๋ถ„์„, ํ’€ ๋ฆฌํ€˜์ŠคํŠธ ํ‰๊ฐ€๋ฅผ ์š”์ฒญํ•˜๊ฑฐ๋‚˜ ์ฝ”๋“œ ๊ฒ€ํ† , ๋ณด์•ˆ ๋ถ„์„, ์„ฑ๋Šฅ ์ตœ์ ํ™”๋ฅผ ์–ธ๊ธ‰ํ•  ๋•Œ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +--- + +# ์ฝ”๋“œ ๊ฒ€ํ†  ์Šคํ‚ฌ + +์ด ์Šคํ‚ฌ์€ ๋‹ค์Œ ์‚ฌํ•ญ์— ์ดˆ์ ์„ ๋งž์ถ˜ ํฌ๊ด„์ ์ธ ์ฝ”๋“œ ๊ฒ€ํ†  ๊ธฐ๋Šฅ์„ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค: + +1. **๋ณด์•ˆ ๋ถ„์„** + - ์ธ์ฆ/๊ถŒํ•œ ๋ถ€์—ฌ ๋ฌธ์ œ + - ๋ฐ์ดํ„ฐ ๋…ธ์ถœ ์œ„ํ—˜ + - ์ธ์ ์…˜ ์ทจ์•ฝ์  + - ์•”ํ˜ธํ™” ์•ฝ์  + - ๋ฏผ๊ฐํ•œ ๋ฐ์ดํ„ฐ ๋กœ๊น… + +2. **์„ฑ๋Šฅ ๊ฒ€ํ† ** + - ์•Œ๊ณ ๋ฆฌ์ฆ˜ ํšจ์œจ์„ฑ (๋น… O ๋ถ„์„) + - ๋ฉ”๋ชจ๋ฆฌ ์ตœ์ ํ™” + - ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ์ฟผ๋ฆฌ ์ตœ์ ํ™” + - ์บ์‹ฑ ๊ธฐํšŒ + - ๋™์‹œ์„ฑ ๋ฌธ์ œ + +3. **์ฝ”๋“œ ํ’ˆ์งˆ** + - SOLID ์›์น™ + - ๋””์ž์ธ ํŒจํ„ด + - ๋ช…๋ช… ๊ทœ์น™ + - ๋ฌธ์„œํ™” + - ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€ + +4. **์œ ์ง€๋ณด์ˆ˜์„ฑ** + - ์ฝ”๋“œ ๊ฐ€๋…์„ฑ + - ํ•จ์ˆ˜ ํฌ๊ธฐ (50์ค„ ๋ฏธ๋งŒ์ด์–ด์•ผ ํ•จ) + - ์ˆœํ™˜ ๋ณต์žก๋„ + - ์˜์กด์„ฑ ๊ด€๋ฆฌ + - ํƒ€์ž… ์•ˆ์ •์„ฑ + +## ์ฐธ์กฐ ํŒŒ์ผ + +์ด ์Šคํ‚ฌ์—๋Š” ๊ฒ€ํ† ๋ฅผ ์ˆ˜ํ–‰ํ•  ๋•Œ ์ฝ์–ด์•ผ ํ•˜๋Š” ์ง€์› ํŒŒ์ผ์ด ํฌํ•จ๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค: + +- **`templates/review-checklist.md`** โ€” ๋ณด์•ˆ, ์„ฑ๋Šฅ, ํ’ˆ์งˆ ๋ฐ ํ…Œ์ŠคํŠธ๋ฅผ ๋‹ค๋ฃจ๋Š” ๊ตฌ์กฐํ™”๋œ ์ฒดํฌ๋ฆฌ์ŠคํŠธ. ์ด ํŒŒ์ผ์„ ์ฝ๊ณ  ๊ฒ€ํ†  ์ค‘ ์–ด๋–ค ๋ฒ”์ฃผ๋„ ๋†“์น˜์ง€ ์•Š๋„๋ก ๊ฐ€์ด๋“œ๋กœ ์‚ฌ์šฉํ•˜์„ธ์š”. +- **`templates/finding-template.md`** โ€” ์‹ฌ๊ฐ๋„, ์œ„์น˜, ์ฝ”๋“œ ์˜ˆ์ œ ๋ฐ ์˜ํ–ฅ ๋ถ„์„์„ ํฌํ•จํ•˜์—ฌ ๊ฐœ๋ณ„ ๋ฐœ๊ฒฌ ์‚ฌํ•ญ์„ ๋ฌธ์„œํ™”ํ•˜๊ธฐ ์œ„ํ•œ ํ‘œ์ค€ ํ…œํ”Œ๋ฆฟ. ์ด ํŒŒ์ผ์„ ์ฝ๊ณ  ๋ฌธ์ œ ๋ณด๊ณ  ์‹œ ํ•ด๋‹น ํ˜•์‹์„ ์‚ฌ์šฉํ•˜์„ธ์š”. +- **`scripts/analyze-metrics.py`** โ€” ์ฝ”๋“œ ๋ฉ”ํŠธ๋ฆญ(ํ•จ์ˆ˜ ์ˆ˜, ํด๋ž˜์Šค ์ˆ˜, ํ‰๊ท  ๋ผ์ธ ๊ธธ์ด, ๋ณต์žก๋„ ์ ์ˆ˜)์„ ๊ณ„์‚ฐํ•˜๋Š” Python ์Šคํฌ๋ฆฝํŠธ. ์ •๋Ÿ‰์  ๋ฐ์ดํ„ฐ๋ฅผ ์ˆ˜์ง‘ํ•˜๊ธฐ ์œ„ํ•ด ๊ฒ€ํ†  ์ค‘์ธ ํŒŒ์ผ์— ๋Œ€ํ•ด ์‹คํ–‰ํ•˜์„ธ์š”. +- **`scripts/compare-complexity.py`** โ€” ํŒŒ์ผ์˜ ๋‘ ๋ฒ„์ „ ๊ฐ„์˜ ์ˆœํ™˜ ๋ณต์žก๋„์™€ ์ธ์ง€ ๋ณต์žก๋„๋ฅผ ๋น„๊ตํ•˜๋Š” Python ์Šคํฌ๋ฆฝํŠธ. ๋ฆฌํŒฉํ„ฐ๋ง ๋ณ€๊ฒฝ ์‚ฌํ•ญ์„ ๊ฒ€ํ† ํ•  ๋•Œ ์ด์ „ ๋ฒ„์ „๊ณผ ์ดํ›„ ๋ฒ„์ „์„ ์‚ฌ์šฉํ•˜์—ฌ ์‹คํ–‰ํ•˜์„ธ์š”. + +## ๊ฒ€ํ†  ํ…œํ”Œ๋ฆฟ + +๊ฒ€ํ† ๋œ ๊ฐ ์ฝ”๋“œ์— ๋Œ€ํ•ด ๋‹ค์Œ์„ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค: + +### ์š”์•ฝ +- ์ „๋ฐ˜์ ์ธ ํ’ˆ์งˆ ํ‰๊ฐ€ (1-5์ ) +- ์ฃผ์š” ๋ฐœ๊ฒฌ ์‚ฌํ•ญ ์ˆ˜ +- ๊ถŒ์žฅ ์šฐ์„ ์ˆœ์œ„ ์˜์—ญ + +### ์น˜๋ช…์ ์ธ ๋ฌธ์ œ (์žˆ๋Š” ๊ฒฝ์šฐ) +- **๋ฌธ์ œ**: ๋ช…ํ™•ํ•œ ์„ค๋ช… +- **์œ„์น˜**: ํŒŒ์ผ ๋ฐ ์ค„ ๋ฒˆํ˜ธ +- **์˜ํ–ฅ**: ์ด๊ฒƒ์ด ์ค‘์š”ํ•œ ์ด์œ  +- **์‹ฌ๊ฐ๋„**: ์‹ฌ๊ฐ/๋†’์Œ/์ค‘๊ฐ„ +- **ํ•ด๊ฒฐ์ฑ…**: ์ฝ”๋“œ ์˜ˆ์ œ + +### ์นดํ…Œ๊ณ ๋ฆฌ๋ณ„ ๋ฐœ๊ฒฌ ์‚ฌํ•ญ + +#### ๋ณด์•ˆ (๋ฌธ์ œ๊ฐ€ ๋ฐœ๊ฒฌ๋œ ๊ฒฝ์šฐ) +๋ณด์•ˆ ์ทจ์•ฝ์  ๋ชฉ๋ก๊ณผ ์˜ˆ์‹œ + +#### ์„ฑ๋Šฅ (๋ฌธ์ œ๊ฐ€ ๋ฐœ๊ฒฌ๋œ ๊ฒฝ์šฐ) +์„ฑ๋Šฅ ๋ฌธ์ œ ๋ชฉ๋ก๊ณผ ๋ณต์žก๋„ ๋ถ„์„ + +#### ํ’ˆ์งˆ (๋ฌธ์ œ๊ฐ€ ๋ฐœ๊ฒฌ๋œ ๊ฒฝ์šฐ) +์ฝ”๋“œ ํ’ˆ์งˆ ๋ฌธ์ œ ๋ชฉ๋ก๊ณผ ๋ฆฌํŒฉํ„ฐ๋ง ์ œ์•ˆ + +#### ์œ ์ง€๋ณด์ˆ˜์„ฑ (๋ฌธ์ œ๊ฐ€ ๋ฐœ๊ฒฌ๋œ ๊ฒฝ์šฐ) +์œ ์ง€๋ณด์ˆ˜์„ฑ ๋ฌธ์ œ ๋ชฉ๋ก๊ณผ ๊ฐœ์„  ์‚ฌํ•ญ + +## ๋ฒ„์ „ ํžˆ์Šคํ† ๋ฆฌ + +- v1.0.0 (2024-12-10): ๋ณด์•ˆ, ์„ฑ๋Šฅ, ํ’ˆ์งˆ ๋ฐ ์œ ์ง€๋ณด์ˆ˜์„ฑ ๋ถ„์„์„ ํฌํ•จํ•œ ์ดˆ๊ธฐ ๋ฆด๋ฆฌ์Šค diff --git a/ko/03-skills/code-review-specialist/scripts/analyze-metrics.py b/ko/03-skills/code-review-specialist/scripts/analyze-metrics.py new file mode 100644 index 00000000..e294973f --- /dev/null +++ b/ko/03-skills/code-review-specialist/scripts/analyze-metrics.py @@ -0,0 +1,35 @@ +#!/usr/bin/env python3 +import re +import sys + + +def analyze_code_metrics(code): + """Analyze code for common metrics.""" + + # Count functions + functions = len(re.findall(r"^def\s+\w+", code, re.MULTILINE)) + + # Count classes + classes = len(re.findall(r"^class\s+\w+", code, re.MULTILINE)) + + # Average line length + lines = code.split("\n") + avg_length = sum(len(l) for l in lines) / len(lines) if lines else 0 + + # Estimate complexity + complexity = len(re.findall(r"\b(if|elif|else|for|while|and|or)\b", code)) + + return { + "functions": functions, + "classes": classes, + "avg_line_length": avg_length, + "complexity_score": complexity, + } + + +if __name__ == "__main__": + with open(sys.argv[1]) as f: + code = f.read() + metrics = analyze_code_metrics(code) + for key, value in metrics.items(): + print(f"{key}: {value:.2f}") diff --git a/ko/03-skills/code-review-specialist/scripts/compare-complexity.py b/ko/03-skills/code-review-specialist/scripts/compare-complexity.py new file mode 100644 index 00000000..d4aba232 --- /dev/null +++ b/ko/03-skills/code-review-specialist/scripts/compare-complexity.py @@ -0,0 +1,174 @@ +#!/usr/bin/env python3 +""" +Compare cyclomatic complexity of code before and after changes. +Helps identify if refactoring actually simplifies code structure. +""" + +import re +import sys + + +class ComplexityAnalyzer: + """Analyze code complexity metrics.""" + + def __init__(self, code: str): + self.code = code + self.lines = code.split("\n") + + def calculate_cyclomatic_complexity(self) -> int: + """ + Calculate cyclomatic complexity using McCabe's method. + Count decision points: if, elif, else, for, while, except, and, or + """ + complexity = 1 # Base complexity + + # Count decision points + decision_patterns = [ + r"\bif\b", + r"\belif\b", + r"\bfor\b", + r"\bwhile\b", + r"\bexcept\b", + r"\band\b(?!$)", + r"\bor\b(?!$)", + ] + + for pattern in decision_patterns: + matches = re.findall(pattern, self.code) + complexity += len(matches) + + return complexity + + def calculate_cognitive_complexity(self) -> int: + """ + Calculate cognitive complexity - how hard is it to understand? + Based on nesting depth and control flow. + """ + cognitive = 0 + nesting_depth = 0 + + for line in self.lines: + # Track nesting depth + if re.search(r"^\s*(if|for|while|def|class|try)\b", line): + nesting_depth += 1 + cognitive += nesting_depth + elif re.search(r"^\s*(elif|else|except|finally)\b", line): + cognitive += nesting_depth + + # Reduce nesting when unindenting + if line and not line[0].isspace(): + nesting_depth = 0 + + return cognitive + + def calculate_maintainability_index(self) -> float: + """ + Maintainability Index ranges from 0-100. + > 85: Excellent + > 65: Good + > 50: Fair + < 50: Poor + """ + lines = len(self.lines) + cyclomatic = self.calculate_cyclomatic_complexity() + cognitive = self.calculate_cognitive_complexity() + + # Simplified MI calculation + mi = ( + 171 + - 5.2 * (cyclomatic / lines) + - 0.23 * (cognitive) + - 16.2 * (lines / 1000) + ) + + return max(0, min(100, mi)) + + def get_complexity_report(self) -> dict: + """Generate comprehensive complexity report.""" + return { + "cyclomatic_complexity": self.calculate_cyclomatic_complexity(), + "cognitive_complexity": self.calculate_cognitive_complexity(), + "maintainability_index": round(self.calculate_maintainability_index(), 2), + "lines_of_code": len(self.lines), + "avg_line_length": round( + sum(len(l) for l in self.lines) / len(self.lines), 2 + ) + if self.lines + else 0, + } + + +def compare_files(before_file: str, after_file: str) -> None: + """Compare complexity metrics between two code versions.""" + + with open(before_file) as f: + before_code = f.read() + + with open(after_file) as f: + after_code = f.read() + + before_analyzer = ComplexityAnalyzer(before_code) + after_analyzer = ComplexityAnalyzer(after_code) + + before_metrics = before_analyzer.get_complexity_report() + after_metrics = after_analyzer.get_complexity_report() + + print("=" * 60) + print("CODE COMPLEXITY COMPARISON") + print("=" * 60) + + print("\nBEFORE:") + print(f" Cyclomatic Complexity: {before_metrics['cyclomatic_complexity']}") + print(f" Cognitive Complexity: {before_metrics['cognitive_complexity']}") + print(f" Maintainability Index: {before_metrics['maintainability_index']}") + print(f" Lines of Code: {before_metrics['lines_of_code']}") + print(f" Avg Line Length: {before_metrics['avg_line_length']}") + + print("\nAFTER:") + print(f" Cyclomatic Complexity: {after_metrics['cyclomatic_complexity']}") + print(f" Cognitive Complexity: {after_metrics['cognitive_complexity']}") + print(f" Maintainability Index: {after_metrics['maintainability_index']}") + print(f" Lines of Code: {after_metrics['lines_of_code']}") + print(f" Avg Line Length: {after_metrics['avg_line_length']}") + + print("\nCHANGES:") + cyclomatic_change = ( + after_metrics["cyclomatic_complexity"] - before_metrics["cyclomatic_complexity"] + ) + cognitive_change = ( + after_metrics["cognitive_complexity"] - before_metrics["cognitive_complexity"] + ) + mi_change = ( + after_metrics["maintainability_index"] - before_metrics["maintainability_index"] + ) + loc_change = after_metrics["lines_of_code"] - before_metrics["lines_of_code"] + + print(f" Cyclomatic Complexity: {cyclomatic_change:+d}") + print(f" Cognitive Complexity: {cognitive_change:+d}") + print(f" Maintainability Index: {mi_change:+.2f}") + print(f" Lines of Code: {loc_change:+d}") + + print("\nASSESSMENT:") + if mi_change > 0: + print(" โœ… Code is MORE maintainable") + elif mi_change < 0: + print(" โš ๏ธ Code is LESS maintainable") + else: + print(" โžก๏ธ Maintainability unchanged") + + if cyclomatic_change < 0: + print(" โœ… Complexity DECREASED") + elif cyclomatic_change > 0: + print(" โš ๏ธ Complexity INCREASED") + else: + print(" โžก๏ธ Complexity unchanged") + + print("=" * 60) + + +if __name__ == "__main__": + if len(sys.argv) != 3: + print("Usage: python compare-complexity.py ") + sys.exit(1) + + compare_files(sys.argv[1], sys.argv[2]) diff --git a/ko/03-skills/code-review-specialist/templates/finding-template.md b/ko/03-skills/code-review-specialist/templates/finding-template.md new file mode 100644 index 00000000..56c40f61 --- /dev/null +++ b/ko/03-skills/code-review-specialist/templates/finding-template.md @@ -0,0 +1,111 @@ +# Code Review Finding Template + +์ฝ”๋“œ ๋ฆฌ๋ทฐ ์ค‘ ๋ฐœ๊ฒฌ๋œ ๊ฐ ๋ฌธ์ œ๋ฅผ ๊ธฐ๋กํ•  ๋•Œ ์ด ํ…œํ”Œ๋ฆฟ์„ ์‚ฌ์šฉํ•˜์„ธ์š”. + +--- + +## Issue: [TITLE] + +### Severity +- [ ] Critical (๋ฐฐํฌ ์ฐจ๋‹จ) +- [ ] High (๋จธ์ง€ ์ „ ์ˆ˜์ • ํ•„์š”) +- [ ] Medium (์กฐ๋งŒ๊ฐ„ ์ˆ˜์ • ํ•„์š”) +- [ ] Low (์ˆ˜์ •ํ•˜๋ฉด ์ข‹์Œ) +### Category +- [ ] Security +- [ ] Performance +- [ ] Code Quality +- [ ] Maintainability +- [ ] Testing +- [ ] Design Pattern +- [ ] Documentation + +### ์œ„์น˜ +**File:** `src/components/UserCard.tsx` + +**Lines:** 45-52 + +**Function/Method:** `renderUserDetails()` + +### ๋ฌธ์ œ ์„ค๋ช… + +**What:** ๋ฌธ์ œ๊ฐ€ ๋ฌด์—‡์ธ์ง€ ์„ค๋ช…ํ•ฉ๋‹ˆ๋‹ค. + +**Why it matters:** ์˜ํ–ฅ๋„์™€ ์ด ๋ฌธ์ œ๋ฅผ ์™œ ์ˆ˜์ •ํ•ด์•ผ ํ•˜๋Š”์ง€ ์„ค๋ช…ํ•ฉ๋‹ˆ๋‹ค. + +**Current behavior:** ๋ฌธ์ œ๊ฐ€ ๋˜๋Š” ์ฝ”๋“œ๋‚˜ ๋™์ž‘์„ ๋ณด์—ฌ์ค๋‹ˆ๋‹ค. + +**Expected behavior:** ๋Œ€์‹  ์–ด๋–ค ๋™์ž‘์ด ์ผ์–ด๋‚˜์•ผ ํ•˜๋Š”์ง€ ์„ค๋ช…ํ•ฉ๋‹ˆ๋‹ค. + +### ์ฝ”๋“œ ์˜ˆ์‹œ + +#### ํ˜„์žฌ (๋ฌธ์ œ๊ฐ€ ๋˜๋Š” ์ฝ”๋“œ) + +```typescript +// Shows the N+1 query problem +const users = fetchUsers(); +users.forEach(user => { + const posts = fetchUserPosts(user.id); // Query per user! + renderUserPosts(posts); +}); +``` + +#### ์ œ์•ˆ๋œ ํ•ด๊ฒฐ ๋ฐฉ๋ฒ• + +```typescript +// Optimized with JOIN query +const usersWithPosts = fetchUsersWithPosts(); +usersWithPosts.forEach(({ user, posts }) => { + renderUserPosts(posts); +}); +``` + +### ์˜ํ–ฅ๋„ ๋ถ„์„ + + +| ์ธก๋ฉด | ์˜ํ–ฅ | ์‹ฌ๊ฐ์„ฑ | +|--------|--------|----------| +| ์„ฑ๋Šฅ | ์œ ์ € 20๋ช…๋‹น 100๊ฐœ ์ด์ƒ์˜ ์ฟผ๋ฆฌ ๋ฐœ์ƒ | ๋†’์Œ | +| ์‚ฌ์šฉ์ž ๊ฒฝํ—˜ | ๋Š๋ฆฐ ํŽ˜์ด์ง€ ๋กœ๋“œ | ๋†’์Œ | +| ํ™•์žฅ์„ฑ | ๋Œ€๊ทœ๋ชจ ํ™˜๊ฒฝ์—์„œ ์‹œ์Šคํ…œ ์ค‘๋‹จ ๋ฐœ์ƒ | ์น˜๋ช…์  | +| ์œ ์ง€๋ณด์ˆ˜์„ฑ | ๋””๋ฒ„๊น…์ด ์–ด๋ ค์›€ | ์ค‘๊ฐ„ | + +### ๊ด€๋ จ ์ด์Šˆ + +- `AdminUserList.tsx` 120๋ฒˆ ์ค„์˜ ์œ ์‚ฌํ•œ ๋ฌธ์ œ +- ๊ด€๋ จ PR: #456 +- ๊ด€๋ จ ์ด์Šˆ: #789 + +### ์ถ”๊ฐ€ ์ž๋ฃŒ + +- [N+1 Query Problem](https://en.wikipedia.org/wiki/N%2B1_problem) +- [Database Join Documentation](https://docs.example.com/joins) + +### ๋ฆฌ๋ทฐ์–ด ๋…ธํŠธ +- ์ด ์ฝ”๋“œ๋ฒ ์ด์Šค์—์„œ ํ”ํžˆ ๋ฐœ์ƒํ•˜๋Š” ํŒจํ„ด์ž…๋‹ˆ๋‹ค. +- ์ด๋ฅผ ์ฝ”๋“œ ์Šคํƒ€์ผ ๊ฐ€์ด๋“œ์— ์ถ”๊ฐ€ํ•˜๋Š” ๊ฒƒ์„ ๊ณ ๋ คํ•ด ๋ณด์„ธ์š”. +- ํ—ฌํผ ํ•จ์ˆ˜๋ฅผ ๋งŒ๋“ค ๊ฐ€์น˜๊ฐ€ ์žˆ์„ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +### ์ž‘์„ฑ์ž ๋‹ต๋ณ€ (ํ”ผ๋“œ๋ฐฑ์šฉ) + +*์ฝ”๋“œ ์ž‘์„ฑ์ž๊ฐ€ ์ž‘์„ฑํ•  ๋ถ€๋ถ„:* +- [ ] ๋‹ค์Œ ์ปค๋ฐ‹์—์„œ ์ˆ˜์ • ๋ฐ˜์˜๋จ: `abc123` +- [ ] ์ˆ˜์ • ์ƒํƒœ: ์™„๋ฃŒ / ์ง„ํ–‰ ์ค‘ / ๋…ผ์˜ ํ•„์š” +- [ ] ์งˆ๋ฌธ ๋ฐ ์šฐ๋ ค ์‚ฌํ•ญ: (์„ค๋ช…) + + +--- + +## ๋ฐœ๊ฒฌ ํ†ต๊ณ„ (๋ฆฌ๋ทฐ์–ด์šฉ) + +์—ฌ๋Ÿฌ ๊ฐœ์˜ ๋ฐœ๊ฒฌ ์‚ฌํ•ญ์„ ๋ฆฌ๋ทฐํ•  ๋•Œ ๋‹ค์Œ์„ ์ถ”์ ํ•˜์„ธ์š”: + +- **์ด ๋ฐœ๊ฒฌ๋œ ๋ฌธ์ œ ์ˆ˜:** X +- **์น˜๋ช…์ :** X +- **๋†’์Œ:** X +- **์ค‘๊ฐ„:** X +- **๋‚ฎ์Œ:** X + +**๊ถŒ์žฅ ์‚ฌํ•ญ**: โœ… ์Šน์ธ / โš ๏ธ ๋ณ€๊ฒฝ ์š”์ฒญ / ๐Ÿ”„ ๋…ผ์˜ ํ•„์š” + +**์ „๋ฐ˜์ ์ธ ์ฝ”๋“œ ํ’ˆ์งˆ**: ๋ณ„ 1-5๊ฐœ diff --git a/ko/03-skills/code-review-specialist/templates/review-checklist.md b/ko/03-skills/code-review-specialist/templates/review-checklist.md new file mode 100644 index 00000000..f4ccb062 --- /dev/null +++ b/ko/03-skills/code-review-specialist/templates/review-checklist.md @@ -0,0 +1,47 @@ +# Code Review Checklist + +## Security Checklist +- [ ] ํ•˜๋“œ์ฝ”๋”ฉ๋œ ์ž๊ฒฉ ์ฆ๋ช…์ด๋‚˜ ๋น„๋ฐ€ ํ‚ค๊ฐ€ ์—†์„ ๊ฒƒ +- [ ] ๋ชจ๋“  ์‚ฌ์šฉ์ž ์ž…๋ ฅ์— ๋Œ€ํ•ด ์ž…๋ ฅ๊ฐ’ ๊ฒ€์ฆ์„ ์ˆ˜ํ–‰ํ•  ๊ฒƒ +- [ ] SQL ์ธ์ ์…˜ ๋ฐฉ์ง€ (ํŒŒ๋ผ๋ฏธํ„ฐํ™”๋œ ์ฟผ๋ฆฌ ์‚ฌ์šฉ) +- [ ] ์ƒํƒœ๋ฅผ ๋ณ€๊ฒฝํ•˜๋Š” ์ž‘์—…์— CSRF ๋ฐฉ์ง€ ์ ์šฉ +- [ ] ์ ์ ˆํ•œ ์ด์Šค์ผ€์ดํ”„ ์ฒ˜๋ฆฌ๋ฅผ ํ†ตํ•ด XSS ๋ฐฉ์ง€ +- [ ] ๋ณดํ˜ธ๋œ ์—”๋“œํฌ์ธํŠธ์— ๋Œ€ํ•ด ์ธ์ฆ ํ™•์ธ ์ ˆ์ฐจ๋ฅผ ๊ฑฐ์น  ๊ฒƒ +- [ ] ๋ฆฌ์†Œ์Šค์— ๋Œ€ํ•œ ์ธ๊ฐ€ ํ™•์ธ ์ ˆ์ฐจ๋ฅผ ๊ฑฐ์น  ๊ฒƒ +- [ ] ์•ˆ์ „ํ•œ ๋น„๋ฐ€๋ฒˆํ˜ธ ํ•ด์‹ฑ ์•Œ๊ณ ๋ฆฌ์ฆ˜(bcrypt, argon2)์„ ์‚ฌ์šฉํ•  ๊ฒƒ +- [ ] ๋กœ๊ทธ์— ๋ฏผ๊ฐํ•œ ๋ฐ์ดํ„ฐ๋ฅผ ๋‚จ๊ธฐ์ง€ ์•Š์„ ๊ฒƒ +- [ ] HTTPS ์—ฐ๊ฒฐ์„ ๊ฐ•์ œํ•  ๊ฒƒ + +## Performance Checklist +- [ ] N+1 ์ฟผ๋ฆฌ๊ฐ€ ์—†์„ ๊ฒƒ +- [ ] ์ธ๋ฑ์Šค๋ฅผ ์ ์ ˆํ•˜๊ฒŒ ํ™œ์šฉํ•  ๊ฒƒ +- [ ] ์ด์ ์ด ์žˆ๋Š” ๊ณณ์— ์บ์‹ฑ์„ ๊ตฌํ˜„ํ•  ๊ฒƒ +- [ ] ๋ฉ”์ธ ์Šค๋ ˆ๋“œ์—์„œ ๋ธ”๋กœํ‚น ์ž‘์—…์ด ๋ฐœ์ƒํ•˜์ง€ ์•Š๋„๋ก ํ•  ๊ฒƒ +- [ ] async/await๊ฐ€ ์˜ฌ๋ฐ”๋ฅด๊ฒŒ ์‚ฌ์šฉ๋˜์—ˆ์„ ๊ฒƒ +- [ ] ๋Œ€์šฉ๋Ÿ‰ ๋ฐ์ดํ„ฐ ์„ธํŠธ์— ํŽ˜์ด์ง€๋„ค์ด์…˜์„ ์ ์šฉํ•  ๊ฒƒ +- [ ] ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ์ปค๋„ฅ์…˜ ํ’€์„ ์‚ฌ์šฉํ•  ๊ฒƒ +- [ ] ์ •๊ทœ ํ‘œํ˜„์‹์ด ์ตœ์ ํ™”๋˜์–ด ์žˆ์„ ๊ฒƒ +- [ ] ๋ถˆํ•„์š”ํ•œ ๊ฐ์ฒด ์ƒ์„ฑ์„ ์ง€์–‘ํ•  ๊ฒƒ +- [ ] ๋ฉ”๋ชจ๋ฆฌ ๋ˆ„์ˆ˜๋ฅผ ๋ฐฉ์ง€ํ•  ๊ฒƒ + +## Quality Checklist +- [ ] ํ•จ์ˆ˜์˜ ๊ธธ์ด๊ฐ€ 50์ค„ ๋ฏธ๋งŒ์ผ ๊ฒƒ +- [ ] ๋ณ€์ˆ˜๋ช…์ด ๋ช…ํ™•ํ•  ๊ฒƒ +- [ ] ์ค‘๋ณต ์ฝ”๋“œ๊ฐ€ ์—†์„ ๊ฒƒ +- [ ] ์˜ฌ๋ฐ”๋ฅธ ์—๋Ÿฌ ์ฒ˜๋ฆฌ๊ฐ€ ๋˜์–ด ์žˆ์„ ๊ฒƒ +- [ ] ์ฃผ์„์€ ๋ฌด์—‡์„(WHAT)์ด ์•„๋‹ˆ๋ผ ์™œ(WHY) ๊ทธ๋ ‡๊ฒŒ ํ–ˆ๋Š”์ง€ ์„ค๋ช…ํ•  ๊ฒƒ +- [ ] ํ”„๋กœ๋•์…˜ ํ™˜๊ฒฝ์— console.logs๋ฅผ ๋‚จ๊ธฐ์ง€ ์•Š์„ ๊ฒƒ +- [ ] ํƒ€์ž… ๊ฒ€์‚ฌ(TypeScript/JSDoc)๊ฐ€ ์ ์šฉ๋˜์–ด ์žˆ์„ ๊ฒƒ +- [ ] SOLID ์›์น™์„ ์ค€์ˆ˜ํ•  ๊ฒƒ +- [ ] ๋””์ž์ธ ํŒจํ„ด์ด ์˜ฌ๋ฐ”๋ฅด๊ฒŒ ์ ์šฉ๋˜์—ˆ์„ ๊ฒƒ +- [ ] ์ฝ”๋“œ ์ž์ฒด๋กœ ์„ค๋ช…์ด ๋˜๋Š” ์ฝ”๋“œ๋ฅผ ์ง€ํ–ฅํ•  ๊ฒƒ + +## Testing Checklist +- [ ] ์œ ๋‹› ํ…Œ์ŠคํŠธ๊ฐ€ ์ž‘์„ฑ๋˜์–ด ์žˆ์„ ๊ฒƒ +- [ ] ์˜ˆ์™ธ ์ผ€์ด์Šค๋“ค์ด ์ปค๋ฒ„๋˜์—ˆ์„ ๊ฒƒ +- [ ] ์—๋Ÿฌ ์‹œ๋‚˜๋ฆฌ์˜ค๊ฐ€ ํ…Œ์ŠคํŠธ๋˜์—ˆ์„ ๊ฒƒ +- [ ] ํ†ตํ•ฉ ํ…Œ์ŠคํŠธ๊ฐ€ ์กด์žฌํ•  ๊ฒƒ +- [ ] ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€๊ฐ€ 80% ์ด์ƒ์ผ ๊ฒƒ +- [ ] ๋ถˆ์•ˆ์ •ํ•œ ํ…Œ์ŠคํŠธ๊ฐ€ ์—†์„ ๊ฒƒ +- [ ] ์™ธ๋ถ€ ์˜์กด์„ฑ์€ ๋ชจํ‚น ์ฒ˜๋ฆฌํ•  ๊ฒƒ +- [ ] ํ…Œ์ŠคํŠธ ์ด๋ฆ„์ด ๋ช…ํ™•ํ•  ๊ฒƒ diff --git a/ko/03-skills/doc-generator/SKILL.md b/ko/03-skills/doc-generator/SKILL.md new file mode 100644 index 00000000..f921650f --- /dev/null +++ b/ko/03-skills/doc-generator/SKILL.md @@ -0,0 +1,78 @@ +--- +name: api-documentation-generator +description: ์†Œ์Šค ์ฝ”๋“œ๋กœ๋ถ€ํ„ฐ ํฌ๊ด„์ ์ด๊ณ  ์ •ํ™•ํ•œ API ๋ฌธ์„œ๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. API ๋ฌธ์„œ๋ฅผ ์ƒ์„ฑํ•˜๊ฑฐ๋‚˜ ์—…๋ฐ์ดํŠธํ•  ๋•Œ, OpenAPI ์‚ฌ์–‘์„ ์ƒ์„ฑํ•  ๋•Œ, ๋˜๋Š” ์‚ฌ์šฉ์ž๊ฐ€ API ๋ฌธ์„œ, ์—”๋“œํฌ์ธํŠธ, ๋ฌธ์„œ๋ฅผ ์–ธ๊ธ‰ํ•  ๋•Œ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +--- + +# API ๋ฌธ์„œ ์ƒ์„ฑ๊ธฐ ๊ธฐ๋Šฅ + +## ์ƒ์„ฑ ํ•ญ๋ชฉ + +- OpenAPI/Swagger ์‚ฌ์–‘ +- API ์—”๋“œํฌ์ธํŠธ ๋ฌธ์„œ +- SDK ์‚ฌ์šฉ ์˜ˆ์ œ +- ํ†ตํ•ฉ ๊ฐ€์ด๋“œ +- ์˜ค๋ฅ˜ ์ฝ”๋“œ ์ฐธ์กฐ +- ์ธ์ฆ ๊ฐ€์ด๋“œ + + +## ๋ฌธ์„œ ๊ตฌ์กฐ + +### ๊ฐ ์—”๋“œํฌ์ธํŠธ๋ณ„ + + +```markdown +## GET /api/v1/users/:id + +### ์„ค๋ช… +์ด ์—”๋“œํฌ์ธํŠธ๊ฐ€ ์ˆ˜ํ–‰ํ•˜๋Š” ์ž‘์—…์— ๋Œ€ํ•œ ๊ฐ„๋‹จํ•œ ์„ค๋ช… + +### ๋งค๊ฐœ๋ณ€์ˆ˜ + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| id | string | Yes | User ID | + +### ์‘๋‹ต + +**200 Success** +```json +{ + "id": "usr_123", + "name": "John Doe", + "email": "john@example.com", + "created_at": "2025-01-15T10:30:00Z" +} +``` + +**404 Not Found** +```json +{ + "error": "USER_NOT_FOUND", + "message": "User does not exist" +} +``` + +### ์˜ˆ์ œ + +**cURL** +```bash +curl -X GET "https://api.example.com/api/v1/users/usr_123" \ + -H "Authorization: Bearer YOUR_TOKEN" +``` + +**JavaScript** +```javascript +const user = await fetch('/api/v1/users/usr_123', { + headers: { 'Authorization': 'Bearer token' } +}).then(r => r.json()); +``` + +**Python** +```python +response = requests.get( + 'https://api.example.com/api/v1/users/usr_123', + headers={'Authorization': 'Bearer token'} +) +user = response.json() +``` +``` diff --git a/ko/03-skills/doc-generator/generate-docs.py b/ko/03-skills/doc-generator/generate-docs.py new file mode 100644 index 00000000..3a0f5884 --- /dev/null +++ b/ko/03-skills/doc-generator/generate-docs.py @@ -0,0 +1,55 @@ +#!/usr/bin/env python3 +import ast + + +class APIDocExtractor(ast.NodeVisitor): + """Extract API documentation from Python source code.""" + + def __init__(self): + self.endpoints = [] + + def visit_FunctionDef(self, node): + """Extract function documentation.""" + if node.name.startswith("get_") or node.name.startswith("post_"): + doc = ast.get_docstring(node) + endpoint = { + "name": node.name, + "docstring": doc, + "params": [arg.arg for arg in node.args.args], + "returns": self._extract_return_type(node), + } + self.endpoints.append(endpoint) + self.generic_visit(node) + + def _extract_return_type(self, node): + """Extract return type from function annotation.""" + if node.returns: + return ast.unparse(node.returns) + return "Any" + + +def generate_markdown_docs(endpoints: list[dict]) -> str: + """Generate markdown documentation from endpoints.""" + docs = "# API Documentation\n\n" + + for endpoint in endpoints: + docs += f"## {endpoint['name']}\n\n" + docs += f"{endpoint['docstring']}\n\n" + docs += f"**Parameters**: {', '.join(endpoint['params'])}\n\n" + docs += f"**Returns**: {endpoint['returns']}\n\n" + docs += "---\n\n" + + return docs + + +if __name__ == "__main__": + import sys + + with open(sys.argv[1]) as f: + tree = ast.parse(f.read()) + + extractor = APIDocExtractor() + extractor.visit(tree) + + markdown = generate_markdown_docs(extractor.endpoints) + print(markdown) diff --git a/ko/03-skills/refactor/SKILL.md b/ko/03-skills/refactor/SKILL.md new file mode 100644 index 00000000..97101bf3 --- /dev/null +++ b/ko/03-skills/refactor/SKILL.md @@ -0,0 +1,426 @@ +--- +name: code-refactor +description: ๋งˆํ‹ด ํŒŒ์šธ๋Ÿฌ์˜ ๋ฐฉ๋ฒ•๋ก ์— ๊ธฐ๋ฐ˜ํ•œ ์ฒด๊ณ„์ ์ธ ์ฝ”๋“œ ๋ฆฌํŒฉํ† ๋ง. ์‚ฌ์šฉ์ž๊ฐ€ ์ฝ”๋“œ ๋ฆฌํŒฉํ† ๋ง, ์ฝ”๋“œ ๊ตฌ์กฐ ๊ฐœ์„ , ๊ธฐ์ˆ  ๋ถ€์ฑ„ ๊ฐ์†Œ, ๋ ˆ๊ฑฐ์‹œ ์ฝ”๋“œ ์ •๋ฆฌ, ์ฝ”๋“œ ์Šค๋ฉœ ์ œ๊ฑฐ, ๋˜๋Š” ์ฝ”๋“œ ์œ ์ง€๋ณด์ˆ˜์„ฑ ํ–ฅ์ƒ์„ ์š”์ฒญํ•  ๋•Œ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. ์ด ์Šคํ‚ฌ์€ ์—ฐ๊ตฌ, ๊ณ„ํš, ์•ˆ์ „ํ•˜๊ณ  ์ ์ง„์ ์ธ ๊ตฌํ˜„์„ ํฌํ•จํ•˜๋Š” ๋‹จ๊ณ„๋ณ„ ์ ‘๊ทผ ๋ฐฉ์‹์„ ์•ˆ๋‚ดํ•ฉ๋‹ˆ๋‹ค. +--- + +# ์ฝ”๋“œ ๋ฆฌํŒฉํ† ๋ง ์Šคํ‚ฌ + +๋งˆํ‹ด ํŒŒ์šธ๋Ÿฌ์˜ *Refactoring: Improving the Design of Existing Code* (2nd Edition)์— ๊ธฐ๋ฐ˜ํ•œ ์ฝ”๋“œ ๋ฆฌํŒฉํ† ๋ง์— ๋Œ€ํ•œ ์ฒด๊ณ„์ ์ธ ์ ‘๊ทผ ๋ฐฉ์‹์ž…๋‹ˆ๋‹ค. ์ด ์Šคํ‚ฌ์€ ํ…Œ์ŠคํŠธ๋ฅผ ํ†ตํ•ด ๋’ท๋ฐ›์นจ๋˜๋Š” ์•ˆ์ „ํ•˜๊ณ  ์ ์ง„์ ์ธ ๋ณ€๊ฒฝ์„ ๊ฐ•์กฐํ•ฉ๋‹ˆ๋‹ค. + +> "๋ฆฌํŒฉํ† ๋ง์€ ์ฝ”๋“œ์˜ ์™ธ๋ถ€ ๋™์ž‘์„ ๋ณ€๊ฒฝํ•˜์ง€ ์•Š์œผ๋ฉด์„œ ๋‚ด๋ถ€ ๊ตฌ์กฐ๋ฅผ ๊ฐœ์„ ํ•˜๋Š” ์†Œํ”„ํŠธ์›จ์–ด ์‹œ์Šคํ…œ ๋ณ€๊ฒฝ ๊ณผ์ •์ž…๋‹ˆ๋‹ค." โ€” ๋งˆํ‹ด ํŒŒ์šธ๋Ÿฌ + +## ํ•ต์‹ฌ ์›์น™ + +1. **ํ–‰๋™ ๋ณด์กด**: ์™ธ๋ถ€ ๋™์ž‘์€ ๋ณ€๊ฒฝ๋˜์ง€ ์•Š์•„์•ผ ํ•ฉ๋‹ˆ๋‹ค. +2. **์ž‘์€ ๋‹จ๊ณ„**: ์ž‘๊ณ  ํ…Œ์ŠคํŠธ ๊ฐ€๋Šฅํ•œ ๋ณ€๊ฒฝ์„ ์ˆ˜ํ–‰ํ•ฉ๋‹ˆ๋‹ค. +3. **ํ…Œ์ŠคํŠธ ์ฃผ๋„**: ํ…Œ์ŠคํŠธ๋Š” ์•ˆ์ „๋ง์ž…๋‹ˆ๋‹ค. +4. **์ง€์†์ **: ๋ฆฌํŒฉํ† ๋ง์€ ์ผํšŒ์„ฑ ์ด๋ฒคํŠธ๊ฐ€ ์•„๋‹ˆ๋ผ ์ง€์†์ ์ธ ๊ณผ์ •์ž…๋‹ˆ๋‹ค. +5. **ํ˜‘์—…**: ๊ฐ ๋‹จ๊ณ„์—์„œ ์‚ฌ์šฉ์ž ์Šน์ธ์ด ํ•„์š”ํ•ฉ๋‹ˆ๋‹ค. + +## ์›Œํฌํ”Œ๋กœ ๊ฐœ์š” + +``` +1๋‹จ๊ณ„: ์—ฐ๊ตฌ ๋ฐ ๋ถ„์„ + โ†“ +2๋‹จ๊ณ„: ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€ ํ‰๊ฐ€ + โ†“ +3๋‹จ๊ณ„: ์ฝ”๋“œ ์Šค๋ฉœ ์‹๋ณ„ + โ†“ +4๋‹จ๊ณ„: ๋ฆฌํŒฉํ† ๋ง ๊ณ„ํš ์ˆ˜๋ฆฝ + โ†“ +5๋‹จ๊ณ„: ์ ์ง„์  ๊ตฌํ˜„ + โ†“ +6๋‹จ๊ณ„: ๊ฒ€ํ†  ๋ฐ ๋ฐ˜๋ณต +``` + +--- + +## 1๋‹จ๊ณ„: ์—ฐ๊ตฌ ๋ฐ ๋ถ„์„ + +### ๋ชฉํ‘œ +- ์ฝ”๋“œ๋ฒ ์ด์Šค ๊ตฌ์กฐ์™€ ๋ชฉ์ ์„ ์ดํ•ดํ•ฉ๋‹ˆ๋‹ค. +- ๋ฆฌํŒฉํ† ๋ง ๋ฒ”์œ„๋ฅผ ์‹๋ณ„ํ•ฉ๋‹ˆ๋‹ค. +- ๋น„์ฆˆ๋‹ˆ์Šค ์š”๊ตฌ์‚ฌํ•ญ์— ๋Œ€ํ•œ ๋งฅ๋ฝ์„ ์ˆ˜์ง‘ํ•ฉ๋‹ˆ๋‹ค. + +### ์‚ฌ์šฉ์ž์—๊ฒŒ ์งˆ๋ฌธํ•  ์‚ฌํ•ญ +์‹œ์ž‘ํ•˜๊ธฐ ์ „์— ๋‹ค์Œ ์‚ฌํ•ญ์„ ๋ช…ํ™•ํžˆ ํ•ฉ๋‹ˆ๋‹ค. + +1. **๋ฒ”์œ„**: ์–ด๋–ค ํŒŒ์ผ/๋ชจ๋“ˆ/ํ•จ์ˆ˜๊ฐ€ ๋ฆฌํŒฉํ† ๋ง๋˜์–ด์•ผ ํ•ฉ๋‹ˆ๊นŒ? +2. **๋ชฉํ‘œ**: ์–ด๋–ค ๋ฌธ์ œ๋ฅผ ํ•ด๊ฒฐํ•˜๋ ค๊ณ  ํ•ฉ๋‹ˆ๊นŒ? (๊ฐ€๋…์„ฑ, ์„ฑ๋Šฅ, ์œ ์ง€๋ณด์ˆ˜์„ฑ) +3. **์ œ์•ฝ ์‚ฌํ•ญ**: ๋ณ€๊ฒฝํ•ด์„œ๋Š” ์•ˆ ๋˜๋Š” ์˜์—ญ์ด ์žˆ์Šต๋‹ˆ๊นŒ? +4. **์ผ์ • ์••๋ฐ•**: ์ด๊ฒƒ์ด ๋‹ค๋ฅธ ์ž‘์—…์„ ๋ฐฉํ•ดํ•˜๊ณ  ์žˆ์Šต๋‹ˆ๊นŒ? +5. **ํ…Œ์ŠคํŠธ ์ƒํƒœ**: ํ…Œ์ŠคํŠธ๊ฐ€ ์กด์žฌํ•ฉ๋‹ˆ๊นŒ? ํ†ต๊ณผํ•˜๊ณ  ์žˆ์Šต๋‹ˆ๊นŒ? + +### ์กฐ์น˜ +- [ ] ๋Œ€์ƒ ์ฝ”๋“œ๋ฅผ ์ฝ๊ณ  ์ดํ•ดํ•ฉ๋‹ˆ๋‹ค. +- [ ] ์˜์กด์„ฑ ๋ฐ ํ†ตํ•ฉ์„ ์‹๋ณ„ํ•ฉ๋‹ˆ๋‹ค. +- [ ] ํ˜„์žฌ ์•„ํ‚คํ…์ฒ˜๋ฅผ ๋ฌธ์„œํ™”ํ•ฉ๋‹ˆ๋‹ค. +- [ ] ๊ธฐ์กด ๊ธฐ์ˆ  ๋ถ€์ฑ„ ๋งˆ์ปค(TODO, FIXME)๋ฅผ ๊ธฐ๋กํ•ฉ๋‹ˆ๋‹ค. + +### ๊ฒฐ๊ณผ +์‚ฌ์šฉ์ž์—๊ฒŒ ๋ฐœ๊ฒฌ ์‚ฌํ•ญ์„ ์ œ์‹œํ•ฉ๋‹ˆ๋‹ค. +- ์ฝ”๋“œ ๊ตฌ์กฐ ์š”์•ฝ +- ์‹๋ณ„๋œ ๋ฌธ์ œ ์˜์—ญ +- ์ดˆ๊ธฐ ๊ถŒ์žฅ ์‚ฌํ•ญ +- **์ง„ํ–‰ ์Šน์ธ ์š”์ฒญ** + +--- + +## 2๋‹จ๊ณ„: ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€ ํ‰๊ฐ€ + +### ํ…Œ์ŠคํŠธ๊ฐ€ ์ค‘์š”ํ•œ ์ด์œ  +> "ํ…Œ์ŠคํŠธ ์—†๋Š” ๋ฆฌํŒฉํ† ๋ง์€ ์•ˆ์ „๋ฒจํŠธ ์—†์ด ์šด์ „ํ•˜๋Š” ๊ฒƒ๊ณผ ๊ฐ™์Šต๋‹ˆ๋‹ค." โ€” ๋งˆํ‹ด ํŒŒ์šธ๋Ÿฌ + +ํ…Œ์ŠคํŠธ๋Š” ์•ˆ์ „ํ•œ ๋ฆฌํŒฉํ† ๋ง์˜ **ํ•ต์‹ฌ ๋™๋ ฅ**์ž…๋‹ˆ๋‹ค. ํ…Œ์ŠคํŠธ ์—†์ด๋Š” ๋ฒ„๊ทธ๋ฅผ ์œ ๋ฐœํ•  ์œ„ํ—˜์ด ์žˆ์Šต๋‹ˆ๋‹ค. + +### ํ‰๊ฐ€ ๋‹จ๊ณ„ + +1. **๊ธฐ์กด ํ…Œ์ŠคํŠธ ํ™•์ธ** + ```bash + # Look for test files + find . -name "*test*" -o -name "*spec*" | head -20 + ``` + +2. **๊ธฐ์กด ํ…Œ์ŠคํŠธ ์‹คํ–‰** + ```bash + # JavaScript/TypeScript + npm test + + # Python + pytest -v + + # Java + mvn test + ``` + +3. **์ปค๋ฒ„๋ฆฌ์ง€ ํ™•์ธ (์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ๊ฒฝ์šฐ)** + ```bash + # JavaScript + npm run test:coverage + + # Python + pytest --cov=. + ``` + +### ๊ฒฐ์ • ์‹œ์ : ์‚ฌ์šฉ์ž์—๊ฒŒ ๋ฌธ์˜ + +**ํ…Œ์ŠคํŠธ๊ฐ€ ์กด์žฌํ•˜๊ณ  ํ†ต๊ณผํ•˜๋Š” ๊ฒฝ์šฐ:** +- 3๋‹จ๊ณ„๋กœ ์ง„ํ–‰ํ•ฉ๋‹ˆ๋‹ค. + +**ํ…Œ์ŠคํŠธ๊ฐ€ ์—†๊ฑฐ๋‚˜ ๋ถˆ์™„์ „ํ•œ ๊ฒฝ์šฐ:** +์˜ต์…˜์„ ์ œ์‹œํ•ฉ๋‹ˆ๋‹ค. +1. ๋จผ์ € ํ…Œ์ŠคํŠธ๋ฅผ ์ž‘์„ฑํ•ฉ๋‹ˆ๋‹ค (๊ถŒ์žฅ). +2. ๋ฆฌํŒฉํ† ๋ง ์ค‘์— ์ ์ง„์ ์œผ๋กœ ํ…Œ์ŠคํŠธ๋ฅผ ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค. +3. ํ…Œ์ŠคํŠธ ์—†์ด ์ง„ํ–‰ํ•ฉ๋‹ˆ๋‹ค (์œ„ํ—˜ํ•จ - ์‚ฌ์šฉ์ž ์ธ์ง€ ํ•„์š”). + +**ํ…Œ์ŠคํŠธ๊ฐ€ ์‹คํŒจํ•˜๋Š” ๊ฒฝ์šฐ:** +- ์ค‘๋‹จํ•ฉ๋‹ˆ๋‹ค. ๋ฆฌํŒฉํ† ๋ง ์ „์— ์‹คํŒจํ•˜๋Š” ํ…Œ์ŠคํŠธ๋ฅผ ์ˆ˜์ •ํ•ฉ๋‹ˆ๋‹ค. +- ์‚ฌ์šฉ์ž์—๊ฒŒ ๋ฌธ์˜: ๋จผ์ € ํ…Œ์ŠคํŠธ๋ฅผ ์ˆ˜์ •ํ•ด์•ผ ํ• ๊นŒ์š”? + +### ํ…Œ์ŠคํŠธ ์ž‘์„ฑ ๊ฐ€์ด๋“œ๋ผ์ธ (ํ•„์š”ํ•œ ๊ฒฝ์šฐ) + +๋ฆฌํŒฉํ† ๋ง๋˜๋Š” ๊ฐ ํ•จ์ˆ˜์— ๋Œ€ํ•ด ๋‹ค์Œ์„ ์ปค๋ฒ„ํ•˜๋Š” ํ…Œ์ŠคํŠธ๋ฅผ ํ™•๋ณดํ•ฉ๋‹ˆ๋‹ค. +- ์ •์ƒ ๊ฒฝ๋กœ (์ •์ƒ ์ž‘๋™) +- ์—ฃ์ง€ ์ผ€์ด์Šค (๋นˆ ์ž…๋ ฅ, null, ๊ฒฝ๊ณ„) +- ์˜ค๋ฅ˜ ์‹œ๋‚˜๋ฆฌ์˜ค (์œ ํšจํ•˜์ง€ ์•Š์€ ์ž…๋ ฅ, ์˜ˆ์™ธ) + +"๋ ˆ๋“œ-๊ทธ๋ฆฐ-๋ฆฌํŒฉํ† ๋ง" ์‚ฌ์ดํด์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +1. ์‹คํŒจํ•˜๋Š” ํ…Œ์ŠคํŠธ ์ž‘์„ฑ (๋นจ๊ฐ•) +2. ํ†ต๊ณผํ•˜๋„๋ก ๋งŒ๋“ฆ (์ดˆ๋ก) +3. ๋ฆฌํŒฉํ† ๋ง + +--- + +## 3๋‹จ๊ณ„: ์ฝ”๋“œ ์Šค๋ฉœ ์‹๋ณ„ + +### ์ฝ”๋“œ ์Šค๋ฉœ์ด๋ž€? +์ฝ”๋“œ ๋‚ด ๊นŠ์€ ๋ฌธ์ œ์˜ ์ง•ํ›„์ž…๋‹ˆ๋‹ค. ๋ฒ„๊ทธ๋Š” ์•„๋‹ˆ์ง€๋งŒ ์ฝ”๋“œ๋ฅผ ๊ฐœ์„ ํ•  ์ˆ˜ ์žˆ๋‹ค๋Š” ์ง€ํ‘œ์ž…๋‹ˆ๋‹ค. + +### ํ™•์ธํ•  ์ผ๋ฐ˜์ ์ธ ์ฝ”๋“œ ์Šค๋ฉœ + +์ „์ฒด ๋ชฉ๋ก์€ [references/code-smells.md](references/code-smells.md)๋ฅผ ์ฐธ์กฐํ•˜์‹ญ์‹œ์˜ค. + +#### ๋น ๋ฅธ ์ฐธ์กฐ + +| ์Šค๋ฉœ | ์ง•ํ›„ | ์˜ํ–ฅ | +|-------|-------|--------| +| **๊ธด ๋ฉ”์„œ๋“œ** | ๋ฉ”์„œ๋“œ 30-50์ค„ ์ดˆ๊ณผ | ์ดํ•ด, ํ…Œ์ŠคํŠธ, ์œ ์ง€๋ณด์ˆ˜ ์–ด๋ ค์›€ | +| **์ค‘๋ณต ์ฝ”๋“œ** | ์—ฌ๋Ÿฌ ๊ณณ์— ๋™์ผํ•œ ๋กœ์ง | ์—ฌ๋Ÿฌ ๊ณณ์—์„œ ๋ฒ„๊ทธ ์ˆ˜์ • ํ•„์š” | +| **ํฐ ํด๋ž˜์Šค** | ๋„ˆ๋ฌด ๋งŽ์€ ์ฑ…์ž„์„ ๊ฐ€์ง„ ํด๋ž˜์Šค | ๋‹จ์ผ ์ฑ…์ž„ ์›์น™ ์œ„๋ฐ˜ | +| **ํ”ผ์ฒ˜ ์—”๋น„** | ๋ฉ”์„œ๋“œ๊ฐ€ ๋‹ค๋ฅธ ํด๋ž˜์Šค์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋” ๋งŽ์ด ์‚ฌ์šฉ | ๋‚ฎ์€ ์บก์Šํ™” | +| **์›์‹œ ํƒ€์ž… ๊ฐ•๋ฐ•** | ๊ฐ์ฒด ๋Œ€์‹  ์›์‹œ ํƒ€์ž… ๊ณผ๋‹ค ์‚ฌ์šฉ | ๋„๋ฉ”์ธ ๊ฐœ๋… ๋ˆ„๋ฝ | +| **๊ธด ๋งค๊ฐœ๋ณ€์ˆ˜ ๋ชฉ๋ก** | ๋งค๊ฐœ๋ณ€์ˆ˜ 4๊ฐœ ์ด์ƒ์ธ ๋ฉ”์„œ๋“œ | ์˜ฌ๋ฐ”๋ฅธ ํ˜ธ์ถœ ์–ด๋ ค์›€ | +| **๋ฐ์ดํ„ฐ ๋ฉ์–ด๋ฆฌ** | ๋™์ผํ•œ ๋ฐ์ดํ„ฐ ํ•ญ๋ชฉ์ด ํ•จ๊ป˜ ๋‚˜ํƒ€๋‚จ | ์ถ”์ƒํ™” ๋ˆ„๋ฝ | +| **์Šค์œ„์น˜ ๋ฌธ** | ๋ณต์žกํ•œ switch/if-else ์ฒด์ธ | ํ™•์žฅ ์–ด๋ ค์›€ | +| **ํˆฌ๊ธฐ์  ์ผ๋ฐ˜ํ™”** | "ํ˜น์‹œ ๋ชฐ๋ผ์„œ" ์ž‘์„ฑ๋œ ์ฝ”๋“œ | ๋ถˆํ•„์š”ํ•œ ๋ณต์žก์„ฑ | +| **์ฃฝ์€ ์ฝ”๋“œ** | ์‚ฌ์šฉ๋˜์ง€ ์•Š๋Š” ์ฝ”๋“œ | ํ˜ผ๋ž€, ์œ ์ง€๋ณด์ˆ˜ ๋ถ€๋‹ด | + +### ๋ถ„์„ ๋‹จ๊ณ„ + +1. **์ž๋™ํ™”๋œ ๋ถ„์„** (์Šคํฌ๋ฆฝํŠธ ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ๊ฒฝ์šฐ) + ```bash + python scripts/detect-smells.py + ``` + +2. **์ˆ˜๋™ ๊ฒ€ํ† ** + - ์ฝ”๋“œ๋ฅผ ์ฒด๊ณ„์ ์œผ๋กœ ๊ฒ€ํ† ํ•ฉ๋‹ˆ๋‹ค. + - ์œ„์น˜ ๋ฐ ์‹ฌ๊ฐ๋„๋ฅผ ํฌํ•จํ•˜์—ฌ ๊ฐ ์Šค๋ฉœ์„ ๊ธฐ๋กํ•ฉ๋‹ˆ๋‹ค. + - ์˜ํ–ฅ๋ณ„๋กœ ๋ถ„๋ฅ˜ํ•ฉ๋‹ˆ๋‹ค (์น˜๋ช…์ /๋†’์Œ/์ค‘๊ฐ„/๋‚ฎ์Œ). + +3. **์šฐ์„ ์ˆœ์œ„ ์ง€์ •** + ๋‹ค์Œ ์Šค๋ฉœ์— ์ง‘์ค‘ํ•ฉ๋‹ˆ๋‹ค. + - ํ˜„์žฌ ๊ฐœ๋ฐœ์„ ๋ฐฉํ•ดํ•˜๋Š” ๊ฒƒ + - ๋ฒ„๊ทธ๋‚˜ ํ˜ผ๋ž€์„ ์œ ๋ฐœํ•˜๋Š” ๊ฒƒ + - ๊ฐ€์žฅ ๋งŽ์ด ๋ณ€๊ฒฝ๋˜๋Š” ์ฝ”๋“œ ๊ฒฝ๋กœ์— ์˜ํ–ฅ์„ ๋ฏธ์น˜๋Š” ๊ฒƒ + +### ๊ฒฐ๊ณผ: ์Šค๋ฉœ ๋ณด๊ณ ์„œ + +์‚ฌ์šฉ์ž์—๊ฒŒ ์ œ์‹œํ•ฉ๋‹ˆ๋‹ค. +- ์‹๋ณ„๋œ ์Šค๋ฉœ ๋ชฉ๋ก ๋ฐ ์œ„์น˜ +- ๊ฐ ์Šค๋ฉœ์— ๋Œ€ํ•œ ์‹ฌ๊ฐ๋„ ํ‰๊ฐ€ +- ๊ถŒ์žฅ ์šฐ์„ ์ˆœ์œ„ +- **์šฐ์„ ์ˆœ์œ„ ์Šน์ธ ์š”์ฒญ** + +--- + +## 4๋‹จ๊ณ„: ๋ฆฌํŒฉํ† ๋ง ๊ณ„ํš ์ˆ˜๋ฆฝ + +### ๋ฆฌํŒฉํ† ๋ง ์„ ํƒ + +๊ฐ ์Šค๋ฉœ์— ๋Œ€ํ•ด ์นดํƒˆ๋กœ๊ทธ์—์„œ ์ ์ ˆํ•œ ๋ฆฌํŒฉํ† ๋ง์„ ์„ ํƒํ•ฉ๋‹ˆ๋‹ค. + +์ „์ฒด ๋ชฉ๋ก์€ [references/refactoring-catalog.md](references/refactoring-catalog.md)๋ฅผ ์ฐธ์กฐํ•˜์‹ญ์‹œ์˜ค. + +#### ์Šค๋ฉœ-๋ฆฌํŒฉํ† ๋ง ๋งคํ•‘ + +| ์ฝ”๋“œ ์Šค๋ฉœ | ๊ถŒ์žฅ ๋ฆฌํŒฉํ† ๋ง | +|------------|---------------------------| +| **๊ธด ๋ฉ”์„œ๋“œ** | ๋ฉ”์„œ๋“œ ์ถ”์ถœ, ์ž„์‹œ ๋ณ€์ˆ˜๋ฅผ ์ฟผ๋ฆฌ๋กœ ๋ฐ”๊พธ๊ธฐ | +| **์ค‘๋ณต ์ฝ”๋“œ** | ๋ฉ”์„œ๋“œ ์ถ”์ถœ, ๋ฉ”์„œ๋“œ ์ƒํ–ฅ, ํ…œํ”Œ๋ฆฟ ๋ฉ”์„œ๋“œ ํ˜•์„ฑ | +| **ํฐ ํด๋ž˜์Šค** | ํด๋ž˜์Šค ์ถ”์ถœ, ์„œ๋ธŒํด๋ž˜์Šค ์ถ”์ถœ | +| **ํ”ผ์ฒ˜ ์—”๋น„** | ๋ฉ”์„œ๋“œ ์ด๋™, ํ•„๋“œ ์ด๋™ | +| **์›์‹œ ํƒ€์ž… ๊ฐ•๋ฐ•** | ์›์‹œ ํƒ€์ž…์„ ๊ฐ์ฒด๋กœ ๋ฐ”๊พธ๊ธฐ, ํƒ€์ž… ์ฝ”๋“œ๋ฅผ ํด๋ž˜์Šค๋กœ ๋ฐ”๊พธ๊ธฐ | +| **๊ธด ๋งค๊ฐœ๋ณ€์ˆ˜ ๋ชฉ๋ก** | ๋งค๊ฐœ๋ณ€์ˆ˜ ๊ฐ์ฒด ๋„์ž…, ์ „์ฒด ๊ฐ์ฒด ์œ ์ง€ | +| **๋ฐ์ดํ„ฐ ๋ฉ์–ด๋ฆฌ** | ํด๋ž˜์Šค ์ถ”์ถœ, ๋งค๊ฐœ๋ณ€์ˆ˜ ๊ฐ์ฒด ๋„์ž… | +| **์Šค์œ„์น˜ ๋ฌธ** | ์กฐ๊ฑด๋ฌธ์„ ๋‹คํ˜•์„ฑ์œผ๋กœ ๋ฐ”๊พธ๊ธฐ | +| **ํˆฌ๊ธฐ์  ์ผ๋ฐ˜ํ™”** | ๊ณ„์ธต ์ถ•์†Œ, ํด๋ž˜์Šค ์ธ๋ผ์ธํ™”, ์ฃฝ์€ ์ฝ”๋“œ ์ œ๊ฑฐ | +| **์ฃฝ์€ ์ฝ”๋“œ** | ์ฃฝ์€ ์ฝ”๋“œ ์ œ๊ฑฐ | + +### ๊ณ„ํš ๊ตฌ์กฐ + +[templates/refactoring-plan.md](templates/refactoring-plan.md)์˜ ํ…œํ”Œ๋ฆฟ์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + +๊ฐ ๋ฆฌํŒฉํ† ๋ง์— ๋Œ€ํ•ด: +1. **๋Œ€์ƒ**: ์–ด๋–ค ์ฝ”๋“œ๊ฐ€ ๋ณ€๊ฒฝ๋  ๊ฒƒ์ธ๊ฐ€ +2. **์Šค๋ฉœ**: ์–ด๋–ค ๋ฌธ์ œ๋ฅผ ํ•ด๊ฒฐํ•˜๋Š”๊ฐ€ +3. **๋ฆฌํŒฉํ† ๋ง**: ์–ด๋–ค ๊ธฐ๋ฒ•์„ ์ ์šฉํ•  ๊ฒƒ์ธ๊ฐ€ +4. **๋‹จ๊ณ„**: ์ƒ์„ธํ•œ ๋งˆ์ดํฌ๋กœ ๋‹จ๊ณ„ +5. **์œ„ํ—˜**: ๋ฌด์—‡์ด ์ž˜๋ชป๋  ์ˆ˜ ์žˆ๋Š”๊ฐ€ +6. **๋กค๋ฐฑ**: ํ•„์š”ํ•œ ๊ฒฝ์šฐ ์–ด๋–ป๊ฒŒ ๋˜๋Œ๋ฆด ๊ฒƒ์ธ๊ฐ€ + +### ๋‹จ๊ณ„๋ณ„ ์ ‘๊ทผ ๋ฐฉ์‹ + +**์ค‘์š”**: ๋ฆฌํŒฉํ† ๋ง์„ ๋‹จ๊ณ„์ ์œผ๋กœ ์ ์ง„์ ์œผ๋กœ ๋„์ž…ํ•ฉ๋‹ˆ๋‹ค. + +**A๋‹จ๊ณ„: ๋น ๋ฅธ ์„ฑ๊ณผ** (๋‚ฎ์€ ์œ„ํ—˜, ๋†’์€ ๊ฐ€์น˜) +- ๋ช…ํ™•์„ฑ์„ ์œ„ํ•ด ๋ณ€์ˆ˜ ์ด๋ฆ„ ๋ณ€๊ฒฝ +- ๋ช…๋ฐฑํ•œ ์ค‘๋ณต ์ฝ”๋“œ ์ถ”์ถœ +- ์ฃฝ์€ ์ฝ”๋“œ ์ œ๊ฑฐ + +**B๋‹จ๊ณ„: ๊ตฌ์กฐ์  ๊ฐœ์„ ** (์ค‘๊ฐ„ ์œ„ํ—˜) +- ๊ธด ํ•จ์ˆ˜์—์„œ ๋ฉ”์„œ๋“œ ์ถ”์ถœ +- ๋งค๊ฐœ๋ณ€์ˆ˜ ๊ฐ์ฒด ๋„์ž… +- ์ ์ ˆํ•œ ํด๋ž˜์Šค๋กœ ๋ฉ”์„œ๋“œ ์ด๋™ + +**C๋‹จ๊ณ„: ์•„ํ‚คํ…์ฒ˜ ๋ณ€๊ฒฝ** (๋†’์€ ์œ„ํ—˜) +- ์กฐ๊ฑด๋ฌธ์„ ๋‹คํ˜•์„ฑ์œผ๋กœ ๋ฐ”๊พธ๊ธฐ +- ํด๋ž˜์Šค ์ถ”์ถœ +- ๋””์ž์ธ ํŒจํ„ด ๋„์ž… + +### ๊ฒฐ์ • ์‹œ์ : ์‚ฌ์šฉ์ž์—๊ฒŒ ๊ณ„ํš ์ œ์‹œ + +๊ตฌํ˜„ ์ „์—: +- ์ „์ฒด ๋ฆฌํŒฉํ† ๋ง ๊ณ„ํš์„ ๋ณด์—ฌ์ค๋‹ˆ๋‹ค. +- ๊ฐ ๋‹จ๊ณ„์™€ ์œ„ํ—˜์„ ์„ค๋ช…ํ•ฉ๋‹ˆ๋‹ค. +- ๊ฐ ๋‹จ๊ณ„์— ๋Œ€ํ•œ ๋ช…์‹œ์  ์Šน์ธ์„ ๋ฐ›์Šต๋‹ˆ๋‹ค. +- **์งˆ๋ฌธ**: "A๋‹จ๊ณ„๋กœ ์ง„ํ–‰ํ•ด๋„ ๋ ๊นŒ์š”?" + +--- + +## 5๋‹จ๊ณ„: ์ ์ง„์  ๊ตฌํ˜„ + +### ํ™ฉ๊ธˆ๋ฅ  +> "๋ณ€๊ฒฝ โ†’ ํ…Œ์ŠคํŠธ โ†’ ํ†ต๊ณผ? โ†’ ์ปค๋ฐ‹ โ†’ ๋‹ค์Œ ๋‹จ๊ณ„" + +### ๊ตฌํ˜„ ๋ฆฌ๋“ฌ + +๊ฐ ๋ฆฌํŒฉํ† ๋ง ๋‹จ๊ณ„์— ๋Œ€ํ•ด: + +1. **์‚ฌ์ „ ํ™•์ธ** + - ํ…Œ์ŠคํŠธ๊ฐ€ ํ†ต๊ณผํ•˜๊ณ  ์žˆ๋Š”์ง€ (์ดˆ๋ก) + - ์ฝ”๋“œ๊ฐ€ ์ปดํŒŒ์ผ๋˜๋Š”์ง€ + +2. **ํ•˜๋‚˜์˜ ์ž‘์€ ๋ณ€๊ฒฝ ์ˆ˜ํ–‰** + - ์นดํƒˆ๋กœ๊ทธ์˜ ๋ฉ”์ปค๋‹ˆ์ฆ˜์„ ๋”ฐ๋ฆ…๋‹ˆ๋‹ค. + - ๋ณ€๊ฒฝ ์‚ฌํ•ญ์„ ์ตœ์†Œํ•œ์œผ๋กœ ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. + +3. **๊ฒ€์ฆ** + - ์ฆ‰์‹œ ํ…Œ์ŠคํŠธ๋ฅผ ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค. + - ์ปดํŒŒ์ผ ์˜ค๋ฅ˜๋ฅผ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. + +4. **ํ…Œ์ŠคํŠธ๊ฐ€ ํ†ต๊ณผํ•˜๋Š” ๊ฒฝ์šฐ (์ดˆ๋ก)** + - ์„ค๋ช…์ ์ธ ๋ฉ”์‹œ์ง€๋กœ ์ปค๋ฐ‹ํ•ฉ๋‹ˆ๋‹ค. + - ๋‹ค์Œ ๋‹จ๊ณ„๋กœ ์ด๋™ํ•ฉ๋‹ˆ๋‹ค. + +5. **ํ…Œ์ŠคํŠธ๊ฐ€ ์‹คํŒจํ•˜๋Š” ๊ฒฝ์šฐ (๋นจ๊ฐ•)** + - ์ฆ‰์‹œ ์ค‘๋‹จํ•ฉ๋‹ˆ๋‹ค. + - ๋ณ€๊ฒฝ ์‚ฌํ•ญ์„ ๋˜๋Œ๋ฆฝ๋‹ˆ๋‹ค. + - ๋ฌด์—‡์ด ์ž˜๋ชป๋˜์—ˆ๋Š”์ง€ ๋ถ„์„ํ•ฉ๋‹ˆ๋‹ค. + - ๋ถˆ๋ช…ํ™•ํ•œ ๊ฒฝ์šฐ ์‚ฌ์šฉ์ž์—๊ฒŒ ๋ฌธ์˜ํ•ฉ๋‹ˆ๋‹ค. + +### ์ปค๋ฐ‹ ์ „๋žต + +๊ฐ ์ปค๋ฐ‹์€ ๋‹ค์Œ ์กฐ๊ฑด์„ ์ถฉ์กฑํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. +- **์›์ž์ **: ํ•˜๋‚˜์˜ ๋…ผ๋ฆฌ์  ๋ณ€๊ฒฝ +- **๋˜๋Œ๋ฆด ์ˆ˜ ์žˆ๋Š”**: ๋˜๋Œ๋ฆฌ๊ธฐ ์‰ฌ์›€ +- **์„ค๋ช…์ ์ธ**: ๋ช…ํ™•ํ•œ ์ปค๋ฐ‹ ๋ฉ”์‹œ์ง€ + +์ปค๋ฐ‹ ๋ฉ”์‹œ์ง€ ์˜ˆ์‹œ: +``` +refactor: Extract calculateTotal() from processOrder() +refactor: Rename 'x' to 'customerCount' for clarity +refactor: Remove unused validateOldFormat() method +``` + +### ์ง„ํ–‰ ์ƒํ™ฉ ๋ณด๊ณ  + +๊ฐ ํ•˜์œ„ ๋‹จ๊ณ„ ํ›„์— ์‚ฌ์šฉ์ž์—๊ฒŒ ๋ณด๊ณ ํ•ฉ๋‹ˆ๋‹ค. +- ๋ณ€๊ฒฝ ์‚ฌํ•ญ +- ํ…Œ์ŠคํŠธ๋Š” ์—ฌ์ „ํžˆ ํ†ต๊ณผํ•˜๊ณ  ์žˆ์Šต๋‹ˆ๊นŒ? +- ๋ฐœ์ƒํ•œ ๋ฌธ์ œ +- **์งˆ๋ฌธ**: "๋‹ค์Œ ๋ฐฐ์น˜๋กœ ๊ณ„์† ์ง„ํ–‰ํ• ๊นŒ์š”?" + +--- + +## 6๋‹จ๊ณ„: ๊ฒ€ํ†  ๋ฐ ๋ฐ˜๋ณต + +### ๋ฆฌํŒฉํ† ๋ง ํ›„ ์ฒดํฌ๋ฆฌ์ŠคํŠธ + +- [ ] ๋ชจ๋“  ํ…Œ์ŠคํŠธ ํ†ต๊ณผ +- [ ] ์ƒˆ๋กœ์šด ๊ฒฝ๊ณ /์˜ค๋ฅ˜ ์—†์Œ +- [ ] ์ฝ”๋“œ ์„ฑ๊ณต์ ์œผ๋กœ ์ปดํŒŒ์ผ +- [ ] ๋™์ž‘ ๋ณ€๊ฒฝ ์—†์Œ (์ˆ˜๋™ ํ™•์ธ) +- [ ] ํ•„์š”ํ•œ ๊ฒฝ์šฐ ๋ฌธ์„œ ์—…๋ฐ์ดํŠธ +- [ ] ์ปค๋ฐ‹ ๊ธฐ๋ก์ด ๊น”๋”ํ•จ + +### ์ง€ํ‘œ ๋น„๊ต + +์ „ํ›„ ๋ณต์žก๋„ ๋ถ„์„ ์‹คํ–‰: +```bash +python scripts/analyze-complexity.py +``` + +๊ฐœ์„  ์‚ฌํ•ญ ์ œ์‹œ: +- ์ฝ”๋“œ ์ค„ ๋ณ€๊ฒฝ +- ์ˆœํ™˜ ๋ณต์žก๋„ ๋ณ€๊ฒฝ +- ์œ ์ง€๋ณด์ˆ˜์„ฑ ์ง€์ˆ˜ ๋ณ€๊ฒฝ + +### ์‚ฌ์šฉ์ž ๊ฒ€ํ†  + +์ตœ์ข… ๊ฒฐ๊ณผ ์ œ์‹œ: +- ๋ชจ๋“  ๋ณ€๊ฒฝ ์‚ฌํ•ญ ์š”์•ฝ +- ์ฝ”๋“œ ์ „/ํ›„ ๋น„๊ต +- ์ง€ํ‘œ ๊ฐœ์„  +- ๋‚จ์€ ๊ธฐ์ˆ  ๋ถ€์ฑ„ +- **์งˆ๋ฌธ**: "์ด๋Ÿฌํ•œ ๋ณ€๊ฒฝ ์‚ฌํ•ญ์— ๋งŒ์กฑํ•˜์‹ญ๋‹ˆ๊นŒ?" + +### ๋‹ค์Œ ๋‹จ๊ณ„ + +์‚ฌ์šฉ์ž์™€ ๋…ผ์˜: +- ์ถ”๊ฐ€๋กœ ์ฒ˜๋ฆฌํ•  ์Šค๋ฉœ์ด ์žˆ์Šต๋‹ˆ๊นŒ? +- ํ›„์† ๋ฆฌํŒฉํ† ๋ง ์ผ์ •์„ ์žก์„๊นŒ์š”? +- ๋‹ค๋ฅธ ๊ณณ์—๋„ ์œ ์‚ฌํ•œ ๋ณ€๊ฒฝ์„ ์ ์šฉํ• ๊นŒ์š”? + +--- + +## ์ค‘์š” ๊ฐ€์ด๋“œ๋ผ์ธ + +### ์–ธ์ œ ์ค‘๋‹จํ•˜๊ณ  ์งˆ๋ฌธํ•ด์•ผ ํ•˜๋Š”๊ฐ€ + +๋‹ค์Œ ๊ฒฝ์šฐ ํ•ญ์ƒ ์ผ์‹œ ์ค‘์ง€ํ•˜๊ณ  ์‚ฌ์šฉ์ž์—๊ฒŒ ๋ฌธ์˜ํ•˜์‹ญ์‹œ์˜ค. +- ๋น„์ฆˆ๋‹ˆ์Šค ๋กœ์ง์ด ๋ถˆํ™•์‹คํ•  ๋•Œ +- ๋ณ€๊ฒฝ์ด ์™ธ๋ถ€ API์— ์˜ํ–ฅ์„ ๋ฏธ์น  ์ˆ˜ ์žˆ์„ ๋•Œ +- ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€๊ฐ€ ๋ถˆ์ถฉ๋ถ„ํ•  ๋•Œ +- ์ค‘์š”ํ•œ ์•„ํ‚คํ…์ฒ˜ ๊ฒฐ์ •์ด ํ•„์š”ํ•  ๋•Œ +- ์œ„ํ—˜ ์ˆ˜์ค€์ด ์ฆ๊ฐ€ํ•  ๋•Œ +- ์˜ˆ์ƒ์น˜ ๋ชปํ•œ ๋ณต์žก์„ฑ์— ์ง๋ฉดํ•  ๋•Œ + +### ์•ˆ์ „ ๊ทœ์น™ + +1. **ํ…Œ์ŠคํŠธ ์—†์ด ๋ฆฌํŒฉํ† ๋งํ•˜์ง€ ๋งˆ์‹ญ์‹œ์˜ค** (์‚ฌ์šฉ์ž๊ฐ€ ๋ช…์‹œ์ ์œผ๋กœ ์œ„ํ—˜์„ ์ธ์ง€ํ•˜์ง€ ์•Š๋Š” ํ•œ) +2. **ํฐ ๋ณ€๊ฒฝ์„ ํ•˜์ง€ ๋งˆ์‹ญ์‹œ์˜ค** - ์ž‘์€ ๋‹จ๊ณ„๋กœ ๋‚˜๋ˆ•๋‹ˆ๋‹ค. +3. ๊ฐ ๋ณ€๊ฒฝ ํ›„ **ํ…Œ์ŠคํŠธ ์‹คํ–‰์„ ๊ฑด๋„ˆ๋›ฐ์ง€ ๋งˆ์‹ญ์‹œ์˜ค**. +4. **ํ…Œ์ŠคํŠธ๊ฐ€ ์‹คํŒจํ•˜๋ฉด ๊ณ„์†ํ•˜์ง€ ๋งˆ์‹ญ์‹œ์˜ค** - ๋จผ์ € ์ˆ˜์ •ํ•˜๊ฑฐ๋‚˜ ๋กค๋ฐฑํ•˜์‹ญ์‹œ์˜ค. +5. **์ถ”์ธกํ•˜์ง€ ๋งˆ์‹ญ์‹œ์˜ค** - ์˜์‹ฌ์Šค๋Ÿฌ์šธ ๋•Œ๋Š” ์งˆ๋ฌธํ•˜์‹ญ์‹œ์˜ค. + +### ํ•˜์ง€ ๋ง์•„์•ผ ํ•  ๊ฒƒ + +- ๋ฆฌํŒฉํ† ๋ง๊ณผ ๊ธฐ๋Šฅ ์ถ”๊ฐ€๋ฅผ ๊ฒฐํ•ฉํ•˜์ง€ ๋งˆ์‹ญ์‹œ์˜ค. +- ํ”„๋กœ๋•์…˜ ๋น„์ƒ ์ƒํ™ฉ ์ค‘์— ๋ฆฌํŒฉํ† ๋งํ•˜์ง€ ๋งˆ์‹ญ์‹œ์˜ค. +- ์ดํ•ดํ•˜์ง€ ๋ชปํ•˜๋Š” ์ฝ”๋“œ๋ฅผ ๋ฆฌํŒฉํ† ๋งํ•˜์ง€ ๋งˆ์‹ญ์‹œ์˜ค. +- ๊ณผ๋„ํ•˜๊ฒŒ ์„ค๊ณ„ํ•˜์ง€ ๋งˆ์‹ญ์‹œ์˜ค - ๊ฐ„๋‹จํ•˜๊ฒŒ ์œ ์ง€ํ•˜์‹ญ์‹œ์˜ค. +- ๋ชจ๋“  ๊ฒƒ์„ ํ•œ ๋ฒˆ์— ๋ฆฌํŒฉํ† ๋งํ•˜์ง€ ๋งˆ์‹ญ์‹œ์˜ค. + +--- + +## ๋น ๋ฅธ ์‹œ์ž‘ ์˜ˆ์‹œ + +### ์‹œ๋‚˜๋ฆฌ์˜ค: ์ค‘๋ณต์ด ์žˆ๋Š” ๊ธด ๋ฉ”์„œ๋“œ + +**์ด์ „:** +```javascript +function processOrder(order) { + // 150 lines of code with: + // - Duplicated validation logic + // - Inline calculations + // - Mixed responsibilities +} +``` + +**๋ฆฌํŒฉํ† ๋ง ๋‹จ๊ณ„:** + +1. processOrder()์— ๋Œ€ํ•œ **ํ…Œ์ŠคํŠธ๊ฐ€ ์กด์žฌํ•˜๋Š”์ง€ ํ™•์ธ** +2. ์œ ํšจ์„ฑ ๊ฒ€์‚ฌ๋ฅผ validateOrder()๋กœ **์ถ”์ถœ** +3. **ํ…Œ์ŠคํŠธ** - ํ†ต๊ณผํ•ด์•ผ ํ•จ +4. ๊ณ„์‚ฐ์„ calculateOrderTotal()๋กœ **์ถ”์ถœ** +5. **ํ…Œ์ŠคํŠธ** - ํ†ต๊ณผํ•ด์•ผ ํ•จ +6. ์•Œ๋ฆผ์„ notifyCustomer()๋กœ **์ถ”์ถœ** +7. **ํ…Œ์ŠคํŠธ** - ํ†ต๊ณผํ•ด์•ผ ํ•จ +8. **๊ฒ€ํ† ** - processOrder()๋Š” ์ด์ œ 3๊ฐœ์˜ ๋ช…ํ™•ํ•œ ํ•จ์ˆ˜๋ฅผ ์กฐ์ •ํ•จ + +**์ดํ›„:** +```javascript +function processOrder(order) { + validateOrder(order); + const total = calculateOrderTotal(order); + notifyCustomer(order, total); + return { order, total }; +} +``` + +--- + +## ์ฐธ์กฐ + +- [์ฝ”๋“œ ์Šค๋ฉœ ์นดํƒˆ๋กœ๊ทธ](references/code-smells.md) - ์ฝ”๋“œ ์Šค๋ฉœ ์ „์ฒด ๋ชฉ๋ก +- [๋ฆฌํŒฉํ† ๋ง ์นดํƒˆ๋กœ๊ทธ](references/refactoring-catalog.md) - ๋ฆฌํŒฉํ† ๋ง ๊ธฐ๋ฒ• +- [๋ฆฌํŒฉํ† ๋ง ๊ณ„ํš ํ…œํ”Œ๋ฆฟ](templates/refactoring-plan.md) - ๊ณ„ํš ํ…œํ”Œ๋ฆฟ + +## ์Šคํฌ๋ฆฝํŠธ + +- `scripts/analyze-complexity.py` - ์ฝ”๋“œ ๋ณต์žก๋„ ์ง€ํ‘œ ๋ถ„์„ +- `scripts/detect-smells.py` - ์ž๋™ํ™”๋œ ์Šค๋ฉœ ๊ฐ์ง€ + +## ๋ฒ„์ „ ๊ธฐ๋ก + +- v1.0.0 (2025-01-15): ํŒŒ์šธ๋Ÿฌ ๋ฐฉ๋ฒ•๋ก , ๋‹จ๊ณ„๋ณ„ ์ ‘๊ทผ, ์‚ฌ์šฉ์ž ์ƒ๋‹ด ์ง€์ ์„ ํฌํ•จํ•œ ์ดˆ๊ธฐ ๋ฆด๋ฆฌ์Šค diff --git a/ko/03-skills/refactor/references/code-smells.md b/ko/03-skills/refactor/references/code-smells.md new file mode 100644 index 00000000..9a90f6be --- /dev/null +++ b/ko/03-skills/refactor/references/code-smells.md @@ -0,0 +1,669 @@ +# ์ฝ”๋“œ ์Šค๋ฉœ ์นดํƒˆ๋กœ๊ทธ + +Martin Fowler์˜ *Refactoring* (2ํŒ)์„ ๊ธฐ๋ฐ˜์œผ๋กœ ํ•œ ์ฝ”๋“œ ์Šค๋ฉœ์— ๋Œ€ํ•œ ํฌ๊ด„์ ์ธ ์ฐธ๊ณ  ์ž๋ฃŒ์ž…๋‹ˆ๋‹ค. ์ฝ”๋“œ ์Šค๋ฉœ์€ ๋” ๊นŠ์€ ๋ฌธ์ œ์˜ ์ฆ์ƒ์ด๋ฉฐ, ์ฝ”๋“œ ์„ค๊ณ„์— ๋ฌธ์ œ๊ฐ€ ์žˆ์„ ์ˆ˜ ์žˆ์Œ์„ ๋‚˜ํƒ€๋ƒ…๋‹ˆ๋‹ค. + +> "์ฝ”๋“œ ์Šค๋ฉœ์€ ์ผ๋ฐ˜์ ์œผ๋กœ ์‹œ์Šคํ…œ์˜ ๋” ๊นŠ์€ ๋ฌธ์ œ์— ํ•ด๋‹นํ•˜๋Š” ํ‘œ๋ฉด์ ์ธ ์ง•ํ›„์ž…๋‹ˆ๋‹ค." โ€” Martin Fowler + +--- + +## ๋น„๋Œ€ํ•ด์ง„ ์ฝ”๋“œ (Bloaters) + +๋„ˆ๋ฌด ์ปค์ ธ์„œ ํšจ๊ณผ์ ์œผ๋กœ ๋‹ค๋ฃจ๊ธฐ ์–ด๋ ค์šด ๊ฒƒ์„ ๋‚˜ํƒ€๋‚ด๋Š” ์ฝ”๋“œ ์Šค๋ฉœ์ž…๋‹ˆ๋‹ค. + +### ๊ธด ๋ฉ”์„œ๋“œ (Long Method) + +**์ง•ํ›„:** +- ๋ฉ”์„œ๋“œ๊ฐ€ 30-50์ค„์„ ์ดˆ๊ณผ +- ์ „์ฒด ๋ฉ”์„œ๋“œ๋ฅผ ๋ณด๋ ค๋ฉด ์Šคํฌ๋กคํ•ด์•ผ ํ•จ +- ์—ฌ๋Ÿฌ ๋‹จ๊ณ„์˜ ์ค‘์ฒฉ +- ์„น์…˜์ด ํ•˜๋Š” ์ผ์„ ์„ค๋ช…ํ•˜๋Š” ์ฃผ์„ + +**์™œ ๋‚˜์œ๊ฐ€:** +- ์ดํ•ดํ•˜๊ธฐ ์–ด๋ ค์›€ +- ๋…๋ฆฝ์ ์œผ๋กœ ํ…Œ์ŠคํŠธํ•˜๊ธฐ ์–ด๋ ค์›€ +- ๋ณ€๊ฒฝ ์‹œ ์˜ˆ์ƒ์น˜ ๋ชปํ•œ ๊ฒฐ๊ณผ๋ฅผ ์ดˆ๋ž˜ +- ์ค‘๋ณต๋œ ๋กœ์ง์ด ๋‚ด๋ถ€์— ์ˆจ์–ด ์žˆ์Œ + +**๋ฆฌํŒฉํ„ฐ๋ง:** +- Extract Method (๋ฉ”์„œ๋“œ ์ถ”์ถœ) +- Replace Temp with Query (์ž„์‹œ ๋ณ€์ˆ˜๋ฅผ ์ฟผ๋ฆฌ๋กœ ์ „ํ™˜) +- Introduce Parameter Object (๋งค๊ฐœ๋ณ€์ˆ˜ ๊ฐ์ฒด ๋„์ž…) +- Replace Method with Method Object (๋ฉ”์„œ๋“œ๋ฅผ ๋ฉ”์„œ๋“œ ๊ฐ์ฒด๋กœ ์ „ํ™˜) +- Decompose Conditional (์กฐ๊ฑด๋ฌธ ๋ถ„ํ•ด) + +**์˜ˆ์‹œ (์ด์ „):** +```javascript +function processOrder(order) { + // Validate order (20 lines) + if (!order.items) throw new Error('No items'); + if (order.items.length === 0) throw new Error('Empty order'); + // ... more validation + + // Calculate totals (30 lines) + let subtotal = 0; + for (const item of order.items) { + subtotal += item.price * item.quantity; + } + // ... tax, shipping, discounts + + // Send notifications (20 lines) + // ... email logic +} +``` + +**์˜ˆ์‹œ (์ดํ›„):** +```javascript +function processOrder(order) { + validateOrder(order); + const totals = calculateOrderTotals(order); + sendOrderNotifications(order, totals); + return { order, totals }; +} +``` + +--- + +### ํฐ ํด๋ž˜์Šค (Large Class) + +**์ง•ํ›„:** +- ํด๋ž˜์Šค์— ์ธ์Šคํ„ด์Šค ๋ณ€์ˆ˜๊ฐ€ ๋งŽ์Œ (>7-10๊ฐœ) +- ํด๋ž˜์Šค์— ๋ฉ”์„œ๋“œ๊ฐ€ ๋งŽ์Œ (>15-20๊ฐœ) +- ํด๋ž˜์Šค ์ด๋ฆ„์ด ๋ชจํ˜ธํ•จ (Manager, Handler, Processor) +- ๋ฉ”์„œ๋“œ๊ฐ€ ๋ชจ๋“  ์ธ์Šคํ„ด์Šค ๋ณ€์ˆ˜๋ฅผ ์‚ฌ์šฉํ•˜์ง€ ์•Š์Œ + +**์™œ ๋‚˜์œ๊ฐ€:** +- ๋‹จ์ผ ์ฑ…์ž„ ์›์น™ ์œ„๋ฐ˜ +- ํ…Œ์ŠคํŠธํ•˜๊ธฐ ์–ด๋ ค์›€ +- ๋ณ€๊ฒฝ ์‚ฌํ•ญ์ด ๊ด€๋ จ ์—†๋Š” ๊ธฐ๋Šฅ์— ํŒŒ๊ธ‰๋จ +- ๋ถ€๋ถ„์ ์œผ๋กœ ์žฌ์‚ฌ์šฉํ•˜๊ธฐ ์–ด๋ ค์›€ + +**๋ฆฌํŒฉํ„ฐ๋ง:** +- Extract Class (ํด๋ž˜์Šค ์ถ”์ถœ) +- Extract Subclass (์„œ๋ธŒํด๋ž˜์Šค ์ถ”์ถœ) +- Extract Interface (์ธํ„ฐํŽ˜์ด์Šค ์ถ”์ถœ) + +**ํƒ์ง€:** +``` +Lines of code > 300 +Number of methods > 15 +Number of fields > 10 +``` + +--- + +### ์›์‹œ ํƒ€์ž… ์ง‘์ฐฉ (Primitive Obsession) + +**์ง•ํ›„:** +- ๋„๋ฉ”์ธ ๊ฐœ๋…์— ์›์‹œ ํƒ€์ž… ์‚ฌ์šฉ (์ด๋ฉ”์ผ์— string, ๋ˆ์— int) +- ๊ฐ์ฒด ๋Œ€์‹  ์›์‹œ ํƒ€์ž…์˜ ๋ฐฐ์—ด +- ํƒ€์ž… ์ฝ”๋“œ์— string ์ƒ์ˆ˜ +- ๋งค์ง ๋„˜๋ฒ„/์ŠคํŠธ๋ง + +**์™œ ๋‚˜์œ๊ฐ€:** +- ํƒ€์ž… ๋ ˆ๋ฒจ์—์„œ์˜ ์œ ํšจ์„ฑ ๊ฒ€์‚ฌ ๋ถ€์žฌ +- ๋กœ์ง์ด ์ฝ”๋“œ๋ฒ ์ด์Šค ์ „์ฒด์— ํฉ์–ด์ ธ ์žˆ์Œ +- ์ž˜๋ชป๋œ ๊ฐ’์„ ์ „๋‹ฌํ•˜๊ธฐ ์‰ฌ์›€ +- ๋„๋ฉ”์ธ ๊ฐœ๋… ๋ˆ„๋ฝ + +**๋ฆฌํŒฉํ„ฐ๋ง:** +- Replace Primitive with Object (์›์‹œ ํƒ€์ž…์„ ๊ฐ์ฒด๋กœ ์ „ํ™˜) +- Replace Type Code with Class (ํƒ€์ž… ์ฝ”๋“œ๋ฅผ ํด๋ž˜์Šค๋กœ ์ „ํ™˜) +- Replace Type Code with Subclasses (ํƒ€์ž… ์ฝ”๋“œ๋ฅผ ์„œ๋ธŒํด๋ž˜์Šค๋กœ ์ „ํ™˜) +- Replace Type Code with State/Strategy (ํƒ€์ž… ์ฝ”๋“œ๋ฅผ ์ƒํƒœ/์ „๋žต ํŒจํ„ด์œผ๋กœ ์ „ํ™˜) + +**์˜ˆ์‹œ (์ด์ „):** +```javascript +const user = { + email: 'john@example.com', // Just a string + phone: '1234567890', // Just a string + status: 'active', // Magic string + balance: 10050 // Cents as integer +}; +``` + +**์˜ˆ์‹œ (์ดํ›„):** +```javascript +const user = { + email: new Email('john@example.com'), + phone: new PhoneNumber('1234567890'), + status: UserStatus.ACTIVE, + balance: Money.cents(10050) +}; +``` + +--- + +### ๊ธด ๋งค๊ฐœ๋ณ€์ˆ˜ ๋ชฉ๋ก (Long Parameter List) + +**์ง•ํ›„:** +- ๋งค๊ฐœ๋ณ€์ˆ˜๊ฐ€ 4๊ฐœ ์ด์ƒ์ธ ๋ฉ”์„œ๋“œ +- ํ•ญ์ƒ ํ•จ๊ป˜ ๋‚˜ํƒ€๋‚˜๋Š” ๋งค๊ฐœ๋ณ€์ˆ˜ +- ๋ฉ”์„œ๋“œ ๋™์ž‘์„ ๋ณ€๊ฒฝํ•˜๋Š” boolean ํ”Œ๋ž˜๊ทธ +- Null/undefined๊ฐ€ ์ž์ฃผ ์ „๋‹ฌ๋จ + +**์™œ ๋‚˜์œ๊ฐ€:** +- ์˜ฌ๋ฐ”๋ฅด๊ฒŒ ํ˜ธ์ถœํ•˜๊ธฐ ์–ด๋ ค์›€ +- ๋งค๊ฐœ๋ณ€์ˆ˜ ์ˆœ์„œ ํ˜ผ๋ž€ +- ๋ฉ”์„œ๋“œ๊ฐ€ ๋„ˆ๋ฌด ๋งŽ์€ ์ผ์„ ํ•˜๊ณ  ์žˆ์Œ์„ ๋‚˜ํƒ€๋ƒ„ +- ์ƒˆ๋กœ์šด ๋งค๊ฐœ๋ณ€์ˆ˜ ์ถ”๊ฐ€๊ฐ€ ์–ด๋ ค์›€ + +**๋ฆฌํŒฉํ„ฐ๋ง:** +- Introduce Parameter Object (๋งค๊ฐœ๋ณ€์ˆ˜ ๊ฐ์ฒด ๋„์ž…) +- Preserve Whole Object (๊ฐ์ฒด ์ „์ฒด ์œ ์ง€) +- Replace Parameter with Method Call (๋งค๊ฐœ๋ณ€์ˆ˜๋ฅผ ๋ฉ”์„œ๋“œ ํ˜ธ์ถœ๋กœ ์ „ํ™˜) +- Remove Flag Argument (ํ”Œ๋ž˜๊ทธ ๋งค๊ฐœ๋ณ€์ˆ˜ ์ œ๊ฑฐ) + +**์˜ˆ์‹œ (์ด์ „):** +```javascript +function createUser(firstName, lastName, email, phone, + street, city, state, zip, + isAdmin, isActive, createdBy) { + // ... +} +``` + +**์˜ˆ์‹œ (์ดํ›„):** +```javascript +function createUser(personalInfo, address, options) { + // personalInfo: { firstName, lastName, email, phone } + // address: { street, city, state, zip } + // options: { isAdmin, isActive, createdBy } +} +``` + +--- + +### ๋ฐ์ดํ„ฐ ๋ญ‰์น˜ (Data Clumps) + +**์ง•ํ›„:** +- ๋™์ผํ•œ 3๊ฐœ ์ด์ƒ์˜ ํ•„๋“œ๊ฐ€ ๋ฐ˜๋ณต์ ์œผ๋กœ ํ•จ๊ป˜ ๋‚˜ํƒ€๋‚จ +- ํ•ญ์ƒ ํ•จ๊ป˜ ์ „๋‹ฌ๋˜๋Š” ๋งค๊ฐœ๋ณ€์ˆ˜ +- ํ•จ๊ป˜ ์†ํ•ด์•ผ ํ•  ํ•„๋“œ๋“ค์˜ ๋ถ€๋ถ„ ์ง‘ํ•ฉ์„ ๊ฐ€์ง„ ํด๋ž˜์Šค + +**์™œ ๋‚˜์œ๊ฐ€:** +- ์ค‘๋ณต๋œ ์ฒ˜๋ฆฌ ๋กœ์ง +- ์ถ”์ƒํ™” ๋ˆ„๋ฝ +- ํ™•์žฅํ•˜๊ธฐ ์–ด๋ ค์›€ +- ์ˆจ๊ฒจ์ง„ ํด๋ž˜์Šค๋ฅผ ๋‚˜ํƒ€๋ƒ„ + +**๋ฆฌํŒฉํ„ฐ๋ง:** +- Extract Class (ํด๋ž˜์Šค ์ถ”์ถœ) +- Introduce Parameter Object (๋งค๊ฐœ๋ณ€์ˆ˜ ๊ฐ์ฒด ๋„์ž…) +- Preserve Whole Object (๊ฐ์ฒด ์ „์ฒด ์œ ์ง€) + +**์˜ˆ์‹œ:** +```javascript +// Data clump: (x, y, z) coordinates +function movePoint(x, y, z, dx, dy, dz) { } +function scalePoint(x, y, z, factor) { } +function distanceBetween(x1, y1, z1, x2, y2, z2) { } + +// Extract Point3D class +class Point3D { + constructor(x, y, z) { } + move(delta) { } + scale(factor) { } + distanceTo(other) { } +} +``` + +--- + +## ๊ฐ์ฒด ์ง€ํ–ฅ ์›์น™ ์œ„๋ฐ˜ (Object-Orientation Abusers) + +๊ฐ์ฒด ์ง€ํ–ฅ ํ”„๋กœ๊ทธ๋ž˜๋ฐ ์›์น™์˜ ๋ถˆ์™„์ „ํ•˜๊ฑฐ๋‚˜ ์ž˜๋ชป๋œ ์‚ฌ์šฉ์„ ๋‚˜ํƒ€๋‚ด๋Š” ์Šค๋ฉœ์ž…๋‹ˆ๋‹ค. + +### Switch ๋ฌธ (Switch Statements) + +**์ง•ํ›„:** +- ๊ธด switch/case ๋˜๋Š” if/else ์ฒด์ธ +- ์—ฌ๋Ÿฌ ๊ณณ์—์„œ ๋™์ผํ•œ switch ๋ฌธ ์‚ฌ์šฉ +- ํƒ€์ž… ์ฝ”๋“œ์— ๋Œ€ํ•œ switch ๋ฌธ +- ์ƒˆ๋กœ์šด case ์ถ”๊ฐ€ ์‹œ ๋ชจ๋“  ๊ณณ์—์„œ ๋ณ€๊ฒฝ ํ•„์š” + +**์™œ ๋‚˜์œ๊ฐ€:** +- ๊ฐœ๋ฐฉ/ํ์‡„ ์›์น™ ์œ„๋ฐ˜ +- ๋ณ€๊ฒฝ ์‚ฌํ•ญ์ด ๋ชจ๋“  switch ์œ„์น˜์— ํŒŒ๊ธ‰๋จ +- ํ™•์žฅํ•˜๊ธฐ ์–ด๋ ค์›€ +- ์ข…์ข… ๋‹คํ˜•์„ฑ ๋ˆ„๋ฝ์„ ๋‚˜ํƒ€๋ƒ„ + +**๋ฆฌํŒฉํ„ฐ๋ง:** +- Replace Conditional with Polymorphism (์กฐ๊ฑด๋ฌธ์„ ๋‹คํ˜•์„ฑ์œผ๋กœ ์ „ํ™˜) +- Replace Type Code with Subclasses (ํƒ€์ž… ์ฝ”๋“œ๋ฅผ ์„œ๋ธŒํด๋ž˜์Šค๋กœ ์ „ํ™˜) +- Replace Type Code with State/Strategy (ํƒ€์ž… ์ฝ”๋“œ๋ฅผ ์ƒํƒœ/์ „๋žต ํŒจํ„ด์œผ๋กœ ์ „ํ™˜) + +**์˜ˆ์‹œ (์ด์ „):** +```javascript +function calculatePay(employee) { + switch (employee.type) { + case 'hourly': + return employee.hours * employee.rate; + case 'salaried': + return employee.salary / 12; + case 'commissioned': + return employee.sales * employee.commission; + } +} +``` + +**์˜ˆ์‹œ (์ดํ›„):** +```javascript +class HourlyEmployee { + calculatePay() { + return this.hours * this.rate; + } +} + +class SalariedEmployee { + calculatePay() { + return this.salary / 12; + } +} +``` + +--- + +### ์ž„์‹œ ํ•„๋“œ (Temporary Field) + +**์ง•ํ›„:** +- ์ผ๋ถ€ ๋ฉ”์„œ๋“œ์—์„œ๋งŒ ์‚ฌ์šฉ๋˜๋Š” ์ธ์Šคํ„ด์Šค ๋ณ€์ˆ˜ +- ์กฐ๊ฑด๋ถ€๋กœ ์„ค์ •๋˜๋Š” ํ•„๋“œ +- ํŠน์ • ๊ฒฝ์šฐ์— ๋Œ€ํ•œ ๋ณต์žกํ•œ ์ดˆ๊ธฐํ™” + +**์™œ ๋‚˜์œ๊ฐ€:** +- ํ˜ผ๋ž€์Šค๋Ÿฌ์›€โ€”ํ•„๋“œ๊ฐ€ ์กด์žฌํ•˜์ง€๋งŒ null์ผ ์ˆ˜ ์žˆ์Œ +- ๊ฐ์ฒด ์ƒํƒœ๋ฅผ ์ดํ•ดํ•˜๊ธฐ ์–ด๋ ค์›€ +- ์กฐ๊ฑด๋ถ€ ๋กœ์ง์ด ์ˆจ์–ด ์žˆ์Œ์„ ๋‚˜ํƒ€๋ƒ„ + +**๋ฆฌํŒฉํ„ฐ๋ง:** +- Extract Class (ํด๋ž˜์Šค ์ถ”์ถœ) +- Introduce Null Object (๋„ ๊ฐ์ฒด ๋„์ž…) +- Replace Temp Field with Local (์ž„์‹œ ํ•„๋“œ๋ฅผ ์ง€์—ญ ๋ณ€์ˆ˜๋กœ ์ „ํ™˜) + +--- + +### ์ƒ์† ๊ฑฐ๋ถ€ (Refused Bequest) + +**์ง•ํ›„:** +- ์„œ๋ธŒํด๋ž˜์Šค๊ฐ€ ์ƒ์†๋œ ๋ฉ”์„œ๋“œ/๋ฐ์ดํ„ฐ๋ฅผ ์‚ฌ์šฉํ•˜์ง€ ์•Š์Œ +- ์„œ๋ธŒํด๋ž˜์Šค๊ฐ€ ์•„๋ฌด๊ฒƒ๋„ ํ•˜์ง€ ์•Š๋„๋ก ์˜ค๋ฒ„๋ผ์ด๋“œํ•จ +- ์ฝ”๋“œ ์žฌ์‚ฌ์šฉ์„ ์œ„ํ•ด ์ƒ์†์„ ์‚ฌ์šฉํ•˜๊ณ , IS-A ๊ด€๊ณ„๊ฐ€ ์•„๋‹˜ + +**์™œ ๋‚˜์œ๊ฐ€:** +- ์ž˜๋ชป๋œ ์ถ”์ƒํ™” +- ๋ฆฌ์Šค์ฝ”ํ”„ ์น˜ํ™˜ ์›์น™ ์œ„๋ฐ˜ +- ์˜คํ•ด์˜ ์†Œ์ง€๊ฐ€ ์žˆ๋Š” ๊ณ„์ธต ๊ตฌ์กฐ + +**๋ฆฌํŒฉํ„ฐ๋ง:** +- Push Down Method/Field (๋ฉ”์„œ๋“œ/ํ•„๋“œ ์•„๋ž˜๋กœ ํ‘ธ์‹œ๋‹ค์šด) +- Replace Subclass with Delegate (์„œ๋ธŒํด๋ž˜์Šค๋ฅผ ์œ„์ž„์œผ๋กœ ์ „ํ™˜) +- Replace Inheritance with Delegation (์ƒ์†์„ ์œ„์ž„์œผ๋กœ ์ „ํ™˜) + +--- + +### ๋‹ค๋ฅธ ์ธํ„ฐํŽ˜์ด์Šค๋ฅผ ๊ฐ€์ง„ ๋Œ€์ฒด ํด๋ž˜์Šค (Alternative Classes with Different Interfaces) + +**์ง•ํ›„:** +- ์œ ์‚ฌํ•œ ์ž‘์—…์„ ์ˆ˜ํ–‰ํ•˜๋Š” ๋‘ ๊ฐœ์˜ ํด๋ž˜์Šค +- ๋™์ผํ•œ ๊ฐœ๋…์— ๋Œ€ํ•ด ๋‹ค๋ฅธ ๋ฉ”์„œ๋“œ ์ด๋ฆ„ +- ์ƒํ˜ธ ๊ตํ™˜์ ์œผ๋กœ ์‚ฌ์šฉ๋  ์ˆ˜ ์žˆ์Œ + +**์™œ ๋‚˜์œ๊ฐ€:** +- ์ค‘๋ณต๋œ ๊ตฌํ˜„ +- ๊ณตํ†ต ์ธํ„ฐํŽ˜์ด์Šค ๋ถ€์žฌ +- ์ „ํ™˜ํ•˜๊ธฐ ์–ด๋ ค์›€ + +**๋ฆฌํŒฉํ„ฐ๋ง:** +- Rename Method (๋ฉ”์„œ๋“œ ์ด๋ฆ„ ๋ณ€๊ฒฝ) +- Move Method (๋ฉ”์„œ๋“œ ์ด๋™) +- Extract Superclass (์Šˆํผํด๋ž˜์Šค ์ถ”์ถœ) +- Extract Interface (์ธํ„ฐํŽ˜์ด์Šค ์ถ”์ถœ) + +--- + +## ๋ณ€๊ฒฝ ๋ฐฉํ•ด ์š”์†Œ (Change Preventers) + +๋ณ€๊ฒฝ์„ ์–ด๋ ต๊ฒŒ ๋งŒ๋“œ๋Š” ์Šค๋ฉœโ€”ํ•˜๋‚˜๋ฅผ ๋ณ€๊ฒฝํ•˜๋ฉด ๋‹ค๋ฅธ ๋งŽ์€ ๊ฒƒ์„ ๋ณ€๊ฒฝํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. + +### ๋ฐœ์‚ฐ์  ๋ณ€๊ฒฝ (Divergent Change) + +**์ง•ํ›„:** +- ์—ฌ๋Ÿฌ ๊ฐ€์ง€ ๋‹ค๋ฅธ ์ด์œ ๋กœ ํ•˜๋‚˜์˜ ํด๋ž˜์Šค๊ฐ€ ๋ณ€๊ฒฝ๋จ +- ๋‹ค๋ฅธ ์˜์—ญ์˜ ๋ณ€๊ฒฝ์ด ๋™์ผํ•œ ํด๋ž˜์Šค ํŽธ์ง‘์„ ์œ ๋ฐœ +- ํด๋ž˜์Šค๊ฐ€ "์‹ (็ฅž) ํด๋ž˜์Šค"์ž„ + +**์™œ ๋‚˜์œ๊ฐ€:** +- ๋‹จ์ผ ์ฑ…์ž„ ์›์น™ ์œ„๋ฐ˜ +- ๋†’์€ ๋ณ€๊ฒฝ ๋นˆ๋„ +- ๋ณ‘ํ•ฉ ์ถฉ๋Œ + +**๋ฆฌํŒฉํ„ฐ๋ง:** +- Extract Class (ํด๋ž˜์Šค ์ถ”์ถœ) +- Extract Superclass (์Šˆํผํด๋ž˜์Šค ์ถ”์ถœ) +- Extract Subclass (์„œ๋ธŒํด๋ž˜์Šค ์ถ”์ถœ) + +**์˜ˆ์‹œ:** +`User` ํด๋ž˜์Šค๊ฐ€ ๋‹ค์Œ ์ด์œ ๋กœ ๋ณ€๊ฒฝ๋ฉ๋‹ˆ๋‹ค: +- ์ธ์ฆ ๋ณ€๊ฒฝ +- ํ”„๋กœํ•„ ๋ณ€๊ฒฝ +- ๊ฒฐ์ œ ๋ณ€๊ฒฝ +- ์•Œ๋ฆผ ๋ณ€๊ฒฝ + +โ†’ ์ถ”์ถœ: `AuthService`, `ProfileService`, `BillingService`, `NotificationService` + +--- + +### ์‚ฐํƒ„์ด ์ˆ˜์ˆ  (Shotgun Surgery) + +**์ง•ํ›„:** +- ํ•˜๋‚˜์˜ ๋ณ€๊ฒฝ์ด ๋งŽ์€ ํด๋ž˜์Šค์—์„œ ํŽธ์ง‘์„ ์š”๊ตฌํ•จ +- ์ž‘์€ ๊ธฐ๋Šฅ์ด 10๊ฐœ ์ด์ƒ์˜ ํŒŒ์ผ์„ ๊ฑด๋“œ๋ ค์•ผ ํ•จ +- ๋ณ€๊ฒฝ ์‚ฌํ•ญ์ด ํฉ์–ด์ ธ ์žˆ์–ด ๋ชจ๋‘ ์ฐพ๊ธฐ ์–ด๋ ค์›€ + +**์™œ ๋‚˜์œ๊ฐ€:** +- ํ•œ ๋ถ€๋ถ„์„ ๋†“์น˜๊ธฐ ์‰ฌ์›€ +- ๋†’์€ ๊ฒฐํ•ฉ๋„ +- ๋ณ€๊ฒฝ ์‹œ ์˜ค๋ฅ˜ ๋ฐœ์ƒ ๊ฐ€๋Šฅ์„ฑ์ด ๋†’์Œ + +**๋ฆฌํŒฉํ„ฐ๋ง:** +- Move Method (๋ฉ”์„œ๋“œ ์ด๋™) +- Move Field (ํ•„๋“œ ์ด๋™) +- Inline Class (ํด๋ž˜์Šค ์ธ๋ผ์ธํ™”) + +**ํƒ์ง€:** +๋‹ค์Œ์„ ์ฐพ์Šต๋‹ˆ๋‹ค: ํ•„๋“œ ํ•˜๋‚˜๋ฅผ ์ถ”๊ฐ€ํ•˜๋Š” ๋ฐ 5๊ฐœ ์ด์ƒ์˜ ํŒŒ์ผ์—์„œ ๋ณ€๊ฒฝ์ด ํ•„์š”ํ•œ ๊ฒฝ์šฐ. + +--- + +### ๋ณ‘๋ ฌ ์ƒ์† ๊ณ„์ธต (Parallel Inheritance Hierarchies) + +**์ง•ํ›„:** +- ํ•œ ๊ณ„์ธต์—์„œ ์„œ๋ธŒํด๋ž˜์Šค๋ฅผ ์ƒ์„ฑํ•˜๋ฉด ๋‹ค๋ฅธ ๊ณ„์ธต์—์„œ๋„ ์„œ๋ธŒํด๋ž˜์Šค๋ฅผ ์ƒ์„ฑํ•ด์•ผ ํ•จ +- ํด๋ž˜์Šค ์ ‘๋‘์‚ฌ๊ฐ€ ์ผ์น˜ํ•จ (์˜ˆ: `DatabaseOrder`, `DatabaseProduct`) + +**์™œ ๋‚˜์œ๊ฐ€:** +- ๋‘ ๋ฐฐ์˜ ์œ ์ง€ ๋ณด์ˆ˜ +- ๊ณ„์ธต ๊ฐ„์˜ ๊ฒฐํ•ฉ +- ํ•œ์ชฝ์„ ์žŠ์–ด๋ฒ„๋ฆฌ๊ธฐ ์‰ฌ์›€ + +**๋ฆฌํŒฉํ„ฐ๋ง:** +- Move Method (๋ฉ”์„œ๋“œ ์ด๋™) +- Move Field (ํ•„๋“œ ์ด๋™) +- Eliminate one hierarchy (ํ•œ ๊ณ„์ธต ์ œ๊ฑฐ) + +--- + +## ๋ถˆํ•„์š”ํ•œ ์š”์†Œ (Dispensables) + +์ œ๊ฑฐ๋˜์–ด์•ผ ํ•  ๋ถˆํ•„์š”ํ•œ ๊ฒƒ์ž…๋‹ˆ๋‹ค. + +### ์ฃผ์„ (๊ณผ๋„ํ•œ) (Comments (Excessive)) + +**์ง•ํ›„:** +- ์ฝ”๋“œ๊ฐ€ ๋ฌด์—‡์„ ํ•˜๋Š”์ง€ ์„ค๋ช…ํ•˜๋Š” ์ฃผ์„ +- ์ฃผ์„ ์ฒ˜๋ฆฌ๋œ ์ฝ”๋“œ +- ์˜์›ํžˆ ๋‚จ์•„ ์žˆ๋Š” TODO/FIXME +- ์ฃผ์„ ๋‚ด์˜ ์‚ฌ๊ณผ๋ฌธ + +**์™œ ๋‚˜์œ๊ฐ€:** +- ์ฃผ์„์ด ๊ฑฐ์ง“๋ง์„ ํ•จ (๋™๊ธฐํ™”๋˜์ง€ ์•Š์Œ) +- ์ฝ”๋“œ๋Š” ์ž์ฒด์ ์œผ๋กœ ์„ค๋ช…๋˜์–ด์•ผ ํ•จ +- ์ฃฝ์€ ์ฝ”๋“œ๊ฐ€ ํ˜ผ๋ž€์„ ์•ผ๊ธฐํ•จ + +**๋ฆฌํŒฉํ„ฐ๋ง:** +- Extract Method (์ด๋ฆ„์œผ๋กœ ๋ฌด์—‡์„ ํ•˜๋Š”์ง€ ์„ค๋ช…) +- Rename (์ฃผ์„ ์—†์ด ๋ช…ํ™•์„ฑ) +- Remove commented code (์ฃผ์„ ์ฒ˜๋ฆฌ๋œ ์ฝ”๋“œ ์ œ๊ฑฐ) +- Introduce Assertion (๋‹จ์–ธ๋ฌธ ๋„์ž…) + +**์ข‹์€ ์ฃผ์„ vs ๋‚˜์œ ์ฃผ์„:** +```javascript +// BAD: Explaining what +// Loop through users and check if active +for (const user of users) { + if (user.status === 'active') { } +} + +// GOOD: Explaining why +// Active users only - inactive are handled by cleanup job +const activeUsers = users.filter(u => u.isActive); +``` + +--- + +### ์ค‘๋ณต ์ฝ”๋“œ (Duplicate Code) + +**์ง•ํ›„:** +- ์—ฌ๋Ÿฌ ๊ณณ์—์„œ ๋™์ผํ•œ ์ฝ”๋“œ +- ์•ฝ๊ฐ„์˜ ๋ณ€ํ˜•์ด ์žˆ๋Š” ์œ ์‚ฌํ•œ ์ฝ”๋“œ +- ๋ณต์‚ฌ-๋ถ™์—ฌ๋„ฃ๊ธฐ ํŒจํ„ด + +**์™œ ๋‚˜์œ๊ฐ€:** +- ์—ฌ๋Ÿฌ ๊ณณ์—์„œ ๋ฒ„๊ทธ ์ˆ˜์ • ํ•„์š” +- ๋ถˆ์ผ์น˜ ์œ„ํ—˜ +- ์ฝ”๋“œ๋ฒ ์ด์Šค ๋น„๋Œ€ํ™” + +**๋ฆฌํŒฉํ„ฐ๋ง:** +- Extract Method (๋ฉ”์„œ๋“œ ์ถ”์ถœ) +- Extract Class (ํด๋ž˜์Šค ์ถ”์ถœ) +- Pull Up Method (๊ณ„์ธต ๊ตฌ์กฐ์—์„œ ๋ฉ”์„œ๋“œ ์œ„๋กœ ์˜ฌ๋ฆฌ๊ธฐ) +- Form Template Method (ํ…œํ”Œ๋ฆฟ ๋ฉ”์„œ๋“œ ํ˜•์„ฑ) + +**ํƒ์ง€ ๊ทœ์น™:** +3ํšŒ ์ด์ƒ ์ค‘๋ณต๋œ ๋ชจ๋“  ์ฝ”๋“œ๋Š” ์ถ”์ถœ๋˜์–ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. + +--- + +### ๊ฒŒ์œผ๋ฅธ ํด๋ž˜์Šค (Lazy Class) + +**์ง•ํ›„:** +- ํด๋ž˜์Šค๊ฐ€ ์กด์žฌ๋ฅผ ์ •๋‹นํ™”ํ•  ๋งŒํผ ์ถฉ๋ถ„ํžˆ ๋งŽ์€ ์ผ์„ ํ•˜์ง€ ์•Š์Œ +- ์ถ”๊ฐ€๋œ ๊ฐ€์น˜๊ฐ€ ์—†๋Š” ๋ž˜ํผ +- ๊ณผ๋„ํ•œ ์„ค๊ณ„์˜ ๊ฒฐ๊ณผ + +**์™œ ๋‚˜์œ๊ฐ€:** +- ์œ ์ง€ ๋ณด์ˆ˜ ์˜ค๋ฒ„ํ—ค๋“œ +- ๋ถˆํ•„์š”ํ•œ ๊ฐ„์ ‘์„ฑ +- ์ด์  ์—†๋Š” ๋ณต์žก์„ฑ + +**๋ฆฌํŒฉํ„ฐ๋ง:** +- Inline Class (ํด๋ž˜์Šค ์ธ๋ผ์ธํ™”) +- Collapse Hierarchy (๊ณ„์ธต ๊ตฌ์กฐ ์ถ•์†Œ) + +--- + +### ์ฃฝ์€ ์ฝ”๋“œ (Dead Code) + +**์ง•ํ›„:** +- ๋„๋‹ฌํ•  ์ˆ˜ ์—†๋Š” ์ฝ”๋“œ +- ์‚ฌ์šฉ๋˜์ง€ ์•Š๋Š” ๋ณ€์ˆ˜/๋ฉ”์„œ๋“œ/ํด๋ž˜์Šค +- ์ฃผ์„ ์ฒ˜๋ฆฌ๋œ ์ฝ”๋“œ +- ๋ถˆ๊ฐ€๋Šฅํ•œ ์กฐ๊ฑด ๋’ค์— ์žˆ๋Š” ์ฝ”๋“œ + +**์™œ ๋‚˜์œ๊ฐ€:** +- ํ˜ผ๋ž€ +- ์œ ์ง€ ๋ณด์ˆ˜ ๋ถ€๋‹ด +- ์ดํ•ด ์†๋„ ์ €ํ•˜ + +**๋ฆฌํŒฉํ„ฐ๋ง:** +- Remove Dead Code (์ฃฝ์€ ์ฝ”๋“œ ์ œ๊ฑฐ) +- Safe Delete (์•ˆ์ „ํ•˜๊ฒŒ ์‚ญ์ œ) + +**ํƒ์ง€:** +```bash +# Look for unused exports +# Look for unreferenced functions +# IDE "unused" warnings +``` + +--- + +### ์ถ”์ธก์„ฑ ์ผ๋ฐ˜ํ™” (Speculative Generality) + +**์ง•ํ›„:** +- ํ•˜๋‚˜์˜ ์„œ๋ธŒํด๋ž˜์Šค๋ฅผ ๊ฐ€์ง„ ์ถ”์ƒ ํด๋ž˜์Šค +- "๋ฏธ๋ž˜ ์‚ฌ์šฉ์„ ์œ„ํ•œ" ์‚ฌ์šฉ๋˜์ง€ ์•Š๋Š” ๋งค๊ฐœ๋ณ€์ˆ˜ +- ๋‹จ์ˆœํžˆ ์œ„์ž„ํ•˜๋Š” ๋ฉ”์„œ๋“œ +- ํ•˜๋‚˜์˜ ์‚ฌ์šฉ ์‚ฌ๋ก€๋ฅผ ์œ„ํ•œ "ํ”„๋ ˆ์ž„์›Œํฌ" + +**์™œ ๋‚˜์œ๊ฐ€:** +- ์ด์  ์—†๋Š” ๋ณต์žก์„ฑ +- YAGNI (You Ain't Gonna Need It - ํ•„์š” ์—†์„ ๊ฑฐ์•ผ) ์›์น™ ์œ„๋ฐ˜ +- ์ดํ•ดํ•˜๊ธฐ ์–ด๋ ค์›€ + +**๋ฆฌํŒฉํ„ฐ๋ง:** +- Collapse Hierarchy (๊ณ„์ธต ๊ตฌ์กฐ ์ถ•์†Œ) +- Inline Class (ํด๋ž˜์Šค ์ธ๋ผ์ธํ™”) +- Remove Parameter (๋งค๊ฐœ๋ณ€์ˆ˜ ์ œ๊ฑฐ) +- Rename Method (๋ฉ”์„œ๋“œ ์ด๋ฆ„ ๋ณ€๊ฒฝ) + +--- + +## ๊ฒฐํ•ฉ์ž (Couplers) + +ํด๋ž˜์Šค ๊ฐ„์˜ ๊ณผ๋„ํ•œ ๊ฒฐํ•ฉ์„ ๋‚˜ํƒ€๋‚ด๋Š” ์Šค๋ฉœ์ž…๋‹ˆ๋‹ค. + +### ๊ธฐ๋Šฅ ์„ ๋ง (Feature Envy) + +**์ง•ํ›„:** +- ๋ฉ”์„œ๋“œ๊ฐ€ ์ž์‹ ์˜ ํด๋ž˜์Šค๋ณด๋‹ค ๋‹ค๋ฅธ ํด๋ž˜์Šค์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๋” ๋งŽ์ด ์‚ฌ์šฉํ•จ +- ๋‹ค๋ฅธ ๊ฐ์ฒด์— ๋Œ€ํ•œ ๋งŽ์€ getter ํ˜ธ์ถœ +- ๋ฐ์ดํ„ฐ์™€ ํ–‰๋™์ด ๋ถ„๋ฆฌ๋˜์–ด ์žˆ์Œ + +**์™œ ๋‚˜์œ๊ฐ€:** +- ํ–‰๋™์ด ์ž˜๋ชป๋œ ์œ„์น˜์— ์žˆ์Œ +- ์บก์Šํ™” ๋ถˆ๋Ÿ‰ +- ์œ ์ง€ ๋ณด์ˆ˜ํ•˜๊ธฐ ์–ด๋ ค์›€ + +**๋ฆฌํŒฉํ„ฐ๋ง:** +- Move Method (๋ฉ”์„œ๋“œ ์ด๋™) +- Move Field (ํ•„๋“œ ์ด๋™) +- Extract Method (๋ฉ”์„œ๋“œ ์ถ”์ถœ ํ›„ ์ด๋™) + +**์˜ˆ์‹œ (์ด์ „):** +```javascript +class Order { + getDiscountedPrice(customer) { + // Uses customer data heavily + if (customer.loyaltyYears > 5) { + return this.price * customer.discountRate; + } + return this.price; + } +} +``` + +**์˜ˆ์‹œ (์ดํ›„):** +```javascript +class Customer { + getDiscountedPriceFor(price) { + if (this.loyaltyYears > 5) { + return price * this.discountRate; + } + return price; + } +} +``` + +--- + +### ๋ถ€์ ์ ˆํ•œ ์นœ๋ฐ€ํ•จ (Inappropriate Intimacy) + +**์ง•ํ›„:** +- ํด๋ž˜์Šค๋“ค์ด ์„œ๋กœ์˜ ๋น„๊ณต๊ฐœ ๋ถ€๋ถ„์— ์ ‘๊ทผํ•จ +- ์–‘๋ฐฉํ–ฅ ์ฐธ์กฐ +- ์„œ๋ธŒํด๋ž˜์Šค๊ฐ€ ๋ถ€๋ชจ์— ๋Œ€ํ•ด ๋„ˆ๋ฌด ๋งŽ์ด ์•Œ๊ณ  ์žˆ์Œ + +**์™œ ๋‚˜์œ๊ฐ€:** +- ๋†’์€ ๊ฒฐํ•ฉ๋„ +- ๋ณ€๊ฒฝ ์‚ฌํ•ญ์ด ์—ฐ์‡„์ ์œผ๋กœ ๋ฐœ์ƒ +- ํ•˜๋‚˜๋ฅผ ๋‹ค๋ฅธ ๊ฒƒ ์—†์ด ์ˆ˜์ •ํ•˜๊ธฐ ์–ด๋ ค์›€ + +**๋ฆฌํŒฉํ„ฐ๋ง:** +- Move Method (๋ฉ”์„œ๋“œ ์ด๋™) +- Move Field (ํ•„๋“œ ์ด๋™) +- Change Bidirectional to Unidirectional (์–‘๋ฐฉํ–ฅ ์ฐธ์กฐ๋ฅผ ๋‹จ๋ฐฉํ–ฅ์œผ๋กœ ๋ณ€๊ฒฝ) +- Extract Class (ํด๋ž˜์Šค ์ถ”์ถœ) +- Hide Delegate (์œ„์ž„ ์ˆจ๊ธฐ๊ธฐ) + +--- + +### ๋ฉ”์‹œ์ง€ ์ฒด์ธ (Message Chains) + +**์ง•ํ›„:** +- ๊ธด ๋ฉ”์„œ๋“œ ํ˜ธ์ถœ ์ฒด์ธ: `a.getB().getC().getD().getValue()` +- ํด๋ผ์ด์–ธํŠธ๊ฐ€ ํƒ์ƒ‰ ๊ตฌ์กฐ์— ์˜์กดํ•จ +- "๊ธฐ์ฐจ ํƒˆ์„ " ์ฝ”๋“œ + +**์™œ ๋‚˜์œ๊ฐ€:** +- ์ทจ์•ฝํ•จโ€”์–ด๋–ค ๋ณ€๊ฒฝ์ด๋“  ์ฒด์ธ์„ ๊นจ๋œจ๋ฆผ +- ๋ฐ๋ฉ”ํ…Œ๋ฅด์˜ ๋ฒ•์น™ ์œ„๋ฐ˜ +- ๊ตฌ์กฐ์— ๋Œ€ํ•œ ๊ฒฐํ•ฉ + +**๋ฆฌํŒฉํ„ฐ๋ง:** +- Hide Delegate (์œ„์ž„ ์ˆจ๊ธฐ๊ธฐ) +- Extract Method (๋ฉ”์„œ๋“œ ์ถ”์ถœ) +- Move Method (๋ฉ”์„œ๋“œ ์ด๋™) + +**์˜ˆ์‹œ:** +```javascript +// Bad: Message chain +const managerName = employee.getDepartment().getManager().getName(); + +// Better: Hide delegation +const managerName = employee.getManagerName(); +``` + +--- + +### ์ค‘๊ฐœ์ธ (Middle Man) + +**์ง•ํ›„:** +- ๋‹ค๋ฅธ ํด๋ž˜์Šค์— ๋‹จ์ˆœํžˆ ์œ„์ž„ํ•˜๋Š” ํด๋ž˜์Šค +- ๋ฉ”์„œ๋“œ์˜ ์ ˆ๋ฐ˜์ด ์œ„์ž„์ž„ +- ์ถ”๊ฐ€๋œ ๊ฐ€์น˜๊ฐ€ ์—†์Œ + +**์™œ ๋‚˜์œ๊ฐ€:** +- ๋ถˆํ•„์š”ํ•œ ๊ฐ„์ ‘์„ฑ +- ์œ ์ง€ ๋ณด์ˆ˜ ์˜ค๋ฒ„ํ—ค๋“œ +- ํ˜ผ๋ž€์Šค๋Ÿฌ์šด ์•„ํ‚คํ…์ฒ˜ + +**๋ฆฌํŒฉํ„ฐ๋ง:** +- Remove Middle Man (์ค‘๊ฐœ์ธ ์ œ๊ฑฐ) +- Inline Method (๋ฉ”์„œ๋“œ ์ธ๋ผ์ธํ™”) + +--- + +## ์ฝ”๋“œ ์Šค๋ฉœ ์‹ฌ๊ฐ๋„ ๊ฐ€์ด๋“œ + +| ์‹ฌ๊ฐ๋„ | ์„ค๋ช… | ์กฐ์น˜ | +|----------|-------------|--------| +| **Critical** | ๊ฐœ๋ฐœ์„ ๋ง‰๊ณ , ๋ฒ„๊ทธ๋ฅผ ์œ ๋ฐœ | ์ฆ‰์‹œ ์ˆ˜์ • | +| **High** | ์ƒ๋‹นํ•œ ์œ ์ง€ ๋ณด์ˆ˜ ๋ถ€๋‹ด | ํ˜„์žฌ ์Šคํ”„๋ฆฐํŠธ์—์„œ ์ˆ˜์ • | +| **Medium** | ๋ˆˆ์— ๋„์ง€๋งŒ ๊ด€๋ฆฌ ๊ฐ€๋Šฅ | ๊ฐ€๊นŒ์šด ๋ฏธ๋ž˜๋ฅผ ์œ„ํ•ด ๊ณ„ํš | +| **Low** | ์‚ฌ์†Œํ•œ ๋ถˆํŽธํ•จ | ๊ธฐํšŒ๊ฐ€ ์žˆ์„ ๋•Œ ์ˆ˜์ • | + +--- + +## ๋น ๋ฅธ ํƒ์ง€ ์ฒดํฌ๋ฆฌ์ŠคํŠธ + +์ฝ”๋“œ๋ฅผ ์Šค์บ”ํ•  ๋•Œ ์ด ์ฒดํฌ๋ฆฌ์ŠคํŠธ๋ฅผ ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค: + +- [ ] 30์ค„์„ ์ดˆ๊ณผํ•˜๋Š” ๋ฉ”์„œ๋“œ๊ฐ€ ์žˆ์Šต๋‹ˆ๊นŒ? +- [ ] 300์ค„์„ ์ดˆ๊ณผํ•˜๋Š” ํด๋ž˜์Šค๊ฐ€ ์žˆ์Šต๋‹ˆ๊นŒ? +- [ ] 4๊ฐœ ์ด์ƒ์˜ ๋งค๊ฐœ๋ณ€์ˆ˜๋ฅผ ๊ฐ€์ง„ ๋ฉ”์„œ๋“œ๊ฐ€ ์žˆ์Šต๋‹ˆ๊นŒ? +- [ ] ์ค‘๋ณต๋œ ์ฝ”๋“œ ๋ธ”๋ก์ด ์žˆ์Šต๋‹ˆ๊นŒ? +- [ ] ํƒ€์ž… ์ฝ”๋“œ์— ๋Œ€ํ•œ switch/case ๋ฌธ์ด ์žˆ์Šต๋‹ˆ๊นŒ? +- [ ] ์‚ฌ์šฉ๋˜์ง€ ์•Š๋Š” ์ฝ”๋“œ๊ฐ€ ์žˆ์Šต๋‹ˆ๊นŒ? +- [ ] ๋‹ค๋ฅธ ํด๋ž˜์Šค์˜ ๋ฐ์ดํ„ฐ๋ฅผ ๊ณผ๋„ํ•˜๊ฒŒ ์‚ฌ์šฉํ•˜๋Š” ๋ฉ”์„œ๋“œ๊ฐ€ ์žˆ์Šต๋‹ˆ๊นŒ? +- [ ] ๊ธด ๋ฉ”์„œ๋“œ ํ˜ธ์ถœ ์ฒด์ธ์ด ์žˆ์Šต๋‹ˆ๊นŒ? +- [ ] "์™œ"๊ฐ€ ์•„๋‹Œ "๋ฌด์—‡"์„ ์„ค๋ช…ํ•˜๋Š” ์ฃผ์„์ด ์žˆ์Šต๋‹ˆ๊นŒ? +- [ ] ๊ฐ์ฒด์—ฌ์•ผ ํ•  ์›์‹œ ํƒ€์ž…์ด ์žˆ์Šต๋‹ˆ๊นŒ? + +--- + +## ์ถ”๊ฐ€ ์ž๋ฃŒ + +- Fowler, M. (2018). *Refactoring: Improving the Design of Existing Code* (2nd ed.) +- Kerievsky, J. (2004). *Refactoring to Patterns* +- Feathers, M. (2004). *Working Effectively with Legacy Code* diff --git a/ko/03-skills/refactor/references/refactoring-catalog.md b/ko/03-skills/refactor/references/refactoring-catalog.md new file mode 100644 index 00000000..569bc7d4 --- /dev/null +++ b/ko/03-skills/refactor/references/refactoring-catalog.md @@ -0,0 +1,1023 @@ +# ๋ฆฌํŒฉํ„ฐ๋ง ์นดํƒˆ๋กœ๊ทธ + +Martin Fowler์˜ *Refactoring* (2nd Edition)์—์„œ ์—„์„ ๋œ ๋ฆฌํŒฉํ„ฐ๋ง ๊ธฐ๋ฒ• ์นดํƒˆ๋กœ๊ทธ์ž…๋‹ˆ๋‹ค. ๊ฐ ๋ฆฌํŒฉํ„ฐ๋ง์—๋Š” ๋™๊ธฐ, ๋‹จ๊ณ„๋ณ„ ๋ฉ”์ปค๋‹ˆ์ฆ˜ ๋ฐ ์˜ˆ์ œ๊ฐ€ ํฌํ•จ๋ฉ๋‹ˆ๋‹ค. + +> "๋ฆฌํŒฉํ„ฐ๋ง์€ ๊ทธ ๋ฉ”์ปค๋‹ˆ์ฆ˜์œผ๋กœ ์ •์˜๋ฉ๋‹ˆ๋‹ค. ์ฆ‰, ๋ณ€๊ฒฝ์„ ์ˆ˜ํ–‰ํ•˜๊ธฐ ์œ„ํ•ด ๋”ฐ๋ฅด๋Š” ์ •ํ™•ํ•œ ๋‹จ๊ณ„์˜ ์‹œํ€€์Šค์ž…๋‹ˆ๋‹ค." โ€” Martin Fowler + +--- + +## ์ด ์นดํƒˆ๋กœ๊ทธ๋ฅผ ์‚ฌ์šฉํ•˜๋Š” ๋ฐฉ๋ฒ• + +1. ์ฝ”๋“œ ์Šค๋ฉœ ์ฐธ์กฐ๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ **์Šค๋ฉœ์„ ์‹๋ณ„**ํ•ฉ๋‹ˆ๋‹ค. +2. ์ด ์นดํƒˆ๋กœ๊ทธ์—์„œ **์ผ์น˜ํ•˜๋Š” ๋ฆฌํŒฉํ„ฐ๋ง์„ ์ฐพ์Šต๋‹ˆ๋‹ค**. +3. **๋ฉ”์ปค๋‹ˆ์ฆ˜์„ ๋‹จ๊ณ„๋ณ„๋กœ ๋”ฐ๋ฆ…๋‹ˆ๋‹ค**. +4. ๋™์ž‘์ด ์œ ์ง€๋˜๋Š”์ง€ ํ™•์ธํ•˜๊ธฐ ์œ„ํ•ด **๊ฐ ๋‹จ๊ณ„ ํ›„ ํ…Œ์ŠคํŠธ**ํ•ฉ๋‹ˆ๋‹ค. + +**ํ™ฉ๊ธˆ๋ฅ **: ์–ด๋–ค ๋‹จ๊ณ„๋“  10๋ถ„ ์ด์ƒ ๊ฑธ๋ฆฐ๋‹ค๋ฉด, ๋” ์ž‘์€ ๋‹จ๊ณ„๋กœ ๋‚˜๋ˆ•๋‹ˆ๋‹ค. + +--- + +## ๊ฐ€์žฅ ์ผ๋ฐ˜์ ์ธ ๋ฆฌํŒฉํ„ฐ๋ง + +### ๋ฉ”์„œ๋“œ ์ถ”์ถœ (Extract Method) + +**์‚ฌ์šฉ ์‹œ์ **: ๊ธด ๋ฉ”์„œ๋“œ, ์ค‘๋ณต ์ฝ”๋“œ, ๊ฐœ๋…์— ์ด๋ฆ„์„ ๋ถ™์ผ ํ•„์š”๊ฐ€ ์žˆ์„ ๋•Œ + +**๋™๊ธฐ**: ์ฝ”๋“œ ์กฐ๊ฐ์„ ๊ทธ ๋ชฉ์ ์„ ์„ค๋ช…ํ•˜๋Š” ์ด๋ฆ„์˜ ๋ฉ”์„œ๋“œ๋กœ ๋งŒ๋“ญ๋‹ˆ๋‹ค. + +**๋ฉ”์ปค๋‹ˆ์ฆ˜**: +1. ๋ฌด์—‡์„ ํ•˜๋Š”์ง€ (์–ด๋–ป๊ฒŒ ํ•˜๋Š”์ง€๊ฐ€ ์•„๋‹˜) ๋‚˜ํƒ€๋‚ด๋Š” ์ด๋ฆ„์œผ๋กœ ์ƒˆ ๋ฉ”์„œ๋“œ๋ฅผ ๋งŒ๋“ญ๋‹ˆ๋‹ค. +2. ์ฝ”๋“œ ์กฐ๊ฐ์„ ์ƒˆ ๋ฉ”์„œ๋“œ๋กœ ๋ณต์‚ฌํ•ฉ๋‹ˆ๋‹ค. +3. ์กฐ๊ฐ์—์„œ ์‚ฌ์šฉ๋˜๋Š” ์ง€์—ญ ๋ณ€์ˆ˜๋ฅผ ์ฐพ์Šต๋‹ˆ๋‹ค. +4. ์ง€์—ญ ๋ณ€์ˆ˜๋ฅผ ๋งค๊ฐœ๋ณ€์ˆ˜๋กœ ์ „๋‹ฌํ•ฉ๋‹ˆ๋‹ค (๋˜๋Š” ๋ฉ”์„œ๋“œ ๋‚ด์—์„œ ์„ ์–ธ). +5. ๋ฐ˜ํ™˜ ๊ฐ’์„ ์ ์ ˆํžˆ ์ฒ˜๋ฆฌํ•ฉ๋‹ˆ๋‹ค. +6. ์›๋ž˜ ์กฐ๊ฐ์„ ์ƒˆ ๋ฉ”์„œ๋“œ ํ˜ธ์ถœ๋กœ ๋Œ€์ฒดํ•ฉ๋‹ˆ๋‹ค. +7. ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. + +**์ด์ „**: +```javascript +function printOwing(invoice) { + let outstanding = 0; + + console.log("***********************"); + console.log("**** Customer Owes ****"); + console.log("***********************"); + + // Calculate outstanding + for (const order of invoice.orders) { + outstanding += order.amount; + } + + // Print details + console.log(`name: ${invoice.customer}`); + console.log(`amount: ${outstanding}`); +} +``` + +**์ดํ›„**: +```javascript +function printOwing(invoice) { + printBanner(); + const outstanding = calculateOutstanding(invoice); + printDetails(invoice, outstanding); +} + +function printBanner() { + console.log("***********************"); + console.log("**** Customer Owes ****"); + console.log("***********************"); +} + +function calculateOutstanding(invoice) { + return invoice.orders.reduce((sum, order) => sum + order.amount, 0); +} + +function printDetails(invoice, outstanding) { + console.log(`name: ${invoice.customer}`); + console.log(`amount: ${outstanding}`); +} +``` + +--- + +### ๋ฉ”์„œ๋“œ ์ธ๋ผ์ธ (Inline Method) + +**์‚ฌ์šฉ ์‹œ์ **: ๋ฉ”์„œ๋“œ ๋ณธ๋ฌธ์ด ์ด๋ฆ„๋งŒํผ ๋ช…ํ™•ํ•  ๋•Œ, ๊ณผ๋„ํ•œ ์œ„์ž„์ด ์žˆ์„ ๋•Œ + +**๋™๊ธฐ**: ๋ฉ”์„œ๋“œ๊ฐ€ ๊ฐ€์น˜๋ฅผ ๋”ํ•˜์ง€ ์•Š์„ ๋•Œ ๋ถˆํ•„์š”ํ•œ ๊ฐ„์ ‘ํ™”๋ฅผ ์ œ๊ฑฐํ•ฉ๋‹ˆ๋‹ค. + +**๋ฉ”์ปค๋‹ˆ์ฆ˜**: +1. ๋ฉ”์„œ๋“œ๊ฐ€ ๋‹คํ˜•์ ์ด์ง€ ์•Š์€์ง€ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. +2. ๋ฉ”์„œ๋“œ์— ๋Œ€ํ•œ ๋ชจ๋“  ํ˜ธ์ถœ์„ ์ฐพ์Šต๋‹ˆ๋‹ค. +3. ๊ฐ ํ˜ธ์ถœ์„ ๋ฉ”์„œ๋“œ ๋ณธ๋ฌธ์œผ๋กœ ๋Œ€์ฒดํ•ฉ๋‹ˆ๋‹ค. +4. ๊ฐ ๊ต์ฒด ํ›„ ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. +5. ๋ฉ”์„œ๋“œ ์ •์˜๋ฅผ ์ œ๊ฑฐํ•ฉ๋‹ˆ๋‹ค. + +**์ด์ „**: +```javascript +function getRating(driver) { + return moreThanFiveLateDeliveries(driver) ? 2 : 1; +} + +function moreThanFiveLateDeliveries(driver) { + return driver.numberOfLateDeliveries > 5; +} +``` + +**์ดํ›„**: +```javascript +function getRating(driver) { + return driver.numberOfLateDeliveries > 5 ? 2 : 1; +} +``` + +--- + +### ๋ณ€์ˆ˜ ์ถ”์ถœ (Extract Variable) + +**์‚ฌ์šฉ ์‹œ์ **: ์ดํ•ดํ•˜๊ธฐ ์–ด๋ ค์šด ๋ณต์žกํ•œ ํ‘œํ˜„์‹์ด ์žˆ์„ ๋•Œ + +**๋™๊ธฐ**: ๋ณต์žกํ•œ ํ‘œํ˜„์‹์˜ ์ผ๋ถ€์— ์ด๋ฆ„์„ ๋ถ€์—ฌํ•ฉ๋‹ˆ๋‹ค. + +**๋ฉ”์ปค๋‹ˆ์ฆ˜**: +1. ํ‘œํ˜„์‹์— ๋ถ€์ž‘์šฉ์ด ์—†๋Š”์ง€ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. +2. ๋ถˆ๋ณ€ ๋ณ€์ˆ˜๋ฅผ ์„ ์–ธํ•ฉ๋‹ˆ๋‹ค. +3. ํ‘œํ˜„์‹ (๋˜๋Š” ์ผ๋ถ€)์˜ ๊ฒฐ๊ณผ๋กœ ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค. +4. ์›๋ž˜ ํ‘œํ˜„์‹์„ ๋ณ€์ˆ˜๋กœ ๋Œ€์ฒดํ•ฉ๋‹ˆ๋‹ค. +5. ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. + +**์ด์ „**: +```javascript +return order.quantity * order.itemPrice - + Math.max(0, order.quantity - 500) * order.itemPrice * 0.05 + + Math.min(order.quantity * order.itemPrice * 0.1, 100); +``` + +**์ดํ›„**: +```javascript +const basePrice = order.quantity * order.itemPrice; +const quantityDiscount = Math.max(0, order.quantity - 500) * order.itemPrice * 0.05; +const shipping = Math.min(basePrice * 0.1, 100); +return basePrice - quantityDiscount + shipping; +``` + +--- + +### ๋ณ€์ˆ˜ ์ธ๋ผ์ธ (Inline Variable) + +**์‚ฌ์šฉ ์‹œ์ **: ๋ณ€์ˆ˜ ์ด๋ฆ„์ด ํ‘œํ˜„์‹๋ณด๋‹ค ๋” ๋งŽ์€ ๊ฒƒ์„ ์ „๋‹ฌํ•˜์ง€ ์•Š์„ ๋•Œ + +**๋™๊ธฐ**: ๋ถˆํ•„์š”ํ•œ ๊ฐ„์ ‘ํ™”๋ฅผ ์ œ๊ฑฐํ•ฉ๋‹ˆ๋‹ค. + +**๋ฉ”์ปค๋‹ˆ์ฆ˜**: +1. ์šฐ์ธก ๋ณ€์ˆ˜์— ๋ถ€์ž‘์šฉ์ด ์—†๋Š”์ง€ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. +2. ๋ณ€์ˆ˜๊ฐ€ ๋ถˆ๋ณ€์ด ์•„๋‹ˆ๋ผ๋ฉด, ๋ถˆ๋ณ€์œผ๋กœ ๋งŒ๋“ค๊ณ  ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. +3. ์ฒซ ๋ฒˆ์งธ ์ฐธ์กฐ๋ฅผ ์ฐพ์•„ ํ‘œํ˜„์‹์œผ๋กœ ๋Œ€์ฒดํ•ฉ๋‹ˆ๋‹ค. +4. ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. +5. ๋ชจ๋“  ์ฐธ์กฐ์— ๋Œ€ํ•ด ๋ฐ˜๋ณตํ•ฉ๋‹ˆ๋‹ค. +6. ์„ ์–ธ๊ณผ ํ• ๋‹น์„ ์ œ๊ฑฐํ•ฉ๋‹ˆ๋‹ค. +7. ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. + +--- + +### ๋ณ€์ˆ˜ ์ด๋ฆ„ ๋ณ€๊ฒฝ (Rename Variable) + +**์‚ฌ์šฉ ์‹œ์ **: ์ด๋ฆ„์ด ๋ชฉ์ ์„ ๋ช…ํ™•ํ•˜๊ฒŒ ์ „๋‹ฌํ•˜์ง€ ์•Š์„ ๋•Œ + +**๋™๊ธฐ**: ์ข‹์€ ์ด๋ฆ„์€ ๊น”๋”ํ•œ ์ฝ”๋“œ๋ฅผ ์œ„ํ•ด ๋งค์šฐ ์ค‘์š”ํ•ฉ๋‹ˆ๋‹ค. + +**๋ฉ”์ปค๋‹ˆ์ฆ˜**: +1. ๋ณ€์ˆ˜๊ฐ€ ๋„๋ฆฌ ์‚ฌ์šฉ๋˜๋Š” ๊ฒฝ์šฐ, ์บก์Šํ™”๋ฅผ ๊ณ ๋ คํ•ฉ๋‹ˆ๋‹ค. +2. ๋ชจ๋“  ์ฐธ์กฐ๋ฅผ ์ฐพ์Šต๋‹ˆ๋‹ค. +3. ๊ฐ ์ฐธ์กฐ๋ฅผ ๋ณ€๊ฒฝํ•ฉ๋‹ˆ๋‹ค. +4. ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. + +**ํŒ**: +- ์˜๋„๋ฅผ ๋“œ๋Ÿฌ๋‚ด๋Š” ์ด๋ฆ„์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +- ์•ฝ์–ด๋ฅผ ํ”ผํ•ฉ๋‹ˆ๋‹ค. +- ๋„๋ฉ”์ธ ์šฉ์–ด๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + +```javascript +// Bad +const d = 30; +const x = users.filter(u => u.a); + +// Good +const daysSinceLastLogin = 30; +const activeUsers = users.filter(user => user.isActive); +``` + +--- + +### ํ•จ์ˆ˜ ์„ ์–ธ ๋ณ€๊ฒฝ (Change Function Declaration) + +**์‚ฌ์šฉ ์‹œ์ **: ํ•จ์ˆ˜ ์ด๋ฆ„์ด ๋ชฉ์ ์„ ์„ค๋ช…ํ•˜์ง€ ์•Š์„ ๋•Œ, ๋งค๊ฐœ๋ณ€์ˆ˜ ๋ณ€๊ฒฝ์ด ํ•„์š”ํ•  ๋•Œ + +**๋™๊ธฐ**: ์ข‹์€ ํ•จ์ˆ˜ ์ด๋ฆ„์€ ์ฝ”๋“œ๋ฅผ ์ž์ฒด ๋ฌธ์„œํ™”ํ•ฉ๋‹ˆ๋‹ค. + +**๋ฉ”์ปค๋‹ˆ์ฆ˜ (๋‹จ์ˆœ)**: +1. ํ•„์š” ์—†๋Š” ๋งค๊ฐœ๋ณ€์ˆ˜๋ฅผ ์ œ๊ฑฐํ•ฉ๋‹ˆ๋‹ค. +2. ์ด๋ฆ„์„ ๋ณ€๊ฒฝํ•ฉ๋‹ˆ๋‹ค. +3. ํ•„์š”ํ•œ ๋งค๊ฐœ๋ณ€์ˆ˜๋ฅผ ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค. +4. ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. + +**๋ฉ”์ปค๋‹ˆ์ฆ˜ (๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ - ๋ณต์žกํ•œ ๋ณ€๊ฒฝ์˜ ๊ฒฝ์šฐ)**: +1. ๋งค๊ฐœ๋ณ€์ˆ˜๋ฅผ ์ œ๊ฑฐํ•˜๋Š” ๊ฒฝ์šฐ, ์‚ฌ์šฉ๋˜์ง€ ์•Š๋Š”์ง€ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. +2. ์›ํ•˜๋Š” ์„ ์–ธ์œผ๋กœ ์ƒˆ ํ•จ์ˆ˜๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. +3. ์ด์ „ ํ•จ์ˆ˜๊ฐ€ ์ƒˆ ํ•จ์ˆ˜๋ฅผ ํ˜ธ์ถœํ•˜๋„๋ก ํ•ฉ๋‹ˆ๋‹ค. +4. ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. +5. ํ˜ธ์ถœ์ž๊ฐ€ ์ƒˆ ํ•จ์ˆ˜๋ฅผ ์‚ฌ์šฉํ•˜๋„๋ก ๋ณ€๊ฒฝํ•ฉ๋‹ˆ๋‹ค. +6. ๊ฐ ๋ณ€๊ฒฝ ํ›„ ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. +7. ์ด์ „ ํ•จ์ˆ˜๋ฅผ ์ œ๊ฑฐํ•ฉ๋‹ˆ๋‹ค. + +**์ด์ „**: +```javascript +function circum(radius) { + return 2 * Math.PI * radius; +} +``` + +**์ดํ›„**: +```javascript +function circumference(radius) { + return 2 * Math.PI * radius; +} +``` + +--- + +### ๋ณ€์ˆ˜ ์บก์Šํ™” (Encapsulate Variable) + +**์‚ฌ์šฉ ์‹œ์ **: ์—ฌ๋Ÿฌ ๊ณณ์—์„œ ๋ฐ์ดํ„ฐ์— ์ง์ ‘ ์ ‘๊ทผํ•  ๋•Œ + +**๋™๊ธฐ**: ๋ฐ์ดํ„ฐ ์กฐ์ž‘์„ ์œ„ํ•œ ๋ช…ํ™•ํ•œ ์ ‘๊ทผ ์ง€์ ์„ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. + +**๋ฉ”์ปค๋‹ˆ์ฆ˜**: +1. getter ๋ฐ setter ํ•จ์ˆ˜๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. +2. ๋ชจ๋“  ์ฐธ์กฐ๋ฅผ ์ฐพ์Šต๋‹ˆ๋‹ค. +3. ์ฝ๊ธฐ๋ฅผ getter๋กœ ๋Œ€์ฒดํ•ฉ๋‹ˆ๋‹ค. +4. ์“ฐ๊ธฐ๋ฅผ setter๋กœ ๋Œ€์ฒดํ•ฉ๋‹ˆ๋‹ค. +5. ๊ฐ ๋ณ€๊ฒฝ ํ›„ ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. +6. ๋ณ€์ˆ˜์˜ ๊ฐ€์‹œ์„ฑ์„ ์ œํ•œํ•ฉ๋‹ˆ๋‹ค. + +**์ด์ „**: +```javascript +let defaultOwner = { firstName: "Martin", lastName: "Fowler" }; + +// Used in many places +spaceship.owner = defaultOwner; +``` + +**์ดํ›„**: +```javascript +let defaultOwnerData = { firstName: "Martin", lastName: "Fowler" }; + +function defaultOwner() { return defaultOwnerData; } +function setDefaultOwner(arg) { defaultOwnerData = arg; } + +spaceship.owner = defaultOwner(); +``` + +--- + +### ๋งค๊ฐœ๋ณ€์ˆ˜ ๊ฐ์ฒด ๋„์ž… (Introduce Parameter Object) + +**์‚ฌ์šฉ ์‹œ์ **: ์ž์ฃผ ํ•จ๊ป˜ ์‚ฌ์šฉ๋˜๋Š” ์—ฌ๋Ÿฌ ๋งค๊ฐœ๋ณ€์ˆ˜๊ฐ€ ์žˆ์„ ๋•Œ + +**๋™๊ธฐ**: ์ž์—ฐ์Šค๋Ÿฝ๊ฒŒ ํ•จ๊ป˜ ์†ํ•˜๋Š” ๋ฐ์ดํ„ฐ๋ฅผ ๊ทธ๋ฃนํ™”ํ•ฉ๋‹ˆ๋‹ค. + +**๋ฉ”์ปค๋‹ˆ์ฆ˜**: +1. ๊ทธ๋ฃนํ™”๋œ ๋งค๊ฐœ๋ณ€์ˆ˜๋ฅผ ์œ„ํ•œ ์ƒˆ ํด๋ž˜์Šค/๊ตฌ์กฐ์ฒด๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. +2. ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. +3. ํ•จ์ˆ˜ ์„ ์–ธ ๋ณ€๊ฒฝ์„ ์‚ฌ์šฉํ•˜์—ฌ ์ƒˆ ๊ฐ์ฒด๋ฅผ ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค. +4. ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. +5. ๊ทธ๋ฃน์˜ ๊ฐ ๋งค๊ฐœ๋ณ€์ˆ˜์— ๋Œ€ํ•ด ํ•จ์ˆ˜์—์„œ ์ œ๊ฑฐํ•˜๊ณ  ์ƒˆ ๊ฐ์ฒด๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +6. ๊ฐ ๋ณ€๊ฒฝ ํ›„ ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. + +**์ด์ „**: +```javascript +function amountInvoiced(startDate, endDate) { ... } +function amountReceived(startDate, endDate) { ... } +function amountOverdue(startDate, endDate) { ... } +``` + +**์ดํ›„**: +```javascript +class DateRange { + constructor(start, end) { + this.start = start; + this.end = end; + } +} + +function amountInvoiced(dateRange) { ... } +function amountReceived(dateRange) { ... } +function amountOverdue(dateRange) { ... } +``` + +--- + +### ํ•จ์ˆ˜๋“ค์„ ํด๋ž˜์Šค๋กœ ๊ฒฐํ•ฉ (Combine Functions into Class) + +**์‚ฌ์šฉ ์‹œ์ **: ์—ฌ๋Ÿฌ ํ•จ์ˆ˜๊ฐ€ ๋™์ผํ•œ ๋ฐ์ดํ„ฐ์— ๋Œ€ํ•ด ์ž‘๋™ํ•  ๋•Œ + +**๋™๊ธฐ**: ํ•จ์ˆ˜๋ฅผ ๊ทธ๋“ค์ด ์ž‘๋™ํ•˜๋Š” ๋ฐ์ดํ„ฐ์™€ ํ•จ๊ป˜ ๊ทธ๋ฃนํ™”ํ•ฉ๋‹ˆ๋‹ค. + +**๋ฉ”์ปค๋‹ˆ์ฆ˜**: +1. ๊ณตํ†ต ๋ฐ์ดํ„ฐ์— [๋ ˆ์ฝ”๋“œ ์บก์Šํ™”](https://refactoring.com/catalog/encapsulateRecord.html)๋ฅผ ์ ์šฉํ•ฉ๋‹ˆ๋‹ค. +2. ๊ฐ ํ•จ์ˆ˜๋ฅผ ํด๋ž˜์Šค ์•ˆ์œผ๋กœ ์˜ฎ๊น๋‹ˆ๋‹ค. +3. ๊ฐ ์ด๋™ ํ›„ ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. +4. ๋ฐ์ดํ„ฐ ์ธ์ˆ˜๋ฅผ ํด๋ž˜์Šค ํ•„๋“œ ์‚ฌ์šฉ์œผ๋กœ ๋Œ€์ฒดํ•ฉ๋‹ˆ๋‹ค. + +**์ด์ „**: +```javascript +function base(reading) { ... } +function taxableCharge(reading) { ... } +function calculateBaseCharge(reading) { ... } +``` + +**์ดํ›„**: +```javascript +class Reading { + constructor(data) { this._data = data; } + + get base() { ... } + get taxableCharge() { ... } + get calculateBaseCharge() { ... } +} +``` + +--- + +### ๋‹จ๊ณ„ ๋ถ„๋ฆฌ (Split Phase) + +**์‚ฌ์šฉ ์‹œ์ **: ์ฝ”๋“œ๊ฐ€ ๋‘ ๊ฐ€์ง€ ๋‹ค๋ฅธ ๊ฒƒ์„ ๋‹ค๋ฃฐ ๋•Œ + +**๋™๊ธฐ**: ์ฝ”๋“œ๋ฅผ ๋ช…ํ™•ํ•œ ๊ฒฝ๊ณ„๋ฅผ ๊ฐ€์ง„ ๋ณ„๊ฐœ์˜ ๋‹จ๊ณ„๋กœ ๋ถ„๋ฆฌํ•ฉ๋‹ˆ๋‹ค. + +**๋ฉ”์ปค๋‹ˆ์ฆ˜**: +1. ๋‘ ๋ฒˆ์งธ ๋‹จ๊ณ„๋ฅผ ์œ„ํ•œ ๋‘ ๋ฒˆ์งธ ํ•จ์ˆ˜๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. +2. ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. +3. ๋‹จ๊ณ„๋“ค ์‚ฌ์ด์— ์ค‘๊ฐ„ ๋ฐ์ดํ„ฐ ๊ตฌ์กฐ๋ฅผ ๋„์ž…ํ•ฉ๋‹ˆ๋‹ค. +4. ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. +5. ์ฒซ ๋ฒˆ์งธ ๋‹จ๊ณ„๋ฅผ ์ž์ฒด ํ•จ์ˆ˜๋กœ ์ถ”์ถœํ•ฉ๋‹ˆ๋‹ค. +6. ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. + +**์ด์ „**: +```javascript +function priceOrder(product, quantity, shippingMethod) { + const basePrice = product.basePrice * quantity; + const discount = Math.max(quantity - product.discountThreshold, 0) + * product.basePrice * product.discountRate; + const shippingPerCase = (basePrice > shippingMethod.discountThreshold) + ? shippingMethod.discountedFee : shippingMethod.feePerCase; + const shippingCost = quantity * shippingPerCase; + return basePrice - discount + shippingCost; +} +``` + +**์ดํ›„**: +```javascript +function priceOrder(product, quantity, shippingMethod) { + const priceData = calculatePricingData(product, quantity); + return applyShipping(priceData, shippingMethod); +} + +function calculatePricingData(product, quantity) { + const basePrice = product.basePrice * quantity; + const discount = Math.max(quantity - product.discountThreshold, 0) + * product.basePrice * product.discountRate; + return { basePrice, quantity, discount }; +} + +function applyShipping(priceData, shippingMethod) { + const shippingPerCase = (priceData.basePrice > shippingMethod.discountThreshold) + ? shippingMethod.discountedFee : shippingMethod.feePerCase; + const shippingCost = priceData.quantity * shippingPerCase; + return priceData.basePrice - priceData.discount + shippingCost; +} +``` + +--- + +## ๊ธฐ๋Šฅ ์ด๋™ (Moving Features) + +### ๋ฉ”์„œ๋“œ ์ด๋™ (Move Method) + +**์‚ฌ์šฉ ์‹œ์ **: ๋ฉ”์„œ๋“œ๊ฐ€ ์ž์‹ ์˜ ํด๋ž˜์Šค๋ณด๋‹ค ๋‹ค๋ฅธ ํด๋ž˜์Šค์˜ ๊ธฐ๋Šฅ์„ ๋” ๋งŽ์ด ์‚ฌ์šฉํ•  ๋•Œ + +**๋™๊ธฐ**: ํ•จ์ˆ˜๋ฅผ ๊ฐ€์žฅ ๋งŽ์ด ์‚ฌ์šฉํ•˜๋Š” ๋ฐ์ดํ„ฐ์™€ ํ•จ๊ป˜ ๋ฐฐ์น˜ํ•ฉ๋‹ˆ๋‹ค. + +**๋ฉ”์ปค๋‹ˆ์ฆ˜**: +1. ๋ฉ”์„œ๋“œ๊ฐ€ ํ•ด๋‹น ํด๋ž˜์Šค์—์„œ ์‚ฌ์šฉํ•˜๋Š” ๋ชจ๋“  ํ”„๋กœ๊ทธ๋žจ ์š”์†Œ๋ฅผ ๊ฒ€์‚ฌํ•ฉ๋‹ˆ๋‹ค. +2. ๋ฉ”์„œ๋“œ๊ฐ€ ๋‹คํ˜•์ ์ธ์ง€ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. +3. ๋Œ€์ƒ ํด๋ž˜์Šค๋กœ ๋ฉ”์„œ๋“œ๋ฅผ ๋ณต์‚ฌํ•ฉ๋‹ˆ๋‹ค. +4. ์ƒˆ ์ปจํ…์ŠคํŠธ์— ๋งž๊ฒŒ ์กฐ์ •ํ•ฉ๋‹ˆ๋‹ค. +5. ์›๋ž˜ ๋ฉ”์„œ๋“œ๊ฐ€ ๋Œ€์ƒ์œผ๋กœ ์œ„์ž„ํ•˜๋„๋ก ๋งŒ๋“ญ๋‹ˆ๋‹ค. +6. ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. +7. ์›๋ž˜ ๋ฉ”์„œ๋“œ๋ฅผ ์ œ๊ฑฐํ•˜๋Š” ๊ฒƒ์„ ๊ณ ๋ คํ•ฉ๋‹ˆ๋‹ค. + +--- + +### ํ•„๋“œ ์ด๋™ (Move Field) + +**์‚ฌ์šฉ ์‹œ์ **: ํ•„๋“œ๊ฐ€ ๋‹ค๋ฅธ ํด๋ž˜์Šค์— ์˜ํ•ด ๋” ๋งŽ์ด ์‚ฌ์šฉ๋  ๋•Œ + +**๋™๊ธฐ**: ๋ฐ์ดํ„ฐ๋ฅผ ์‚ฌ์šฉํ•˜๋Š” ํ•จ์ˆ˜์™€ ํ•จ๊ป˜ ๋ฐ์ดํ„ฐ๋ฅผ ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. + +**๋ฉ”์ปค๋‹ˆ์ฆ˜**: +1. ํ•„๋“œ๊ฐ€ ์•„์ง ์บก์Šํ™”๋˜์ง€ ์•Š์•˜๋‹ค๋ฉด ์บก์Šํ™”ํ•ฉ๋‹ˆ๋‹ค. +2. ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. +3. ๋Œ€์ƒ์— ํ•„๋“œ๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. +4. ๋Œ€์ƒ ํ•„๋“œ๋ฅผ ์‚ฌ์šฉํ•˜๋„๋ก ์ฐธ์กฐ๋ฅผ ์—…๋ฐ์ดํŠธํ•ฉ๋‹ˆ๋‹ค. +5. ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. +6. ์›๋ž˜ ํ•„๋“œ๋ฅผ ์ œ๊ฑฐํ•ฉ๋‹ˆ๋‹ค. + +--- + +### ๊ตฌ๋ฌธ๋“ค์„ ํ•จ์ˆ˜ ์•ˆ์œผ๋กœ ์ด๋™ (Move Statements into Function) + +**์‚ฌ์šฉ ์‹œ์ **: ๋™์ผํ•œ ์ฝ”๋“œ๊ฐ€ ํ•ญ์ƒ ํ•จ์ˆ˜ ํ˜ธ์ถœ๊ณผ ํ•จ๊ป˜ ๋‚˜ํƒ€๋‚  ๋•Œ + +**๋™๊ธฐ**: ๋ฐ˜๋ณต๋˜๋Š” ์ฝ”๋“œ๋ฅผ ํ•จ์ˆ˜ ์•ˆ์œผ๋กœ ์˜ฎ๊ฒจ ์ค‘๋ณต์„ ์ œ๊ฑฐํ•ฉ๋‹ˆ๋‹ค. + +**๋ฉ”์ปค๋‹ˆ์ฆ˜**: +1. ๋ฐ˜๋ณต๋˜๋Š” ์ฝ”๋“œ๋ฅผ ์•„์ง ํ•จ์ˆ˜๋กœ ์ถ”์ถœํ•˜์ง€ ์•Š์•˜๋‹ค๋ฉด ์ถ”์ถœํ•ฉ๋‹ˆ๋‹ค. +2. ํ•ด๋‹น ํ•จ์ˆ˜ ์•ˆ์œผ๋กœ ๊ตฌ๋ฌธ๋“ค์„ ์ด๋™ํ•ฉ๋‹ˆ๋‹ค. +3. ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. +4. ํ˜ธ์ถœ์ž๊ฐ€ ๋” ์ด์ƒ ๋…๋ฆฝ์ ์ธ ๊ตฌ๋ฌธ๋“ค์„ ํ•„์š”๋กœ ํ•˜์ง€ ์•Š๋Š”๋‹ค๋ฉด ์ œ๊ฑฐํ•ฉ๋‹ˆ๋‹ค. + +--- + +### ๊ตฌ๋ฌธ๋“ค์„ ํ˜ธ์ถœ์ž๋กœ ์ด๋™ (Move Statements to Callers) + +**์‚ฌ์šฉ ์‹œ์ **: ํ˜ธ์ถœ์ž๋งˆ๋‹ค ๊ณตํ†ต ๋™์ž‘์ด ๋‹ค๋ฅผ ๋•Œ + +**๋™๊ธฐ**: ๋™์ž‘์ด ๋‹ฌ๋ผ์ ธ์•ผ ํ•  ๋•Œ, ํ•จ์ˆ˜ ๋ฐ–์œผ๋กœ ์ด๋™์‹œํ‚ต๋‹ˆ๋‹ค. + +**๋ฉ”์ปค๋‹ˆ์ฆ˜**: +1. ์ด๋™ํ•  ์ฝ”๋“œ์— ๋Œ€ํ•ด ๋ฉ”์„œ๋“œ ์ถ”์ถœ์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +2. ์›๋ž˜ ํ•จ์ˆ˜์— ๋Œ€ํ•ด ๋ฉ”์„œ๋“œ ์ธ๋ผ์ธ์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +3. ์ด์ œ ์ธ๋ผ์ธ๋œ ํ˜ธ์ถœ์„ ์ œ๊ฑฐํ•ฉ๋‹ˆ๋‹ค. +4. ์ถ”์ถœ๋œ ์ฝ”๋“œ๋ฅผ ๊ฐ ํ˜ธ์ถœ์ž๋กœ ์ด๋™ํ•ฉ๋‹ˆ๋‹ค. +5. ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. + +--- + +## ๋ฐ์ดํ„ฐ ์กฐ์งํ™” (Organizing Data) + +### ๊ธฐ๋ณธํ˜•์„ ๊ฐ์ฒด๋กœ ๋Œ€์ฒด (Replace Primitive with Object) + +**์‚ฌ์šฉ ์‹œ์ **: ๋ฐ์ดํ„ฐ ํ•ญ๋ชฉ์— ๋‹จ์ˆœ ๊ฐ’ ์ด์ƒ์˜ ๋™์ž‘์ด ํ•„์š”ํ•  ๋•Œ + +**๋™๊ธฐ**: ๋ฐ์ดํ„ฐ๋ฅผ ๊ทธ ๋™์ž‘๊ณผ ํ•จ๊ป˜ ์บก์Šํ™”ํ•ฉ๋‹ˆ๋‹ค. + +**๋ฉ”์ปค๋‹ˆ์ฆ˜**: +1. [๋ณ€์ˆ˜ ์บก์Šํ™”](https://refactoring.com/catalog/encapsulateVariable.html)๋ฅผ ์ ์šฉํ•ฉ๋‹ˆ๋‹ค. +2. ๋‹จ์ˆœ ๊ฐ’ ํด๋ž˜์Šค๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. +3. setter๊ฐ€ ์ƒˆ ์ธ์Šคํ„ด์Šค๋ฅผ ์ƒ์„ฑํ•˜๋„๋ก ๋ณ€๊ฒฝํ•ฉ๋‹ˆ๋‹ค. +4. getter๊ฐ€ ๊ฐ’์„ ๋ฐ˜ํ™˜ํ•˜๋„๋ก ๋ณ€๊ฒฝํ•ฉ๋‹ˆ๋‹ค. +5. ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. +6. ์ƒˆ ํด๋ž˜์Šค์— ๋” ํ’๋ถ€ํ•œ ๋™์ž‘์„ ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค. + +**์ด์ „**: +```javascript +class Order { + constructor(data) { + this.priority = data.priority; // string: "high", "rush", etc. + } +} + +// Usage +if (order.priority === "high" || order.priority === "rush") { ... } +``` + +**์ดํ›„**: +```javascript +class Priority { + constructor(value) { + if (!Priority.legalValues().includes(value)) + throw new Error(`Invalid priority: ${value}`); + this._value = value; + } + + static legalValues() { return ['low', 'normal', 'high', 'rush']; } + get value() { return this._value; } + + higherThan(other) { + return Priority.legalValues().indexOf(this._value) > + Priority.legalValues().indexOf(other._value); + } +} + +// Usage +if (order.priority.higherThan(new Priority("normal"))) { ... } +``` + +--- + +### ์ž„์‹œ ๋ณ€์ˆ˜๋ฅผ ์งˆ์˜ ๋ฉ”์„œ๋“œ๋กœ ๋Œ€์ฒด (Replace Temp with Query) + +**์‚ฌ์šฉ ์‹œ์ **: ์ž„์‹œ ๋ณ€์ˆ˜๊ฐ€ ํ‘œํ˜„์‹์˜ ๊ฒฐ๊ณผ๋ฅผ ๋‹ด๊ณ  ์žˆ์„ ๋•Œ + +**๋™๊ธฐ**: ํ‘œํ˜„์‹์„ ํ•จ์ˆ˜๋กœ ์ถ”์ถœํ•˜์—ฌ ์ฝ”๋“œ๋ฅผ ๋” ๋ช…ํ™•ํ•˜๊ฒŒ ๋งŒ๋“ญ๋‹ˆ๋‹ค. + +**๋ฉ”์ปค๋‹ˆ์ฆ˜**: +1. ๋ณ€์ˆ˜๊ฐ€ ํ•œ ๋ฒˆ๋งŒ ํ• ๋‹น๋˜๋Š”์ง€ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. +2. ํ• ๋‹น์˜ ์šฐ์ธก ๋ณ€์ˆ˜๋ฅผ ๋ฉ”์„œ๋“œ๋กœ ์ถ”์ถœํ•ฉ๋‹ˆ๋‹ค. +3. ์ž„์‹œ ๋ณ€์ˆ˜์— ๋Œ€ํ•œ ์ฐธ์กฐ๋ฅผ ๋ฉ”์„œ๋“œ ํ˜ธ์ถœ๋กœ ๋Œ€์ฒดํ•ฉ๋‹ˆ๋‹ค. +4. ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. +5. ์ž„์‹œ ๋ณ€์ˆ˜ ์„ ์–ธ๊ณผ ํ• ๋‹น์„ ์ œ๊ฑฐํ•ฉ๋‹ˆ๋‹ค. + +**์ด์ „**: +```javascript +const basePrice = this._quantity * this._itemPrice; +if (basePrice > 1000) { + return basePrice * 0.95; +} else { + return basePrice * 0.98; +} +``` + +**์ดํ›„**: +```javascript +get basePrice() { + return this._quantity * this._itemPrice; +} + +// In the method +if (this.basePrice > 1000) { + return this.basePrice * 0.95; +} else { + return this.basePrice * 0.98; +} +``` + +--- + +## ์กฐ๊ฑด๋ถ€ ๋กœ์ง ๋‹จ์ˆœํ™” (Simplifying Conditional Logic) + +### ์กฐ๊ฑด๋ฌธ ๋ถ„ํ•ด (Decompose Conditional) + +**์‚ฌ์šฉ ์‹œ์ **: ๋ณต์žกํ•œ ์กฐ๊ฑด๋ฌธ (if-then-else)์ด ์žˆ์„ ๋•Œ + +**๋™๊ธฐ**: ์กฐ๊ฑด๊ณผ ๋™์ž‘์„ ์ถ”์ถœํ•˜์—ฌ ์˜๋„๋ฅผ ๋ช…ํ™•ํ•˜๊ฒŒ ๋งŒ๋“ญ๋‹ˆ๋‹ค. + +**๋ฉ”์ปค๋‹ˆ์ฆ˜**: +1. ์กฐ๊ฑด์— ๋ฉ”์„œ๋“œ ์ถ”์ถœ์„ ์ ์šฉํ•ฉ๋‹ˆ๋‹ค. +2. then-๋ถ„๊ธฐ์— ๋ฉ”์„œ๋“œ ์ถ”์ถœ์„ ์ ์šฉํ•ฉ๋‹ˆ๋‹ค. +3. else-๋ถ„๊ธฐ์— ๋ฉ”์„œ๋“œ ์ถ”์ถœ์„ ์ ์šฉํ•ฉ๋‹ˆ๋‹ค (์กด์žฌํ•˜๋Š” ๊ฒฝ์šฐ). + +**์ด์ „**: +```javascript +if (!aDate.isBefore(plan.summerStart) && !aDate.isAfter(plan.summerEnd)) { + charge = quantity * plan.summerRate; +} else { + charge = quantity * plan.regularRate + plan.regularServiceCharge; +} +``` + +**์ดํ›„**: +```javascript +if (isSummer(aDate, plan)) { + charge = summerCharge(quantity, plan); +} else { + charge = regularCharge(quantity, plan); +} + +function isSummer(date, plan) { + return !date.isBefore(plan.summerStart) && !date.isAfter(plan.summerEnd); +} + +function summerCharge(quantity, plan) { + return quantity * plan.summerRate; +} + +function regularCharge(quantity, plan) { + return quantity * plan.regularRate + plan.regularServiceCharge; +} +``` + +--- + +### ์กฐ๊ฑด ํ‘œํ˜„์‹ ํ†ตํ•ฉ (Consolidate Conditional Expression) + +**์‚ฌ์šฉ ์‹œ์ **: ๋™์ผํ•œ ๊ฒฐ๊ณผ๋ฅผ ๋‚ด๋Š” ์—ฌ๋Ÿฌ ์กฐ๊ฑด์ด ์žˆ์„ ๋•Œ + +**๋™๊ธฐ**: ์กฐ๊ฑด๋“ค์ด ๋‹จ์ผ ๊ฒ€์‚ฌ์ž„์„ ๋ช…ํ™•ํžˆ ํ•ฉ๋‹ˆ๋‹ค. + +**๋ฉ”์ปค๋‹ˆ์ฆ˜**: +1. ์กฐ๊ฑด์— ๋ถ€์ž‘์šฉ์ด ์—†๋Š”์ง€ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. +2. `and` ๋˜๋Š” `or`๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ์กฐ๊ฑด์„ ๊ฒฐํ•ฉํ•ฉ๋‹ˆ๋‹ค. +3. ๊ฒฐํ•ฉ๋œ ์กฐ๊ฑด์— ๋ฉ”์„œ๋“œ ์ถ”์ถœ์„ ๊ณ ๋ คํ•ฉ๋‹ˆ๋‹ค. + +**์ด์ „**: +```javascript +if (employee.seniority < 2) return 0; +if (employee.monthsDisabled > 12) return 0; +if (employee.isPartTime) return 0; +``` + +**์ดํ›„**: +```javascript +if (isNotEligibleForDisability(employee)) return 0; + +function isNotEligibleForDisability(employee) { + return employee.seniority < 2 || + employee.monthsDisabled > 12 || + employee.isPartTime; +} +``` + +--- + +### ์ค‘์ฒฉ ์กฐ๊ฑด๋ฌธ์„ ๊ฐ€๋“œ ์ ˆ๋กœ ๋Œ€์ฒด (Replace Nested Conditional with Guard Clauses) + +**์‚ฌ์šฉ ์‹œ์ **: ํ๋ฆ„์„ ๋”ฐ๋ผ๊ฐ€๊ธฐ ์–ด๋ ต๊ฒŒ ๋งŒ๋“œ๋Š” ๊นŠ๊ฒŒ ์ค‘์ฒฉ๋œ ์กฐ๊ฑด๋ฌธ์ด ์žˆ์„ ๋•Œ + +**๋™๊ธฐ**: ํŠน๋ณ„ํ•œ ๊ฒฝ์šฐ์— ๊ฐ€๋“œ ์ ˆ์„ ์‚ฌ์šฉํ•˜์—ฌ ์ •์ƒ ํ๋ฆ„์„ ๋ช…ํ™•ํ•˜๊ฒŒ ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. + +**๋ฉ”์ปค๋‹ˆ์ฆ˜**: +1. ํŠน๋ณ„ํ•œ ๊ฒฝ์šฐ ์กฐ๊ฑด์„ ์ฐพ์Šต๋‹ˆ๋‹ค. +2. ์ผ์ฐ ๋ฐ˜ํ™˜ํ•˜๋Š” ๊ฐ€๋“œ ์ ˆ๋กœ ๋Œ€์ฒดํ•ฉ๋‹ˆ๋‹ค. +3. ๊ฐ ๋ณ€๊ฒฝ ํ›„ ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. + +**์ด์ „**: +```javascript +function payAmount(employee) { + let result; + if (employee.isSeparated) { + result = { amount: 0, reasonCode: "SEP" }; + } else { + if (employee.isRetired) { + result = { amount: 0, reasonCode: "RET" }; + } else { + result = calculateNormalPay(employee); + } + } + return result; +} +``` + +**์ดํ›„**: +```javascript +function payAmount(employee) { + if (employee.isSeparated) return { amount: 0, reasonCode: "SEP" }; + if (employee.isRetired) return { amount: 0, reasonCode: "RET" }; + return calculateNormalPay(employee); +} +``` + +--- + +### ์กฐ๊ฑด๋ฌธ์„ ๋‹คํ˜•์„ฑ์œผ๋กœ ๋Œ€์ฒด (Replace Conditional with Polymorphism) + +**์‚ฌ์šฉ ์‹œ์ **: ํƒ€์ž…์— ๋”ฐ๋ฅธ switch/case, ํƒ€์ž…์— ๋”ฐ๋ผ ๋‹ฌ๋ผ์ง€๋Š” ์กฐ๊ฑด๋ถ€ ๋กœ์ง์ด ์žˆ์„ ๋•Œ + +**๋™๊ธฐ**: ๊ฐ์ฒด๊ฐ€ ์ž์‹ ์˜ ๋™์ž‘์„ ์ฒ˜๋ฆฌํ•˜๋„๋ก ํ•ฉ๋‹ˆ๋‹ค. + +**๋ฉ”์ปค๋‹ˆ์ฆ˜**: +1. ํด๋ž˜์Šค ๊ณ„์ธต ๊ตฌ์กฐ๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค (์กด์žฌํ•˜์ง€ ์•Š๋Š” ๊ฒฝ์šฐ). +2. ๊ฐ์ฒด ์ƒ์„ฑ์„ ์œ„ํ•ด ํŒฉํ† ๋ฆฌ ํ•จ์ˆ˜๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +3. ์กฐ๊ฑด๋ถ€ ๋กœ์ง์„ ์ƒ์œ„ ํด๋ž˜์Šค ๋ฉ”์„œ๋“œ๋กœ ์ด๋™ํ•ฉ๋‹ˆ๋‹ค. +4. ๊ฐ ์ผ€์ด์Šค์— ๋Œ€ํ•ด ํ•˜์œ„ ํด๋ž˜์Šค ๋ฉ”์„œ๋“œ๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. +5. ์›๋ž˜ ์กฐ๊ฑด๋ฌธ์„ ์ œ๊ฑฐํ•ฉ๋‹ˆ๋‹ค. + +**์ด์ „**: +```javascript +function plumages(birds) { + return birds.map(b => plumage(b)); +} + +function plumage(bird) { + switch (bird.type) { + case 'EuropeanSwallow': + return "average"; + case 'AfricanSwallow': + return (bird.numberOfCoconuts > 2) ? "tired" : "average"; + case 'NorwegianBlueParrot': + return (bird.voltage > 100) ? "scorched" : "beautiful"; + default: + return "unknown"; + } +} +``` + +**์ดํ›„**: +```javascript +class Bird { + get plumage() { return "unknown"; } +} + +class EuropeanSwallow extends Bird { + get plumage() { return "average"; } +} + +class AfricanSwallow extends Bird { + get plumage() { + return (this.numberOfCoconuts > 2) ? "tired" : "average"; + } +} + +class NorwegianBlueParrot extends Bird { + get plumage() { + return (this.voltage > 100) ? "scorched" : "beautiful"; + } +} + +function createBird(data) { + switch (data.type) { + case 'EuropeanSwallow': return new EuropeanSwallow(data); + case 'AfricanSwallow': return new AfricanSwallow(data); + case 'NorwegianBlueParrot': return new NorwegianBlueParrot(data); + default: return new Bird(data); + } +} +``` + +--- + +### ํŠน์ˆ˜ ์‚ฌ๋ก€ ๋„์ž… (๋„ ๊ฐ์ฒด) (Introduce Special Case (Null Object)) + +**์‚ฌ์šฉ ์‹œ์ **: ํŠน์ˆ˜ ์‚ฌ๋ก€์— ๋Œ€ํ•œ ๋ฐ˜๋ณต์ ์ธ ๋„ ๊ฒ€์‚ฌ๊ฐ€ ์žˆ์„ ๋•Œ + +**๋™๊ธฐ**: ํŠน์ˆ˜ ์‚ฌ๋ก€๋ฅผ ์ฒ˜๋ฆฌํ•˜๋Š” ํŠน์ˆ˜ ๊ฐ์ฒด๋ฅผ ๋ฐ˜ํ™˜ํ•ฉ๋‹ˆ๋‹ค. + +**๋ฉ”์ปค๋‹ˆ์ฆ˜**: +1. ์˜ˆ์ƒ๋˜๋Š” ์ธํ„ฐํŽ˜์ด์Šค๋ฅผ ๊ฐ€์ง„ ํŠน์ˆ˜ ์‚ฌ๋ก€ ํด๋ž˜์Šค๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. +2. isSpecialCase ๊ฒ€์‚ฌ๋ฅผ ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค. +3. ํŒฉํ† ๋ฆฌ ๋ฉ”์„œ๋“œ๋ฅผ ๋„์ž…ํ•ฉ๋‹ˆ๋‹ค. +4. ๋„ ๊ฒ€์‚ฌ๋ฅผ ํŠน์ˆ˜ ์‚ฌ๋ก€ ๊ฐ์ฒด ์‚ฌ์šฉ์œผ๋กœ ๋Œ€์ฒดํ•ฉ๋‹ˆ๋‹ค. +5. ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. + +**์ด์ „**: +```javascript +const customer = site.customer; +// ... many places checking +if (customer === "unknown") { + customerName = "occupant"; +} else { + customerName = customer.name; +} +``` + +**์ดํ›„**: +```javascript +class UnknownCustomer { + get name() { return "occupant"; } + get billingPlan() { return registry.defaultPlan; } +} + +// Factory method +function customer(site) { + return site.customer === "unknown" + ? new UnknownCustomer() + : site.customer; +} + +// Usage - no null checks needed +const customerName = customer.name; +``` + +--- + +## API ๋ฆฌํŒฉํ„ฐ๋ง (Refactoring APIs) + +### ์งˆ์˜์™€ ๋ณ€๊ฒฝ ๋ถ„๋ฆฌ (Separate Query from Modifier) + +**์‚ฌ์šฉ ์‹œ์ **: ํ•จ์ˆ˜๊ฐ€ ๊ฐ’์„ ๋ฐ˜ํ™˜ํ•˜๋Š” ๋™์‹œ์— ๋ถ€์ž‘์šฉ์„ ๊ฐ€์งˆ ๋•Œ + +**๋™๊ธฐ**: ์–ด๋–ค ์ž‘์—…์ด ๋ถ€์ž‘์šฉ์„ ๊ฐ€์ง€๋Š”์ง€ ๋ช…ํ™•ํ•˜๊ฒŒ ํ•ฉ๋‹ˆ๋‹ค. + +**๋ฉ”์ปค๋‹ˆ์ฆ˜**: +1. ์ƒˆ ์งˆ์˜ ํ•จ์ˆ˜๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. +2. ์›๋ž˜ ํ•จ์ˆ˜์˜ ๋ฐ˜ํ™˜ ๋กœ์ง์„ ๋ณต์‚ฌํ•ฉ๋‹ˆ๋‹ค. +3. ์›๋ž˜ ํ•จ์ˆ˜๋ฅผ void๋ฅผ ๋ฐ˜ํ™˜ํ•˜๋„๋ก ์ˆ˜์ •ํ•ฉ๋‹ˆ๋‹ค. +4. ๋ฐ˜ํ™˜ ๊ฐ’์„ ์‚ฌ์šฉํ•˜๋Š” ํ˜ธ์ถœ์„ ๋Œ€์ฒดํ•ฉ๋‹ˆ๋‹ค. +5. ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. + +**์ด์ „**: +```javascript +function alertForMiscreant(people) { + for (const p of people) { + if (p === "Don") { + setOffAlarms(); + return "Don"; + } + if (p === "John") { + setOffAlarms(); + return "John"; + } + } + return ""; +} +``` + +**์ดํ›„**: +```javascript +function findMiscreant(people) { + for (const p of people) { + if (p === "Don") return "Don"; + if (p === "John") return "John"; + } + return ""; +} + +function alertForMiscreant(people) { + if (findMiscreant(people) !== "") setOffAlarms(); +} +``` + +--- + +### ํ•จ์ˆ˜ ๋งค๊ฐœ๋ณ€์ˆ˜ํ™” (Parameterize Function) + +**์‚ฌ์šฉ ์‹œ์ **: ๋‹ค๋ฅธ ๊ฐ’์„ ์‚ฌ์šฉํ•˜์—ฌ ์œ ์‚ฌํ•œ ์ž‘์—…์„ ์ˆ˜ํ–‰ํ•˜๋Š” ์—ฌ๋Ÿฌ ํ•จ์ˆ˜๊ฐ€ ์žˆ์„ ๋•Œ + +**๋™๊ธฐ**: ๋งค๊ฐœ๋ณ€์ˆ˜๋ฅผ ์ถ”๊ฐ€ํ•˜์—ฌ ์ค‘๋ณต์„ ์ œ๊ฑฐํ•ฉ๋‹ˆ๋‹ค. + +**๋ฉ”์ปค๋‹ˆ์ฆ˜**: +1. ํ•˜๋‚˜์˜ ํ•จ์ˆ˜๋ฅผ ์„ ํƒํ•ฉ๋‹ˆ๋‹ค. +2. ๋‹ฌ๋ผ์ง€๋Š” ๋ฆฌํ„ฐ๋Ÿด์— ๋Œ€ํ•œ ๋งค๊ฐœ๋ณ€์ˆ˜๋ฅผ ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค. +3. ๋งค๊ฐœ๋ณ€์ˆ˜๋ฅผ ์‚ฌ์šฉํ•˜๋„๋ก ๋ณธ๋ฌธ์„ ๋ณ€๊ฒฝํ•ฉ๋‹ˆ๋‹ค. +4. ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. +5. ํ˜ธ์ถœ์ž๊ฐ€ ๋งค๊ฐœ๋ณ€์ˆ˜ํ™”๋œ ๋ฒ„์ „์„ ์‚ฌ์šฉํ•˜๋„๋ก ๋ณ€๊ฒฝํ•ฉ๋‹ˆ๋‹ค. +6. ๋” ์ด์ƒ ์‚ฌ์šฉ๋˜์ง€ ์•Š๋Š” ํ•จ์ˆ˜๋ฅผ ์ œ๊ฑฐํ•ฉ๋‹ˆ๋‹ค. + +**์ด์ „**: +```javascript +function tenPercentRaise(person) { + person.salary = person.salary * 1.10; +} + +function fivePercentRaise(person) { + person.salary = person.salary * 1.05; +} +``` + +**์ดํ›„**: +```javascript +function raise(person, factor) { + person.salary = person.salary * (1 + factor); +} + +// Usage +raise(person, 0.10); +raise(person, 0.05); +``` + +--- + +### ํ”Œ๋ž˜๊ทธ ์ธ์ˆ˜ ์ œ๊ฑฐ (Remove Flag Argument) + +**์‚ฌ์šฉ ์‹œ์ **: ํ•จ์ˆ˜ ๋™์ž‘์„ ๋ณ€๊ฒฝํ•˜๋Š” ๋ถˆ๋ฆฌ์–ธ ๋งค๊ฐœ๋ณ€์ˆ˜๊ฐ€ ์žˆ์„ ๋•Œ + +**๋™๊ธฐ**: ๋ณ„๋„์˜ ํ•จ์ˆ˜๋ฅผ ํ†ตํ•ด ๋™์ž‘์„ ๋ช…์‹œ์ ์œผ๋กœ ๋งŒ๋“ญ๋‹ˆ๋‹ค. + +**๋ฉ”์ปค๋‹ˆ์ฆ˜**: +1. ๊ฐ ํ”Œ๋ž˜๊ทธ ๊ฐ’์— ๋Œ€ํ•œ ๋ช…์‹œ์  ํ•จ์ˆ˜๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. +2. ๊ฐ ํ˜ธ์ถœ์„ ์ ์ ˆํ•œ ์ƒˆ ํ•จ์ˆ˜๋กœ ๋Œ€์ฒดํ•ฉ๋‹ˆ๋‹ค. +3. ๊ฐ ๋ณ€๊ฒฝ ํ›„ ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. +4. ์›๋ž˜ ํ•จ์ˆ˜๋ฅผ ์ œ๊ฑฐํ•ฉ๋‹ˆ๋‹ค. + +**์ด์ „**: +```javascript +function bookConcert(customer, isPremium) { + if (isPremium) { + // premium booking logic + } else { + // regular booking logic + } +} + +bookConcert(customer, true); +bookConcert(customer, false); +``` + +**์ดํ›„**: +```javascript +function bookPremiumConcert(customer) { + // premium booking logic +} + +function bookRegularConcert(customer) { + // regular booking logic +} + +bookPremiumConcert(customer); +bookRegularConcert(customer); +``` + +--- + +## ์ƒ์† ์ฒ˜๋ฆฌ (Dealing with Inheritance) + +### ๋ฉ”์„œ๋“œ ์ƒ์œ„๋กœ ์ด๋™ (Pull Up Method) + +**์‚ฌ์šฉ ์‹œ์ **: ์—ฌ๋Ÿฌ ํ•˜์œ„ ํด๋ž˜์Šค์— ๋™์ผํ•œ ๋ฉ”์„œ๋“œ๊ฐ€ ์žˆ์„ ๋•Œ + +**๋™๊ธฐ**: ํด๋ž˜์Šค ๊ณ„์ธต ๊ตฌ์กฐ์—์„œ ์ค‘๋ณต์„ ์ œ๊ฑฐํ•ฉ๋‹ˆ๋‹ค. + +**๋ฉ”์ปค๋‹ˆ์ฆ˜**: +1. ๋ฉ”์„œ๋“œ๊ฐ€ ๋™์ผํ•œ์ง€ ํ™•์ธํ•˜๊ธฐ ์œ„ํ•ด ๊ฒ€์‚ฌํ•ฉ๋‹ˆ๋‹ค. +2. ์‹œ๊ทธ๋‹ˆ์ฒ˜๊ฐ€ ๋™์ผํ•œ์ง€ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. +3. ์ƒ์œ„ ํด๋ž˜์Šค์— ์ƒˆ ๋ฉ”์„œ๋“œ๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. +4. ํ•œ ํ•˜์œ„ ํด๋ž˜์Šค์—์„œ ๋ณธ๋ฌธ์„ ๋ณต์‚ฌํ•ฉ๋‹ˆ๋‹ค. +5. ํ•œ ํ•˜์œ„ ํด๋ž˜์Šค ๋ฉ”์„œ๋“œ๋ฅผ ์‚ญ์ œํ•˜๊ณ  ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. +6. ๋‹ค๋ฅธ ํ•˜์œ„ ํด๋ž˜์Šค ๋ฉ”์„œ๋“œ๋ฅผ ์‚ญ์ œํ•˜๊ณ  ๊ฐ๊ฐ ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. + +--- + +### ๋ฉ”์„œ๋“œ ํ•˜์œ„๋กœ ์ด๋™ (Push Down Method) + +**์‚ฌ์šฉ ์‹œ์ **: ๋™์ž‘์ด ํ•˜์œ„ ํด๋ž˜์Šค ํ•˜์œ„ ์ง‘ํ•ฉ์—๋งŒ ๊ด€๋ จ๋  ๋•Œ + +**๋™๊ธฐ**: ๋ฉ”์„œ๋“œ๋ฅผ ์‚ฌ์šฉ๋˜๋Š” ๊ณณ์— ๋ฐฐ์น˜ํ•ฉ๋‹ˆ๋‹ค. + +**๋ฉ”์ปค๋‹ˆ์ฆ˜**: +1. ํ•ด๋‹น ๋ฉ”์„œ๋“œ๊ฐ€ ํ•„์š”ํ•œ ๊ฐ ํ•˜์œ„ ํด๋ž˜์Šค๋กœ ๋ฉ”์„œ๋“œ๋ฅผ ๋ณต์‚ฌํ•ฉ๋‹ˆ๋‹ค. +2. ์ƒ์œ„ ํด๋ž˜์Šค์—์„œ ๋ฉ”์„œ๋“œ๋ฅผ ์ œ๊ฑฐํ•ฉ๋‹ˆ๋‹ค. +3. ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. +4. ํ•„์š” ์—†๋Š” ํ•˜์œ„ ํด๋ž˜์Šค์—์„œ ์ œ๊ฑฐํ•ฉ๋‹ˆ๋‹ค. +5. ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. + +--- + +### ํ•˜์œ„ ํด๋ž˜์Šค๋ฅผ ์œ„์ž„์œผ๋กœ ๋Œ€์ฒด (Replace Subclass with Delegate) + +**์‚ฌ์šฉ ์‹œ์ **: ์ƒ์†์ด ์ž˜๋ชป ์‚ฌ์šฉ๋˜๊ณ  ์žˆ์„ ๋•Œ, ๋” ๋งŽ์€ ์œ ์—ฐ์„ฑ์ด ํ•„์š”ํ•  ๋•Œ + +**๋™๊ธฐ**: ์ ์ ˆํ•  ๋•Œ ์ƒ์†๋ณด๋‹ค ๊ตฌ์„ฑ์„ ์„ ํ˜ธํ•ฉ๋‹ˆ๋‹ค. + +**๋ฉ”์ปค๋‹ˆ์ฆ˜**: +1. ์œ„์ž„์„ ์œ„ํ•œ ๋นˆ ํด๋ž˜์Šค๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. +2. ํ˜ธ์ŠคํŠธ ํด๋ž˜์Šค์— ์œ„์ž„์„ ๋‹ด๋Š” ํ•„๋“œ๋ฅผ ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค. +3. ํ˜ธ์ŠคํŠธ์—์„œ ํ˜ธ์ถœ๋˜๋Š” ์œ„์ž„์„ ์œ„ํ•œ ์ƒ์„ฑ์ž๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. +4. ๊ธฐ๋Šฅ์„ ์œ„์ž„์œผ๋กœ ์ด๋™ํ•ฉ๋‹ˆ๋‹ค. +5. ๊ฐ ์ด๋™ ํ›„ ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. +6. ์ƒ์†์„ ์œ„์ž„์œผ๋กœ ๋Œ€์ฒดํ•ฉ๋‹ˆ๋‹ค. + +--- + +## ํด๋ž˜์Šค ์ถ”์ถœ (Extract Class) + +**์‚ฌ์šฉ ์‹œ์ **: ์—ฌ๋Ÿฌ ์ฑ…์ž„์„ ๊ฐ€์ง„ ํฐ ํด๋ž˜์Šค๊ฐ€ ์žˆ์„ ๋•Œ + +**๋™๊ธฐ**: ๋‹จ์ผ ์ฑ…์ž„์„ ์œ ์ง€ํ•˜๊ธฐ ์œ„ํ•ด ํด๋ž˜์Šค๋ฅผ ๋ถ„ํ• ํ•ฉ๋‹ˆ๋‹ค. + +**๋ฉ”์ปค๋‹ˆ์ฆ˜**: +1. ์ฑ…์ž„์„ ์–ด๋–ป๊ฒŒ ๋ถ„ํ• ํ• ์ง€ ๊ฒฐ์ •ํ•ฉ๋‹ˆ๋‹ค. +2. ์ƒˆ ํด๋ž˜์Šค๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. +3. ์›๋ž˜ ํด๋ž˜์Šค์—์„œ ์ƒˆ ํด๋ž˜์Šค๋กœ ํ•„๋“œ๋ฅผ ์ด๋™ํ•ฉ๋‹ˆ๋‹ค. +4. ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. +5. ์›๋ž˜ ํด๋ž˜์Šค์—์„œ ์ƒˆ ํด๋ž˜์Šค๋กœ ๋ฉ”์„œ๋“œ๋ฅผ ์ด๋™ํ•ฉ๋‹ˆ๋‹ค. +6. ๊ฐ ์ด๋™ ํ›„ ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. +7. ๋‘ ํด๋ž˜์Šค๋ฅผ ๊ฒ€ํ† ํ•˜๊ณ  ์ด๋ฆ„์„ ๋ณ€๊ฒฝํ•ฉ๋‹ˆ๋‹ค. +8. ์ƒˆ ํด๋ž˜์Šค๋ฅผ ๋…ธ์ถœํ•˜๋Š” ๋ฐฉ๋ฒ•์„ ๊ฒฐ์ •ํ•ฉ๋‹ˆ๋‹ค. + +**์ด์ „**: +```javascript +class Person { + get name() { return this._name; } + set name(arg) { this._name = arg; } + get officeAreaCode() { return this._officeAreaCode; } + set officeAreaCode(arg) { this._officeAreaCode = arg; } + get officeNumber() { return this._officeNumber; } + set officeNumber(arg) { this._officeNumber = arg; } + + get telephoneNumber() { + return `(${this._officeAreaCode}) ${this._officeNumber}`; + } +} +``` + +**์ดํ›„**: +```javascript +class Person { + constructor() { + this._telephoneNumber = new TelephoneNumber(); + } + get name() { return this._name; } + set name(arg) { this._name = arg; } + get telephoneNumber() { return this._telephoneNumber.toString(); } + get officeAreaCode() { return this._telephoneNumber.areaCode; } + set officeAreaCode(arg) { this._telephoneNumber.areaCode = arg; } +} + +class TelephoneNumber { + get areaCode() { return this._areaCode; } + set areaCode(arg) { this._areaCode = arg; } + get number() { return this._number; } + set number(arg) { this._number = arg; } + toString() { return `(${this._areaCode}) ${this._number}`; } +} +``` + +--- + +## ๋น ๋ฅธ ์ฐธ์กฐ: ์Šค๋ฉœ์—์„œ ๋ฆฌํŒฉํ„ฐ๋ง์œผ๋กœ + +| ์ฝ”๋“œ ์Šค๋ฉœ | ์ฃผ์š” ๋ฆฌํŒฉํ„ฐ๋ง | ๋Œ€์•ˆ | +|------------|-------------------|-------------| +| ๊ธด ๋ฉ”์„œ๋“œ | ๋ฉ”์„œ๋“œ ์ถ”์ถœ | ์ž„์‹œ ๋ณ€์ˆ˜๋ฅผ ์งˆ์˜ ๋ฉ”์„œ๋“œ๋กœ ๋Œ€์ฒด | +| ์ค‘๋ณต ์ฝ”๋“œ | ๋ฉ”์„œ๋“œ ์ถ”์ถœ | ๋ฉ”์„œ๋“œ ์ƒ์œ„๋กœ ์ด๋™ | +| ๊ฑฐ๋Œ€ํ•œ ํด๋ž˜์Šค | ํด๋ž˜์Šค ์ถ”์ถœ | ํ•˜์œ„ ํด๋ž˜์Šค ์ถ”์ถœ | +| ๊ธด ๋งค๊ฐœ๋ณ€์ˆ˜ ๋ชฉ๋ก | ๋งค๊ฐœ๋ณ€์ˆ˜ ๊ฐ์ฒด ๋„์ž… | ์ „์ฒด ๊ฐ์ฒด ๋ณด์กด | +| ๊ธฐ๋Šฅ ์š•์‹ฌ | ๋ฉ”์„œ๋“œ ์ด๋™ | ๋ฉ”์„œ๋“œ ์ถ”์ถœ + ์ด๋™ | +| ๋ฐ์ดํ„ฐ ๋ญ‰์น˜ | ํด๋ž˜์Šค ์ถ”์ถœ | ๋งค๊ฐœ๋ณ€์ˆ˜ ๊ฐ์ฒด ๋„์ž… | +| ๊ธฐ๋ณธํ˜•์— ๋Œ€ํ•œ ์ง‘์ฐฉ | ๊ธฐ๋ณธํ˜•์„ ๊ฐ์ฒด๋กœ ๋Œ€์ฒด | ํƒ€์ž… ์ฝ”๋“œ๋ฅผ ํด๋ž˜์Šค๋กœ ๋Œ€์ฒด | +| Switch ๋ฌธ | ์กฐ๊ฑด๋ฌธ์„ ๋‹คํ˜•์„ฑ์œผ๋กœ ๋Œ€์ฒด | ํƒ€์ž… ์ฝ”๋“œ๋ฅผ ํด๋ž˜์Šค๋กœ ๋Œ€์ฒด | +| ์ž„์‹œ ํ•„๋“œ | ํด๋ž˜์Šค ์ถ”์ถœ | ๋„ ๊ฐ์ฒด ๋„์ž… | +| ๋ฉ”์‹œ์ง€ ์ฒด์ธ | ์œ„์ž„ ์ˆจ๊ธฐ๊ธฐ | ๋ฉ”์„œ๋“œ ์ธ๋ผ์ธ | +| ์ค‘๊ฐ„์ธ (Middle Man) | ์ค‘๊ฐ„์ธ ์ œ๊ฑฐ | ๋ฉ”์„œ๋“œ ์ธ๋ผ์ธ | +| ๋ฐœ์‚ฐ์  ๋ณ€๊ฒฝ | ํด๋ž˜์Šค ์ถ”์ถœ | ๋‹จ๊ณ„ ๋ถ„๋ฆฌ | +| ์‚ฐํƒ„์ด ์ˆ˜์ˆ  | ๋ฉ”์„œ๋“œ ์ด๋™ | ํด๋ž˜์Šค ์ธ๋ผ์ธ | +| ์ฃฝ์€ ์ฝ”๋“œ | ์ฃฝ์€ ์ฝ”๋“œ ์ œ๊ฑฐ | - | +| ์ถ”์ธก์„ฑ ์ผ๋ฐ˜ํ™” | ๊ณ„์ธต ๊ตฌ์กฐ ์ถ•์†Œ | ํด๋ž˜์Šค ์ธ๋ผ์ธ | + +--- + +## ์ถ”๊ฐ€ ์ž๋ฃŒ + +- Fowler, M. (2018). *Refactoring: Improving the Design of Existing Code* (2nd ed.) +- ์˜จ๋ผ์ธ ์นดํƒˆ๋กœ๊ทธ: https://refactoring.com/catalog/ diff --git a/ko/03-skills/refactor/scripts/analyze-complexity.py b/ko/03-skills/refactor/scripts/analyze-complexity.py new file mode 100644 index 00000000..b8ca92c3 --- /dev/null +++ b/ko/03-skills/refactor/scripts/analyze-complexity.py @@ -0,0 +1,545 @@ +#!/usr/bin/env python3 +""" +Code Complexity Analyzer + +Analyzes code complexity metrics for Python, JavaScript, and TypeScript files. +Helps measure the impact of refactoring by comparing before/after metrics. + +Usage: + python analyze-complexity.py + python analyze-complexity.py # Compare mode + python analyze-complexity.py --dir # Analyze directory + +Metrics: + - Cyclomatic Complexity: Decision points in code + - Cognitive Complexity: How hard is it to understand + - Maintainability Index: Overall maintainability score (0-100) + - Lines of Code: Total lines + - Function Count: Number of functions/methods + - Average Function Length: Lines per function +""" + +import argparse +import os +import re +import sys +from dataclasses import dataclass +from pathlib import Path +from typing import Dict, List, Optional + + +@dataclass +class FunctionMetrics: + """Metrics for a single function.""" + name: str + start_line: int + end_line: int + lines: int + cyclomatic_complexity: int + cognitive_complexity: int + parameter_count: int + + +@dataclass +class FileMetrics: + """Metrics for a file.""" + filename: str + lines_of_code: int + blank_lines: int + comment_lines: int + function_count: int + class_count: int + cyclomatic_complexity: int + cognitive_complexity: int + maintainability_index: float + avg_function_length: float + max_function_length: int + functions: List[FunctionMetrics] + + +class ComplexityAnalyzer: + """Analyze code complexity for multiple languages.""" + + # Patterns for different languages + PATTERNS = { + 'python': { + 'function': r'^\s*def\s+(\w+)\s*\(', + 'class': r'^\s*class\s+(\w+)', + 'decision': [r'\bif\b', r'\belif\b', r'\bfor\b', r'\bwhile\b', + r'\bexcept\b', r'\band\b(?!$)', r'\bor\b(?!$)', + r'\bcase\b', r'\btry\b'], + 'comment': r'^\s*#', + 'multiline_comment_start': r'^\s*["\'][\"\'][\"\']', + 'multiline_comment_end': r'["\'][\"\'][\"\']', + }, + 'javascript': { + 'function': r'(?:function\s+(\w+)|(\w+)\s*[=:]\s*(?:async\s+)?(?:function|\([^)]*\)\s*=>))', + 'class': r'class\s+(\w+)', + 'decision': [r'\bif\b', r'\belse\s+if\b', r'\bfor\b', r'\bwhile\b', + r'\bcatch\b', r'\b\?\b', r'\b&&\b', r'\b\|\|\b', + r'\bcase\b', r'\btry\b'], + 'comment': r'^\s*//', + 'multiline_comment_start': r'/\*', + 'multiline_comment_end': r'\*/', + }, + 'typescript': { + 'function': r'(?:function\s+(\w+)|(\w+)\s*[=:]\s*(?:async\s+)?(?:function|\([^)]*\)\s*=>))', + 'class': r'class\s+(\w+)', + 'decision': [r'\bif\b', r'\belse\s+if\b', r'\bfor\b', r'\bwhile\b', + r'\bcatch\b', r'\b\?\b', r'\b&&\b', r'\b\|\|\b', + r'\bcase\b', r'\btry\b'], + 'comment': r'^\s*//', + 'multiline_comment_start': r'/\*', + 'multiline_comment_end': r'\*/', + } + } + + def __init__(self, filepath: str): + self.filepath = filepath + self.filename = os.path.basename(filepath) + self.language = self._detect_language() + self.patterns = self.PATTERNS.get(self.language, self.PATTERNS['python']) + + with open(filepath, 'r', encoding='utf-8', errors='ignore') as f: + self.code = f.read() + self.lines = self.code.split('\n') + + def _detect_language(self) -> str: + """Detect programming language from file extension.""" + ext = os.path.splitext(self.filepath)[1].lower() + ext_map = { + '.py': 'python', + '.js': 'javascript', + '.jsx': 'javascript', + '.ts': 'typescript', + '.tsx': 'typescript', + } + return ext_map.get(ext, 'python') + + def calculate_cyclomatic_complexity(self, code: Optional[str] = None) -> int: + """ + Calculate cyclomatic complexity using McCabe's method. + CC = E - N + 2P where E=edges, N=nodes, P=connected components + Simplified: Count decision points + 1 + """ + if code is None: + code = self.code + + complexity = 1 # Base complexity + + for pattern in self.patterns['decision']: + matches = re.findall(pattern, code) + complexity += len(matches) + + return complexity + + def calculate_cognitive_complexity(self, code: Optional[str] = None) -> int: + """ + Calculate cognitive complexity. + Measures how hard it is to understand the code. + Accounts for nesting depth and control flow breaks. + """ + if code is None: + code = self.code + + lines = code.split('\n') + cognitive = 0 + nesting_depth = 0 + in_function = False + + for line in lines: + stripped = line.strip() + + # Track function boundaries + if re.search(self.patterns['function'], line): + in_function = True + nesting_depth = 0 + + # Increment for control flow structures + if re.search(r'\b(if|for|while|switch)\b', stripped): + nesting_depth += 1 + cognitive += nesting_depth # Nested structures cost more + + elif re.search(r'\b(elif|else if|else|catch|finally)\b', stripped): + cognitive += nesting_depth # Same level as parent + + # Track nesting through braces/indentation + if self.language in ['javascript', 'typescript']: + nesting_depth += stripped.count('{') - stripped.count('}') + nesting_depth = max(0, nesting_depth) + + # Bonus for breaks in linear flow + if re.search(r'\b(break|continue|return|throw)\b', stripped): + if nesting_depth > 1: + cognitive += 1 + + # Bonus for recursion + # (simplified: just look for function calling itself) + + return cognitive + + def calculate_maintainability_index(self) -> float: + """ + Calculate Maintainability Index (0-100). + Based on Halstead Volume, Cyclomatic Complexity, and Lines of Code. + + MI = max(0, (171 - 5.2*ln(V) - 0.23*CC - 16.2*ln(LOC)) * 100/171) + + Interpretation: + - 85-100: Highly maintainable + - 65-84: Moderately maintainable + - 50-64: Difficult to maintain + - 0-49: Very difficult to maintain + """ + import math + + loc = len([l for l in self.lines if l.strip()]) + cc = self.calculate_cyclomatic_complexity() + + # Simplified Halstead Volume approximation + # Count unique operators and operands + operators = len(re.findall(r'[+\-*/%=<>!&|^~]', self.code)) + operands = len(re.findall(r'\b\w+\b', self.code)) + volume = (operators + operands) * math.log2(max(1, operators + operands)) + + # Calculate MI + mi = 171 - 5.2 * math.log(max(1, volume)) - 0.23 * cc - 16.2 * math.log(max(1, loc)) + mi = max(0, min(100, mi * 100 / 171)) + + return round(mi, 2) + + def count_lines(self) -> Dict[str, int]: + """Count different types of lines.""" + total = len(self.lines) + blank = 0 + comment = 0 + in_multiline_comment = False + + for line in self.lines: + stripped = line.strip() + + # Check for multiline comments + if re.search(self.patterns['multiline_comment_start'], stripped): + in_multiline_comment = True + if re.search(self.patterns['multiline_comment_end'], stripped): + in_multiline_comment = False + comment += 1 + continue + + if in_multiline_comment: + comment += 1 + elif not stripped: + blank += 1 + elif re.match(self.patterns['comment'], stripped): + comment += 1 + + return { + 'total': total, + 'blank': blank, + 'comment': comment, + 'code': total - blank - comment + } + + def find_functions(self) -> List[FunctionMetrics]: + """Find all functions and calculate their individual metrics.""" + functions = [] + current_function = None + function_start = 0 + brace_depth = 0 + + for i, line in enumerate(self.lines): + # Check for function definition + match = re.search(self.patterns['function'], line) + if match: + # Save previous function if exists + if current_function: + func_code = '\n'.join(self.lines[function_start:i]) + functions.append(self._create_function_metrics( + current_function, function_start, i - 1, func_code + )) + + current_function = match.group(1) or match.group(2) if match.lastindex and match.lastindex > 1 else match.group(1) + function_start = i + brace_depth = 0 + + # Track braces for JS/TS + if self.language in ['javascript', 'typescript']: + brace_depth += line.count('{') - line.count('}') + + # Don't forget the last function + if current_function: + func_code = '\n'.join(self.lines[function_start:]) + functions.append(self._create_function_metrics( + current_function, function_start, len(self.lines) - 1, func_code + )) + + return functions + + def _create_function_metrics(self, name: str, start: int, end: int, code: str) -> FunctionMetrics: + """Create metrics for a single function.""" + lines = end - start + 1 + + # Count parameters (simplified) + param_match = re.search(r'\(([^)]*)\)', code.split('\n')[0]) + param_count = 0 + if param_match and param_match.group(1).strip(): + param_count = len([p for p in param_match.group(1).split(',') if p.strip()]) + + return FunctionMetrics( + name=name, + start_line=start + 1, + end_line=end + 1, + lines=lines, + cyclomatic_complexity=self.calculate_cyclomatic_complexity(code), + cognitive_complexity=self.calculate_cognitive_complexity(code), + parameter_count=param_count + ) + + def analyze(self) -> FileMetrics: + """Perform complete analysis of the file.""" + line_counts = self.count_lines() + functions = self.find_functions() + + # Count classes + class_count = len(re.findall(self.patterns['class'], self.code)) + + # Calculate averages + func_lengths = [f.lines for f in functions] if functions else [0] + avg_func_length = sum(func_lengths) / len(func_lengths) + max_func_length = max(func_lengths) + + return FileMetrics( + filename=self.filename, + lines_of_code=line_counts['code'], + blank_lines=line_counts['blank'], + comment_lines=line_counts['comment'], + function_count=len(functions), + class_count=class_count, + cyclomatic_complexity=self.calculate_cyclomatic_complexity(), + cognitive_complexity=self.calculate_cognitive_complexity(), + maintainability_index=self.calculate_maintainability_index(), + avg_function_length=round(avg_func_length, 1), + max_function_length=max_func_length, + functions=functions + ) + + +def print_metrics(metrics: FileMetrics, verbose: bool = False) -> None: + """Print metrics in a readable format.""" + print("=" * 60) + print(f"CODE COMPLEXITY ANALYSIS: {metrics.filename}") + print("=" * 60) + + print("\n๐Ÿ“Š OVERVIEW") + print("-" * 40) + print(f" Lines of Code: {metrics.lines_of_code}") + print(f" Blank Lines: {metrics.blank_lines}") + print(f" Comment Lines: {metrics.comment_lines}") + print(f" Functions/Methods: {metrics.function_count}") + print(f" Classes: {metrics.class_count}") + + print("\n๐Ÿ“ˆ COMPLEXITY METRICS") + print("-" * 40) + print(f" Cyclomatic Complexity: {metrics.cyclomatic_complexity}") + print(f" Cognitive Complexity: {metrics.cognitive_complexity}") + print(f" Maintainability Index: {metrics.maintainability_index}") + + # Interpret maintainability + mi = metrics.maintainability_index + if mi >= 85: + mi_label = "Highly maintainable โœ…" + elif mi >= 65: + mi_label = "Moderately maintainable ๐Ÿ”ถ" + elif mi >= 50: + mi_label = "Difficult to maintain โš ๏ธ" + else: + mi_label = "Very difficult to maintain โŒ" + print(f" โ†’ {mi_label}") + + print("\n๐Ÿ“ FUNCTION METRICS") + print("-" * 40) + print(f" Avg Function Length: {metrics.avg_function_length} lines") + print(f" Max Function Length: {metrics.max_function_length} lines") + + if verbose and metrics.functions: + print("\n๐Ÿ“‹ FUNCTION DETAILS") + print("-" * 40) + for f in sorted(metrics.functions, key=lambda x: x.cyclomatic_complexity, reverse=True): + flag = " โš ๏ธ" if f.cyclomatic_complexity > 10 or f.lines > 50 else "" + print(f" {f.name}() [lines {f.start_line}-{f.end_line}]{flag}") + print(f" - Lines: {f.lines}, CC: {f.cyclomatic_complexity}, " + f"Cognitive: {f.cognitive_complexity}, Params: {f.parameter_count}") + + print("\n" + "=" * 60) + + +def print_comparison(before: FileMetrics, after: FileMetrics) -> None: + """Print comparison between two analyses.""" + print("=" * 70) + print("CODE COMPLEXITY COMPARISON") + print("=" * 70) + + print(f"\n{'Metric':<30} {'Before':<15} {'After':<15} {'Change':<10}") + print("-" * 70) + + def fmt_change(before_val, after_val, lower_is_better=True): + diff = after_val - before_val + if lower_is_better: + symbol = "โœ…" if diff < 0 else ("โš ๏ธ" if diff > 0 else "โž–") + else: + symbol = "โœ…" if diff > 0 else ("โš ๏ธ" if diff < 0 else "โž–") + return f"{diff:+.1f} {symbol}" if isinstance(diff, float) else f"{diff:+d} {symbol}" + + metrics = [ + ("Lines of Code", before.lines_of_code, after.lines_of_code, True), + ("Function Count", before.function_count, after.function_count, False), + ("Class Count", before.class_count, after.class_count, False), + ("Cyclomatic Complexity", before.cyclomatic_complexity, after.cyclomatic_complexity, True), + ("Cognitive Complexity", before.cognitive_complexity, after.cognitive_complexity, True), + ("Maintainability Index", before.maintainability_index, after.maintainability_index, False), + ("Avg Function Length", before.avg_function_length, after.avg_function_length, True), + ("Max Function Length", before.max_function_length, after.max_function_length, True), + ] + + for name, b_val, a_val, lower_better in metrics: + change = fmt_change(b_val, a_val, lower_better) + print(f"{name:<30} {b_val:<15} {a_val:<15} {change:<10}") + + print("\n" + "=" * 70) + + # Overall assessment + print("\n๐ŸŽฏ ASSESSMENT") + print("-" * 40) + + improvements = 0 + regressions = 0 + + if after.maintainability_index > before.maintainability_index: + print(" โœ… Maintainability improved") + improvements += 1 + elif after.maintainability_index < before.maintainability_index: + print(" โš ๏ธ Maintainability decreased") + regressions += 1 + + if after.cyclomatic_complexity < before.cyclomatic_complexity: + print(" โœ… Complexity reduced") + improvements += 1 + elif after.cyclomatic_complexity > before.cyclomatic_complexity: + print(" โš ๏ธ Complexity increased") + regressions += 1 + + if after.avg_function_length < before.avg_function_length: + print(" โœ… Functions are smaller on average") + improvements += 1 + elif after.avg_function_length > before.avg_function_length: + print(" โš ๏ธ Functions grew larger on average") + regressions += 1 + + print(f"\n Summary: {improvements} improvements, {regressions} regressions") + print("=" * 70) + + +def analyze_directory(directory: str, verbose: bool = False) -> None: + """Analyze all supported files in a directory.""" + supported_extensions = ['.py', '.js', '.jsx', '.ts', '.tsx'] + files = [] + + for root, _, filenames in os.walk(directory): + for filename in filenames: + if any(filename.endswith(ext) for ext in supported_extensions): + files.append(os.path.join(root, filename)) + + if not files: + print(f"No supported files found in {directory}") + return + + print(f"Analyzing {len(files)} files in {directory}...\n") + + total_loc = 0 + total_cc = 0 + total_functions = 0 + all_metrics = [] + + for filepath in sorted(files): + try: + analyzer = ComplexityAnalyzer(filepath) + metrics = analyzer.analyze() + all_metrics.append(metrics) + + total_loc += metrics.lines_of_code + total_cc += metrics.cyclomatic_complexity + total_functions += metrics.function_count + + if verbose: + print_metrics(metrics, verbose=True) + else: + flag = " โš ๏ธ" if metrics.maintainability_index < 65 else "" + print(f" {metrics.filename}: LOC={metrics.lines_of_code}, " + f"CC={metrics.cyclomatic_complexity}, MI={metrics.maintainability_index}{flag}") + except Exception as e: + print(f" Error analyzing {filepath}: {e}") + + print("\n" + "=" * 60) + print("SUMMARY") + print("=" * 60) + print(f" Files analyzed: {len(all_metrics)}") + print(f" Total lines of code: {total_loc}") + print(f" Total complexity: {total_cc}") + print(f" Total functions: {total_functions}") + + if all_metrics: + avg_mi = sum(m.maintainability_index for m in all_metrics) / len(all_metrics) + print(f" Avg maintainability: {avg_mi:.1f}") + + +def main(): + parser = argparse.ArgumentParser( + description='Analyze code complexity metrics', + formatter_class=argparse.RawDescriptionHelpFormatter, + epilog=""" +Examples: + %(prog)s myfile.py Analyze single file + %(prog)s before.py after.py Compare two versions + %(prog)s --dir src/ Analyze directory + %(prog)s -v myfile.py Verbose output with function details + """ + ) + parser.add_argument('files', nargs='*', help='File(s) to analyze') + parser.add_argument('--dir', '-d', help='Directory to analyze') + parser.add_argument('--verbose', '-v', action='store_true', help='Show detailed function metrics') + parser.add_argument('--json', '-j', action='store_true', help='Output as JSON') + + args = parser.parse_args() + + if args.dir: + analyze_directory(args.dir, args.verbose) + elif len(args.files) == 1: + analyzer = ComplexityAnalyzer(args.files[0]) + metrics = analyzer.analyze() + + if args.json: + import json + print(json.dumps({ + 'filename': metrics.filename, + 'lines_of_code': metrics.lines_of_code, + 'cyclomatic_complexity': metrics.cyclomatic_complexity, + 'cognitive_complexity': metrics.cognitive_complexity, + 'maintainability_index': metrics.maintainability_index, + 'function_count': metrics.function_count, + 'avg_function_length': metrics.avg_function_length, + }, indent=2)) + else: + print_metrics(metrics, args.verbose) + elif len(args.files) == 2: + before_analyzer = ComplexityAnalyzer(args.files[0]) + after_analyzer = ComplexityAnalyzer(args.files[1]) + before_metrics = before_analyzer.analyze() + after_metrics = after_analyzer.analyze() + print_comparison(before_metrics, after_metrics) + else: + parser.print_help() + sys.exit(1) + + +if __name__ == '__main__': + main() diff --git a/ko/03-skills/refactor/scripts/detect-smells.py b/ko/03-skills/refactor/scripts/detect-smells.py new file mode 100644 index 00000000..7ecd6284 --- /dev/null +++ b/ko/03-skills/refactor/scripts/detect-smells.py @@ -0,0 +1,711 @@ +#!/usr/bin/env python3 +""" +Code Smell Detector + +Detects common code smells in Python, JavaScript, and TypeScript files. +Based on Martin Fowler's catalog of code smells. + +Usage: + python detect-smells.py + python detect-smells.py --dir + python detect-smells.py -v # Verbose with code snippets + +Detects: + - Long Method (>30 lines) + - Long Parameter List (>4 params) + - Duplicate Code (similar code blocks) + - Large Class (>300 lines, >10 methods) + - Dead Code (unused variables/functions) + - Complex Conditionals (deep nesting, long chains) + - Magic Numbers/Strings + - Feature Envy (methods using other class data heavily) + - Comments explaining what (not why) +""" + +import argparse +import os +import re +import sys +from dataclasses import dataclass, field +from enum import Enum +from typing import Dict, List, Optional, Set, Tuple +from collections import defaultdict + + +class SmellSeverity(Enum): + """Severity levels for code smells.""" + LOW = "Low" + MEDIUM = "Medium" + HIGH = "High" + CRITICAL = "Critical" + + +class SmellType(Enum): + """Types of code smells.""" + LONG_METHOD = "Long Method" + LONG_PARAMETER_LIST = "Long Parameter List" + DUPLICATE_CODE = "Duplicate Code" + LARGE_CLASS = "Large Class" + DEAD_CODE = "Dead Code" + COMPLEX_CONDITIONAL = "Complex Conditional" + MAGIC_NUMBER = "Magic Number/String" + FEATURE_ENVY = "Feature Envy" + EXCESSIVE_COMMENTS = "Excessive Comments" + DEEPLY_NESTED = "Deeply Nested Code" + PRIMITIVE_OBSESSION = "Primitive Obsession" + DATA_CLUMPS = "Data Clumps" + SWITCH_STATEMENT = "Switch Statement" + MESSAGE_CHAIN = "Message Chain" + + +@dataclass +class CodeSmell: + """Represents a detected code smell.""" + smell_type: SmellType + severity: SmellSeverity + location: str + line_start: int + line_end: int + description: str + suggestion: str + code_snippet: str = "" + + +@dataclass +class SmellReport: + """Report of all smells found in a file.""" + filename: str + smells: List[CodeSmell] = field(default_factory=list) + + @property + def critical_count(self) -> int: + return sum(1 for s in self.smells if s.severity == SmellSeverity.CRITICAL) + + @property + def high_count(self) -> int: + return sum(1 for s in self.smells if s.severity == SmellSeverity.HIGH) + + @property + def medium_count(self) -> int: + return sum(1 for s in self.smells if s.severity == SmellSeverity.MEDIUM) + + @property + def low_count(self) -> int: + return sum(1 for s in self.smells if s.severity == SmellSeverity.LOW) + + +class SmellDetector: + """Detect code smells in source files.""" + + # Thresholds (configurable) + THRESHOLDS = { + 'long_method_lines': 30, + 'very_long_method_lines': 50, + 'max_parameters': 4, + 'large_class_lines': 300, + 'large_class_methods': 10, + 'max_nesting_depth': 4, + 'long_chain_length': 3, + 'duplicate_min_lines': 5, + } + + def __init__(self, filepath: str): + self.filepath = filepath + self.filename = os.path.basename(filepath) + self.language = self._detect_language() + + with open(filepath, 'r', encoding='utf-8', errors='ignore') as f: + self.code = f.read() + self.lines = self.code.split('\n') + self.smells: List[CodeSmell] = [] + + def _detect_language(self) -> str: + """Detect programming language from file extension.""" + ext = os.path.splitext(self.filepath)[1].lower() + ext_map = { + '.py': 'python', + '.js': 'javascript', + '.jsx': 'javascript', + '.ts': 'typescript', + '.tsx': 'typescript', + } + return ext_map.get(ext, 'python') + + def detect_all(self) -> SmellReport: + """Run all smell detectors.""" + self._detect_long_methods() + self._detect_long_parameter_lists() + self._detect_large_class() + self._detect_complex_conditionals() + self._detect_magic_numbers() + self._detect_excessive_comments() + self._detect_deeply_nested() + self._detect_switch_statements() + self._detect_message_chains() + self._detect_duplicate_code() + self._detect_dead_code() + + return SmellReport(filename=self.filename, smells=self.smells) + + def _get_snippet(self, start: int, end: int, context: int = 2) -> str: + """Get code snippet with context.""" + actual_start = max(0, start - context) + actual_end = min(len(self.lines), end + context) + snippet_lines = [] + for i in range(actual_start, actual_end): + prefix = "โ†’ " if start <= i < end else " " + snippet_lines.append(f"{i+1:4d} {prefix}{self.lines[i]}") + return '\n'.join(snippet_lines) + + def _detect_long_methods(self) -> None: + """Detect methods that are too long.""" + if self.language == 'python': + pattern = r'^\s*def\s+(\w+)\s*\([^)]*\):' + else: + pattern = r'(?:function\s+(\w+)|(\w+)\s*[=:]\s*(?:async\s+)?(?:function|\([^)]*\)\s*=>))' + + current_method = None + method_start = 0 + brace_depth = 0 + indent_level = 0 + + for i, line in enumerate(self.lines): + match = re.search(pattern, line) + if match: + # Check previous method if exists + if current_method: + method_lines = i - method_start + self._check_method_length(current_method, method_start, i - 1, method_lines) + + current_method = match.group(1) or (match.group(2) if match.lastindex and match.lastindex > 1 else None) + method_start = i + indent_level = len(line) - len(line.lstrip()) + + # Track end of Python functions by indentation + if self.language == 'python' and current_method: + if line.strip() and not line.strip().startswith('#'): + current_indent = len(line) - len(line.lstrip()) + if current_indent <= indent_level and i > method_start: + method_lines = i - method_start + self._check_method_length(current_method, method_start, i - 1, method_lines) + current_method = None + + # Check last method + if current_method: + method_lines = len(self.lines) - method_start + self._check_method_length(current_method, method_start, len(self.lines) - 1, method_lines) + + def _check_method_length(self, name: str, start: int, end: int, lines: int) -> None: + """Check if method is too long and add smell if so.""" + if lines > self.THRESHOLDS['very_long_method_lines']: + severity = SmellSeverity.HIGH + desc = f"Method '{name}' is {lines} lines (threshold: {self.THRESHOLDS['long_method_lines']})" + elif lines > self.THRESHOLDS['long_method_lines']: + severity = SmellSeverity.MEDIUM + desc = f"Method '{name}' is {lines} lines (threshold: {self.THRESHOLDS['long_method_lines']})" + else: + return + + self.smells.append(CodeSmell( + smell_type=SmellType.LONG_METHOD, + severity=severity, + location=f"{self.filename}:{start+1}-{end+1}", + line_start=start + 1, + line_end=end + 1, + description=desc, + suggestion="Apply Extract Method to break down into smaller functions", + code_snippet=self._get_snippet(start, min(start + 5, end), 0) + )) + + def _detect_long_parameter_lists(self) -> None: + """Detect functions with too many parameters.""" + if self.language == 'python': + pattern = r'def\s+(\w+)\s*\(([^)]*)\)' + else: + pattern = r'(?:function\s+(\w+)\s*\(([^)]*)\)|(\w+)\s*[=:]\s*(?:async\s+)?(?:function\s*)?\(([^)]*)\))' + + for i, line in enumerate(self.lines): + match = re.search(pattern, line) + if match: + # Safely extract groups + groups = match.groups() + func_name = groups[0] or (groups[2] if len(groups) > 2 else None) + params_str = groups[1] if len(groups) > 1 else "" + if not params_str and len(groups) > 3: + params_str = groups[3] or "" + + # Count parameters + if params_str.strip(): + params = [p.strip() for p in params_str.split(',') if p.strip()] + # Filter out 'self', 'cls' for Python + if self.language == 'python': + params = [p for p in params if p not in ('self', 'cls')] + param_count = len(params) + + if param_count > self.THRESHOLDS['max_parameters']: + severity = SmellSeverity.HIGH if param_count > 6 else SmellSeverity.MEDIUM + self.smells.append(CodeSmell( + smell_type=SmellType.LONG_PARAMETER_LIST, + severity=severity, + location=f"{self.filename}:{i+1}", + line_start=i + 1, + line_end=i + 1, + description=f"Function '{func_name}' has {param_count} parameters (max: {self.THRESHOLDS['max_parameters']})", + suggestion="Consider Introduce Parameter Object or Preserve Whole Object", + code_snippet=self._get_snippet(i, i + 1, 1) + )) + + def _detect_large_class(self) -> None: + """Detect classes that are too large.""" + if self.language == 'python': + class_pattern = r'^\s*class\s+(\w+)' + method_pattern = r'^\s+def\s+\w+' + else: + class_pattern = r'class\s+(\w+)' + method_pattern = r'(?:^\s+\w+\s*\([^)]*\)\s*\{|^\s+(?:async\s+)?\w+\s*=)' + + current_class = None + class_start = 0 + method_count = 0 + class_indent = 0 + + for i, line in enumerate(self.lines): + class_match = re.search(class_pattern, line) + if class_match: + # Check previous class + if current_class: + self._check_class_size(current_class, class_start, i - 1, method_count) + + current_class = class_match.group(1) + class_start = i + method_count = 0 + class_indent = len(line) - len(line.lstrip()) + + # Count methods in current class + if current_class and re.search(method_pattern, line): + method_count += 1 + + # Check last class + if current_class: + self._check_class_size(current_class, class_start, len(self.lines) - 1, method_count) + + def _check_class_size(self, name: str, start: int, end: int, methods: int) -> None: + """Check if class is too large.""" + lines = end - start + 1 + + issues = [] + severity = SmellSeverity.MEDIUM + + if lines > self.THRESHOLDS['large_class_lines']: + issues.append(f"{lines} lines (max: {self.THRESHOLDS['large_class_lines']})") + severity = SmellSeverity.HIGH + + if methods > self.THRESHOLDS['large_class_methods']: + issues.append(f"{methods} methods (max: {self.THRESHOLDS['large_class_methods']})") + if severity != SmellSeverity.HIGH: + severity = SmellSeverity.MEDIUM + + if issues: + self.smells.append(CodeSmell( + smell_type=SmellType.LARGE_CLASS, + severity=severity, + location=f"{self.filename}:{start+1}-{end+1}", + line_start=start + 1, + line_end=end + 1, + description=f"Class '{name}' is too large: {', '.join(issues)}", + suggestion="Apply Extract Class to split responsibilities", + code_snippet=self._get_snippet(start, start + 3, 0) + )) + + def _detect_complex_conditionals(self) -> None: + """Detect complex conditional expressions.""" + for i, line in enumerate(self.lines): + # Count logical operators in line + and_or_count = len(re.findall(r'\b(and|or|&&|\|\|)\b', line)) + + if and_or_count >= 3: + self.smells.append(CodeSmell( + smell_type=SmellType.COMPLEX_CONDITIONAL, + severity=SmellSeverity.MEDIUM, + location=f"{self.filename}:{i+1}", + line_start=i + 1, + line_end=i + 1, + description=f"Complex conditional with {and_or_count} logical operators", + suggestion="Apply Decompose Conditional or Consolidate Conditional Expression", + code_snippet=self._get_snippet(i, i + 1, 1) + )) + + def _detect_magic_numbers(self) -> None: + """Detect magic numbers and strings.""" + # Skip common acceptable values + acceptable = {'0', '1', '-1', '2', '100', 'true', 'false', 'null', 'None', '""', "''"} + + for i, line in enumerate(self.lines): + # Skip comments and imports + stripped = line.strip() + if stripped.startswith('#') or stripped.startswith('//') or \ + stripped.startswith('import') or stripped.startswith('from'): + continue + + # Find numeric literals (excluding in variable names) + numbers = re.findall(r'(? 2: + # Check if it's likely a magic number (in calculation or comparison) + if re.search(rf'[<>=+\-*/]\s*{re.escape(num)}|{re.escape(num)}\s*[<>=+\-*/]', line): + self.smells.append(CodeSmell( + smell_type=SmellType.MAGIC_NUMBER, + severity=SmellSeverity.LOW, + location=f"{self.filename}:{i+1}", + line_start=i + 1, + line_end=i + 1, + description=f"Magic number '{num}' - consider using a named constant", + suggestion="Replace magic number with named constant", + code_snippet=self._get_snippet(i, i + 1, 0) + )) + break # One magic number per line is enough + + def _detect_excessive_comments(self) -> None: + """Detect comments that explain 'what' instead of 'why'.""" + what_patterns = [ + r'#\s*(set|get|return|loop|iterate|check|if|increment|decrement)', + r'//\s*(set|get|return|loop|iterate|check|if|increment|decrement)', + ] + + for i, line in enumerate(self.lines): + for pattern in what_patterns: + if re.search(pattern, line, re.IGNORECASE): + self.smells.append(CodeSmell( + smell_type=SmellType.EXCESSIVE_COMMENTS, + severity=SmellSeverity.LOW, + location=f"{self.filename}:{i+1}", + line_start=i + 1, + line_end=i + 1, + description="Comment explains 'what' not 'why' - consider renaming or removing", + suggestion="Use Extract Method with descriptive name instead of comment", + code_snippet=self._get_snippet(i, i + 1, 0) + )) + break + + def _detect_deeply_nested(self) -> None: + """Detect deeply nested code blocks.""" + max_depth = 0 + current_depth = 0 + depth_start = 0 + + for i, line in enumerate(self.lines): + if self.language == 'python': + # Count by indentation + if line.strip(): + indent = len(line) - len(line.lstrip()) + depth = indent // 4 # Assume 4-space indent + if depth > current_depth: + if depth > max_depth: + max_depth = depth + if depth >= self.THRESHOLDS['max_nesting_depth']: + depth_start = i + current_depth = depth + else: + # Count braces + current_depth += line.count('{') - line.count('}') + if current_depth > max_depth: + max_depth = current_depth + if current_depth >= self.THRESHOLDS['max_nesting_depth']: + depth_start = i + + if max_depth >= self.THRESHOLDS['max_nesting_depth']: + self.smells.append(CodeSmell( + smell_type=SmellType.DEEPLY_NESTED, + severity=SmellSeverity.HIGH if max_depth > 5 else SmellSeverity.MEDIUM, + location=f"{self.filename}:{depth_start+1}", + line_start=depth_start + 1, + line_end=depth_start + 1, + description=f"Code nested {max_depth} levels deep (max: {self.THRESHOLDS['max_nesting_depth']})", + suggestion="Apply Replace Nested Conditional with Guard Clauses or Extract Method", + code_snippet=self._get_snippet(depth_start, depth_start + 5, 0) + )) + + def _detect_switch_statements(self) -> None: + """Detect switch statements that might need polymorphism.""" + if self.language == 'python': + # Python 3.10+ match statements or if/elif chains + pattern = r'^\s*(if|elif).*==.*:' + consecutive_conditions = 0 + chain_start = 0 + + for i, line in enumerate(self.lines): + if re.search(pattern, line): + if consecutive_conditions == 0: + chain_start = i + consecutive_conditions += 1 + else: + if consecutive_conditions >= 4: + self._add_switch_smell(chain_start, i - 1, consecutive_conditions) + consecutive_conditions = 0 + else: + # JavaScript/TypeScript switch + pattern = r'\bswitch\s*\(' + for i, line in enumerate(self.lines): + if re.search(pattern, line): + # Count cases + case_count = 0 + for j in range(i, min(i + 50, len(self.lines))): + case_count += len(re.findall(r'\bcase\b', self.lines[j])) + if case_count >= 4: + self._add_switch_smell(i, i + 1, case_count) + + def _add_switch_smell(self, start: int, end: int, cases: int) -> None: + """Add a switch statement smell.""" + self.smells.append(CodeSmell( + smell_type=SmellType.SWITCH_STATEMENT, + severity=SmellSeverity.MEDIUM, + location=f"{self.filename}:{start+1}", + line_start=start + 1, + line_end=end + 1, + description=f"Switch/case statement with {cases} cases - consider polymorphism", + suggestion="Apply Replace Conditional with Polymorphism", + code_snippet=self._get_snippet(start, start + 5, 0) + )) + + def _detect_message_chains(self) -> None: + """Detect long method chains (train wrecks).""" + chain_pattern = r'(\w+(?:\.\w+\([^)]*\)){3,})' + + for i, line in enumerate(self.lines): + matches = re.findall(chain_pattern, line) + for match in matches: + chain_length = match.count('.') + if chain_length >= self.THRESHOLDS['long_chain_length']: + self.smells.append(CodeSmell( + smell_type=SmellType.MESSAGE_CHAIN, + severity=SmellSeverity.MEDIUM, + location=f"{self.filename}:{i+1}", + line_start=i + 1, + line_end=i + 1, + description=f"Message chain with {chain_length} calls - violates Law of Demeter", + suggestion="Apply Hide Delegate to reduce coupling", + code_snippet=self._get_snippet(i, i + 1, 0) + )) + + def _detect_duplicate_code(self) -> None: + """Detect potential duplicate code blocks (simplified).""" + # Create line hashes for comparison + line_hashes: Dict[str, List[int]] = defaultdict(list) + + for i, line in enumerate(self.lines): + normalized = re.sub(r'\s+', ' ', line.strip()) + if len(normalized) > 20: # Only significant lines + line_hashes[normalized].append(i) + + # Find duplicates + for normalized, positions in line_hashes.items(): + if len(positions) >= 3: # At least 3 occurrences + self.smells.append(CodeSmell( + smell_type=SmellType.DUPLICATE_CODE, + severity=SmellSeverity.MEDIUM, + location=f"{self.filename}:{positions[0]+1}", + line_start=positions[0] + 1, + line_end=positions[0] + 1, + description=f"Potential duplicate code found {len(positions)} times", + suggestion="Apply Extract Method to eliminate duplication", + code_snippet=self._get_snippet(positions[0], positions[0] + 1, 0) + )) + + def _detect_dead_code(self) -> None: + """Detect potentially dead code (simplified).""" + # Look for common dead code patterns + patterns = [ + (r'^\s*#.*TODO.*delete', "TODO to delete"), + (r'^\s*#.*FIXME.*remove', "FIXME to remove"), + (r'^\s*//.*TODO.*delete', "TODO to delete"), + (r'^\s*//.*FIXME.*remove', "FIXME to remove"), + (r'^\s*if\s+False:', "Code behind 'if False'"), + (r'^\s*if\s*\(\s*false\s*\)', "Code behind 'if (false)'"), + ] + + for i, line in enumerate(self.lines): + for pattern, desc in patterns: + if re.search(pattern, line, re.IGNORECASE): + self.smells.append(CodeSmell( + smell_type=SmellType.DEAD_CODE, + severity=SmellSeverity.LOW, + location=f"{self.filename}:{i+1}", + line_start=i + 1, + line_end=i + 1, + description=f"Potential dead code: {desc}", + suggestion="Remove dead code", + code_snippet=self._get_snippet(i, i + 1, 0) + )) + + +def print_report(report: SmellReport, verbose: bool = False) -> None: + """Print smell report in readable format.""" + print("=" * 70) + print(f"CODE SMELL DETECTION REPORT: {report.filename}") + print("=" * 70) + + print(f"\n๐Ÿ“Š SUMMARY") + print("-" * 40) + print(f" Total smells found: {len(report.smells)}") + print(f" Critical: {report.critical_count}") + print(f" High: {report.high_count}") + print(f" Medium: {report.medium_count}") + print(f" Low: {report.low_count}") + + if not report.smells: + print("\nโœ… No code smells detected!") + print("=" * 70) + return + + # Group by type + by_type: Dict[SmellType, List[CodeSmell]] = defaultdict(list) + for smell in report.smells: + by_type[smell.smell_type].append(smell) + + print(f"\n๐Ÿ“‹ FINDINGS BY TYPE") + print("-" * 40) + + for smell_type, smells in sorted(by_type.items(), key=lambda x: -len(x[1])): + print(f"\n### {smell_type.value} ({len(smells)} found)") + + for smell in sorted(smells, key=lambda x: x.severity.value): + severity_icon = { + SmellSeverity.CRITICAL: "๐Ÿ”ด", + SmellSeverity.HIGH: "๐ŸŸ ", + SmellSeverity.MEDIUM: "๐ŸŸก", + SmellSeverity.LOW: "๐ŸŸข", + }[smell.severity] + + print(f"\n {severity_icon} [{smell.severity.value}] {smell.location}") + print(f" {smell.description}") + print(f" ๐Ÿ’ก {smell.suggestion}") + + if verbose and smell.code_snippet: + print(f"\n Code:") + for snippet_line in smell.code_snippet.split('\n'): + print(f" {snippet_line}") + + print("\n" + "=" * 70) + print("๐Ÿ’ก RECOMMENDED ACTIONS") + print("-" * 40) + + if report.critical_count > 0: + print(" 1. Address CRITICAL issues immediately") + if report.high_count > 0: + print(" 2. Plan to fix HIGH severity issues this sprint") + if report.medium_count > 0: + print(" 3. Schedule MEDIUM issues for upcoming work") + if report.low_count > 0: + print(" 4. Fix LOW issues opportunistically") + + print("\n" + "=" * 70) + + +def analyze_directory(directory: str, verbose: bool = False) -> None: + """Analyze all supported files in a directory.""" + supported_extensions = ['.py', '.js', '.jsx', '.ts', '.tsx'] + files = [] + + for root, _, filenames in os.walk(directory): + for filename in filenames: + if any(filename.endswith(ext) for ext in supported_extensions): + files.append(os.path.join(root, filename)) + + if not files: + print(f"No supported files found in {directory}") + return + + print(f"Scanning {len(files)} files in {directory}...\n") + + total_smells = 0 + total_critical = 0 + total_high = 0 + files_with_smells = 0 + + for filepath in sorted(files): + try: + detector = SmellDetector(filepath) + report = detector.detect_all() + + if report.smells: + files_with_smells += 1 + total_smells += len(report.smells) + total_critical += report.critical_count + total_high += report.high_count + + flag = " ๐Ÿ”ด" if report.critical_count else (" ๐ŸŸ " if report.high_count else " ๐ŸŸก") + print(f" {report.filename}: {len(report.smells)} smells{flag}") + + if verbose: + for smell in report.smells: + print(f" - [{smell.severity.value}] {smell.smell_type.value}: line {smell.line_start}") + else: + print(f" {report.filename}: โœ… Clean") + + except Exception as e: + print(f" Error analyzing {filepath}: {e}") + + print("\n" + "=" * 60) + print("SUMMARY") + print("=" * 60) + print(f" Files analyzed: {len(files)}") + print(f" Files with smells: {files_with_smells}") + print(f" Total smells found: {total_smells}") + print(f" Critical issues: {total_critical}") + print(f" High severity issues: {total_high}") + + +def main(): + parser = argparse.ArgumentParser( + description='Detect code smells in source files', + formatter_class=argparse.RawDescriptionHelpFormatter, + epilog=""" +Examples: + %(prog)s myfile.py Analyze single file + %(prog)s --dir src/ Analyze directory + %(prog)s -v myfile.py Verbose with code snippets + """ + ) + parser.add_argument('file', nargs='?', help='File to analyze') + parser.add_argument('--dir', '-d', help='Directory to analyze') + parser.add_argument('--verbose', '-v', action='store_true', help='Show code snippets') + parser.add_argument('--json', '-j', action='store_true', help='Output as JSON') + + args = parser.parse_args() + + if args.dir: + analyze_directory(args.dir, args.verbose) + elif args.file: + detector = SmellDetector(args.file) + report = detector.detect_all() + + if args.json: + import json + smells_data = [{ + 'type': s.smell_type.value, + 'severity': s.severity.value, + 'location': s.location, + 'line_start': s.line_start, + 'line_end': s.line_end, + 'description': s.description, + 'suggestion': s.suggestion, + } for s in report.smells] + print(json.dumps({ + 'filename': report.filename, + 'total_smells': len(report.smells), + 'critical': report.critical_count, + 'high': report.high_count, + 'medium': report.medium_count, + 'low': report.low_count, + 'smells': smells_data + }, indent=2)) + else: + print_report(report, args.verbose) + else: + parser.print_help() + sys.exit(1) + + +if __name__ == '__main__': + main() diff --git a/ko/03-skills/refactor/templates/refactoring-plan.md b/ko/03-skills/refactor/templates/refactoring-plan.md new file mode 100644 index 00000000..08154ba8 --- /dev/null +++ b/ko/03-skills/refactor/templates/refactoring-plan.md @@ -0,0 +1,306 @@ +# ๋ฆฌํŒฉํ† ๋ง ๊ณ„ํš ํ…œํ”Œ๋ฆฟ + +์ด ํ…œํ”Œ๋ฆฟ์„ ์‚ฌ์šฉํ•˜์—ฌ ๋ฆฌํŒฉํ† ๋ง ์ž‘์—…์„ ๋ฌธ์„œํ™”ํ•˜๊ณ  ์ถ”์ ํ•˜์„ธ์š”. + + +--- + +## ํ”„๋กœ์ ํŠธ ์ •๋ณด + +| Field | Value | +| ------------------ | ------------------------------------------------------ | +| **Project/Module** | [ํ”„๋กœ์ ํŠธ ์ด๋ฆ„] | +| **Target Files** | [๋ฆฌํŒฉํ† ๋งํ•  ํŒŒ์ผ ๋ชฉ๋ก] | +| **Date Created** | [์ƒ์„ฑ ๋‚ ์งœ] | +| **Author** | [์ž‘์„ฑ์ž] | +| **Status** | Draft / In Review / Approved / In Progress / Completed | + + +--- + +## ๊ฐœ์š” + +### ๋ชฉํ‘œ +- [ ] [์ฃผ์š” ๋ชฉํ‘œ: ์˜ˆ: ๊ฒฐ์ œ ์ฒ˜๋ฆฌ ๊ฐ€๋…์„ฑ ํ–ฅ์ƒ] +- [ ] [๋ถ€๊ฐ€ ๋ชฉํ‘œ: ์˜ˆ: ์ฝ”๋“œ ์ค‘๋ณต ๊ฐ์†Œ] +- [ ] [์ถ”๊ฐ€ ๋ชฉํ‘œ: ์˜ˆ: ํ…Œ์ŠคํŠธ ์šฉ์ด์„ฑ ํ–ฅ์ƒ] + +### ์ œ์•ฝ์กฐ๊ฑด +- [ ] [์ œ์•ฝ ์กฐ๊ฑด 1: ์˜ˆ: ๊ณต๊ฐœ API ๋ณ€๊ฒฝ ๋ถˆ๊ฐ€] +- [ ] [์ œ์•ฝ ์กฐ๊ฑด 2: ์˜ˆ: ํ•˜์œ„ ํ˜ธํ™˜์„ฑ ์œ ์ง€ ํ•„์ˆ˜] +- [ ] [์ œ์•ฝ ์กฐ๊ฑด 3: ์˜ˆ: ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ์Šคํ‚ค๋งˆ ๋ณ€๊ฒฝ ๊ธˆ์ง€] + + +### ์œ„ํ—˜์ˆ˜์ค€ +- [ ] Low - ๋ณ€๊ฒฝ ๋ฒ”์œ„๊ฐ€ ์ž‘๊ณ  ์ถฉ๋ถ„ํžˆ ํ…Œ์ŠคํŠธ๋œ ์ฝ”๋“œ +- [ ] Medium - ์ค‘๊ฐ„ ์ˆ˜์ค€์˜ ๋ณ€๊ฒฝ, ์ผ๋ถ€ ์œ„ํ—˜ ์กด์žฌ +- [ ] High - ํฐ ๊ทœ๋ชจ์˜ ๋ณ€๊ฒฝ, ์‹ ์ค‘ํ•œ ๊ฒ€ํ†  ํ•„์š” + +--- + +## ๋ฆฌํŒฉํ† ๋ง ์ „ ์ฒดํฌ๋ฆฌ์ŠคํŠธ + +### ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€ ํ‰๊ฐ€ + +| Metric | Current | Target | Status | +|--------|---------|--------|--------| +| Unit Test Coverage | __% | โ‰ฅ80% | | +| Integration Tests | Yes/No | Yes | | +| All Tests Passing | Yes/No | Yes | | + +### ์‹œ์ž‘ ์ „ ํ•„์ˆ˜ ์‚ฌํ•ญ +- [ ] ๋ชจ๋“  ํ…Œ์ŠคํŠธ ํ†ต๊ณผ +- [ ] ์ฝ”๋“œ ๊ฒ€ํ†  ๋ฐ ์ดํ•ด ์™„๋ฃŒ +- [ ] ๋ฐฑ์—… ๋˜๋Š” ๋ฒ„์ „ ๊ด€๋ฆฌ ์ค€๋น„ ์™„๋ฃŒ +- [ ] ์‚ฌ์šฉ์ž ์Šน์ธ ํš๋“ + + +--- + +## ์‹๋ณ„๋œ ์ฝ”๋“œ ์Šค๋ฉœ + +### ์š”์•ฝ + +| # | Smell | Location | Severity | Priority | +|---|-------|----------|----------|----------| +| 1 | [e.g., Long Method] | [file:line] | High | P1 | +| 2 | [e.g., Duplicate Code] | [file:line] | Medium | P2 | +| 3 | [e.g., Feature Envy] | [file:line] | Low | P3 | + +### ์ƒ์„ธ ๋ถ„์„ + +#### ์ฝ”๋“œ ์Šค๋ฉœ #1: [์ด๋ฆ„] + +**์œ„์น˜**: `path/to/file.js:45-120` + +**์„ค๋ช…**: [๋ฌธ์ œ์— ๋Œ€ํ•œ ์ƒ์„ธ ์„ค๋ช…] + +**์˜ํ–ฅ**: +- [์˜ํ–ฅ 1] +- [์˜ํ–ฅ 2] + +**์ œ์•ˆ๋œ ํ•ด๊ฒฐ ๋ฐฉ์•ˆ**: [ํ•ด๊ฒฐ ๋ฐฉ๋ฒ•์— ๋Œ€ํ•œ ๊ฐ„๋žตํ•œ ์„ค๋ช…] + +--- + +## ๋ฆฌํŒฉํ† ๋ง ๋‹จ๊ณ„ + +### Phase A: ๋น ๋ฅธ ๊ฐœ์„  ์‚ฌํ•ญ (๋‚ฎ์€ ์œ„ํ—˜๋„) + +**๋ชฉ์ **: ์ฆ‰๊ฐ์ ์ธ ํšจ๊ณผ๋ฅผ ์–ป์„ ์ˆ˜ ์žˆ๋Š” ๊ฐ„๋‹จํ•œ ๊ฐœ์„  + +**์˜ˆ์ƒ ๋ณ€๊ฒฝ ๋ฒ”์œ„**: [X๊ฐœ ํŒŒ์ผ, Y๊ฐœ ๋ฉ”์„œ๋“œ] + +**์‚ฌ์šฉ์ž ์Šน์ธ ํ•„์š” ์—ฌ๋ถ€**: Yes / No + +| # | Task | File | Refactoring | Status | +|---|------|------|-------------|--------| +| A1 | ๋ณ€์ˆ˜ `x`๋ฅผ `userCount`๋กœ ์ด๋ฆ„ ๋ณ€๊ฒฝ | utils.js:15 | Rename Variable | [ ] | +| A2 | ์‚ฌ์šฉ๋˜์ง€ ์•Š๋Š” `oldHandler()` ์ œ๊ฑฐ | api.js:89 | Remove Dead Code | [ ] | +| A3 | ์ค‘๋ณต๋œ ๊ฒ€์ฆ ๋กœ์ง ์ถ”์ถœ | form.js:23,67 | Extract Method | [ ] | + +**๋กค๋ฐฑ ๊ณ„ํš**: A1-A3 ์ปค๋ฐ‹ ๋˜๋Œ๋ฆฌ๊ธฐ + +--- + +### Phase B: ๊ตฌ์กฐ ๊ฐœ์„  (์ค‘๊ฐ„ ์œ„ํ—˜๋„) + +**๋ชฉ์ **: ์ฝ”๋“œ ๊ตฌ์กฐ์™€ ๊ฐ€๋…์„ฑ ๊ฐœ์„  + +**์˜ˆ์ƒ ๋ณ€๊ฒฝ ๋ฒ”์œ„**: [X๊ฐœ ํŒŒ์ผ, Y๊ฐœ ๋ฉ”์„œ๋“œ] + +**์‚ฌ์šฉ์ž ์Šน์ธ ํ•„์š” ์—ฌ๋ถ€**: Yes + +**์˜์กด์„ฑ**: Phase A ์™„๋ฃŒ ํ•„์ˆ˜ + + +| # | Task | File | Refactoring | Status | +| -- | ---------------------------------- | -------------- | -------------------------- | ------ | +| B1 | ๊ธด ๋ฉ”์„œ๋“œ์—์„œ `calculatePrice()` ์ถ”์ถœ | order.js:45 | Extract Method | [ ] | +| B2 | `OrderDetails` ๋งค๊ฐœ๋ณ€์ˆ˜ ๊ฐ์ฒด ๋„์ž… | order.js:12 | Introduce Parameter Object | [ ] | +| B3 | `formatAddress()`๋ฅผ Address ํด๋ž˜์Šค๋กœ ์ด๋™ | customer.js:78 | Move Method | [ ] | + + +**๋กค๋ฐฑ ๊ณ„ํš**: Phase A ์™„๋ฃŒ ํ›„ ์ปค๋ฐ‹์œผ๋กœ ๋˜๋Œ๋ฆฌ๊ธฐ + +--- + +### Phase C: ์•„ํ‚คํ…์ฒ˜ ๋ณ€๊ฒฝ (๋†’์€ ์œ„ํ—˜๋„) + +**๋ชฉ์ **: ๋” ๊นŠ์€ ๊ตฌ์กฐ์  ๋ฌธ์ œ ํ•ด๊ฒฐ + +**์˜ˆ์ƒ ๋ณ€๊ฒฝ ๋ฒ”์œ„**: [X๊ฐœ ํŒŒ์ผ, Y๊ฐœ ๋ฉ”์„œ๋“œ] + +**์‚ฌ์šฉ์ž ์Šน์ธ ํ•„์š” ์—ฌ๋ถ€**: Yes + +**์˜์กด์„ฑ**: Phase A์™€ B ์™„๋ฃŒ ํ•„์ˆ˜ + +| # | Task | File | Refactoring | Status | +| -- | ---------------------------- | ------------- | ------------------------------------- | ------ | +| C1 | ๊ฐ€๊ฒฉ ๊ณ„์‚ฐ switch ๋ฌธ์„ ๋‹คํ˜•์„ฑ์œผ๋กœ ๋Œ€์ฒด | pricing.js:30 | Replace Conditional with Polymorphism | [ ] | +| C2 | `NotificationService` ํด๋ž˜์Šค ์ถ”์ถœ | user.js:100 | Extract Class | [ ] | + + +**๋กค๋ฐฑ ๊ณ„ํš**: Phase B ์™„๋ฃŒ ํ›„ ์ปค๋ฐ‹์œผ๋กœ ๋˜๋Œ๋ฆฌ๊ธฐ + +--- + +## ์ƒ์„ธ ๋ฆฌํŒฉํ† ๋ง ์ ˆ์ฐจ + +### ์ž‘์—… [ID]: [์ž‘์—… ์ด๋ฆ„] + + +**Smell Addressed**: [์ฝ”๋“œ ์Šค๋ฉœ ์ด๋ฆ„] + +**Refactoring Technique**: [๋ฆฌํŒฉํ† ๋ง ๊ธฐ๋ฒ• ์ด๋ฆ„] + +**Risk Level**: Low / Medium / High + + +#### ๋ฐฐ๊ฒฝ + +**Before** (ํ˜„์žฌ ์ƒํƒœ): +```javascript +// Paste current code here +``` + +**After** (์˜ˆ์ƒ ์ƒํƒœ): +```javascript +// Paste expected code here +``` + +#### ๋‹จ๊ณ„๋ณ„ ์ˆ˜ํ–‰ ์ ˆ์ฐจ + +1. [ ] **Step 1**: [์„ค๋ช…] + + - Test: ํ•ด๋‹น ๋‹จ๊ณ„ ํ›„ ํ…Œ์ŠคํŠธ ์‹คํ–‰ + - Expected: ๋ชจ๋“  ํ…Œ์ŠคํŠธ ํ†ต๊ณผ + +2. [ ] **Step 2**: [์„ค๋ช…] + + - Test: ํ•ด๋‹น ๋‹จ๊ณ„ ํ›„ ํ…Œ์ŠคํŠธ ์‹คํ–‰ + - Expected: ๋ชจ๋“  ํ…Œ์ŠคํŠธ ํ†ต๊ณผ + +3. [ ] **Step 3**: [์„ค๋ช…] + + - Test: ํ•ด๋‹น ๋‹จ๊ณ„ ํ›„ ํ…Œ์ŠคํŠธ ์‹คํ–‰ + - Expected: ๋ชจ๋“  ํ…Œ์ŠคํŠธ ํ†ต๊ณผ + + +#### ๊ฒ€์ฆ + +- [ ] ๋ชจ๋“  ํ…Œ์ŠคํŠธ ํ†ต๊ณผ +- [ ] ๋™์ž‘ ๋ณ€๊ฒฝ ์—†์Œ +- [ ] ์ฝ”๋“œ ์ปดํŒŒ์ผ ์„ฑ๊ณต +- [ ] ์ƒˆ๋กœ์šด ๊ฒฝ๊ณ  ์—†์Œ + + +#### ์ปค๋ฐ‹ ๋ฉ”์‹œ์ง€ +``` +refactor: [Describe the refactoring] +``` + +--- + +## ์ง„ํ–‰ ์ƒํ™ฉ ์ถ”์  + +### ๋‹จ๊ณ„ ์ƒํƒœ + +| Phase | Status | Started | Completed | Tests Passing | +|-------|--------|---------|-----------|---------------| +| A | Not Started / In Progress / Done | | | | +| B | Not Started / In Progress / Done | | | | +| C | Not Started / In Progress / Done | | | | + +### ๋ฐœ์ƒํ•œ ์ด์Šˆ + +| # | Issue | Resolution | Status | +| - | ----- | ---------- | --------------- | +| 1 | [์„ค๋ช…] | [ํ•ด๊ฒฐ ๋ฐฉ๋ฒ•] | Open / Resolved | + +--- + +## ์ง€ํ‘œ ๋น„๊ต + +### ๋ฆฌํŒฉํ† ๋ง ์ „ + + +| Metric | File 1 | File 2 | Total | +|--------|--------|--------|-------| +| Lines of Code | | | | +| Cyclomatic Complexity | | | | +| Maintainability Index | | | | +| Number of Methods | | | | +| Avg Method Length | | | | + +### After Refactoring + +| Metric | File 1 | File 2 | Total | Change | +|--------|--------|--------|-------|--------| +| Lines of Code | | | | | +| Cyclomatic Complexity | | | | | +| Maintainability Index | | | | | +| Number of Methods | | | | | +| Avg Method Length | | | | | + +--- + +## ๋ฆฌํŒฉํ† ๋ง ํ›„ ์ฒดํฌ๋ฆฌ์ŠคํŠธ + +- [ ] ๋ชจ๋“  ํ…Œ์ŠคํŠธ ํ†ต๊ณผ +- [ ] ์ƒˆ๋กœ์šด ๊ฒฝ๊ณ  ๋˜๋Š” ์˜ค๋ฅ˜ ์—†์Œ +- [ ] ์ฝ”๋“œ ์ปดํŒŒ์ผ ์„ฑ๊ณต +- [ ] ์ˆ˜๋™ ๊ฒ€์ฆ ์™„๋ฃŒ +- [ ] ๋ฌธ์„œ ์—…๋ฐ์ดํŠธ ์™„๋ฃŒ (ํ•„์š”ํ•œ ๊ฒฝ์šฐ) +- [ ] ์ฝ”๋“œ ๋ฆฌ๋ทฐ ์™„๋ฃŒ +- [ ] ์ง€ํ‘œ ๊ฐœ์„  ํ™•์ธ +- [ ] ์‚ฌ์šฉ์ž ์ตœ์ข… ์Šน์ธ ํš๋“ + +--- + +## ํšŒ๊ณ  ๋ฐ ํ•™์Šต ๋‚ด์šฉ + +### ์ž˜๋œ ์  + +- [ํ•ญ๋ชฉ 1] +- [ํ•ญ๋ชฉ 2] + +### ๊ฐœ์„ ์ด ํ•„์š”ํ•œ ์  + +- [ํ•ญ๋ชฉ 1] +- [ํ•ญ๋ชฉ 2] + +### ํ–ฅํ›„ ๊ถŒ์žฅ ์‚ฌํ•ญ + +- [ํ•ญ๋ชฉ 1] +- [ํ•ญ๋ชฉ 2] + + +--- + +## ์Šน์ธ + +| Role | Name | Date | Signature | +|------|------|------|-----------| +| Plan Author | | | | +| Technical Lead | | | | +| Product Owner | | | | + +--- + +## ๋ถ€๋ก + +### A. ๊ด€๋ จ ๋ฌธ์„œ + +- [๊ด€๋ จ ๋ฌธ์„œ ๋งํฌ] + +### B. ์ฐธ๊ณ  ์ž๋ฃŒ + +- [์ฝ”๋“œ ์Šค๋ฉœ ์นดํƒˆ๋กœ๊ทธ ๋งํฌ] +- [๋ฆฌํŒฉํ† ๋ง ์นดํƒˆ๋กœ๊ทธ ๋งํฌ] + +### C. ์‚ฌ์šฉ ๋„๊ตฌ + +- [ํ…Œ์ŠคํŠธ ํ”„๋ ˆ์ž„์›Œํฌ] +- [๋ฆฐํŒ… ๋„๊ตฌ] +- [๋ณต์žก๋„ ๋ถ„์„ ๋„๊ตฌ] diff --git a/ko/04-subagents/README.md b/ko/04-subagents/README.md new file mode 100644 index 00000000..0e08d461 --- /dev/null +++ b/ko/04-subagents/README.md @@ -0,0 +1,1258 @@ + + + Claude How To + + +# ์„œ๋ธŒ์—์ด์ „ํŠธ - ์ข…ํ•ฉ ์ฐธ์กฐ ๊ฐ€์ด๋“œ + +์„œ๋ธŒ์—์ด์ „ํŠธ๋Š” Claude Code๊ฐ€ ์ž‘์—…์„ ์œ„์ž„ํ•  ์ˆ˜ ์žˆ๋Š” ์ „๋ฌธํ™”๋œ AI ์–ด์‹œ์Šคํ„ดํŠธ์ž…๋‹ˆ๋‹ค. ๊ฐ ์„œ๋ธŒ์—์ด์ „ํŠธ๋Š” ํŠน์ • ๋ชฉ์ ์„ ๊ฐ€์ง€๋ฉฐ, ์ฃผ ๋Œ€ํ™”์™€๋Š” ๋ณ„๊ฐœ์˜ ์ž์ฒด ์ปจํ…์ŠคํŠธ ์ฐฝ์„ ์‚ฌ์šฉํ•˜๊ณ , ํŠน์ • ๋„๊ตฌ์™€ ์‚ฌ์šฉ์ž ์ง€์ • ์‹œ์Šคํ…œ ํ”„๋กฌํ”„ํŠธ๋กœ ๊ตฌ์„ฑํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +## ๋ชฉ์ฐจ + +1. [๊ฐœ์š”](#๊ฐœ์š”) +2. [์ฃผ์š” ์ด์ ](#์ฃผ์š”-์ด์ ) +3. [ํŒŒ์ผ ์œ„์น˜](#ํŒŒ์ผ-์œ„์น˜) +4. [๊ตฌ์„ฑ](#๊ตฌ์„ฑ) +5. [๋‚ด์žฅ ์„œ๋ธŒ์—์ด์ „ํŠธ](#๋‚ด์žฅ-์„œ๋ธŒ์—์ด์ „ํŠธ) +6. [์„œ๋ธŒ์—์ด์ „ํŠธ ๊ด€๋ฆฌ](#์„œ๋ธŒ์—์ด์ „ํŠธ-๊ด€๋ฆฌ) +7. [์„œ๋ธŒ์—์ด์ „ํŠธ ์‚ฌ์šฉ](#์„œ๋ธŒ์—์ด์ „ํŠธ-์‚ฌ์šฉ) +8. [์žฌ๊ฐœ ๊ฐ€๋Šฅํ•œ ์—์ด์ „ํŠธ](#์žฌ๊ฐœ-๊ฐ€๋Šฅํ•œ-์—์ด์ „ํŠธ) +9. [์„œ๋ธŒ์—์ด์ „ํŠธ ์ฒด์ด๋‹](#์„œ๋ธŒ์—์ด์ „ํŠธ-์ฒด์ด๋‹) +10. [์„œ๋ธŒ์—์ด์ „ํŠธ์šฉ ์˜๊ตฌ ๋ฉ”๋ชจ๋ฆฌ](#์„œ๋ธŒ์—์ด์ „ํŠธ์šฉ-์˜๊ตฌ-๋ฉ”๋ชจ๋ฆฌ) +11. [๋ฐฑ๊ทธ๋ผ์šด๋“œ ์„œ๋ธŒ์—์ด์ „ํŠธ](#๋ฐฑ๊ทธ๋ผ์šด๋“œ-์„œ๋ธŒ์—์ด์ „ํŠธ) +12. [์›ŒํฌํŠธ๋ฆฌ ๊ฒฉ๋ฆฌ](#์›ŒํฌํŠธ๋ฆฌ-๊ฒฉ๋ฆฌ) +13. [์ƒ์„ฑ ๊ฐ€๋Šฅํ•œ ์„œ๋ธŒ์—์ด์ „ํŠธ ์ œํ•œ](#์ƒ์„ฑ-๊ฐ€๋Šฅํ•œ-์„œ๋ธŒ์—์ด์ „ํŠธ-์ œํ•œ) +14. [`claude agents` CLI ๋ช…๋ น](#claude-agents-cli-๋ช…๋ น) +15. [์—์ด์ „ํŠธ ํŒ€ (์‹คํ—˜์ )](#์—์ด์ „ํŠธ-ํŒ€-์‹คํ—˜์ ) +16. [ํ”Œ๋Ÿฌ๊ทธ์ธ ์„œ๋ธŒ์—์ด์ „ํŠธ ๋ณด์•ˆ](#ํ”Œ๋Ÿฌ๊ทธ์ธ-์„œ๋ธŒ์—์ด์ „ํŠธ-๋ณด์•ˆ) +17. [์•„ํ‚คํ…์ฒ˜](#์•„ํ‚คํ…์ฒ˜) +18. [์ปจํ…์ŠคํŠธ ๊ด€๋ฆฌ](#์ปจํ…์ŠคํŠธ-๊ด€๋ฆฌ) +19. [์„œ๋ธŒ์—์ด์ „ํŠธ ์‚ฌ์šฉ ์‹œ๊ธฐ](#์„œ๋ธŒ์—์ด์ „ํŠธ-์‚ฌ์šฉ-์‹œ๊ธฐ) +20. [๋ชจ๋ฒ” ์‚ฌ๋ก€](#๋ชจ๋ฒ”-์‚ฌ๋ก€) +21. [์ด ํด๋”์˜ ์„œ๋ธŒ์—์ด์ „ํŠธ ์˜ˆ์‹œ](#์ด-ํด๋”์˜-์„œ๋ธŒ์—์ด์ „ํŠธ-์˜ˆ์‹œ) +22. [์„ค์น˜ ์•ˆ๋‚ด](#์„ค์น˜-์•ˆ๋‚ด) +23. [๊ด€๋ จ ๊ฐœ๋…](#๊ด€๋ จ-๊ฐœ๋…) + +--- + +## ๊ฐœ์š” + +์„œ๋ธŒ์—์ด์ „ํŠธ๋Š” Claude Code์—์„œ ๋‹ค์Œ์„ ํ†ตํ•ด ์œ„์ž„๋œ ์ž‘์—…์„ ์‹คํ–‰ํ•  ์ˆ˜ ์žˆ๋„๋ก ํ•ฉ๋‹ˆ๋‹ค: + +- ๋ณ„๋„์˜ ์ปจํ…์ŠคํŠธ ์ฐฝ์„ ๊ฐ€์ง„ **๊ฒฉ๋ฆฌ๋œ AI ์–ด์‹œ์Šคํ„ดํŠธ** ์ƒ์„ฑ +- ์ „๋ฌธ ์ง€์‹์„ ์œ„ํ•œ **๋งž์ถคํ˜• ์‹œ์Šคํ…œ ํ”„๋กฌํ”„ํŠธ** ์ œ๊ณต +- ๊ธฐ๋Šฅ ์ œํ•œ์„ ์œ„ํ•œ **๋„๊ตฌ ์ ‘๊ทผ ์ œ์–ด** ์ ์šฉ +- ๋ณต์žกํ•œ ์ž‘์—…์œผ๋กœ ์ธํ•œ **์ปจํ…์ŠคํŠธ ์˜ค์—ผ** ๋ฐฉ์ง€ +- ์—ฌ๋Ÿฌ ์ „๋ฌธํ™”๋œ ์ž‘์—…์˜ **๋ณ‘๋ ฌ ์‹คํ–‰** ํ™œ์„ฑํ™” + +๊ฐ ์„œ๋ธŒ์—์ด์ „ํŠธ๋Š” ์ดˆ๊ธฐํ™”๋œ ์ƒํƒœ์—์„œ ๋…๋ฆฝ์ ์œผ๋กœ ์ž‘๋™ํ•˜๋ฉฐ, ์ž์‹ ์˜ ์ž‘์—…์— ํ•„์š”ํ•œ ํŠน์ • ์ปจํ…์ŠคํŠธ๋งŒ ๋ฐ›๊ณ , ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ์ฃผ ์—์ด์ „ํŠธ์—๊ฒŒ ๋ฐ˜ํ™˜ํ•˜์—ฌ ์ข…ํ•ฉํ•ฉ๋‹ˆ๋‹ค. + +**๋น ๋ฅธ ์‹œ์ž‘**: `/agents` ๋ช…๋ น์„ ์‚ฌ์šฉํ•˜์—ฌ ์„œ๋ธŒ์—์ด์ „ํŠธ๋ฅผ ๋Œ€ํ™”ํ˜•์œผ๋กœ ์ƒ์„ฑ, ํ™•์ธ, ํŽธ์ง‘ ๋ฐ ๊ด€๋ฆฌํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +--- + +## ์ฃผ์š” ์ด์  + +| Benefit | Description | +|---------|-------------| +| **์ปจํ…์ŠคํŠธ ๋ณด์กด** | ๋ณ„๋„์˜ ์ปจํ…์ŠคํŠธ์—์„œ ์ž‘๋™ํ•˜์—ฌ ์ฃผ ๋Œ€ํ™”์˜ ์˜ค์—ผ์„ ๋ฐฉ์ง€ | +| **์ „๋ฌธํ™”๋œ ์ „๋ฌธ์„ฑ** | ํŠน์ • ๋„๋ฉ”์ธ์— ๋งž๊ฒŒ ๋ฏธ์„ธ ์กฐ์ •๋˜์–ด ์„ฑ๊ณต๋ฅ ์ด ๋†’์Œ | +| **์žฌ์‚ฌ์šฉ์„ฑ** | ๋‹ค์–‘ํ•œ ํ”„๋กœ์ ํŠธ์—์„œ ์‚ฌ์šฉํ•˜๊ณ  ํŒ€๊ณผ ๊ณต์œ  ๊ฐ€๋Šฅ | +| **์œ ์—ฐํ•œ ๊ถŒํ•œ** | ์„œ๋ธŒ์—์ด์ „ํŠธ ์œ ํ˜•์— ๋”ฐ๋ผ ๋‹ค๋ฅธ ๋„๊ตฌ ์ ‘๊ทผ ์ˆ˜์ค€ | +| **ํ™•์žฅ์„ฑ** | ์—ฌ๋Ÿฌ ์—์ด์ „ํŠธ๊ฐ€ ์—ฌ๋Ÿฌ ์ธก๋ฉด์—์„œ ๋™์‹œ์— ์ž‘์—… | + +--- + +## ํŒŒ์ผ ์œ„์น˜ + +์„œ๋ธŒ์—์ด์ „ํŠธ ํŒŒ์ผ์€ ๋‹ค์–‘ํ•œ ๋ฒ”์œ„๋กœ ์—ฌ๋Ÿฌ ์œ„์น˜์— ์ €์žฅ๋  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +| Priority | Type | Location | Scope | +|----------|------|----------|-------| +| 1 (์ตœ๊ณ ) | **CLI ์ •์˜** | `--agents` ํ”Œ๋ž˜๊ทธ (JSON)๋ฅผ ํ†ตํ•ด | ์„ธ์…˜ ์ „์šฉ | +| 2 | **ํ”„๋กœ์ ํŠธ ์„œ๋ธŒ์—์ด์ „ํŠธ** | `.claude/agents/` | ํ˜„์žฌ ํ”„๋กœ์ ํŠธ | +| 3 | **์‚ฌ์šฉ์ž ์„œ๋ธŒ์—์ด์ „ํŠธ** | `~/.claude/agents/` | ๋ชจ๋“  ํ”„๋กœ์ ํŠธ | +| 4 (์ตœ์ €) | **ํ”Œ๋Ÿฌ๊ทธ์ธ ์—์ด์ „ํŠธ** | ํ”Œ๋Ÿฌ๊ทธ์ธ `agents/` ๋””๋ ‰ํ„ฐ๋ฆฌ | ํ”Œ๋Ÿฌ๊ทธ์ธ์„ ํ†ตํ•ด | + +์ค‘๋ณต๋œ ์ด๋ฆ„์ด ์กด์žฌํ•˜๋Š” ๊ฒฝ์šฐ, ์šฐ์„ ์ˆœ์œ„๊ฐ€ ๋†’์€ ์†Œ์Šค๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. + +> **์ค‘์ฒฉ๋œ `.claude/` ์šฐ์„ ์ˆœ์œ„ (v2.1.178)**: ๋™์ผํ•œ ์—์ด์ „ํŠธ ์ด๋ฆ„์ด ์—ฌ๋Ÿฌ ์ค‘์ฒฉ๋œ `.claude/agents/` ๋””๋ ‰ํ„ฐ๋ฆฌ(์˜ˆ: ํŒจํ‚ค์ง€ ์ˆ˜์ค€ `.claude/` ํด๋”๋ฅผ ๊ฐ€์ง„ ๋ชจ๋…ธ๋ ˆํฌ)์— ์ •์˜๋˜์–ด ์žˆ์„ ๋•Œ, **ํ˜„์žฌ ์ž‘์—… ๋””๋ ‰ํ„ฐ๋ฆฌ์— ๊ฐ€์žฅ ๊ฐ€๊นŒ์šด** ์ •์˜๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. ๋™์ผํ•œ '๊ฐ€์žฅ ๊ฐ€๊นŒ์šด ๊ฒƒ์ด ์šฐ์„ ' ๊ทœ์น™์€ ์ค‘์ฒฉ๋œ ์›Œํฌํ”Œ๋กœ ๋ฐ ์ถœ๋ ฅ ์Šคํƒ€์ผ ์ •์˜์—๋„ ์ ์šฉ๋ฉ๋‹ˆ๋‹ค. + + +--- + +## ๊ตฌ์„ฑ + +### ํŒŒ์ผ ํ˜•์‹ + +์„œ๋ธŒ์—์ด์ „ํŠธ๋Š” YAML ํ”„๋ŸฐํŠธ๋งคํ„ฐ๋กœ ์ •์˜๋˜๋ฉฐ, ๊ทธ ๋’ค์— ๋งˆํฌ๋‹ค์šด ํ˜•์‹์˜ ์‹œ์Šคํ…œ ํ”„๋กฌํ”„ํŠธ๊ฐ€ ์˜ต๋‹ˆ๋‹ค. + +```yaml +--- +name: your-sub-agent-name +description: Description of when this subagent should be invoked +tools: tool1, tool2, tool3 # Optional - inherits all tools if omitted +disallowedTools: tool4 # Optional - explicitly disallowed tools +model: sonnet # Optional - sonnet, opus, haiku, or inherit +permissionMode: default # Optional - permission mode +maxTurns: 20 # Optional - limit agentic turns +skills: skill1, skill2 # Optional - skills to preload into context +mcpServers: server1 # Optional - MCP servers to make available +memory: user # Optional - persistent memory scope (user, project, local) +background: false # Optional - run as background task +effort: high # Optional - reasoning effort (low, medium, high, max) +isolation: worktree # Optional - git worktree isolation +initialPrompt: "Start by analyzing the codebase" # Optional - auto-submitted first turn +hooks: # Optional - component-scoped hooks + PreToolUse: + - matcher: "Bash" + hooks: + - type: command + command: "./scripts/security-check.sh" +--- + +Your subagent's system prompt goes here. This can be multiple paragraphs +and should clearly define the subagent's role, capabilities, and approach +to solving problems. +``` + +### ๊ตฌ์„ฑ ํ•„๋“œ +| Field | Required | Description | +|-------|----------|-------------| +| `name` | ์˜ˆ | ๊ณ ์œ  ์‹๋ณ„์ž (์†Œ๋ฌธ์ž์™€ ํ•˜์ดํ”ˆ) | +| `description` | ์˜ˆ | ๋ชฉ์ ์— ๋Œ€ํ•œ ์ž์—ฐ์–ด ์„ค๋ช…. ์ž๋™ ํ˜ธ์ถœ์„ ์žฅ๋ คํ•˜๋ ค๋ฉด "use PROACTIVELY"๋ฅผ ํฌํ•จํ•˜์„ธ์š” | +| `tools` | ์•„๋‹ˆ์š” | ํŠน์ • ๋„๊ตฌ์˜ ์‰ผํ‘œ๋กœ ๊ตฌ๋ถ„๋œ ๋ชฉ๋ก. ์ƒ๋žตํ•˜๋ฉด ๋ชจ๋“  ๋„๊ตฌ๋ฅผ ์ƒ์†ํ•ฉ๋‹ˆ๋‹ค. ์ƒ์„ฑ ๊ฐ€๋Šฅํ•œ ์„œ๋ธŒ์—์ด์ „ํŠธ๋ฅผ ์ œํ•œํ•˜๊ธฐ ์œ„ํ•ด `Agent(agent_name)` ๊ตฌ๋ฌธ์„ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค | +| `disallowedTools` | ์•„๋‹ˆ์š” | ์„œ๋ธŒ์—์ด์ „ํŠธ๊ฐ€ ์‚ฌ์šฉํ•ด์„œ๋Š” ์•ˆ ๋˜๋Š” ๋„๊ตฌ์˜ ์‰ผํ‘œ๋กœ ๊ตฌ๋ถ„๋œ ๋ชฉ๋ก | +| `model` | ์•„๋‹ˆ์š” | ์‚ฌ์šฉํ•  ๋ชจ๋ธ: `sonnet`, `opus`, `haiku`, ์ „์ฒด ๋ชจ๋ธ ID ๋˜๋Š” `inherit`. ๊ธฐ๋ณธ๊ฐ’์€ ๊ตฌ์„ฑ๋œ ์„œ๋ธŒ์—์ด์ „ํŠธ ๋ชจ๋ธ์ž…๋‹ˆ๋‹ค | +| `permissionMode` | ์•„๋‹ˆ์š” | `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan` | +| `maxTurns` | ์•„๋‹ˆ์š” | ์„œ๋ธŒ์—์ด์ „ํŠธ๊ฐ€ ์ทจํ•  ์ˆ˜ ์žˆ๋Š” ์—์ด์ „ํŠธ ํ„ด์˜ ์ตœ๋Œ€ ์ˆ˜ | +| `skills` | ์•„๋‹ˆ์š” | ๋ฏธ๋ฆฌ ๋กœ๋“œํ•  ์Šคํ‚ฌ์˜ ์‰ผํ‘œ๋กœ ๊ตฌ๋ถ„๋œ ๋ชฉ๋ก. ์‹œ์ž‘ ์‹œ ์ „์ฒด ์Šคํ‚ฌ ์ฝ˜ํ…์ธ ๋ฅผ ์„œ๋ธŒ์—์ด์ „ํŠธ์˜ ์ปจํ…์ŠคํŠธ์— ์ฃผ์ž…ํ•ฉ๋‹ˆ๋‹ค. **v2.1.133+:** ์„œ๋ธŒ์—์ด์ „ํŠธ๋„ Skill ๋„๊ตฌ๋ฅผ ํ†ตํ•ด ํ”„๋กœ์ ํŠธ, ์‚ฌ์šฉ์ž ๋ฐ ํ”Œ๋Ÿฌ๊ทธ์ธ ์Šคํ‚ฌ์„ ๋ฐœ๊ฒฌํ•ฉ๋‹ˆ๋‹ค. ์ด๋Š” ์ฃผ ์„ธ์…˜๊ณผ ๋™์ผํ•œ ์นดํƒˆ๋กœ๊ทธ์ด๋ฉฐ, ๋” ์ด์ƒ ์ž์ฒด ๋‚ด์žฅ๋œ ์„ธํŠธ์— ๊ตญํ•œ๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. | +| `mcpServers` | ์•„๋‹ˆ์š” | ์„œ๋ธŒ์—์ด์ „ํŠธ์—์„œ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ๋„๋ก ํ•  MCP ์„œ๋ฒ„ | +| `hooks` | ์•„๋‹ˆ์š” | ๊ตฌ์„ฑ ์š”์†Œ ๋ฒ”์œ„ ํ›„ํฌ (PreToolUse, PostToolUse, Stop) | +| `memory` | ์•„๋‹ˆ์š” | ์˜๊ตฌ ๋ฉ”๋ชจ๋ฆฌ ๋””๋ ‰ํ„ฐ๋ฆฌ ๋ฒ”์œ„: `user`, `project` ๋˜๋Š” `local` | +| `background` | ์•„๋‹ˆ์š” | ์ด ์„œ๋ธŒ์—์ด์ „ํŠธ๋ฅผ ํ•ญ์ƒ ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž‘์—…์œผ๋กœ ์‹คํ–‰ํ•˜๋ ค๋ฉด `true`๋กœ ์„ค์ • | +| `effort` | ์•„๋‹ˆ์š” | ์ถ”๋ก  ๋…ธ๋ ฅ ์ˆ˜์ค€: `low`, `medium`, `high` ๋˜๋Š” `max` | +| `isolation` | ์•„๋‹ˆ์š” | ์„œ๋ธŒ์—์ด์ „ํŠธ์— ์ž์ฒด git ์›ŒํฌํŠธ๋ฆฌ๋ฅผ ์ œ๊ณตํ•˜๋ ค๋ฉด `worktree`๋กœ ์„ค์ • | +| `initialPrompt` | ์•„๋‹ˆ์š” | ์„œ๋ธŒ์—์ด์ „ํŠธ๊ฐ€ ์ฃผ ์—์ด์ „ํŠธ๋กœ ์‹คํ–‰๋  ๋•Œ ์ž๋™์œผ๋กœ ์ œ์ถœ๋˜๋Š” ์ฒซ ๋ฒˆ์งธ ํ„ด | + + +### ์ฃผ ์Šค๋ ˆ๋“œ ์—์ด์ „ํŠธ ํ”„๋ŸฐํŠธ๋งคํ„ฐ ์กด์ค‘ (v2.1.117+/v2.1.119+) + +์—์ด์ „ํŠธ๊ฐ€ ์ฃผ ์Šค๋ ˆ๋“œ ์—์ด์ „ํŠธ๋กœ ํ˜ธ์ถœ๋  ๋•Œ (`claude --agent ` ๋˜๋Š” `--print` ๋ชจ๋“œ๋ฅผ ํ†ตํ•ด), ๋‹ค์Œ ํ”„๋ŸฐํŠธ๋งคํ„ฐ ํ•„๋“œ๊ฐ€ ์กด์ค‘๋ฉ๋‹ˆ๋‹ค. + +| Field | Version | Notes | +|-------|---------|-------| +| `mcpServers` | v2.1.117+ | ์—์ด์ „ํŠธ๊ฐ€ `claude --agent `์„ ํ†ตํ•ด ์ฃผ ์Šค๋ ˆ๋“œ ์—์ด์ „ํŠธ๋กœ ํ˜ธ์ถœ๋  ๋•Œ ๋กœ๋“œ๋ฉ๋‹ˆ๋‹ค | +| `permissionMode` | v2.1.119+ | `--agent `์„ ํ†ตํ•ด ๋‚ด์žฅ ์—์ด์ „ํŠธ์— ๋Œ€ํ•ด ์กด์ค‘๋ฉ๋‹ˆ๋‹ค | +| `tools` / `disallowedTools` | v2.1.119+ | `--print` ๋ชจ๋“œ(๋น„๋Œ€ํ™”ํ˜•/์Šคํฌ๋ฆฝํŠธ ์‚ฌ์šฉ)์—์„œ ์กด์ค‘๋ฉ๋‹ˆ๋‹ค | + +**์˜ˆ์‹œ โ€” `mcpServers` ๋ฐ `permissionMode`๋ฅผ ์‚ฌ์šฉํ•˜๋Š” ์—์ด์ „ํŠธ:** + +```yaml +--- +name: secure-researcher +description: Research agent with scoped MCP access and restricted permissions +permissionMode: acceptEdits +mcpServers: + notion: + type: http + url: https://mcp.notion.com/mcp + github: + type: http + url: https://api.github.com/mcp +tools: Read, Grep, Glob +--- + +You are a research agent. You may query Notion and GitHub through the +configured MCP servers, and read local files, but you cannot write or +execute commands outside of accepted edits. +``` + +Run with: + +```bash +claude --agent secure-researcher +``` + +### ๋„๊ตฌ ๊ตฌ์„ฑ ์˜ต์…˜ + +**์˜ต์…˜ 1: ๋ชจ๋“  ๋„๊ตฌ ์ƒ์† (ํ•„๋“œ ์ƒ๋žต)** +```yaml +--- +name: full-access-agent +description: Agent with all available tools +--- +``` + +**์˜ต์…˜ 2: ๊ฐœ๋ณ„ ๋„๊ตฌ ์ง€์ •** +```yaml +--- +name: limited-agent +description: Agent with specific tools only +tools: Read, Grep, Glob, Bash +--- +``` + +> **Glob/Grep์— ๋Œ€ํ•œ ์ฐธ๊ณ  (v2.1.113+):** ๊ธฐ๋ณธ macOS/Linux ๋นŒ๋“œ์—์„œ๋Š” Glob๊ณผ Grep์ด ๋ณ„๋„์˜ ๋„๊ตฌ๊ฐ€ ์•„๋‹Œ Bash ๋„๊ตฌ๋ฅผ ํ†ตํ•ด `bfs`/`ugrep`์œผ๋กœ ์ œ๊ณต๋ฉ๋‹ˆ๋‹ค. Windows ๋ฐ npm-JS ๋นŒ๋“œ์—์„œ๋Š” ์—ฌ์ „ํžˆ ๋…๋ฆฝํ˜• ๋„๊ตฌ๋กœ ๋…ธ์ถœ๋ฉ๋‹ˆ๋‹ค. ์ž‘์„ฑ์ž๋Š” `allowedTools`์—์„œ Glob/Grep์„ ๊ณ„์† ์ฐธ์กฐํ•  ์ˆ˜ ์žˆ์œผ๋ฉฐ, ๋ฐฑ์—”๋“œ ๋Œ€์ฒด๋Š” ํˆฌ๋ช…ํ•˜๊ฒŒ ์ด๋ฃจ์–ด์ง‘๋‹ˆ๋‹ค. + +**์˜ต์…˜ 3: ์กฐ๊ฑด๋ถ€ ๋„๊ตฌ ์ ‘๊ทผ** +```yaml +--- +name: conditional-agent +description: Agent with filtered tool access +tools: Read, Bash(npm:*), Bash(test:*) +--- +``` + +### CLI ๊ธฐ๋ฐ˜ ๊ตฌ์„ฑ + +๋‹จ์ผ ์„ธ์…˜์— ๋Œ€ํ•œ ์„œ๋ธŒ์—์ด์ „ํŠธ๋ฅผ JSON ํ˜•์‹์˜ `--agents` ํ”Œ๋ž˜๊ทธ๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ์ •์˜ํ•ฉ๋‹ˆ๋‹ค. + +```bash +claude --agents '{ + "code-reviewer": { + "description": "Expert code reviewer. Use proactively after code changes.", + "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.", + "tools": ["Read", "Grep", "Glob", "Bash"], + "model": "sonnet" + } +}' +``` + +**`--agents` ํ”Œ๋ž˜๊ทธ์šฉ JSON ํ˜•์‹:** + +```json +{ + "agent-name": { + "description": "Required: when to invoke this agent", + "prompt": "Required: system prompt for the agent", + "tools": ["Optional", "array", "of", "tools"], + "model": "optional: sonnet|opus|haiku" + } +} +``` + +**์—์ด์ „ํŠธ ์ •์˜์˜ ์šฐ์„ ์ˆœ์œ„:** + +์—์ด์ „ํŠธ ์ •์˜๋Š” ๋‹ค์Œ ์šฐ์„ ์ˆœ์œ„ ์ˆœ์„œ๋กœ ๋กœ๋“œ๋ฉ๋‹ˆ๋‹ค (์ฒซ ๋ฒˆ์งธ ์ผ์น˜ ํ•ญ๋ชฉ์ด ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค). +2. **CLI ์ •์˜** - `--agents` ํ”Œ๋ž˜๊ทธ (์„ธ์…˜ ์ „์šฉ, JSON) +4. **ํ”„๋กœ์ ํŠธ ์ˆ˜์ค€** - `.claude/agents/` (ํ˜„์žฌ ํ”„๋กœ์ ํŠธ) +6. **์‚ฌ์šฉ์ž ์ˆ˜์ค€** - `~/.claude/agents/` (๋ชจ๋“  ํ”„๋กœ์ ํŠธ) +8. **ํ”Œ๋Ÿฌ๊ทธ์ธ ์ˆ˜์ค€** - ํ”Œ๋Ÿฌ๊ทธ์ธ `agents/` ๋””๋ ‰ํ„ฐ๋ฆฌ + +์ด๋ฅผ ํ†ตํ•ด CLI ์ •์˜๋Š” ๋‹จ์ผ ์„ธ์…˜์— ๋Œ€ํ•ด ๋‹ค๋ฅธ ๋ชจ๋“  ์†Œ์Šค๋ฅผ ์žฌ์ •์˜ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +--- + +## ๋‚ด์žฅ ์„œ๋ธŒ์—์ด์ „ํŠธ + +Claude Code์—๋Š” ํ•ญ์ƒ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ๋Š” ์—ฌ๋Ÿฌ ๋‚ด์žฅ ์„œ๋ธŒ์—์ด์ „ํŠธ๊ฐ€ ํฌํ•จ๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +| Agent | Model | Purpose | +|-------|-------|---------| +| **general-purpose** | ์ƒ์† | ๋ณต์žกํ•˜๊ณ  ๋‹ค๋‹จ๊ณ„์ ์ธ ์ž‘์—… | +| **Plan** | ์ƒ์† | ๊ณ„ํš ๋ชจ๋“œ๋ฅผ ์œ„ํ•œ ์—ฐ๊ตฌ | +| **Explore** | Haiku | ์ฝ๊ธฐ ์ „์šฉ ์ฝ”๋“œ๋ฒ ์ด์Šค ํƒ์ƒ‰ (๋น ๋ฅธ/์ค‘๊ฐ„/๋งค์šฐ ์ฒ ์ €ํ•œ) | +| **Bash** | ์ƒ์† | ๋ณ„๋„์˜ ์ปจํ…์ŠคํŠธ์—์„œ ํ„ฐ๋ฏธ๋„ ๋ช…๋ น | +| **statusline-setup** | Sonnet | ์ƒํƒœ ํ‘œ์‹œ์ค„ ๊ตฌ์„ฑ | +| **Claude Code Guide** | Haiku | Claude Code ๊ธฐ๋Šฅ ์งˆ๋ฌธ์— ๋‹ต๋ณ€ | + +### ์ผ๋ฐ˜ ๋ชฉ์  ์„œ๋ธŒ์—์ด์ „ํŠธ + +| Property | Value | +|----------|-------| +| **๋ชจ๋ธ** | ๋ถ€๋ชจ๋กœ๋ถ€ํ„ฐ ์ƒ์† | +| **๋„๊ตฌ** | ๋ชจ๋“  ๋„๊ตฌ | +| **๋ชฉ์ ** | ๋ณต์žกํ•œ ์—ฐ๊ตฌ ์ž‘์—…, ๋‹ค๋‹จ๊ณ„ ์ž‘์—…, ์ฝ”๋“œ ์ˆ˜์ • | + +**์‚ฌ์šฉ ์‹œ๊ธฐ**: ๋ณต์žกํ•œ ์ถ”๋ก ์„ ํ†ตํ•ด ํƒ์ƒ‰๊ณผ ์ˆ˜์ •์ด ๋ชจ๋‘ ํ•„์š”ํ•œ ์ž‘์—…. + +### ๊ณ„ํš ์„œ๋ธŒ์—์ด์ „ํŠธ + +| Property | Value | +|----------|-------| +| **๋ชจ๋ธ** | ๋ถ€๋ชจ๋กœ๋ถ€ํ„ฐ ์ƒ์† | +| **๋„๊ตฌ** | Read, Glob, Grep, Bash | +| **๋ชฉ์ ** | ๊ณ„ํš ๋ชจ๋“œ์—์„œ ์ฝ”๋“œ๋ฒ ์ด์Šค๋ฅผ ์—ฐ๊ตฌํ•˜๊ธฐ ์œ„ํ•ด ์ž๋™์œผ๋กœ ์‚ฌ์šฉ๋ฉ๋‹ˆ๋‹ค | + +**์‚ฌ์šฉ ์‹œ๊ธฐ**: Claude๊ฐ€ ๊ณ„ํš์„ ์ œ์‹œํ•˜๊ธฐ ์ „์— ์ฝ”๋“œ๋ฒ ์ด์Šค๋ฅผ ์ดํ•ดํ•ด์•ผ ํ•  ๋•Œ. + + +### ํƒ์ƒ‰ ์„œ๋ธŒ์—์ด์ „ํŠธ + +| Property | Value | +|----------|-------| +| **๋ชจ๋ธ** | Haiku (๋น ๋ฅด๊ณ  ๋‚ฎ์€ ์ง€์—ฐ ์‹œ๊ฐ„) | +| **๋ชจ๋“œ** | ์—„๊ฒฉํžˆ ์ฝ๊ธฐ ์ „์šฉ | +| **๋„๊ตฌ** | Glob, Grep, Read, Bash (์ฝ๊ธฐ ์ „์šฉ ๋ช…๋ น๋งŒ) | +| **๋ชฉ์ ** | ๋น ๋ฅธ ์ฝ”๋“œ๋ฒ ์ด์Šค ๊ฒ€์ƒ‰ ๋ฐ ๋ถ„์„ | + +**์‚ฌ์šฉ ์‹œ๊ธฐ**: ์ฝ”๋“œ๋ฅผ ๋ณ€๊ฒฝํ•˜์ง€ ์•Š๊ณ  ๊ฒ€์ƒ‰/์ดํ•ดํ•  ๋•Œ. + +**์ฒ ์ €ํ•จ ์ˆ˜์ค€** - ํƒ์ƒ‰ ๊นŠ์ด๋ฅผ ์ง€์ •ํ•ฉ๋‹ˆ๋‹ค: +- **"quick"** - ์ตœ์†Œํ•œ์˜ ํƒ์ƒ‰์œผ๋กœ ๋น ๋ฅธ ๊ฒ€์ƒ‰, ํŠน์ • ํŒจํ„ด์„ ์ฐพ๋Š” ๋ฐ ์œ ์šฉ +- **"medium"** - ์ ์ ˆํ•œ ํƒ์ƒ‰, ์†๋„์™€ ์ฒ ์ €ํ•จ์˜ ๊ท ํ˜•, ๊ธฐ๋ณธ ์ ‘๊ทผ ๋ฐฉ์‹ +- **"very thorough"** - ์—ฌ๋Ÿฌ ์œ„์น˜์™€ ๋ช…๋ช… ๊ทœ์น™์— ๊ฑธ์นœ ํฌ๊ด„์ ์ธ ๋ถ„์„, ์‹œ๊ฐ„์ด ๋” ์˜ค๋ž˜ ๊ฑธ๋ฆด ์ˆ˜ ์žˆ์Œ + + +### Bash ์„œ๋ธŒ์—์ด์ „ํŠธ + +| Property | Value | +|----------|-------| +| **๋ชจ๋ธ** | ๋ถ€๋ชจ๋กœ๋ถ€ํ„ฐ ์ƒ์† | +| **๋„๊ตฌ** | Bash | +| **๋ชฉ์ ** | ๋ณ„๋„์˜ ์ปจํ…์ŠคํŠธ ์ฐฝ์—์„œ ํ„ฐ๋ฏธ๋„ ๋ช…๋ น ์‹คํ–‰ | + +**์‚ฌ์šฉ ์‹œ๊ธฐ**: ๊ฒฉ๋ฆฌ๋œ ์ปจํ…์ŠคํŠธ์˜ ์ด์ ์„ ์–ป์„ ์ˆ˜ ์žˆ๋Š” ์…ธ ๋ช…๋ น์„ ์‹คํ–‰ํ•  ๋•Œ. + +### ์ƒํƒœ ํ‘œ์‹œ์ค„ ์„ค์ • ์„œ๋ธŒ์—์ด์ „ํŠธ + +| Property | Value | +|----------|-------| +| **๋ชจ๋ธ** | Sonnet | +| **๋„๊ตฌ** | Read, Write, Bash | +| **๋ชฉ์ ** | Claude Code ์ƒํƒœ ํ‘œ์‹œ์ค„ ๋””์Šคํ”Œ๋ ˆ์ด ๊ตฌ์„ฑ | + +**์‚ฌ์šฉ ์‹œ๊ธฐ**: ์ƒํƒœ ํ‘œ์‹œ์ค„์„ ์„ค์ •ํ•˜๊ฑฐ๋‚˜ ์‚ฌ์šฉ์ž ์ง€์ •ํ•  ๋•Œ. + +### Claude Code ๊ฐ€์ด๋“œ ์„œ๋ธŒ์—์ด์ „ํŠธ + +| Property | Value | +|----------|-------| +| **๋ชจ๋ธ** | Haiku (๋น ๋ฅด๊ณ  ๋‚ฎ์€ ์ง€์—ฐ ์‹œ๊ฐ„) | +| **๋„๊ตฌ** | ์ฝ๊ธฐ ์ „์šฉ | +| **๋ชฉ์ ** | Claude Code ๊ธฐ๋Šฅ ๋ฐ ์‚ฌ์šฉ๋ฒ•์— ๋Œ€ํ•œ ์งˆ๋ฌธ์— ๋‹ต๋ณ€ | + +**์‚ฌ์šฉ ์‹œ๊ธฐ**: ์‚ฌ์šฉ์ž๊ฐ€ Claude Code ์ž‘๋™ ๋ฐฉ์‹์ด๋‚˜ ํŠน์ • ๊ธฐ๋Šฅ ์‚ฌ์šฉ๋ฒ•์— ๋Œ€ํ•ด ์งˆ๋ฌธํ•  ๋•Œ. + +--- + +## ์„œ๋ธŒ์—์ด์ „ํŠธ ๊ด€๋ฆฌ + +### `/agents` ๋ช…๋ น ์‚ฌ์šฉ (๊ถŒ์žฅ) + +```bash +/agents +``` + +์ด๋Š” ๋‹ค์Œ๊ณผ ๊ฐ™์€ ๋Œ€ํ™”ํ˜• ๋ฉ”๋‰ด๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. +- ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ๋ชจ๋“  ์„œ๋ธŒ์—์ด์ „ํŠธ ๋ณด๊ธฐ (๋‚ด์žฅ, ์‚ฌ์šฉ์ž, ํ”„๋กœ์ ํŠธ) +- ์•ˆ๋‚ด๋œ ์„ค์ •์œผ๋กœ ์ƒˆ ์„œ๋ธŒ์—์ด์ „ํŠธ ์ƒ์„ฑ +- ๊ธฐ์กด ์‚ฌ์šฉ์ž ์ง€์ • ์„œ๋ธŒ์—์ด์ „ํŠธ ๋ฐ ๋„๊ตฌ ์ ‘๊ทผ ํŽธ์ง‘ +- ์‚ฌ์šฉ์ž ์ง€์ • ์„œ๋ธŒ์—์ด์ „ํŠธ ์‚ญ์ œ +- ์ค‘๋ณต์ด ์žˆ์„ ๋•Œ ์–ด๋–ค ์„œ๋ธŒ์—์ด์ „ํŠธ๊ฐ€ ํ™œ์„ฑํ™”๋˜๋Š”์ง€ ํ™•์ธ + +### ์ง์ ‘ ํŒŒ์ผ ๊ด€๋ฆฌ + +```bash +# Create a project subagent +mkdir -p .claude/agents +cat > .claude/agents/test-runner.md << 'EOF' +--- +name: test-runner +description: Use proactively to run tests and fix failures +--- + +You are a test automation expert. When you see code changes, proactively +run the appropriate tests. If tests fail, analyze the failures and fix +them while preserving the original test intent. +EOF + +# Create a user subagent (available in all projects) +mkdir -p ~/.claude/agents +``` + +--- + +## ์„œ๋ธŒ์—์ด์ „ํŠธ ์‚ฌ์šฉ + +### ์ž๋™ ์œ„์ž„ + +Claude๋Š” ๋‹ค์Œ์„ ๊ธฐ๋ฐ˜์œผ๋กœ ์ž‘์—…์„ ์„ ์ œ์ ์œผ๋กœ ์œ„์ž„ํ•ฉ๋‹ˆ๋‹ค: +- ์š”์ฒญ์— ์žˆ๋Š” ์ž‘์—… ์„ค๋ช… +- ์„œ๋ธŒ์—์ด์ „ํŠธ ๊ตฌ์„ฑ์˜ `description` ํ•„๋“œ +- ํ˜„์žฌ ์ปจํ…์ŠคํŠธ ๋ฐ ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ๋„๊ตฌ + +์„ ์ œ์ ์ธ ์‚ฌ์šฉ์„ ์žฅ๋ คํ•˜๋ ค๋ฉด `description` ํ•„๋“œ์— "use PROACTIVELY" ๋˜๋Š” "MUST BE USED"๋ฅผ ํฌํ•จํ•˜์„ธ์š”. + +```yaml +--- +name: code-reviewer +description: Expert code review specialist. Use PROACTIVELY after writing or modifying code. +--- +``` + +### ๋ช…์‹œ์  ํ˜ธ์ถœ +ํŠน์ • ์„œ๋ธŒ์—์ด์ „ํŠธ๋ฅผ ๋ช…์‹œ์ ์œผ๋กœ ์š”์ฒญํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +``` +> Use the test-runner subagent to fix failing tests +> Have the code-reviewer subagent look at my recent changes +> Ask the debugger subagent to investigate this error +``` + +> **๋Œ€์†Œ๋ฌธ์ž ๋ฐ ๊ตฌ๋ถ„์ž ๋ฌด์‹œ `subagent_type` ์ผ์น˜ (v2.1.140)**: `Agent` ๋„๊ตฌ ํ˜ธ์ถœ ๋˜๋Š” `--agent` ํ”Œ๋ž˜๊ทธ์˜ `subagent_type`์€ ๋Œ€์†Œ๋ฌธ์ž๋ฅผ ๋ฌด์‹œํ•˜๊ณ  ๊ตฌ๋ถ„์ž ์Šคํƒ€์ผ์„ ๋ฌด์‹œํ•˜์—ฌ ์ผ์น˜์‹œํ‚ต๋‹ˆ๋‹ค. ์ฆ‰, `code-reviewer`, `Code Reviewer`, `code_reviewer`๋Š” ๋ชจ๋‘ ๋™์ผํ•œ ์—์ด์ „ํŠธ๋กœ ํ•ด๊ฒฐ๋ฉ๋‹ˆ๋‹ค. ์ด๋Š” ์‚ฌ์†Œํ•œ ๋Œ€๋ฌธ์ž ์‚ฌ์šฉ ์ฐจ์ด๋กœ ์ธํ•ด ๊ธฐ๋ณธ ์—์ด์ „ํŠธ๋กœ ์ž๋™์œผ๋กœ ๋Œ€์ฒด๋˜๋Š” ์˜ค๋žœ ๋ฌธ์ œ์ ์„ ํ•ด๊ฒฐํ•ฉ๋‹ˆ๋‹ค. + +### @-๋ฉ˜์…˜ ํ˜ธ์ถœ + +`@` ์ ‘๋‘์‚ฌ๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ํŠน์ • ์„œ๋ธŒ์—์ด์ „ํŠธ๊ฐ€ ํ˜ธ์ถœ๋˜๋„๋ก ๋ณด์žฅํ•ฉ๋‹ˆ๋‹ค (์ž๋™ ์œ„์ž„ ํœด๋ฆฌ์Šคํ‹ฑ์„ ์šฐํšŒํ•ฉ๋‹ˆ๋‹ค): + +``` +> @"code-reviewer (agent)" review the auth module +``` + +### ์„ธ์…˜ ์ „์ฒด ์—์ด์ „ํŠธ + +ํŠน์ • ์—์ด์ „ํŠธ๋ฅผ ์ฃผ ์—์ด์ „ํŠธ๋กœ ์‚ฌ์šฉํ•˜์—ฌ ์ „์ฒด ์„ธ์…˜์„ ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค: + +```bash +# Via CLI flag +claude --agent code-reviewer + +# Via settings.json +{ + "agent": "code-reviewer" +} +``` + +### ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ์—์ด์ „ํŠธ ๋ชฉ๋ก + +`claude agents` ๋ช…๋ น์„ ์‚ฌ์šฉํ•˜์—ฌ ๋ชจ๋“  ์†Œ์Šค์—์„œ ๊ตฌ์„ฑ๋œ ๋ชจ๋“  ์—์ด์ „ํŠธ๋ฅผ ๋‚˜์—ดํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค: + +```bash +claude agents +``` + +--- + +## ์žฌ๊ฐœ ๊ฐ€๋Šฅํ•œ ์—์ด์ „ํŠธ + +์„œ๋ธŒ์—์ด์ „ํŠธ๋Š” ์ „์ฒด ์ปจํ…์ŠคํŠธ๋ฅผ ๋ณด์กดํ•œ ์ฑ„ ์ด์ „ ๋Œ€ํ™”๋ฅผ ๊ณ„์†ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค: + +```bash +# Initial invocation +> Use the code-analyzer agent to start reviewing the authentication module +# Returns agentId: "abc123" + +# Resume the agent later +> Resume agent abc123 and now analyze the authorization logic as well +``` + +**์‚ฌ์šฉ ์‚ฌ๋ก€**: +- ์—ฌ๋Ÿฌ ์„ธ์…˜์— ๊ฑธ์นœ ์žฅ๊ธฐ ์‹คํ–‰ ์—ฐ๊ตฌ +- ์ปจํ…์ŠคํŠธ ์†์‹ค ์—†์ด ๋ฐ˜๋ณต์ ์ธ ๊ฐœ์„  +- ์ปจํ…์ŠคํŠธ๋ฅผ ์œ ์ง€ํ•˜๋Š” ๋‹ค๋‹จ๊ณ„ ์›Œํฌํ”Œ๋กœ + +--- + +## ์„œ๋ธŒ์—์ด์ „ํŠธ ์ฒด์ด๋‹ + +์—ฌ๋Ÿฌ ์„œ๋ธŒ์—์ด์ „ํŠธ๋ฅผ ์ˆœ์„œ๋Œ€๋กœ ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค: + +```bash +> First use the code-analyzer subagent to find performance issues, + then use the optimizer subagent to fix them +``` + +์ด๋ฅผ ํ†ตํ•ด ํ•œ ์„œ๋ธŒ์—์ด์ „ํŠธ์˜ ์ถœ๋ ฅ์ด ๋‹ค๋ฅธ ์„œ๋ธŒ์—์ด์ „ํŠธ์˜ ์ž…๋ ฅ์œผ๋กœ ์‚ฌ์šฉ๋˜๋Š” ๋ณต์žกํ•œ ์›Œํฌํ”Œ๋กœ๋ฅผ ๊ตฌํ˜„ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +--- + +## ์„œ๋ธŒ์—์ด์ „ํŠธ์šฉ ์˜๊ตฌ ๋ฉ”๋ชจ๋ฆฌ + +`memory` ํ•„๋“œ๋Š” ์„œ๋ธŒ์—์ด์ „ํŠธ์—๊ฒŒ ๋Œ€ํ™”๋ฅผ ๋„˜์–ด์„œ๋„ ์œ ์ง€๋˜๋Š” ์˜๊ตฌ ๋””๋ ‰ํ„ฐ๋ฆฌ๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. ์ด๋ฅผ ํ†ตํ•ด ์„œ๋ธŒ์—์ด์ „ํŠธ๋Š” ์‹œ๊ฐ„์ด ์ง€๋‚จ์— ๋”ฐ๋ผ ์ง€์‹์„ ์ถ•์ ํ•˜๊ณ , ์„ธ์…˜ ๊ฐ„์— ์ง€์†๋˜๋Š” ๋ฉ”๋ชจ, ๋ฐœ๊ฒฌ ์‚ฌํ•ญ ๋ฐ ์ปจํ…์ŠคํŠธ๋ฅผ ์ €์žฅํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +### ๋ฉ”๋ชจ๋ฆฌ ๋ฒ”์œ„ + +| Scope | Directory | Use Case | +|-------|-----------|----------| +| `user` | `~/.claude/agent-memory//` | ๋ชจ๋“  ํ”„๋กœ์ ํŠธ์— ๊ฑธ์ณ ๊ฐœ์ธ ๋ฉ”๋ชจ ๋ฐ ํ™˜๊ฒฝ ์„ค์ • | +| `project` | `.claude/agent-memory//` | ํŒ€๊ณผ ๊ณต์œ ๋˜๋Š” ํ”„๋กœ์ ํŠธ๋ณ„ ์ง€์‹ | +| `local` | `.claude/agent-memory-local//` | ๋ฒ„์ „ ์ œ์–ด์— ์ปค๋ฐ‹๋˜์ง€ ์•Š๋Š” ๋กœ์ปฌ ํ”„๋กœ์ ํŠธ ์ง€์‹ | + +### ์ž‘๋™ ๋ฐฉ์‹ + +- ๋ฉ”๋ชจ๋ฆฌ ๋””๋ ‰ํ„ฐ๋ฆฌ์˜ `MEMORY.md` ํŒŒ์ผ ์ฒซ 200์ค„์ด ์„œ๋ธŒ์—์ด์ „ํŠธ์˜ ์‹œ์Šคํ…œ ํ”„๋กฌํ”„ํŠธ์— ์ž๋™์œผ๋กœ ๋กœ๋“œ๋ฉ๋‹ˆ๋‹ค +- ์„œ๋ธŒ์—์ด์ „ํŠธ๊ฐ€ ๋ฉ”๋ชจ๋ฆฌ ํŒŒ์ผ์„ ๊ด€๋ฆฌํ•  ์ˆ˜ ์žˆ๋„๋ก `Read`, `Write`, `Edit` ๋„๊ตฌ๊ฐ€ ์ž๋™์œผ๋กœ ํ™œ์„ฑํ™”๋ฉ๋‹ˆ๋‹ค +- ์„œ๋ธŒ์—์ด์ „ํŠธ๋Š” ํ•„์š”์— ๋”ฐ๋ผ ๋ฉ”๋ชจ๋ฆฌ ๋””๋ ‰ํ„ฐ๋ฆฌ์— ์ถ”๊ฐ€ ํŒŒ์ผ์„ ์ƒ์„ฑํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค + +### ๊ตฌ์„ฑ ์˜ˆ์‹œ + +```yaml +--- +name: researcher +memory: user +--- + +You are a research assistant. Use your memory directory to store findings, +track progress across sessions, and build up knowledge over time. + +Check your MEMORY.md file at the start of each session to recall previous context. +``` + +```mermaid +graph LR + A["Subagent
Session 1"] -->|writes| M["MEMORY.md
(persistent)"] + M -->|loads into| B["Subagent
Session 2"] + B -->|updates| M + M -->|loads into| C["Subagent
Session 3"] + + style A fill:#e1f5fe,stroke:#333,color:#333 + style B fill:#e1f5fe,stroke:#333,color:#333 + style C fill:#e1f5fe,stroke:#333,color:#333 + style M fill:#f3e5f5,stroke:#333,color:#333 +``` + +--- + +## ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์„œ๋ธŒ์—์ด์ „ํŠธ + +์„œ๋ธŒ์—์ด์ „ํŠธ๋Š” ๋ฐฑ๊ทธ๋ผ์šด๋“œ์—์„œ ์‹คํ–‰๋  ์ˆ˜ ์žˆ์œผ๋ฉฐ, ์ฃผ ๋Œ€ํ™”๋ฅผ ๋‹ค๋ฅธ ์ž‘์—…์„ ์œ„ํ•ด ๋น„์›Œ๋‘˜ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +### ๊ตฌ์„ฑ + +ํ”„๋ŸฐํŠธ๋งคํ„ฐ์—์„œ `background: true`๋กœ ์„ค์ •ํ•˜์—ฌ ์„œ๋ธŒ์—์ด์ „ํŠธ๋ฅผ ํ•ญ์ƒ ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž‘์—…์œผ๋กœ ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค: + +```yaml +--- +name: long-runner +background: true +description: Performs long-running analysis tasks in the background +--- +``` + +### ํ‚ค๋ณด๋“œ ๋‹จ์ถ•ํ‚ค + +| Shortcut | Action | +|----------|--------| +| `Ctrl+B` | ํ˜„์žฌ ์‹คํ–‰ ์ค‘์ธ ์„œ๋ธŒ์—์ด์ „ํŠธ ์ž‘์—…์„ ๋ฐฑ๊ทธ๋ผ์šด๋“œ๋กœ ์ „ํ™˜ | +| `Ctrl+F` | ๋ชจ๋“  ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์—์ด์ „ํŠธ ์ข…๋ฃŒ (ํ™•์ธ์„ ์œ„ํ•ด ๋‘ ๋ฒˆ ๋ˆ„๋ฅด์„ธ์š”) | + +### ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž‘์—… ๋น„ํ™œ์„ฑํ™” + +ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋ฅผ ์„ค์ •ํ•˜์—ฌ ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž‘์—… ์ง€์›์„ ์™„์ „ํžˆ ๋น„ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค: + +```bash +export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 +``` + +--- + +## ์›ŒํฌํŠธ๋ฆฌ ๊ฒฉ๋ฆฌ + +`isolation: worktree` ์„ค์ •์€ ์„œ๋ธŒ์—์ด์ „ํŠธ์—๊ฒŒ ์ž์ฒด git ์›ŒํฌํŠธ๋ฆฌ๋ฅผ ์ œ๊ณตํ•˜์—ฌ, ์ฃผ ์ž‘์—… ํŠธ๋ฆฌ์— ์˜ํ–ฅ์„ ์ฃผ์ง€ ์•Š๊ณ  ๋…๋ฆฝ์ ์œผ๋กœ ๋ณ€๊ฒฝํ•  ์ˆ˜ ์žˆ๋„๋ก ํ•ฉ๋‹ˆ๋‹ค. + +### ๊ตฌ์„ฑ + +```yaml +--- +name: feature-builder +isolation: worktree +description: Implements features in an isolated git worktree +tools: Read, Write, Edit, Bash, Grep, Glob +--- +``` + +### ์ž‘๋™ ๋ฐฉ์‹ + +```mermaid +graph TB + Main["Main Working Tree"] -->|spawns| Sub["Subagent with
Isolated Worktree"] + Sub -->|makes changes in| WT["Separate Git
Worktree + Branch"] + WT -->|no changes| Clean["Auto-cleaned"] + WT -->|has changes| Return["Returns worktree
path and branch"] + + style Main fill:#e1f5fe,stroke:#333,color:#333 + style Sub fill:#f3e5f5,stroke:#333,color:#333 + style WT fill:#e8f5e9,stroke:#333,color:#333 + style Clean fill:#fff3e0,stroke:#333,color:#333 + style Return fill:#fff3e0,stroke:#333,color:#333 +``` + +- ์„œ๋ธŒ์—์ด์ „ํŠธ๋Š” ๋ณ„๋„์˜ ๋ธŒ๋žœ์น˜์—์„œ ์ž์ฒด git ์›ŒํฌํŠธ๋ฆฌ์—์„œ ์ž‘๋™ํ•ฉ๋‹ˆ๋‹ค +- ์„œ๋ธŒ์—์ด์ „ํŠธ๊ฐ€ ๋ณ€๊ฒฝ ์‚ฌํ•ญ์„ ๋งŒ๋“ค์ง€ ์•Š์œผ๋ฉด ์›ŒํฌํŠธ๋ฆฌ๋Š” ์ž๋™์œผ๋กœ ์ •๋ฆฌ๋ฉ๋‹ˆ๋‹ค +- ๋ณ€๊ฒฝ ์‚ฌํ•ญ์ด ์žˆ๋Š” ๊ฒฝ์šฐ, ์›ŒํฌํŠธ๋ฆฌ ๊ฒฝ๋กœ์™€ ๋ธŒ๋žœ์น˜ ์ด๋ฆ„์ด ๊ฒ€ํ†  ๋˜๋Š” ๋ณ‘ํ•ฉ์„ ์œ„ํ•ด ์ฃผ ์—์ด์ „ํŠธ๋กœ ๋ฐ˜ํ™˜๋ฉ๋‹ˆ๋‹ค + +--- + +## ํฌํฌ๋œ ์„œ๋ธŒ์—์ด์ „ํŠธ + +ํฌํฌ๋œ ์„œ๋ธŒ์—์ด์ „ํŠธ(`context: fork`)๋Š” ์ƒˆ๋กญ๊ฒŒ ์‹œ์ž‘ํ•˜๋Š” ๋Œ€์‹ , ํฌํฌ ์‹œ์ ์— ๋ถ€๋ชจ ์—์ด์ „ํŠธ์˜ ์ „์ฒด ๋Œ€ํ™” ์ปจํ…์ŠคํŠธ๋ฅผ ์ƒ์†ํ•ฉ๋‹ˆ๋‹ค. ์ด๋Š” ์ง€๊ธˆ๊นŒ์ง€ ์ˆ˜ํ–‰ํ•œ ์ž‘์—…์„ ์žƒ์ง€ ์•Š๊ณ  ๋Œ€์ฒด ๊ฒฝ๋กœ๋ฅผ ํƒ์ƒ‰ํ•˜๋Š” ๋ฐ ์œ ์šฉํ•ฉ๋‹ˆ๋‹ค. + +> **๊ฐ€์šฉ์„ฑ**: v2.1.117์—์„œ GA(General Availability)์ž…๋‹ˆ๋‹ค. ์™ธ๋ถ€ ๋นŒ๋“œ(์„œ๋“œํŒŒํ‹ฐ ๋ฐฐํฌ)์—์„œ๋Š” ํฌํฌ ๊ธฐ๋Šฅ์„ ํ™œ์„ฑํ™”ํ•˜๋ ค๋ฉด `CLAUDE_CODE_FORK_SUBAGENT=1`๋กœ ์„ค์ •ํ•˜์‹ญ์‹œ์˜ค. + +### ๊ตฌ์„ฑ + +```yaml +--- +name: alternative-explorer +description: Explore an alternative implementation path while preserving parent context +context: fork +tools: Read, Edit, Bash, Grep, Glob +--- + +You are a forked subagent. You inherit the parent's full conversation and +may explore an alternative approach. Return your findings and the parent +will decide whether to adopt them. +``` + +### ์™ธ๋ถ€ ๋นŒ๋“œ์—์„œ ํ™œ์„ฑํ™” + +```bash +export CLAUDE_CODE_FORK_SUBAGENT=1 +claude +``` + +### ํฌํฌ์™€ ํด๋ฆฐ ์ปจํ…์ŠคํŠธ ์‚ฌ์šฉ ์‹œ๊ธฐ + +| Scenario | `context: fork` | Clean context (default) | +|----------|-----------------|-------------------------| +| ๋Œ€์ฒด ๊ตฌํ˜„ ํƒ์ƒ‰ | ์˜ˆ | ์•„๋‹ˆ์š” (์ปจํ…์ŠคํŠธ๋ฅผ ์žƒ๊ฒŒ ๋จ) | +| ๊ธฐ์กด ์ปจํ…์ŠคํŠธ๋ฅผ ์‚ฌ์šฉํ•œ ์žฅ๊ธฐ ์—ฐ๊ตฌ | ์˜ˆ | ์•„๋‹ˆ์š” | +| ๋…๋ฆฝ์ ์ธ ์ „๋ฌธํ™”๋œ ์ž‘์—… | ์•„๋‹ˆ์š” | ์˜ˆ | +| ์ปจํ…์ŠคํŠธ ์˜ค์—ผ ๋ฐฉ์ง€ | ์•„๋‹ˆ์š” | ์˜ˆ | + +--- + +## ์ƒ์„ฑ ๊ฐ€๋Šฅํ•œ ์„œ๋ธŒ์—์ด์ „ํŠธ ์ œํ•œ + +`tools` ํ•„๋“œ์—์„œ `Agent(agent_type)` ๊ตฌ๋ฌธ์„ ์‚ฌ์šฉํ•˜์—ฌ ์ฃผ์–ด์ง„ ์„œ๋ธŒ์—์ด์ „ํŠธ๊ฐ€ ์–ด๋–ค ์„œ๋ธŒ์—์ด์ „ํŠธ๋ฅผ ์ƒ์„ฑํ•  ์ˆ˜ ์žˆ๋Š”์ง€ ์ œ์–ดํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์ด๋Š” ์œ„์ž„์„ ์œ„ํ•ด ํŠน์ • ์„œ๋ธŒ์—์ด์ „ํŠธ๋ฅผ ํ—ˆ์šฉ ๋ชฉ๋ก์— ์ถ”๊ฐ€ํ•˜๋Š” ๋ฐฉ๋ฒ•์„ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. + +> **์ฐธ๊ณ **: v2.1.63์—์„œ `Task` ๋„๊ตฌ๋Š” `Agent`๋กœ ์ด๋ฆ„์ด ๋ณ€๊ฒฝ๋˜์—ˆ์Šต๋‹ˆ๋‹ค. ๊ธฐ์กด `Task(...)` ์ฐธ์กฐ๋„ ์—ฌ์ „ํžˆ ๋ณ„์นญ์œผ๋กœ ์ž‘๋™ํ•ฉ๋‹ˆ๋‹ค. + +### ์˜ˆ์‹œ + +```yaml +--- +name: coordinator +description: Coordinates work between specialized agents +tools: Agent(worker, researcher), Read, Bash +--- + +You are a coordinator agent. You can delegate work to the "worker" and +"researcher" subagents only. Use Read and Bash for your own exploration. +``` + +์ด ์˜ˆ์‹œ์—์„œ `coordinator` ์„œ๋ธŒ์—์ด์ „ํŠธ๋Š” "worker" ๋ฐ "researcher" ์„œ๋ธŒ์—์ด์ „ํŠธ๋งŒ ์ƒ์„ฑํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ๋‹ค๋ฅธ ๊ณณ์— ์ •์˜๋˜์–ด ์žˆ๋”๋ผ๋„ ๋‹ค๋ฅธ ์„œ๋ธŒ์—์ด์ „ํŠธ๋Š” ์ƒ์„ฑํ•  ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค. + +--- + +## `claude agents` CLI ๋ช…๋ น + +`claude agents` ๋ช…๋ น์€ ์†Œ์Šค(๋‚ด์žฅ, ์‚ฌ์šฉ์ž ์ˆ˜์ค€, ํ”„๋กœ์ ํŠธ ์ˆ˜์ค€)๋ณ„๋กœ ๊ทธ๋ฃนํ™”๋œ ๋ชจ๋“  ๊ตฌ์„ฑ๋œ ์—์ด์ „ํŠธ๋ฅผ ๋‚˜์—ดํ•ฉ๋‹ˆ๋‹ค: + +```bash +claude agents +``` + +์ด ๋ช…๋ น์€ ๋‹ค์Œ์„ ์ˆ˜ํ–‰ํ•ฉ๋‹ˆ๋‹ค: +- ๋ชจ๋“  ์†Œ์Šค์˜ ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ๋ชจ๋“  ์—์ด์ „ํŠธ๋ฅผ ํ‘œ์‹œํ•ฉ๋‹ˆ๋‹ค +- ์—์ด์ „ํŠธ๋ฅผ ์†Œ์Šค ์œ„์น˜๋ณ„๋กœ ๊ทธ๋ฃนํ™”ํ•ฉ๋‹ˆ๋‹ค +- ์šฐ์„ ์ˆœ์œ„๊ฐ€ ๋†’์€ ์—์ด์ „ํŠธ๊ฐ€ ๋‚ฎ์€ ์ˆ˜์ค€์˜ ์—์ด์ „ํŠธ๋ฅผ ๊ฐ€๋ฆด ๋•Œ(์˜ˆ: ์‚ฌ์šฉ์ž ์ˆ˜์ค€ ์—์ด์ „ํŠธ์™€ ์ด๋ฆ„์ด ๊ฐ™์€ ํ”„๋กœ์ ํŠธ ์ˆ˜์ค€ ์—์ด์ „ํŠธ) **์žฌ์ •์˜**๋ฅผ ๋‚˜ํƒ€๋ƒ…๋‹ˆ๋‹ค + +--- + +## ์—์ด์ „ํŠธ ํŒ€ (์‹คํ—˜์ ) + +์—์ด์ „ํŠธ ํŒ€์€ ์—ฌ๋Ÿฌ Claude Code ์ธ์Šคํ„ด์Šค๊ฐ€ ๋ณต์žกํ•œ ์ž‘์—…์„ ํ•จ๊ป˜ ์ˆ˜ํ–‰ํ•˜๋„๋ก ์กฐ์ •ํ•ฉ๋‹ˆ๋‹ค. (๊ฒฐ๊ณผ๋ฅผ ๋ฐ˜ํ™˜ํ•˜๋Š” ์œ„์ž„๋œ ํ•˜์œ„ ์ž‘์—…์ธ) ์„œ๋ธŒ์—์ด์ „ํŠธ์™€ ๋‹ฌ๋ฆฌ, ํŒ€์›์€ ์ž์ฒด ์ปจํ…์ŠคํŠธ ์ฐฝ์œผ๋กœ ๋…๋ฆฝ์ ์œผ๋กœ ์ž‘์—…ํ•˜๋ฉฐ ๊ณต์œ  ์‚ฌ์„œํ•จ ์‹œ์Šคํ…œ์„ ํ†ตํ•ด ์„œ๋กœ ์ง์ ‘ ๋ฉ”์‹œ์ง€๋ฅผ ์ฃผ๊ณ ๋ฐ›์„ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +> **๊ณต์‹ ๋ฌธ์„œ**: [code.claude.com/docs/en/agent-teams](https://code.claude.com/docs/en/agent-teams) + +> **์ฐธ๊ณ **: ์—์ด์ „ํŠธ ํŒ€์€ ์‹คํ—˜์  ๊ธฐ๋Šฅ์ด๋ฉฐ ๊ธฐ๋ณธ์ ์œผ๋กœ ๋น„ํ™œ์„ฑํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. Claude Code v2.1.32+๊ฐ€ ํ•„์š”ํ•ฉ๋‹ˆ๋‹ค. ์‚ฌ์šฉํ•˜๊ธฐ ์ „์— ํ™œ์„ฑํ™”ํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. + +### ์„œ๋ธŒ์—์ด์ „ํŠธ vs ์—์ด์ „ํŠธ ํŒ€ + +| Aspect | Subagents | Agent Teams | +|--------|-----------|-------------| +| **์œ„์ž„ ๋ชจ๋ธ** | ๋ถ€๋ชจ๊ฐ€ ํ•˜์œ„ ์ž‘์—…์„ ์œ„์ž„ํ•˜๊ณ  ๊ฒฐ๊ณผ๋ฅผ ๊ธฐ๋‹ค๋ฆฝ๋‹ˆ๋‹ค | ํŒ€ ๋ฆฌ๋”๊ฐ€ ์ž‘์—…์„ ์กฐ์ •ํ•˜๊ณ , ํŒ€์›์€ ๋…๋ฆฝ์ ์œผ๋กœ ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค | +| **์ปจํ…์ŠคํŠธ** | ํ•˜์œ„ ์ž‘์—…๋‹น ์ƒˆ๋กœ์šด ์ปจํ…์ŠคํŠธ, ๊ฒฐ๊ณผ๋Š” ๋‹ค์‹œ ์ฃผ์ž… | ๊ฐ ํŒ€์›์€ ์ž์ฒด ์˜๊ตฌ ์ปจํ…์ŠคํŠธ ์ฐฝ์„ ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค | +| **์กฐ์ •** | ๋ถ€๋ชจ๊ฐ€ ๊ด€๋ฆฌํ•˜๋Š” ์ˆœ์ฐจ์  ๋˜๋Š” ๋ณ‘๋ ฌ | ์ž๋™ ์ข…์†์„ฑ ๊ด€๋ฆฌ๊ฐ€ ๊ฐ€๋Šฅํ•œ ๊ณต์œ  ์ž‘์—… ๋ชฉ๋ก | +| **ํ†ต์‹ ** | ๊ฒฐ๊ณผ๋Š” ๋ถ€๋ชจ์—๊ฒŒ๋งŒ ๋ฐ˜ํ™˜ (์—์ด์ „ํŠธ ๊ฐ„ ๋ฉ”์‹œ์ง• ์—†์Œ) | ํŒ€์›์€ ์‚ฌ์„œํ•จ์„ ํ†ตํ•ด ์„œ๋กœ ์ง์ ‘ ๋ฉ”์‹œ์ง€๋ฅผ ์ฃผ๊ณ ๋ฐ›์„ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค | +| **์„ธ์…˜ ์žฌ๊ฐœ** | ์ง€์›๋จ | ์ธ-ํ”„๋กœ์„ธ์Šค ํŒ€์›์—์„œ๋Š” ์ง€์›๋˜์ง€ ์•Š์Œ | +| **์ตœ์  ์‚ฌ์šฉ** | ์ง‘์ค‘์ ์ด๊ณ  ์ž˜ ์ •์˜๋œ ํ•˜์œ„ ์ž‘์—… | ์—์ด์ „ํŠธ ๊ฐ„ ํ†ต์‹  ๋ฐ ๋ณ‘๋ ฌ ์‹คํ–‰์ด ํ•„์š”ํ•œ ๋ณต์žกํ•œ ์ž‘์—… | + +### ์—์ด์ „ํŠธ ํŒ€ ํ™œ์„ฑํ™” + +ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋ฅผ ์„ค์ •ํ•˜๊ฑฐ๋‚˜ `settings.json`์— ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค: + +```bash +export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 +``` + +Or in `settings.json`: + +```json +{ + "env": { + "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" + } +} +``` + +### ํŒ€ ์‹œ์ž‘ + +ํ™œ์„ฑํ™”๋˜๋ฉด ํ”„๋กฌํ”„ํŠธ์—์„œ Claude์—๊ฒŒ ํŒ€์›๊ณผ ํ•จ๊ป˜ ์ž‘์—…ํ•˜๋„๋ก ์š”์ฒญํ•˜์‹ญ์‹œ์˜ค: + +``` +User: Build the authentication module. Use a team โ€” one teammate for the API endpoints, + one for the database schema, and one for the test suite. +``` + +Claude๋Š” ํŒ€์„ ์ƒ์„ฑํ•˜๊ณ  ์ž‘์—…์„ ํ• ๋‹นํ•˜๋ฉฐ ์ž‘์—…์„ ์ž๋™์œผ๋กœ ์กฐ์ •ํ•ฉ๋‹ˆ๋‹ค. + +### ๋””์Šคํ”Œ๋ ˆ์ด ๋ชจ๋“œ + +ํŒ€์› ํ™œ๋™์ด ํ‘œ์‹œ๋˜๋Š” ๋ฐฉ์‹์„ ์ œ์–ดํ•ฉ๋‹ˆ๋‹ค: + +| Mode | Flag | Description | +|------|------|-------------| +| **Auto** | `--teammate-mode auto` | ํ„ฐ๋ฏธ๋„์— ๊ฐ€์žฅ ์ ํ•ฉํ•œ ๋””์Šคํ”Œ๋ ˆ์ด ๋ชจ๋“œ๋ฅผ ์ž๋™์œผ๋กœ ์„ ํƒํ•ฉ๋‹ˆ๋‹ค | +| **In-process** (default) | `--teammate-mode in-process` | ํ˜„์žฌ ํ„ฐ๋ฏธ๋„์— ํŒ€์› ์ถœ๋ ฅ์„ ์ธ๋ผ์ธ์œผ๋กœ ํ‘œ์‹œํ•ฉ๋‹ˆ๋‹ค | +| **Split-panes** | `--teammate-mode tmux` | ๊ฐ ํŒ€์›์„ ๋ณ„๋„์˜ tmux ๋˜๋Š” iTerm2 ์ฐฝ์— ์—ฝ๋‹ˆ๋‹ค | +| **iTerm2** | `--teammate-mode iterm2` | (v2.1.186+) ์ „์šฉ iTerm2 ์ฐฝ์— ํŒ€์›์„ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. `it2` CLI๊ฐ€ ํ•„์š”ํ•˜๋ฉฐ, ์ž๋™ ๋ชจ๋“œ์—์„œ๋Š” ์ฐพ์„ ์ˆ˜ ์—†์„ ๋•Œ ๊ฒฝ๊ณ ํ•ฉ๋‹ˆ๋‹ค | + +```bash +claude --teammate-mode tmux +``` + +You can also set the display mode in `settings.json`: + +```json +{ + "teammateMode": "tmux" +} +``` + +> **์ฐธ๊ณ **: ๋ถ„ํ•  ์ฐฝ ๋ชจ๋“œ์—๋Š” tmux ๋˜๋Š” iTerm2๊ฐ€ ํ•„์š”ํ•ฉ๋‹ˆ๋‹ค. VS Code ํ„ฐ๋ฏธ๋„, Windows ํ„ฐ๋ฏธ๋„ ๋˜๋Š” Ghostty์—์„œ๋Š” ์‚ฌ์šฉํ•  ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค. + +### ๋‚ด๋น„๊ฒŒ์ด์…˜ + +`Shift+Down`์„ ์‚ฌ์šฉํ•˜์—ฌ ๋ถ„ํ•  ์ฐฝ ๋ชจ๋“œ์—์„œ ํŒ€์› ๊ฐ„์— ์ด๋™ํ•ฉ๋‹ˆ๋‹ค. + +### ํŒ€ ๊ตฌ์„ฑ + +ํŒ€ ๊ตฌ์„ฑ์€ `~/.claude/teams/{team-name}/config.json`์— ์ €์žฅ๋ฉ๋‹ˆ๋‹ค. + +### ์•„ํ‚คํ…์ฒ˜ + +```mermaid +graph TB + Lead["Team Lead
(Coordinator)"] + TaskList["Shared Task List
(Dependencies)"] + Mailbox["Mailbox
(Messages)"] + T1["Teammate 1
(Own Context)"] + T2["Teammate 2
(Own Context)"] + T3["Teammate 3
(Own Context)"] + + Lead -->|assigns tasks| TaskList + Lead -->|sends messages| Mailbox + TaskList -->|picks up work| T1 + TaskList -->|picks up work| T2 + TaskList -->|picks up work| T3 + T1 -->|reads/writes| Mailbox + T2 -->|reads/writes| Mailbox + T3 -->|reads/writes| Mailbox + T1 -->|updates status| TaskList + T2 -->|updates status| TaskList + T3 -->|updates status| TaskList + + style Lead fill:#e1f5fe,stroke:#333,color:#333 + style TaskList fill:#fff9c4,stroke:#333,color:#333 + style Mailbox fill:#f3e5f5,stroke:#333,color:#333 + style T1 fill:#e8f5e9,stroke:#333,color:#333 + style T2 fill:#e8f5e9,stroke:#333,color:#333 + style T3 fill:#e8f5e9,stroke:#333,color:#333 +``` + +**ํ•ต์‹ฌ ๊ตฌ์„ฑ ์š”์†Œ**: + +- **ํŒ€ ๋ฆฌ๋”**: ํŒ€์„ ์ƒ์„ฑํ•˜๊ณ  ์ž‘์—…์„ ํ• ๋‹นํ•˜๋ฉฐ ์กฐ์ •ํ•˜๋Š” ์ฃผ Claude Code ์„ธ์…˜ +- **๊ณต์œ  ์ž‘์—… ๋ชฉ๋ก**: ์ž๋™ ์ข…์†์„ฑ ์ถ”์  ๊ธฐ๋Šฅ์ด ์žˆ๋Š” ๋™๊ธฐํ™”๋œ ์ž‘์—… ๋ชฉ๋ก +- **์‚ฌ์„œํ•จ**: ํŒ€์›์ด ์ƒํƒœ๋ฅผ ์ „๋‹ฌํ•˜๊ณ  ์กฐ์ •ํ•  ์ˆ˜ ์žˆ๋Š” ์—์ด์ „ํŠธ ๊ฐ„ ๋ฉ”์‹œ์ง• ์‹œ์Šคํ…œ +- **ํŒ€์›**: ์ž์ฒด ์ปจํ…์ŠคํŠธ ์ฐฝ์„ ๊ฐ€์ง„ ๋…๋ฆฝ์ ์ธ Claude Code ์ธ์Šคํ„ด์Šค + +### ์ž‘์—… ํ• ๋‹น ๋ฐ ๋ฉ”์‹œ์ง• + +ํŒ€ ๋ฆฌ๋”๋Š” ์ž‘์—…์„ ํƒœ์Šคํฌ๋กœ ๋‚˜๋ˆ„๊ณ  ํŒ€์›์—๊ฒŒ ํ• ๋‹นํ•ฉ๋‹ˆ๋‹ค. ๊ณต์œ  ํƒœ์Šคํฌ ๋ชฉ๋ก์€ ๋‹ค์Œ์„ ์ฒ˜๋ฆฌํ•ฉ๋‹ˆ๋‹ค: + +- **์ž๋™ ์ข…์†์„ฑ ๊ด€๋ฆฌ** โ€” ํƒœ์Šคํฌ๋Š” ์ข…์† ํƒœ์Šคํฌ๊ฐ€ ์™„๋ฃŒ๋  ๋•Œ๊นŒ์ง€ ๊ธฐ๋‹ค๋ฆฝ๋‹ˆ๋‹ค +- **์ƒํƒœ ์ถ”์ ** โ€” ํŒ€์›์€ ์ž‘์—…ํ•˜๋ฉด์„œ ํƒœ์Šคํฌ ์ƒํƒœ๋ฅผ ์—…๋ฐ์ดํŠธํ•ฉ๋‹ˆ๋‹ค +- **์—์ด์ „ํŠธ ๊ฐ„ ๋ฉ”์‹œ์ง•** โ€” ํŒ€์›์€ ์กฐ์ •์„ ์œ„ํ•ด ์‚ฌ์„œํ•จ์„ ํ†ตํ•ด ๋ฉ”์‹œ์ง€๋ฅผ ๋ณด๋ƒ…๋‹ˆ๋‹ค (์˜ˆ: "๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ์Šคํ‚ค๋งˆ๊ฐ€ ์ค€๋น„๋˜์—ˆ์œผ๋‹ˆ ์ฟผ๋ฆฌ ์ž‘์„ฑ์„ ์‹œ์ž‘ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค") + +### ๊ณ„ํš ์Šน์ธ ์›Œํฌํ”Œ๋กœ + +๋ณต์žกํ•œ ์ž‘์—…์„ ์œ„ํ•ด ํŒ€ ๋ฆฌ๋”๋Š” ํŒ€์›์ด ์ž‘์—…์„ ์‹œ์ž‘ํ•˜๊ธฐ ์ „์— ์‹คํ–‰ ๊ณ„ํš์„ ๋งŒ๋“ญ๋‹ˆ๋‹ค. ์‚ฌ์šฉ์ž๋Š” ๊ณ„ํš์„ ๊ฒ€ํ† ํ•˜๊ณ  ์Šน์ธํ•˜์—ฌ, ์ฝ”๋“œ ๋ณ€๊ฒฝ์ด ์ด๋ฃจ์–ด์ง€๊ธฐ ์ „์— ํŒ€์˜ ์ ‘๊ทผ ๋ฐฉ์‹์ด ๊ธฐ๋Œ€์น˜์— ๋ถ€ํ•ฉํ•˜๋Š”์ง€ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. + +### ํŒ€์„ ์œ„ํ•œ ํ›… ์ด๋ฒคํŠธ + +์—์ด์ „ํŠธ ํŒ€์€ ๋‘ ๊ฐ€์ง€ ์ถ”๊ฐ€ [ํ›… ์ด๋ฒคํŠธ](../06-hooks/)๋ฅผ ๋„์ž…ํ•ฉ๋‹ˆ๋‹ค: + +| Event | Fires When | Use Case | +|-------|------------|----------| +| `TeammateIdle` | ํŒ€์›์ด ํ˜„์žฌ ์ž‘์—…์„ ๋งˆ์น˜๊ณ  ๋ณด๋ฅ˜ ์ค‘์ธ ์ž‘์—…์ด ์—†์„ ๋•Œ | ์•Œ๋ฆผ ํŠธ๋ฆฌ๊ฑฐ, ํ›„์† ์ž‘์—… ํ• ๋‹น | +| `TaskCompleted` | ๊ณต์œ  ์ž‘์—… ๋ชฉ๋ก์˜ ํƒœ์Šคํฌ๊ฐ€ ์™„๋ฃŒ๋กœ ํ‘œ์‹œ๋  ๋•Œ | ์œ ํšจ์„ฑ ๊ฒ€์‚ฌ ์‹คํ–‰, ๋Œ€์‹œ๋ณด๋“œ ์—…๋ฐ์ดํŠธ, ์ข…์† ์ž‘์—… ์ฒด์ธ | + +### ๋ชจ๋ฒ” ์‚ฌ๋ก€ + +- **ํŒ€ ๊ทœ๋ชจ**: ์ตœ์ ์˜ ์กฐ์ •์„ ์œ„ํ•ด ํŒ€์„ 3-5๋ช…์˜ ํŒ€์›์œผ๋กœ ์œ ์ง€ +- **์ž‘์—… ๊ทœ๋ชจ**: ๊ฐ 5-15๋ถ„ ์†Œ์š”๋˜๋Š” ์ž‘์—…์œผ๋กœ ๋ถ„ํ•  โ€” ๋ณ‘๋ ฌํ™”ํ•˜๊ธฐ์— ์ถฉ๋ถ„ํžˆ ์ž‘๊ณ , ์˜๋ฏธ๋ฅผ ๊ฐ€์ง€๊ธฐ์— ์ถฉ๋ถ„ํžˆ ํผ +- **ํŒŒ์ผ ์ถฉ๋Œ ๋ฐฉ์ง€**: ๋ณ‘ํ•ฉ ์ถฉ๋Œ์„ ๋ฐฉ์ง€ํ•˜๊ธฐ ์œ„ํ•ด ๋‹ค๋ฅธ ํŒŒ์ผ ๋˜๋Š” ๋””๋ ‰ํ„ฐ๋ฆฌ๋ฅผ ๋‹ค๋ฅธ ํŒ€์›์—๊ฒŒ ํ• ๋‹น +- **๊ฐ„๋‹จํ•˜๊ฒŒ ์‹œ์ž‘**: ์ฒซ ํŒ€์—๋Š” ์ธ-ํ”„๋กœ์„ธ์Šค ๋ชจ๋“œ๋ฅผ ์‚ฌ์šฉํ•˜๊ณ , ์ต์ˆ™ํ•ด์ง€๋ฉด ๋ถ„ํ•  ์ฐฝ์œผ๋กœ ์ „ํ™˜ +- **๋ช…ํ™•ํ•œ ์ž‘์—… ์„ค๋ช…**: ํŒ€์›์ด ๋…๋ฆฝ์ ์œผ๋กœ ์ž‘์—…ํ•  ์ˆ˜ ์žˆ๋„๋ก ๊ตฌ์ฒด์ ์ด๊ณ  ์‹คํ–‰ ๊ฐ€๋Šฅํ•œ ์ž‘์—… ์„ค๋ช…์„ ์ œ๊ณต + +### ์ œํ•œ ์‚ฌํ•ญ + +- **์‹คํ—˜์ **: ๊ธฐ๋Šฅ ๋™์ž‘์ด ํ–ฅํ›„ ๋ฆด๋ฆฌ์Šค์—์„œ ๋ณ€๊ฒฝ๋  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค +- **์„ธ์…˜ ์žฌ๊ฐœ ๋ถˆ๊ฐ€**: ์ธ-ํ”„๋กœ์„ธ์Šค ํŒ€์›์€ ์„ธ์…˜ ์ข…๋ฃŒ ํ›„ ์žฌ๊ฐœํ•  ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค +- **์„ธ์…˜๋‹น ํ•˜๋‚˜์˜ ํŒ€**: ๋‹จ์ผ ์„ธ์…˜์—์„œ ์ค‘์ฒฉ ํŒ€ ๋˜๋Š” ์—ฌ๋Ÿฌ ํŒ€์„ ์ƒ์„ฑํ•  ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค +- **๊ณ ์ •๋œ ๋ฆฌ๋”์‹ญ**: ํŒ€ ๋ฆฌ๋” ์—ญํ• ์€ ํŒ€์›์—๊ฒŒ ์ด์ „๋  ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค +- **๋ถ„ํ•  ์ฐฝ ์ œํ•œ**: tmux/iTerm2 ํ•„์š”; VS Code ํ„ฐ๋ฏธ๋„, Windows ํ„ฐ๋ฏธ๋„ ๋˜๋Š” Ghostty์—์„œ๋Š” ์‚ฌ์šฉํ•  ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค +- **์„ธ์…˜ ๊ฐ„ ํŒ€ ๋ถˆ๊ฐ€**: ํŒ€์›์€ ํ˜„์žฌ ์„ธ์…˜ ๋‚ด์—์„œ๋งŒ ์กด์žฌํ•ฉ๋‹ˆ๋‹ค + +> **๊ฒฝ๊ณ **: ์—์ด์ „ํŠธ ํŒ€์€ ์‹คํ—˜์  ๊ธฐ๋Šฅ์ž…๋‹ˆ๋‹ค. ์ค‘์š”ํ•˜์ง€ ์•Š์€ ์ž‘์—…์œผ๋กœ ๋จผ์ € ํ…Œ์ŠคํŠธํ•˜๊ณ , ์˜ˆ๊ธฐ์น˜ ์•Š์€ ๋™์ž‘์ด ์žˆ๋Š”์ง€ ํŒ€์› ์กฐ์ •์„ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์‹ญ์‹œ์˜ค. + +--- + +## ํ”Œ๋Ÿฌ๊ทธ์ธ ์„œ๋ธŒ์—์ด์ „ํŠธ ๋ณด์•ˆ + +ํ”Œ๋Ÿฌ๊ทธ์ธ์ด ์ œ๊ณตํ•˜๋Š” ์„œ๋ธŒ์—์ด์ „ํŠธ๋Š” ๋ณด์•ˆ์„ ์œ„ํ•ด ํ”„๋ŸฐํŠธ๋งคํ„ฐ ๊ธฐ๋Šฅ์ด ์ œํ•œ๋ฉ๋‹ˆ๋‹ค. ํ”Œ๋Ÿฌ๊ทธ์ธ ์„œ๋ธŒ์—์ด์ „ํŠธ ์ •์˜์—์„œ๋Š” ๋‹ค์Œ ํ•„๋“œ๊ฐ€ **ํ—ˆ์šฉ๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค**: + +- `hooks` - ๋ผ์ดํ”„์‚ฌ์ดํด ํ›…์„ ์ •์˜ํ•  ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค +- `mcpServers` - MCP ์„œ๋ฒ„๋ฅผ ๊ตฌ์„ฑํ•  ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค +- `permissionMode` - ๊ถŒํ•œ ์„ค์ •์„ ์žฌ์ •์˜ํ•  ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค + +์ด๋Š” ํ”Œ๋Ÿฌ๊ทธ์ธ์ด ์„œ๋ธŒ์—์ด์ „ํŠธ ํ›…์„ ํ†ตํ•ด ๊ถŒํ•œ์„ ์—์Šค์ปฌ๋ ˆ์ด์…˜ํ•˜๊ฑฐ๋‚˜ ์ž„์˜์˜ ๋ช…๋ น์„ ์‹คํ–‰ํ•˜๋Š” ๊ฒƒ์„ ๋ฐฉ์ง€ํ•ฉ๋‹ˆ๋‹ค. + +--- + +## ์•„ํ‚คํ…์ฒ˜ + +### ๊ณ ์ˆ˜์ค€ ์•„ํ‚คํ…์ฒ˜ + +```mermaid +graph TB + User["User"] + Main["Main Agent
(Coordinator)"] + Reviewer["Code Reviewer
Subagent"] + Tester["Test Engineer
Subagent"] + Docs["Documentation
Subagent"] + + User -->|asks| Main + Main -->|delegates| Reviewer + Main -->|delegates| Tester + Main -->|delegates| Docs + Reviewer -->|returns result| Main + Tester -->|returns result| Main + Docs -->|returns result| Main + Main -->|synthesizes| User +``` + +### ์„œ๋ธŒ์—์ด์ „ํŠธ ์ƒ๋ช…์ฃผ๊ธฐ + +```mermaid +sequenceDiagram + participant User + participant MainAgent as Main Agent + participant CodeReviewer as Code Reviewer
Subagent + participant Context as Separate
Context Window + + User->>MainAgent: "Build new auth feature" + MainAgent->>MainAgent: Analyze task + MainAgent->>CodeReviewer: "Review this code" + CodeReviewer->>Context: Initialize clean context + Context->>CodeReviewer: Load reviewer instructions + CodeReviewer->>CodeReviewer: Perform review + CodeReviewer-->>MainAgent: Return findings + MainAgent->>MainAgent: Incorporate results + MainAgent-->>User: Provide synthesis +``` + +--- + +## ์ปจํ…์ŠคํŠธ ๊ด€๋ฆฌ + +```mermaid +graph TB + A["Main Agent Context
50,000 tokens"] + B["Subagent 1 Context
20,000 tokens"] + C["Subagent 2 Context
20,000 tokens"] + D["Subagent 3 Context
20,000 tokens"] + + A -->|Clean slate| B + A -->|Clean slate| C + A -->|Clean slate| D + + B -->|Results only| A + C -->|Results only| A + D -->|Results only| A + + style A fill:#e1f5fe + style B fill:#fff9c4 + style C fill:#fff9c4 + style D fill:#fff9c4 +``` + +### ์ฃผ์š” ์‚ฌํ•ญ + +- ๊ฐ ์„œ๋ธŒ์—์ด์ „ํŠธ๋Š” ์ฃผ ๋Œ€ํ™” ๊ธฐ๋ก ์—†์ด **์ƒˆ๋กœ์šด ์ปจํ…์ŠคํŠธ ์ฐฝ**์„ ์–ป์Šต๋‹ˆ๋‹ค +- **๊ด€๋ จ ์ปจํ…์ŠคํŠธ**๋งŒ ํŠน์ • ์ž‘์—…์„ ์œ„ํ•ด ์„œ๋ธŒ์—์ด์ „ํŠธ์—๊ฒŒ ์ „๋‹ฌ๋ฉ๋‹ˆ๋‹ค +- ๊ฒฐ๊ณผ๋Š” ์ฃผ ์—์ด์ „ํŠธ๋กœ **์š”์•ฝ๋˜์–ด** ๋Œ์•„์˜ต๋‹ˆ๋‹ค +- ์ด๋Š” ๊ธด ํ”„๋กœ์ ํŠธ์—์„œ **์ปจํ…์ŠคํŠธ ํ† ํฐ ์†Œ์ง„**์„ ๋ฐฉ์ง€ํ•ฉ๋‹ˆ๋‹ค + +### ์„ฑ๋Šฅ ๊ณ ๋ ค ์‚ฌํ•ญ + +- **์ปจํ…์ŠคํŠธ ํšจ์œจ์„ฑ** - ์—์ด์ „ํŠธ๊ฐ€ ์ฃผ ์ปจํ…์ŠคํŠธ๋ฅผ ๋ณด์กดํ•˜์—ฌ ๋” ๊ธด ์„ธ์…˜์„ ๊ฐ€๋Šฅํ•˜๊ฒŒ ํ•ฉ๋‹ˆ๋‹ค +- **์ง€์—ฐ ์‹œ๊ฐ„** - ์„œ๋ธŒ์—์ด์ „ํŠธ๋Š” ๊นจ๋—ํ•œ ์ƒํƒœ๋กœ ์‹œ์ž‘ํ•˜๋ฉฐ ์ดˆ๊ธฐ ์ปจํ…์ŠคํŠธ๋ฅผ ์ˆ˜์ง‘ํ•˜๋Š” ๋ฐ ์ง€์—ฐ ์‹œ๊ฐ„์„ ์ถ”๊ฐ€ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค + +### ์ฃผ์š” ๋™์ž‘ + +- **์ค‘์ฒฉ ์ƒ์„ฑ (์ตœ๋Œ€ 5๋‹จ๊ณ„)** - v2.1.172๋ถ€ํ„ฐ ์„œ๋ธŒ์—์ด์ „ํŠธ๋Š” ์ž์ฒด ์„œ๋ธŒ์—์ด์ „ํŠธ๋ฅผ ์ตœ๋Œ€ 5๋‹จ๊ณ„ ๊นŠ์ด๋กœ ์ค‘์ฒฉํ•˜์—ฌ ์ƒ์„ฑํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์ด์ „ ๋ฒ„์ „์—์„œ๋Š” ์ค‘์ฒฉ์ด ํ—ˆ์šฉ๋˜์ง€ ์•Š์•˜์Šต๋‹ˆ๋‹ค. ์ฃผ์–ด์ง„ ์„œ๋ธŒ์—์ด์ „ํŠธ๊ฐ€ ์ƒ์„ฑํ•  ์ˆ˜ ์žˆ๋Š” ์„œ๋ธŒ์—์ด์ „ํŠธ๋ฅผ ์ œ์–ดํ•˜๋ ค๋ฉด `Agent(agent_type)` ์ œํ•œ ๊ตฌ๋ฌธ(์ฐธ์กฐ: [์ƒ์„ฑ ๊ฐ€๋Šฅํ•œ ์„œ๋ธŒ์—์ด์ „ํŠธ ์ œํ•œ](#์ƒ์„ฑ-๊ฐ€๋Šฅํ•œ-์„œ๋ธŒ์—์ด์ „ํŠธ-์ œํ•œ))์„ ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค +- **๋ฐฑ๊ทธ๋ผ์šด๋“œ ๊ถŒํ•œ** - ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์„œ๋ธŒ์—์ด์ „ํŠธ๋Š” ์‚ฌ์ „ ์Šน์ธ๋˜์ง€ ์•Š์€ ๋ชจ๋“  ๊ถŒํ•œ์„ ์ž๋™์œผ๋กœ ๊ฑฐ๋ถ€ํ•ฉ๋‹ˆ๋‹ค +- **๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ „ํ™˜** - `Ctrl+B`๋ฅผ ๋ˆŒ๋Ÿฌ ํ˜„์žฌ ์‹คํ–‰ ์ค‘์ธ ์ž‘์—…์„ ๋ฐฑ๊ทธ๋ผ์šด๋“œ๋กœ ์ „ํ™˜ํ•ฉ๋‹ˆ๋‹ค +- **ํŠธ๋žœ์Šคํฌ๋ฆฝํŠธ** - ์„œ๋ธŒ์—์ด์ „ํŠธ ํŠธ๋žœ์Šคํฌ๋ฆฝํŠธ๋Š” `~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl`์— ์ €์žฅ๋ฉ๋‹ˆ๋‹ค +- **์ž๋™ ์••์ถ•** - ์„œ๋ธŒ์—์ด์ „ํŠธ ์ปจํ…์ŠคํŠธ๋Š” ์šฉ๋Ÿ‰์˜ ~95%์—์„œ ์ž๋™์œผ๋กœ ์••์ถ•๋ฉ๋‹ˆ๋‹ค (`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋กœ ์žฌ์ •์˜) + +--- + +## ์„œ๋ธŒ์—์ด์ „ํŠธ ์‚ฌ์šฉ ์‹œ๊ธฐ + +| Scenario | Use Subagent | Why | +|----------|--------------|-----| +| ์—ฌ๋Ÿฌ ๋‹จ๊ณ„๊ฐ€ ์žˆ๋Š” ๋ณต์žกํ•œ ๊ธฐ๋Šฅ | ์˜ˆ | ๊ด€์‹ฌ์‚ฌ ๋ถ„๋ฆฌ, ์ปจํ…์ŠคํŠธ ์˜ค์—ผ ๋ฐฉ์ง€ | +| ๋น ๋ฅธ ์ฝ”๋“œ ๊ฒ€ํ†  | ์•„๋‹ˆ์š” | ๋ถˆํ•„์š”ํ•œ ์˜ค๋ฒ„ํ—ค๋“œ | +| ๋ณ‘๋ ฌ ์ž‘์—… ์‹คํ–‰ | ์˜ˆ | ๊ฐ ์„œ๋ธŒ์—์ด์ „ํŠธ๋Š” ์ž์ฒด ์ปจํ…์ŠคํŠธ๋ฅผ ๊ฐ€์ง‘๋‹ˆ๋‹ค | +| ์ „๋ฌธํ™”๋œ ์ „๋ฌธ ์ง€์‹ ํ•„์š” | ์˜ˆ | ๋งž์ถคํ˜• ์‹œ์Šคํ…œ ํ”„๋กฌํ”„ํŠธ | +| ์žฅ๊ธฐ ์‹คํ–‰ ๋ถ„์„ | ์˜ˆ | ์ฃผ ์ปจํ…์ŠคํŠธ ์†Œ์ง„ ๋ฐฉ์ง€ | +| ๋‹จ์ผ ์ž‘์—… | ์•„๋‹ˆ์š” | ๋ถˆํ•„์š”ํ•˜๊ฒŒ ์ง€์—ฐ ์‹œ๊ฐ„ ์ถ”๊ฐ€ | + +--- + +## ๋ชจ๋ฒ” ์‚ฌ๋ก€ + +### ์„ค๊ณ„ ์›์น™ + +**๊ถŒ์žฅ ์‚ฌํ•ญ:** +- Claude๊ฐ€ ์ƒ์„ฑํ•œ ์—์ด์ „ํŠธ๋กœ ์‹œ์ž‘ - Claude๋กœ ์ดˆ๊ธฐ ์„œ๋ธŒ์—์ด์ „ํŠธ๋ฅผ ์ƒ์„ฑํ•œ ๋‹ค์Œ ๋ฐ˜๋ณตํ•˜์—ฌ ์‚ฌ์šฉ์ž ์ •์˜ +- ์ง‘์ค‘๋œ ์„œ๋ธŒ์—์ด์ „ํŠธ ์„ค๊ณ„ - ๋ชจ๋“  ๊ฒƒ์„ ํ•˜๋Š” ๋Œ€์‹  ๋‹จ์ผํ•˜๊ณ  ๋ช…ํ™•ํ•œ ์ฑ…์ž„ +- ์ž์„ธํ•œ ํ”„๋กฌํ”„ํŠธ ์ž‘์„ฑ - ํŠน์ • ์ง€์นจ, ์˜ˆ์‹œ ๋ฐ ์ œ์•ฝ ์กฐ๊ฑด ํฌํ•จ +- ๋„๊ตฌ ์ ‘๊ทผ ์ œํ•œ - ์„œ๋ธŒ์—์ด์ „ํŠธ์˜ ๋ชฉ์ ์— ํ•„์š”ํ•œ ๋„๊ตฌ๋งŒ ๋ถ€์—ฌ +- ๋ฒ„์ „ ๊ด€๋ฆฌ - ํŒ€ ํ˜‘์—…์„ ์œ„ํ•ด ํ”„๋กœ์ ํŠธ ์„œ๋ธŒ์—์ด์ „ํŠธ๋ฅผ ๋ฒ„์ „ ์ œ์–ด์— ์ฒดํฌ์ธ + +**ํ”ผํ•ด์•ผ ํ•  ์‚ฌํ•ญ:** +- ์—ญํ• ์ด ์ค‘๋ณต๋˜๋Š” ์„œ๋ธŒ์—์ด์ „ํŠธ ์ƒ์„ฑ +- ์„œ๋ธŒ์—์ด์ „ํŠธ์— ๋ถˆํ•„์š”ํ•œ ๋„๊ตฌ ์ ‘๊ทผ ๊ถŒํ•œ ๋ถ€์—ฌ +- ๊ฐ„๋‹จํ•œ ๋‹จ์ผ ๋‹จ๊ณ„ ์ž‘์—…์— ์„œ๋ธŒ์—์ด์ „ํŠธ ์‚ฌ์šฉ +- ํ•˜๋‚˜์˜ ์„œ๋ธŒ์—์ด์ „ํŠธ ํ”„๋กฌํ”„ํŠธ์— ์—ฌ๋Ÿฌ ๊ด€์‹ฌ์‚ฌ ํ˜ผํ•ฉ +- ํ•„์š”ํ•œ ์ปจํ…์ŠคํŠธ ์ „๋‹ฌ์„ ์žŠ์ง€ ๋งˆ์„ธ์š” + +### ์‹œ์Šคํ…œ ํ”„๋กฌํ”„ํŠธ ๋ชจ๋ฒ” ์‚ฌ๋ก€ + +1. **์—ญํ• ์— ๋Œ€ํ•ด ๊ตฌ์ฒด์ ์œผ๋กœ ์„ค๋ช…** + ``` + You are an expert code reviewer specializing in [specific areas] + ``` + +2. **์šฐ์„ ์ˆœ์œ„๋ฅผ ๋ช…ํ™•ํ•˜๊ฒŒ ์ •์˜** + ``` + Review priorities (in order): + 1. Security Issues + 2. Performance Problems + 3. Code Quality + ``` + +3. **์ถœ๋ ฅ ํ˜•์‹ ์ง€์ •** + ``` + For each issue provide: Severity, Category, Location, Description, Fix, Impact + ``` + +4. **์‹คํ–‰ ๋‹จ๊ณ„ ํฌํ•จ** + ``` + When invoked: + 1. Run git diff to see recent changes + 2. Focus on modified files + 3. Begin review immediately + ``` + +### ๋„๊ตฌ ์ ‘๊ทผ ์ „๋žต + +1. **์ œํ•œ์ ์œผ๋กœ ์‹œ์ž‘**: ํ•„์ˆ˜ ๋„๊ตฌ๋งŒ์œผ๋กœ ์‹œ์ž‘ +2. **ํ•„์š”ํ•  ๋•Œ๋งŒ ํ™•์žฅ**: ์š”๊ตฌ ์‚ฌํ•ญ์— ๋”ฐ๋ผ ๋„๊ตฌ ์ถ”๊ฐ€ +3. **๊ฐ€๋Šฅํ•  ๋•Œ ์ฝ๊ธฐ ์ „์šฉ**: ๋ถ„์„ ์—์ด์ „ํŠธ์—๋Š” Read/Grep ์‚ฌ์šฉ +4. **์ƒŒ๋“œ๋ฐ•์Šค ์‹คํ–‰**: Bash ๋ช…๋ น์„ ํŠน์ • ํŒจํ„ด์œผ๋กœ ์ œํ•œ + +--- + +## ์ด ํด๋”์˜ ์„œ๋ธŒ์—์ด์ „ํŠธ ์˜ˆ์‹œ + +์ด ํด๋”์—๋Š” ๋ฐ”๋กœ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ๋Š” ์„œ๋ธŒ์—์ด์ „ํŠธ ์˜ˆ์‹œ๊ฐ€ ํฌํ•จ๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค: + +### 1. ์ฝ”๋“œ ๋ฆฌ๋ทฐ์–ด (`code-reviewer.md`) + +**๋ชฉ์ **: ํฌ๊ด„์ ์ธ ์ฝ”๋“œ ํ’ˆ์งˆ ๋ฐ ์œ ์ง€ ๋ณด์ˆ˜์„ฑ ๋ถ„์„ + +**๋„๊ตฌ**: Read, Grep, Glob, Bash + +**์ „๋ฌธ ๋ถ„์•ผ**: +- ๋ณด์•ˆ ์ทจ์•ฝ์  ๊ฐ์ง€ +- ์„ฑ๋Šฅ ์ตœ์ ํ™” ์‹๋ณ„ +- ์ฝ”๋“œ ์œ ์ง€ ๋ณด์ˆ˜์„ฑ ํ‰๊ฐ€ +- ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€ ๋ถ„์„ + +**์‚ฌ์šฉ ์‹œ๊ธฐ**: ํ’ˆ์งˆ ๋ฐ ๋ณด์•ˆ์— ์ค‘์ ์„ ๋‘” ์ž๋™ํ™”๋œ ์ฝ”๋“œ ๊ฒ€ํ† ๊ฐ€ ํ•„์š”ํ•  ๋•Œ + +--- + +### 2. ํ…Œ์ŠคํŠธ ์—”์ง€๋‹ˆ์–ด (`test-engineer.md`) + +**๋ชฉ์ **: ํ…Œ์ŠคํŠธ ์ „๋žต, ์ปค๋ฒ„๋ฆฌ์ง€ ๋ถ„์„ ๋ฐ ์ž๋™ํ™”๋œ ํ…Œ์ŠคํŠธ + +**๋„๊ตฌ**: Read, Write, Bash, Grep + +**์ „๋ฌธ ๋ถ„์•ผ**: +- ๋‹จ์œ„ ํ…Œ์ŠคํŠธ ์ƒ์„ฑ +- ํ†ตํ•ฉ ํ…Œ์ŠคํŠธ ์„ค๊ณ„ +- ์—์ง€ ์ผ€์ด์Šค ์‹๋ณ„ +- ์ปค๋ฒ„๋ฆฌ์ง€ ๋ถ„์„ (80% ์ด์ƒ ๋ชฉํ‘œ) + +**์‚ฌ์šฉ ์‹œ๊ธฐ**: ํฌ๊ด„์ ์ธ ํ…Œ์ŠคํŠธ ์Šค์œ„ํŠธ ์ƒ์„ฑ ๋˜๋Š” ์ปค๋ฒ„๋ฆฌ์ง€ ๋ถ„์„์ด ํ•„์š”ํ•  ๋•Œ + +--- + +### 3. ๋ฌธ์„œ ์ž‘์„ฑ๊ธฐ (`documentation-writer.md`) + +**๋ชฉ์ **: ๊ธฐ์ˆ  ๋ฌธ์„œ, API ๋ฌธ์„œ ๋ฐ ์‚ฌ์šฉ์ž ๊ฐ€์ด๋“œ + +**๋„๊ตฌ**: Read, Write, Grep + +**์ „๋ฌธ ๋ถ„์•ผ**: +- API ์—”๋“œํฌ์ธํŠธ ๋ฌธ์„œํ™” +- ์‚ฌ์šฉ์ž ๊ฐ€์ด๋“œ ์ƒ์„ฑ +- ์•„ํ‚คํ…์ฒ˜ ๋ฌธ์„œํ™” +- ์ฝ”๋“œ ์ฃผ์„ ๊ฐœ์„  + +**์‚ฌ์šฉ ์‹œ๊ธฐ**: ํ”„๋กœ์ ํŠธ ๋ฌธ์„œ๋ฅผ ์ƒ์„ฑํ•˜๊ฑฐ๋‚˜ ์—…๋ฐ์ดํŠธํ•ด์•ผ ํ•  ๋•Œ + +--- + +### 4. ๋ณด์•ˆ ๋ฆฌ๋ทฐ์–ด (`secure-reviewer.md`) + +**๋ชฉ์ **: ์ตœ์†Œํ•œ์˜ ๊ถŒํ•œ์œผ๋กœ ๋ณด์•ˆ์— ์ค‘์ ์„ ๋‘” ์ฝ”๋“œ ๊ฒ€ํ†  + +**๋„๊ตฌ**: Read, Grep + +**์ „๋ฌธ ๋ถ„์•ผ**: +- ๋ณด์•ˆ ์ทจ์•ฝ์  ๊ฐ์ง€ +- ์ธ์ฆ/๊ถŒํ•œ ๋ถ€์—ฌ ๋ฌธ์ œ +- ๋ฐ์ดํ„ฐ ๋…ธ์ถœ ์œ„ํ—˜ +- ์ธ์ ์…˜ ๊ณต๊ฒฉ ์‹๋ณ„ + +**์‚ฌ์šฉ ์‹œ๊ธฐ**: ์ˆ˜์ • ๊ธฐ๋Šฅ ์—†์ด ๋ณด์•ˆ ๊ฐ์‚ฌ๋งŒ ํ•„์š”ํ•œ ๊ฒฝ์šฐ + +--- + +### 5. ๊ตฌํ˜„ ์—์ด์ „ํŠธ (`implementation-agent.md`) + +**๋ชฉ์ **: ๊ธฐ๋Šฅ ๊ฐœ๋ฐœ์„ ์œ„ํ•œ ์™„์ „ํ•œ ๊ตฌํ˜„ ๊ธฐ๋Šฅ + +**๋„๊ตฌ**: Read, Write, Edit, Bash, Grep, Glob + +**์ „๋ฌธ ๋ถ„์•ผ**: +- ๊ธฐ๋Šฅ ๊ตฌํ˜„ +- ์ฝ”๋“œ ์ƒ์„ฑ +- ๋นŒ๋“œ ๋ฐ ํ…Œ์ŠคํŠธ ์‹คํ–‰ +- ์ฝ”๋“œ๋ฒ ์ด์Šค ์ˆ˜์ • + +**์‚ฌ์šฉ ์‹œ๊ธฐ**: ๊ธฐ๋Šฅ ๊ตฌํ˜„์„ ์ฒ˜์Œ๋ถ€ํ„ฐ ๋๊นŒ์ง€ ์ˆ˜ํ–‰ํ•  ์„œ๋ธŒ์—์ด์ „ํŠธ๊ฐ€ ํ•„์š”ํ•  ๋•Œ + +--- + +### 6. ๋””๋ฒ„๊ฑฐ (`debugger.md`) + +**๋ชฉ์ **: ์˜ค๋ฅ˜, ํ…Œ์ŠคํŠธ ์‹คํŒจ ๋ฐ ์˜ˆ๊ธฐ์น˜ ์•Š์€ ๋™์ž‘์„ ์œ„ํ•œ ๋””๋ฒ„๊น… ์ „๋ฌธ๊ฐ€ + +**๋„๊ตฌ**: Read, Edit, Bash, Grep, Glob + +**์ „๋ฌธ ๋ถ„์•ผ**: +- ๊ทผ๋ณธ ์›์ธ ๋ถ„์„ +- ์˜ค๋ฅ˜ ์กฐ์‚ฌ +- ํ…Œ์ŠคํŠธ ์‹คํŒจ ํ•ด๊ฒฐ +- ์ตœ์†Œํ•œ์˜ ์ˆ˜์ • ๊ตฌํ˜„ + +**์‚ฌ์šฉ ์‹œ๊ธฐ**: ๋ฒ„๊ทธ, ์˜ค๋ฅ˜ ๋˜๋Š” ์˜ˆ๊ธฐ์น˜ ์•Š์€ ๋™์ž‘์ด ๋ฐœ์ƒํ•  ๋•Œ + +--- + +### 7. ๋ฐ์ดํ„ฐ ๊ณผํ•™์ž (`data-scientist.md`) + +**๋ชฉ์ **: SQL ์ฟผ๋ฆฌ ๋ฐ ๋ฐ์ดํ„ฐ ํ†ต์ฐฐ๋ ฅ์„ ์œ„ํ•œ ๋ฐ์ดํ„ฐ ๋ถ„์„ ์ „๋ฌธ๊ฐ€ + +**๋„๊ตฌ**: Bash, Read, Write + +**์ „๋ฌธ ๋ถ„์•ผ**: +- SQL ์ฟผ๋ฆฌ ์ตœ์ ํ™” +- BigQuery ์ž‘์—… +- ๋ฐ์ดํ„ฐ ๋ถ„์„ ๋ฐ ์‹œ๊ฐํ™” +- ํ†ต๊ณ„์  ํ†ต์ฐฐ๋ ฅ + +**์‚ฌ์šฉ ์‹œ๊ธฐ**: ๋ฐ์ดํ„ฐ ๋ถ„์„, SQL ์ฟผ๋ฆฌ ๋˜๋Š” BigQuery ์ž‘์—…์ด ํ•„์š”ํ•  ๋•Œ + +--- + +## ์„ค์น˜ ์•ˆ๋‚ด + +### ๋ฐฉ๋ฒ• 1: /agents ๋ช…๋ น ์‚ฌ์šฉ (๊ถŒ์žฅ) + +```bash +/agents +``` + +๊ทธ๋Ÿฐ ๋‹ค์Œ: +1. '์ƒˆ ์—์ด์ „ํŠธ ์ƒ์„ฑ' ์„ ํƒ +2. ํ”„๋กœ์ ํŠธ ์ˆ˜์ค€ ๋˜๋Š” ์‚ฌ์šฉ์ž ์ˆ˜์ค€ ์„ ํƒ +3. ์„œ๋ธŒ์—์ด์ „ํŠธ๋ฅผ ์ž์„ธํžˆ ์„ค๋ช… +4. ์ ‘๊ทผ ๊ถŒํ•œ์„ ๋ถ€์—ฌํ•  ๋„๊ตฌ ์„ ํƒ (๋˜๋Š” ๋ชจ๋“  ๋„๊ตฌ๋ฅผ ์ƒ์†ํ•˜๋ ค๋ฉด ๋น„์›Œ๋‘ก๋‹ˆ๋‹ค) +5. ์ €์žฅ ๋ฐ ์‚ฌ์šฉ + +### ๋ฐฉ๋ฒ• 2: ํ”„๋กœ์ ํŠธ๋กœ ๋ณต์‚ฌ + +์—์ด์ „ํŠธ ํŒŒ์ผ์„ ํ”„๋กœ์ ํŠธ์˜ `.claude/agents/` ๋””๋ ‰ํ„ฐ๋ฆฌ๋กœ ๋ณต์‚ฌํ•ฉ๋‹ˆ๋‹ค: + +```bash +# Navigate to your project +cd /path/to/your/project + +# Create agents directory if it doesn't exist +mkdir -p .claude/agents + +# Copy all agent files from this folder +cp /path/to/04-subagents/*.md .claude/agents/ + +# Remove the README (not needed in .claude/agents) +rm .claude/agents/README.md +``` + +### ๋ฐฉ๋ฒ• 3: ์‚ฌ์šฉ์ž ๋””๋ ‰ํ„ฐ๋ฆฌ๋กœ ๋ณต์‚ฌ + +๋ชจ๋“  ํ”„๋กœ์ ํŠธ์—์„œ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ๋Š” ์—์ด์ „ํŠธ์˜ ๊ฒฝ์šฐ: + +```bash +# Create user agents directory +mkdir -p ~/.claude/agents + +# Copy agents +cp /path/to/04-subagents/code-reviewer.md ~/.claude/agents/ +cp /path/to/04-subagents/debugger.md ~/.claude/agents/ +# ... copy others as needed +``` + +### ํ™•์ธ + +์„ค์น˜ ํ›„ ์—์ด์ „ํŠธ๊ฐ€ ์ธ์‹๋˜๋Š”์ง€ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค: + +```bash +/agents +``` + +์„ค์น˜๋œ ์—์ด์ „ํŠธ๊ฐ€ ๋‚ด์žฅ ์—์ด์ „ํŠธ์™€ ํ•จ๊ป˜ ๋‚˜์—ด๋˜์–ด ์žˆ๋Š” ๊ฒƒ์„ ๋ณผ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +--- + +## ํŒŒ์ผ ๊ตฌ์กฐ + +``` +project/ +โ”œโ”€โ”€ .claude/ +โ”‚ โ””โ”€โ”€ agents/ +โ”‚ โ”œโ”€โ”€ code-reviewer.md +โ”‚ โ”œโ”€โ”€ test-engineer.md +โ”‚ โ”œโ”€โ”€ documentation-writer.md +โ”‚ โ”œโ”€โ”€ secure-reviewer.md +โ”‚ โ”œโ”€โ”€ implementation-agent.md +โ”‚ โ”œโ”€โ”€ debugger.md +โ”‚ โ””โ”€โ”€ data-scientist.md +โ””โ”€โ”€ ... +``` + +--- + +## ๊ด€๋ จ ๊ฐœ๋… + +### ๊ด€๋ จ ๊ธฐ๋Šฅ + +- **[์Šฌ๋ž˜์‹œ ๋ช…๋ น](../01-slash-commands/)** - ์‚ฌ์šฉ์ž๊ฐ€ ๋น ๋ฅด๊ฒŒ ํ˜ธ์ถœํ•˜๋Š” ๋‹จ์ถ•ํ‚ค +- **[๋ฉ”๋ชจ๋ฆฌ](../02-memory/)** - ์˜๊ตฌ์ ์ธ ์„ธ์…˜ ๊ฐ„ ์ปจํ…์ŠคํŠธ +- **[์Šคํ‚ฌ](../03-skills/)** - ์žฌ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ์ž์œจ ๊ธฐ๋Šฅ +- **[MCP ํ”„๋กœํ† ์ฝœ](../05-mcp/)** - ์‹ค์‹œ๊ฐ„ ์™ธ๋ถ€ ๋ฐ์ดํ„ฐ ์ ‘๊ทผ +- **[ํ›…](../06-hooks/)** - ์ด๋ฒคํŠธ ๊ธฐ๋ฐ˜ ์…ธ ๋ช…๋ น ์ž๋™ํ™” +- **[ํ”Œ๋Ÿฌ๊ทธ์ธ](../07-plugins/)** - ๋ฒˆ๋“ค ํ™•์žฅ ํŒจํ‚ค์ง€ + +### ๋‹ค๋ฅธ ๊ธฐ๋Šฅ๊ณผ์˜ ๋น„๊ต + +| Feature | User-Invoked | Auto-Invoked | Persistent | External Access | Isolated Context | +|---------|--------------|--------------|-----------|------------------|------------------| +| **์Šฌ๋ž˜์‹œ ๋ช…๋ น** | ์˜ˆ | ์•„๋‹ˆ์š” | ์•„๋‹ˆ์š” | ์•„๋‹ˆ์š” | ์•„๋‹ˆ์š” | +| **์„œ๋ธŒ์—์ด์ „ํŠธ** | ์˜ˆ | ์˜ˆ | ์•„๋‹ˆ์š” | ์•„๋‹ˆ์š” | ์˜ˆ | +| **๋ฉ”๋ชจ๋ฆฌ** | ์ž๋™ | ์ž๋™ | ์˜ˆ | ์•„๋‹ˆ์š” | ์•„๋‹ˆ์š” | +| **MCP** | ์ž๋™ | ์˜ˆ | ์•„๋‹ˆ์š” | ์˜ˆ | ์•„๋‹ˆ์š” | +| **์Šคํ‚ฌ** | ์˜ˆ | ์˜ˆ | ์•„๋‹ˆ์š” | ์•„๋‹ˆ์š” | ์•„๋‹ˆ์š” | + +### ํ†ตํ•ฉ ํŒจํ„ด + +```mermaid +graph TD + User["User Request"] --> Main["Main Agent"] + Main -->|Uses| Memory["Memory
(Context)"] + Main -->|Queries| MCP["MCP
(Live Data)"] + Main -->|Invokes| Skills["Skills
(Auto Tools)"] + Main -->|Delegates| Subagents["Subagents
(Specialists)"] + + Subagents -->|Use| Memory + Subagents -->|Query| MCP + Subagents -->|Isolated| Context["Clean Context
Window"] +``` + +--- + +## ๊ด€์ธก ๊ฐ€๋Šฅ์„ฑ + +> **v2.1.139์— ์ถ”๊ฐ€๋จ.** + +์„œ๋ธŒ์—์ด์ „ํŠธ์—์„œ ์‹œ์ž‘๋œ API ์š”์ฒญ์—๋Š” ์ถ”์  ๋ฐ ๋กœ๊ทธ๋ฅผ ๋””์ŠคํŒจ์น˜ ์„ธ์…˜๊ณผ ์ƒํ˜ธ ์—ฐ๊ด€์‹œํ‚ฌ ์ˆ˜ ์žˆ๋„๋ก ๋‘ ๊ฐœ์˜ ์ถ”๊ฐ€ HTTP ํ—ค๋”๊ฐ€ ํฌํ•จ๋ฉ๋‹ˆ๋‹ค: + +| Header | Description | +|--------|-------------| +| `x-claude-code-agent-id` | ์š”์ฒญ์„ ํ•˜๋Š” ์„œ๋ธŒ์—์ด์ „ํŠธ์˜ UUID์ž…๋‹ˆ๋‹ค. | +| `x-claude-code-parent-agent-id` | ์ด ์„œ๋ธŒ์—์ด์ „ํŠธ๋ฅผ ๋””์ŠคํŒจ์น˜ํ•œ ์—์ด์ „ํŠธ (์ฃผ ์—์ด์ „ํŠธ ๋˜๋Š” ์ฒด์ธ์˜ ์ƒ์œ„ ์„œ๋ธŒ์—์ด์ „ํŠธ)์˜ UUID์ž…๋‹ˆ๋‹ค. | + +๋™์ผํ•œ ์‹๋ณ„์ž๋Š” `claude_code.llm_request` OpenTelemetry ์ŠคํŒฌ์— `claude.code.agent.id` ๋ฐ `claude.code.agent.parent_id` ์†์„ฑ์œผ๋กœ ๋…ธ์ถœ๋ฉ๋‹ˆ๋‹ค. ์ด๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ๋‹ค์Œ์„ ์ˆ˜ํ–‰ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค: + +- API ์‚ฌ์šฉ๋Ÿ‰์„ ๋ถ€๋ชจ ์„ธ์…˜ ๋Œ€์‹  ํŠน์ • ์„œ๋ธŒ์—์ด์ „ํŠธ ์œ ํ˜•์— ํ• ๋‹น +- ์‚ฌํ›„ ์—์ด์ „ํŠธ ํ˜ธ์ถœ ์ฒด์ธ ์žฌ๊ตฌ์„ฑ (parent_id๋Š” ํŠธ๋ฆฌ๋ฅผ ํ˜•์„ฑ) +- ํญ์ฃผํ•˜๋Š” ์„œ๋ธŒ์—์ด์ „ํŠธ์— ๋Œ€ํ•œ ๊ฒฝ๊ณ  (์˜ˆ: ํ•˜๋‚˜์˜ `agent.id`๊ฐ€ ์„ธ์…˜ ์‚ฌ์šฉ๋Ÿ‰์˜ 50% ์ด์ƒ์„ ์ฐจ์ง€) + +์ข…๋‹จ ๊ฐ„ ์ต์Šคํฌํ„ฐ ์„ค์ •์— ๋Œ€ํ•ด์„œ๋Š” [๊ณ ๊ธ‰ ๊ธฐ๋Šฅ โ†’ ํ…”๋ ˆ๋ฉ”ํŠธ๋ฆฌ](../09-advanced-features/README.md)์˜ OpenTelemetry ์„น์…˜์„ ์ฐธ์กฐํ•˜์‹ญ์‹œ์˜ค. + +## ์ถ”๊ฐ€ ์ž๋ฃŒ + +- [๊ณต์‹ ์„œ๋ธŒ์—์ด์ „ํŠธ ๋ฌธ์„œ](https://code.claude.com/docs/en/sub-agents) +- [CLI ์ฐธ์กฐ](https://code.claude.com/docs/en/cli-reference) - `--agents` ํ”Œ๋ž˜๊ทธ ๋ฐ ๊ธฐํƒ€ CLI ์˜ต์…˜ +- [ํ”Œ๋Ÿฌ๊ทธ์ธ ๊ฐ€์ด๋“œ](../07-plugins/) - ๋‹ค๋ฅธ ๊ธฐ๋Šฅ๊ณผ ์—์ด์ „ํŠธ๋ฅผ ๋ฒˆ๋“ค๋งํ•˜๋Š” ๋ฐฉ๋ฒ• +- [์Šคํ‚ฌ ๊ฐ€์ด๋“œ](../03-skills/) - ์ž๋™ ํ˜ธ์ถœ ๊ธฐ๋Šฅ +- [๋ฉ”๋ชจ๋ฆฌ ๊ฐ€์ด๋“œ](../02-memory/) - ์˜๊ตฌ ์ปจํ…์ŠคํŠธ +- [ํ›… ๊ฐ€์ด๋“œ](../06-hooks/) - ์ด๋ฒคํŠธ ๊ธฐ๋ฐ˜ ์ž๋™ํ™” + +--- + +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: 2026๋…„ 6์›” 24์ผ +**Claude Code ๋ฒ„์ „**: 2.1.187 +**์ถœ์ฒ˜**: +- https://code.claude.com/docs/en/sub-agents +- https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md +- https://code.claude.com/docs/en/agent-teams +- https://code.claude.com/docs/en/changelog#2-1-172 +- https://code.claude.com/docs/en/changelog +- https://github.com/anthropics/claude-code/releases/tag/v2.1.117 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.131 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.138 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.139 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.140 +**ํ˜ธํ™˜ ๋ชจ๋ธ**: Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5 diff --git a/ko/04-subagents/clean-code-reviewer.md b/ko/04-subagents/clean-code-reviewer.md new file mode 100644 index 00000000..f9d44f58 --- /dev/null +++ b/ko/04-subagents/clean-code-reviewer.md @@ -0,0 +1,73 @@ +--- +name: clean-code-reviewer +description: ํด๋ฆฐ ์ฝ”๋“œ ์›์น™ ์ ์šฉ ์ „๋ฌธ ๋ฆฌ๋ทฐ์–ด์ž…๋‹ˆ๋‹ค. ํด๋ฆฐ ์ฝ”๋“œ ์ด๋ก ๊ณผ ๋ชจ๋ฒ” ์‚ฌ๋ก€ ์œ„๋ฐ˜ ์‚ฌํ•ญ์„ ๊ฒ€ํ† ํ•ฉ๋‹ˆ๋‹ค. ์œ ์ง€๋ณด์ˆ˜์„ฑ๊ณผ ์ „๋ฌธ์ ์ธ ํ’ˆ์งˆ์„ ๋ณด์žฅํ•˜๊ธฐ ์œ„ํ•ด ์ฝ”๋“œ๋ฅผ ์ž‘์„ฑํ•œ ํ›„ ์ ๊ทน์ ์œผ๋กœ ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค. +tools: Read, Grep, Glob, Bash +model: inherit +--- + +# ํด๋ฆฐ ์ฝ”๋“œ ๋ฆฌ๋ทฐ์–ด ์—์ด์ „ํŠธ + +๋‹น์‹ ์€ ํด๋ฆฐ ์ฝ”๋“œ ์›์น™(Robert C. Martin)์„ ์ „๋ฌธ์œผ๋กœ ํ•˜๋Š” ์‹œ๋‹ˆ์–ด ์ฝ”๋“œ ๋ฆฌ๋ทฐ์–ด์ž…๋‹ˆ๋‹ค. ์œ„๋ฐ˜ ์‚ฌํ•ญ์„ ์‹๋ณ„ํ•˜๊ณ  ์‹คํ–‰ ๊ฐ€๋Šฅํ•œ ๊ฐœ์„  ๋ฐฉ์•ˆ์„ ์ œ์‹œํ•˜์‹ญ์‹œ์˜ค. + +## ํ”„๋กœ์„ธ์Šค + +1. ์ตœ๊ทผ ๋ณ€๊ฒฝ ์‚ฌํ•ญ์„ ํ™•์ธํ•˜๊ธฐ ์œ„ํ•ด `git diff`๋ฅผ ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค. +2. ๊ด€๋ จ ํŒŒ์ผ์„ ์ถฉ๋ถ„ํžˆ ๊ฒ€ํ† ํ•ฉ๋‹ˆ๋‹ค. +3. ์œ„๋ฐ˜ ์‚ฌํ•ญ์„ ํŒŒ์ผ:๋ผ์ธ, ์ฝ”๋“œ ์Šค๋‹ˆํŽซ, ์ˆ˜์ • ๋ฐฉ์•ˆ๊ณผ ํ•จ๊ป˜ ๋ณด๊ณ ํ•ฉ๋‹ˆ๋‹ค. + +## ๊ฒ€ํ†  ํ•ญ๋ชฉ + +**์ด๋ฆ„ ์ง“๊ธฐ(Naming)**: ์˜๋„๊ฐ€ ๋“œ๋Ÿฌ๋‚˜๊ณ , ๋ฐœ์Œ ๊ฐ€๋Šฅํ•˜๋ฉฐ, ๊ฒ€์ƒ‰ ๊ฐ€๋Šฅํ•œ ์ด๋ฆ„์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. ์ธ์ฝ”๋”ฉ์ด๋‚˜ ์ ‘๋‘์‚ฌ๋Š” ์‚ฌ์šฉํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ํด๋ž˜์Šค๋Š” ๋ช…์‚ฌ, ๋ฉ”์„œ๋“œ๋Š” ๋™์‚ฌ๋กœ ์ž‘์„ฑํ•ฉ๋‹ˆ๋‹ค. + +**ํ•จ์ˆ˜(Functions)**: 20์ค„ ๋ฏธ๋งŒ, ํ•˜๋‚˜์˜ ์ผ๋งŒ ์ˆ˜ํ–‰, ๋งค๊ฐœ๋ณ€์ˆ˜ ์ตœ๋Œ€ 3๊ฐœ, ํ”Œ๋ž˜๊ทธ ์ธ์ˆ˜ ๊ธˆ์ง€, ๋ถ€์ž‘์šฉ ๊ธˆ์ง€, null ๋ฐ˜ํ™˜ ๊ธˆ์ง€. + +**์ฃผ์„(Comments)**: ์ฝ”๋“œ๋Š” ์Šค์Šค๋กœ ์„ค๋ช…ํ•  ์ˆ˜ ์žˆ์–ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. ์ฃผ์„ ์ฒ˜๋ฆฌ๋œ ์ฝ”๋“œ๋Š” ์‚ญ์ œํ•ฉ๋‹ˆ๋‹ค. ์ค‘๋ณต๋˜๊ฑฐ๋‚˜ ์˜คํ•ด๋ฅผ ์œ ๋ฐœํ•˜๋Š” ์ฃผ์„์€ ์‚ฌ์šฉํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. + +**๊ตฌ์กฐ(Structure)**: ์ž‘๊ณ  ์ง‘์ค‘๋œ ํด๋ž˜์Šค, ๋‹จ์ผ ์ฑ…์ž„ ์›์น™, ๋†’์€ ์‘์ง‘๋„, ๋‚ฎ์€ ๊ฒฐํ•ฉ๋„. God Class๋ฅผ ํ”ผํ•ฉ๋‹ˆ๋‹ค. + +**SOLID**: ๋‹จ์ผ ์ฑ…์ž„ ์›์น™(SRP), ๊ฐœ๋ฐฉ-ํ์‡„ ์›์น™(OCP), ๋ฆฌ์Šค์ฝ”ํ”„ ์น˜ํ™˜ ์›์น™(LSP), ์ธํ„ฐํŽ˜์ด์Šค ๋ถ„๋ฆฌ ์›์น™(ISP), ์˜์กด์„ฑ ์—ญ์ „ ์›์น™(DIP). + +**DRY/KISS/YAGNI**: ์ค‘๋ณต ์ œ๊ฑฐ, ๋‹จ์ˆœ์„ฑ ์œ ์ง€, ๊ฐ€์ •๋œ ๋ฏธ๋ž˜ ์š”๊ตฌ์‚ฌํ•ญ์„ ์œ„ํ•œ ๊ตฌํ˜„ ๊ธˆ์ง€. + +**์˜ค๋ฅ˜ ์ฒ˜๋ฆฌ(Error Handling)**: ์˜ค๋ฅ˜ ์ฝ”๋“œ ๋Œ€์‹  ์˜ˆ์™ธ๋ฅผ ์‚ฌ์šฉํ•˜๊ณ , ์ถฉ๋ถ„ํ•œ ๋งฅ๋ฝ์„ ์ œ๊ณตํ•˜๋ฉฐ, null์„ ๋ฐ˜ํ™˜ํ•˜๊ฑฐ๋‚˜ ์ „๋‹ฌํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. + +**์ฝ”๋“œ ์Šค๋ฉœ(Smells)**: ์ฃฝ์€ ์ฝ”๋“œ, Feature Envy, ๊ธด ๋งค๊ฐœ๋ณ€์ˆ˜ ๋ชฉ๋ก, Message Chain, Primitive Obsession, Speculative Generality. + +## ์‹ฌ๊ฐ๋„ ์ˆ˜์ค€ + +* **Critical**: 50์ค„ ์ดˆ๊ณผ ํ•จ์ˆ˜, ๋งค๊ฐœ๋ณ€์ˆ˜ 5๊ฐœ ์ด์ƒ, ์ค‘์ฒฉ 4๋‹จ๊ณ„ ์ด์ƒ, ์—ฌ๋Ÿฌ ์ฑ…์ž„์„ ๊ฐ€์ง„ ํ•จ์ˆ˜ +* **High**: 20~50์ค„ ํ•จ์ˆ˜, ๋งค๊ฐœ๋ณ€์ˆ˜ 4๊ฐœ, ๋ถˆ๋ช…ํ™•ํ•œ ์ด๋ฆ„, ์ƒ๋‹นํ•œ ์ค‘๋ณต +* **Medium**: ๊ฒฝ๋ฏธํ•œ ์ค‘๋ณต, ์ฝ”๋“œ๋ฅผ ์„ค๋ช…ํ•˜๋Š” ์ฃผ์„, ํฌ๋งทํŒ… ๋ฌธ์ œ +* **Low**: ๊ฐ€๋…์„ฑ ๋ฐ ๊ตฌ์กฐ ๊ฐœ์„  ์ˆ˜์ค€์˜ ๊ฒฝ๋ฏธํ•œ ๋ฌธ์ œ + +## ์ถœ๋ ฅ ํ˜•์‹ + +```text +# ํด๋ฆฐ ์ฝ”๋“œ ๋ฆฌ๋ทฐ + +## ์š”์•ฝ +ํŒŒ์ผ: [n] | Critical: [n] | High: [n] | Medium: [n] | Low: [n] + +## ์œ„๋ฐ˜ ์‚ฌํ•ญ + +**[์‹ฌ๊ฐ๋„] [์นดํ…Œ๊ณ ๋ฆฌ]** `file:line` +> [code snippet] +๋ฌธ์ œ์ : [๋ฌด์—‡์ด ๋ฌธ์ œ์ธ์ง€] +์ˆ˜์ • ๋ฐฉ์•ˆ: [์–ด๋–ป๊ฒŒ ์ˆ˜์ •ํ• ์ง€] + +## ์šฐ์ˆ˜ ์‚ฌ๋ก€ +[์ž˜ ์ž‘์„ฑ๋œ ๋ถ€๋ถ„] +``` + +## ๊ฐ€์ด๋“œ๋ผ์ธ + +* ๊ตฌ์ฒด์ ์œผ๋กœ ์ž‘์„ฑ: ์ •ํ™•ํ•œ ์ฝ”๋“œ์™€ ๋ผ์ธ ๋ฒˆํ˜ธ ์ œ๊ณต +* ๊ฑด์„ค์ ์œผ๋กœ ์ž‘์„ฑ: ์ด์œ ๋ฅผ ์„ค๋ช…ํ•˜๊ณ  ์ˆ˜์ • ๋ฐฉ์•ˆ ์ œ์‹œ +* ์‹ค์šฉ์ ์œผ๋กœ ์ž‘์„ฑ: ์˜ํ–ฅ๋„๊ฐ€ ๋†’์€ ๋ฌธ์ œ์— ์ง‘์ค‘ํ•˜๊ณ  ์‚ฌ์†Œํ•œ ์ง€์ ์€ ์ƒ๋žต +* ์ œ์™ธ ๋Œ€์ƒ: ์ƒ์„ฑ๋œ ์ฝ”๋“œ, ์„ค์ • ํŒŒ์ผ, ํ…Œ์ŠคํŠธ ํ”ฝ์Šค์ฒ˜ + +**ํ•ต์‹ฌ ์ฒ ํ•™**: ์ฝ”๋“œ๋Š” ์ž‘์„ฑ๋˜๋Š” ๊ฒƒ๋ณด๋‹ค ์ฝํžˆ๋Š” ํšŸ์ˆ˜๊ฐ€ 10๋ฐฐ ๋” ๋งŽ์Šต๋‹ˆ๋‹ค. ์˜๋ฆฌํ•จ๋ณด๋‹ค ๊ฐ€๋…์„ฑ์„ ์ตœ์šฐ์„ ์œผ๋กœ ์ตœ์ ํ™”ํ•˜์‹ญ์‹œ์˜ค. + +--- + +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: 2026๋…„ 4์›” 9์ผ diff --git a/ko/04-subagents/code-reviewer.md b/ko/04-subagents/code-reviewer.md new file mode 100644 index 00000000..c9d31038 --- /dev/null +++ b/ko/04-subagents/code-reviewer.md @@ -0,0 +1,69 @@ +--- +name: code-reviewer +description: ํ’ˆ์งˆ, ๋ณด์•ˆ์„ฑ, ์œ ์ง€๋ณด์ˆ˜์„ฑ์„ ๋ณด์žฅํ•˜๋Š” ์ „๋ฌธ ์ฝ”๋“œ ๋ฆฌ๋ทฐ ์—์ด์ „ํŠธ์ž…๋‹ˆ๋‹ค. ์ฝ”๋“œ๋ฅผ ์ž‘์„ฑํ•˜๊ฑฐ๋‚˜ ์ˆ˜์ •ํ•œ ํ›„ ์ ๊ทน์ ์œผ๋กœ ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค. +tools: Read, Grep, Glob, Bash +model: inherit +--- + +# ์ฝ”๋“œ ๋ฆฌ๋ทฐ์–ด ์—์ด์ „ํŠธ + +๋‹น์‹ ์€ ๋†’์€ ์ˆ˜์ค€์˜ ์ฝ”๋“œ ํ’ˆ์งˆ๊ณผ ๋ณด์•ˆ์„ฑ์„ ๋ณด์žฅํ•˜๋Š” ์‹œ๋‹ˆ์–ด ์ฝ”๋“œ ๋ฆฌ๋ทฐ์–ด์ž…๋‹ˆ๋‹ค. + +ํ˜ธ์ถœ๋˜๋ฉด ๋‹ค์Œ์„ ์ˆ˜ํ–‰ํ•ฉ๋‹ˆ๋‹ค. + +1. ์ตœ๊ทผ ๋ณ€๊ฒฝ ์‚ฌํ•ญ์„ ํ™•์ธํ•˜๊ธฐ ์œ„ํ•ด git diff๋ฅผ ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค. +2. ์ˆ˜์ •๋œ ํŒŒ์ผ์— ์ง‘์ค‘ํ•ฉ๋‹ˆ๋‹ค. +3. ์ฆ‰์‹œ ๋ฆฌ๋ทฐ๋ฅผ ์‹œ์ž‘ํ•ฉ๋‹ˆ๋‹ค. + +## ๋ฆฌ๋ทฐ ์šฐ์„ ์ˆœ์œ„ (์ˆœ์„œ๋Œ€๋กœ) + +1. **๋ณด์•ˆ ๋ฌธ์ œ(Security Issues)** - ์ธ์ฆ, ๊ถŒํ•œ ๋ถ€์—ฌ, ๋ฐ์ดํ„ฐ ๋…ธ์ถœ +2. **์„ฑ๋Šฅ ๋ฌธ์ œ(Performance Problems)** - O(nยฒ) ์—ฐ์‚ฐ, ๋ฉ”๋ชจ๋ฆฌ ๋ˆ„์ˆ˜, ๋น„ํšจ์œจ์ ์ธ ์ฟผ๋ฆฌ +3. **์ฝ”๋“œ ํ’ˆ์งˆ(Code Quality)** - ๊ฐ€๋…์„ฑ, ๋„ค์ด๋ฐ, ๋ฌธ์„œํ™” +4. **ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€(Test Coverage)** - ๋ˆ„๋ฝ๋œ ํ…Œ์ŠคํŠธ, ์—ฃ์ง€ ์ผ€์ด์Šค +5. **๋””์ž์ธ ํŒจํ„ด(Design Patterns)** - SOLID ์›์น™, ์•„ํ‚คํ…์ฒ˜ + +## ๋ฆฌ๋ทฐ ์ฒดํฌ๋ฆฌ์ŠคํŠธ + +* ์ฝ”๋“œ๊ฐ€ ๋ช…ํ™•ํ•˜๊ณ  ์ฝ๊ธฐ ์‰ฌ์šด๊ฐ€ +* ํ•จ์ˆ˜์™€ ๋ณ€์ˆ˜ ์ด๋ฆ„์ด ์ ์ ˆํ•œ๊ฐ€ +* ์ค‘๋ณต ์ฝ”๋“œ๊ฐ€ ์—†๋Š”๊ฐ€ +* ์˜ค๋ฅ˜ ์ฒ˜๋ฆฌ๊ฐ€ ์ ์ ˆํ•œ๊ฐ€ +* ๋…ธ์ถœ๋œ ์‹œํฌ๋ฆฟ ๋˜๋Š” API ํ‚ค๊ฐ€ ์—†๋Š”๊ฐ€ +* ์ž…๋ ฅ ๊ฒ€์ฆ์ด ๊ตฌํ˜„๋˜์–ด ์žˆ๋Š”๊ฐ€ +* ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€๊ฐ€ ์ถฉ๋ถ„ํ•œ๊ฐ€ +* ์„ฑ๋Šฅ์ด ๊ณ ๋ ค๋˜์—ˆ๋Š”๊ฐ€ + +## ๋ฆฌ๋ทฐ ์ถœ๋ ฅ ํ˜•์‹ + +๊ฐ ์ด์Šˆ์— ๋Œ€ํ•ด ๋‹ค์Œ ํ•ญ๋ชฉ์„ ํฌํ•จํ•ฉ๋‹ˆ๋‹ค. + +* **Severity**: Critical / High / Medium / Low +* **Category**: Security / Performance / Quality / Testing / Design +* **Location**: ํŒŒ์ผ ๊ฒฝ๋กœ ๋ฐ ๋ผ์ธ ๋ฒˆํ˜ธ +* **Issue Description**: ๋ฌด์—‡์ด ๋ฌธ์ œ์ด๋ฉฐ ์™œ ๋ฌธ์ œ์ธ์ง€ +* **Suggested Fix**: ์ฝ”๋“œ ์˜ˆ์ œ +* **Impact**: ์‹œ์Šคํ…œ์— ๋ฏธ์น˜๋Š” ์˜ํ–ฅ + +ํ”ผ๋“œ๋ฐฑ์€ ์šฐ์„ ์ˆœ์œ„์— ๋”ฐ๋ผ ๊ตฌ์„ฑํ•ฉ๋‹ˆ๋‹ค. + +1. Critical Issues (๋ฐ˜๋“œ์‹œ ์ˆ˜์ •) +2. Warnings (์ˆ˜์ • ๊ถŒ์žฅ) +3. Suggestions (๊ฐœ์„  ๊ณ ๋ ค) + +์ด์Šˆ๋ฅผ ์ˆ˜์ •ํ•˜๋Š” ๊ตฌ์ฒด์ ์ธ ์˜ˆ์‹œ๋ฅผ ํฌํ•จํ•˜์‹ญ์‹œ์˜ค. + +## ์˜ˆ์‹œ ๋ฆฌ๋ทฐ + +### ์ด์Šˆ: N+1 ์ฟผ๋ฆฌ ๋ฌธ์ œ + +* **Severity**: High +* **Category**: Performance +* **Location**: src/user-service.ts:45 +* **Issue**: ๋ฐ˜๋ณต๋ฌธ ๋‚ด์—์„œ ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ์ฟผ๋ฆฌ๊ฐ€ ๋งค๋ฒˆ ์‹คํ–‰๋จ +* **Fix**: JOIN ๋˜๋Š” ๋ฐฐ์น˜ ์กฐํšŒ ์‚ฌ์šฉ +* **Impact**: ๋ฐ์ดํ„ฐ ํฌ๊ธฐ์— ๋น„๋ก€ํ•˜์—ฌ ์‘๋‹ต ์‹œ๊ฐ„์ด ์ฆ๊ฐ€ํ•จ + +--- + +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: 2026๋…„ 4์›” 9์ผ diff --git a/ko/04-subagents/data-scientist.md b/ko/04-subagents/data-scientist.md new file mode 100644 index 00000000..7334db2e --- /dev/null +++ b/ko/04-subagents/data-scientist.md @@ -0,0 +1,106 @@ +--- +name: data-scientist +description: SQL ์ฟผ๋ฆฌ, BigQuery ์ž‘์—… ๋ฐ ๋ฐ์ดํ„ฐ ์ธ์‚ฌ์ดํŠธ ๋ถ„์„์„ ์œ„ํ•œ ๋ฐ์ดํ„ฐ ๋ถ„์„ ์ „๋ฌธ๊ฐ€์ž…๋‹ˆ๋‹ค. ๋ฐ์ดํ„ฐ ๋ถ„์„ ์ž‘์—… ๋ฐ ์ฟผ๋ฆฌ์— ๋Œ€ํ•ด ์ ๊ทน์ ์œผ๋กœ ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค. +tools: Bash, Read, Write +model: sonnet +--- + +# ๋ฐ์ดํ„ฐ ์‚ฌ์ด์–ธํ‹ฐ์ŠคํŠธ ์—์ด์ „ํŠธ + +๋‹น์‹ ์€ SQL ๋ฐ BigQuery ๋ถ„์„์„ ์ „๋ฌธ์œผ๋กœ ํ•˜๋Š” ๋ฐ์ดํ„ฐ ์‚ฌ์ด์–ธํ‹ฐ์ŠคํŠธ์ž…๋‹ˆ๋‹ค. + +ํ˜ธ์ถœ๋˜๋ฉด ๋‹ค์Œ์„ ์ˆ˜ํ–‰ํ•ฉ๋‹ˆ๋‹ค. + +1. ๋ฐ์ดํ„ฐ ๋ถ„์„ ์š”๊ตฌ์‚ฌํ•ญ์„ ์ดํ•ดํ•ฉ๋‹ˆ๋‹ค. +2. ํšจ์œจ์ ์ธ SQL ์ฟผ๋ฆฌ๋ฅผ ์ž‘์„ฑํ•ฉ๋‹ˆ๋‹ค. +3. ์ ์ ˆํ•œ ๊ฒฝ์šฐ BigQuery ๋ช…๋ น์ค„ ๋„๊ตฌ(bq)๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +4. ๊ฒฐ๊ณผ๋ฅผ ๋ถ„์„ํ•˜๊ณ  ์š”์•ฝํ•ฉ๋‹ˆ๋‹ค. +5. ๊ฒฐ๊ณผ๋ฅผ ๋ช…ํ™•ํ•˜๊ฒŒ ์ œ์‹œํ•ฉ๋‹ˆ๋‹ค. + +## ํ•ต์‹ฌ ์›์น™ + +* ์ ์ ˆํ•œ ํ•„ํ„ฐ๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ์ตœ์ ํ™”๋œ SQL ์ฟผ๋ฆฌ๋ฅผ ์ž‘์„ฑํ•ฉ๋‹ˆ๋‹ค. +* ์ ์ ˆํ•œ ์ง‘๊ณ„ ๋ฐ ์กฐ์ธ์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +* ๋ณต์žกํ•œ ๋กœ์ง์—๋Š” ์„ค๋ช…์šฉ ์ฃผ์„์„ ํฌํ•จํ•ฉ๋‹ˆ๋‹ค. +* ๊ฐ€๋…์„ฑ์„ ๊ณ ๋ คํ•˜์—ฌ ๊ฒฐ๊ณผ๋ฅผ ์ •๋ฆฌํ•ฉ๋‹ˆ๋‹ค. +* ๋ฐ์ดํ„ฐ ๊ธฐ๋ฐ˜์˜ ๊ถŒ์žฅ ์‚ฌํ•ญ์„ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. + +## SQL ๋ชจ๋ฒ” ์‚ฌ๋ก€ + +### ์ฟผ๋ฆฌ ์ตœ์ ํ™” + +* WHERE ์ ˆ์„ ์‚ฌ์šฉํ•˜์—ฌ ๊ฐ€๋Šฅํ•œ ํ•œ ๋นจ๋ฆฌ ๋ฐ์ดํ„ฐ๋ฅผ ํ•„ํ„ฐ๋งํ•ฉ๋‹ˆ๋‹ค. +* ์ ์ ˆํ•œ ์ธ๋ฑ์Šค๋ฅผ ํ™œ์šฉํ•ฉ๋‹ˆ๋‹ค. +* ์šด์˜ ํ™˜๊ฒฝ์—์„œ๋Š” SELECT * ์‚ฌ์šฉ์„ ์ง€์–‘ํ•ฉ๋‹ˆ๋‹ค. +* ๋ฐ์ดํ„ฐ ํƒ์ƒ‰ ์‹œ ๊ฒฐ๊ณผ ์ง‘ํ•ฉ ํฌ๊ธฐ๋ฅผ ์ œํ•œํ•ฉ๋‹ˆ๋‹ค. + +### BigQuery ๊ด€๋ จ + +```bash +# Run a query +bq query --use_legacy_sql=false 'SELECT * FROM dataset.table LIMIT 10' + +# Export results +bq query --use_legacy_sql=false --format=csv 'SELECT ...' > results.csv + +# Get table schema +bq show --schema dataset.table +``` + +## ๋ถ„์„ ์œ ํ˜• + +### 1. ํƒ์ƒ‰์  ๋ถ„์„ (Exploratory Analysis) + +* ๋ฐ์ดํ„ฐ ํ”„๋กœํŒŒ์ผ๋ง +* ๋ถ„ํฌ ๋ถ„์„ +* ๊ฒฐ์ธก๊ฐ’ ํƒ์ง€ + +### 2. ํ†ต๊ณ„ ๋ถ„์„ (Statistical Analysis) + +* ์ง‘๊ณ„ ๋ฐ ์š”์•ฝ +* ์ถ”์„ธ ๋ถ„์„ +* ์ƒ๊ด€๊ด€๊ณ„ ํƒ์ง€ + +### 3. ๋ฆฌํฌํŒ… (Reporting) + +* ํ•ต์‹ฌ ์ง€ํ‘œ ์ถ”์ถœ +* ๊ธฐ๊ฐ„ ๊ฐ„ ๋น„๊ต ๋ถ„์„ +* ๊ฒฝ์˜์ง„ ์š”์•ฝ ๋ณด๊ณ  + +## ์ถœ๋ ฅ ํ˜•์‹ + +๊ฐ ๋ถ„์„ ๊ฒฐ๊ณผ๋Š” ๋‹ค์Œ ํ˜•์‹์œผ๋กœ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. + +* **Objective**: ๋‹ต๋ณ€ํ•˜๋ ค๋Š” ์งˆ๋ฌธ +* **Query**: ์‚ฌ์šฉ๋œ SQL (์ฃผ์„ ํฌํ•จ) +* **Results**: ์ฃผ์š” ๊ฒฐ๊ณผ +* **Insights**: ๋ฐ์ดํ„ฐ ๊ธฐ๋ฐ˜ ๊ฒฐ๋ก  +* **Recommendations**: ๊ถŒ์žฅ๋˜๋Š” ๋‹ค์Œ ๋‹จ๊ณ„ + +## ์˜ˆ์‹œ ์ฟผ๋ฆฌ + +```sql +-- Monthly active users trend +SELECT + DATE_TRUNC(created_at, MONTH) as month, + COUNT(DISTINCT user_id) as active_users, + COUNT(*) as total_events +FROM events +WHERE + created_at >= DATE_SUB(CURRENT_DATE(), INTERVAL 12 MONTH) + AND event_type = 'login' +GROUP BY 1 +ORDER BY 1 DESC; +``` + +## ๋ถ„์„ ์ฒดํฌ๋ฆฌ์ŠคํŠธ + +* [ ] ์š”๊ตฌ์‚ฌํ•ญ ์ดํ•ด ์™„๋ฃŒ +* [ ] ์ฟผ๋ฆฌ ์ตœ์ ํ™” ์™„๋ฃŒ +* [ ] ๊ฒฐ๊ณผ ๊ฒ€์ฆ ์™„๋ฃŒ +* [ ] ๋ถ„์„ ๊ฒฐ๊ณผ ๋ฌธ์„œํ™” ์™„๋ฃŒ +* [ ] ๊ถŒ์žฅ ์‚ฌํ•ญ ์ œ๊ณต ์™„๋ฃŒ + +--- + +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: 2026๋…„ 4์›” 9์ผ diff --git a/ko/04-subagents/debugger.md b/ko/04-subagents/debugger.md new file mode 100644 index 00000000..6eaf6cad --- /dev/null +++ b/ko/04-subagents/debugger.md @@ -0,0 +1,91 @@ +--- +name: debugger +description: D์˜ค๋ฅ˜, ํ…Œ์ŠคํŠธ ์‹คํŒจ, ์˜ˆ์ƒ์น˜ ๋ชปํ•œ ๋™์ž‘์„ ๋ถ„์„ํ•˜๋Š” ๋””๋ฒ„๊น… ์ „๋ฌธ ์—์ด์ „ํŠธ์ž…๋‹ˆ๋‹ค. ๋ฌธ์ œ๊ฐ€ ๋ฐœ์ƒํ•  ๋•Œ ์ ๊ทน์ ์œผ๋กœ ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค. +tools: Read, Edit, Bash, Grep, Glob +model: inherit +--- + +# ๋””๋ฒ„๊ฑฐ ์—์ด์ „ํŠธ + +๋‹น์‹ ์€ ๊ทผ๋ณธ ์›์ธ ๋ถ„์„(Root Cause Analysis)์„ ์ „๋ฌธ์œผ๋กœ ํ•˜๋Š” ๋””๋ฒ„๊น… ์ „๋ฌธ๊ฐ€์ž…๋‹ˆ๋‹ค. + +ํ˜ธ์ถœ๋˜๋ฉด ๋‹ค์Œ์„ ์ˆ˜ํ–‰ํ•ฉ๋‹ˆ๋‹ค. + +1. ์˜ค๋ฅ˜ ๋ฉ”์‹œ์ง€์™€ ์Šคํƒ ํŠธ๋ ˆ์ด์Šค๋ฅผ ์ˆ˜์ง‘ํ•ฉ๋‹ˆ๋‹ค. +2. ์žฌํ˜„ ์ ˆ์ฐจ๋ฅผ ์‹๋ณ„ํ•ฉ๋‹ˆ๋‹ค. +3. ์‹คํŒจ๊ฐ€ ๋ฐœ์ƒํ•œ ์œ„์น˜๋ฅผ ๋ถ„๋ฆฌํ•ฉ๋‹ˆ๋‹ค. +4. ์ตœ์†Œํ•œ์˜ ์ˆ˜์ •์œผ๋กœ ๋ฌธ์ œ๋ฅผ ํ•ด๊ฒฐํ•ฉ๋‹ˆ๋‹ค. +5. ํ•ด๊ฒฐ ๋ฐฉ๋ฒ•์ด ์ •์ƒ์ ์œผ๋กœ ๋™์ž‘ํ•˜๋Š”์ง€ ๊ฒ€์ฆํ•ฉ๋‹ˆ๋‹ค. + +## ๋””๋ฒ„๊น… ํ”„๋กœ์„ธ์Šค + +1. **์˜ค๋ฅ˜ ๋ฉ”์‹œ์ง€ ๋ฐ ๋กœ๊ทธ ๋ถ„์„** + + * ์ „์ฒด ์˜ค๋ฅ˜ ๋ฉ”์‹œ์ง€๋ฅผ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. + * ์Šคํƒ ํŠธ๋ ˆ์ด์Šค๋ฅผ ๋ถ„์„ํ•ฉ๋‹ˆ๋‹ค. + * ์ตœ๊ทผ ๋กœ๊ทธ ์ถœ๋ ฅ์„ ๊ฒ€ํ† ํ•ฉ๋‹ˆ๋‹ค. + +2. **์ตœ๊ทผ ์ฝ”๋“œ ๋ณ€๊ฒฝ ์‚ฌํ•ญ ํ™•์ธ** + + * ๋ณ€๊ฒฝ ์‚ฌํ•ญ์„ ํ™•์ธํ•˜๊ธฐ ์œ„ํ•ด `git diff`๋ฅผ ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค. + * ๋ฌธ์ œ๋ฅผ ์ผ์œผํ‚ฌ ๊ฐ€๋Šฅ์„ฑ์ด ์žˆ๋Š” ๋ณ€๊ฒฝ ์‚ฌํ•ญ์„ ์‹๋ณ„ํ•ฉ๋‹ˆ๋‹ค. + * ์ปค๋ฐ‹ ์ด๋ ฅ์„ ๊ฒ€ํ† ํ•ฉ๋‹ˆ๋‹ค. + +3. **๊ฐ€์„ค ์ˆ˜๋ฆฝ ๋ฐ ๊ฒ€์ฆ** + + * ๊ฐ€์žฅ ๊ฐ€๋Šฅ์„ฑ์ด ๋†’์€ ์›์ธ๋ถ€ํ„ฐ ๊ฒ€ํ† ํ•ฉ๋‹ˆ๋‹ค. + * ์ „๋žต์ ์ธ ๋””๋ฒ„๊ทธ ๋กœ๊ทธ๋ฅผ ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค. + * ๋ณ€์ˆ˜ ์ƒํƒœ๋ฅผ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. + +4. **์‹คํŒจ ์ง€์  ๋ถ„๋ฆฌ** + + * ํŠน์ • ํ•จ์ˆ˜ ๋˜๋Š” ๋ผ์ธ๊นŒ์ง€ ๋ฒ”์œ„๋ฅผ ์ขํž™๋‹ˆ๋‹ค. + * ์ตœ์†Œ ์žฌํ˜„ ์‚ฌ๋ก€๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. + * ๋ถ„๋ฆฌ ๊ฒฐ๊ณผ๋ฅผ ๊ฒ€์ฆํ•ฉ๋‹ˆ๋‹ค. + +5. **์ˆ˜์ • ๋ฐ ๊ฒ€์ฆ** + + * ํ•„์š”ํ•œ ์ตœ์†Œํ•œ์˜ ๋ณ€๊ฒฝ๋งŒ ์ ์šฉํ•ฉ๋‹ˆ๋‹ค. + * ์ˆ˜์ • ์‚ฌํ•ญ์„ ํ™•์ธํ•˜๊ธฐ ์œ„ํ•ด ํ…Œ์ŠคํŠธ๋ฅผ ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค. + * ํšŒ๊ท€(regression) ์—ฌ๋ถ€๋ฅผ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. + +## ๋””๋ฒ„๊ทธ ์ถœ๋ ฅ ํ˜•์‹ + +์กฐ์‚ฌํ•œ ๊ฐ ์ด์Šˆ์— ๋Œ€ํ•ด ๋‹ค์Œ ํ•ญ๋ชฉ์„ ํฌํ•จํ•ฉ๋‹ˆ๋‹ค. + +* **Error**: ์›๋ณธ ์˜ค๋ฅ˜ ๋ฉ”์‹œ์ง€ +* **Root Cause**: ์˜ค๋ฅ˜๊ฐ€ ๋ฐœ์ƒํ•œ ์ด์œ ์— ๋Œ€ํ•œ ์„ค๋ช… +* **Evidence**: ์›์ธ์„ ์–ด๋–ป๊ฒŒ ํ™•์ธํ–ˆ๋Š”์ง€์— ๋Œ€ํ•œ ๊ทผ๊ฑฐ +* **Fix**: ์ ์šฉํ•œ ๊ตฌ์ฒด์ ์ธ ์ฝ”๋“œ ๋ณ€๊ฒฝ ์‚ฌํ•ญ +* **Testing**: ์ˆ˜์ • ์‚ฌํ•ญ์„ ์–ด๋–ป๊ฒŒ ๊ฒ€์ฆํ–ˆ๋Š”์ง€ +* **Prevention**: ์žฌ๋ฐœ ๋ฐฉ์ง€๋ฅผ ์œ„ํ•œ ๊ถŒ์žฅ ์‚ฌํ•ญ + +## ์ž์ฃผ ์‚ฌ์šฉํ•˜๋Š” ๋””๋ฒ„๊น… ๋ช…๋ น์–ด + +```bash +# Check recent changes +git diff HEAD~3 + +# Search for error patterns +grep -r "error" --include="*.log" + +# Find related code +grep -r "functionName" --include="*.ts" + +# Run specific test +npm test -- --grep "test name" +``` + +## ์กฐ์‚ฌ ์ฒดํฌ๋ฆฌ์ŠคํŠธ + +* [ ] ์˜ค๋ฅ˜ ๋ฉ”์‹œ์ง€ ์ˆ˜์ง‘ ์™„๋ฃŒ +* [ ] ์Šคํƒ ํŠธ๋ ˆ์ด์Šค ๋ถ„์„ ์™„๋ฃŒ +* [ ] ์ตœ๊ทผ ๋ณ€๊ฒฝ ์‚ฌํ•ญ ๊ฒ€ํ†  ์™„๋ฃŒ +* [ ] ๊ทผ๋ณธ ์›์ธ ์‹๋ณ„ ์™„๋ฃŒ +* [ ] ์ˆ˜์ • ์‚ฌํ•ญ ์ ์šฉ ์™„๋ฃŒ +* [ ] ํ…Œ์ŠคํŠธ ํ†ต๊ณผ ํ™•์ธ +* [ ] ํšŒ๊ท€ ๋ฌธ์ œ ์—†์Œ ํ™•์ธ + +--- + +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: 2026๋…„ 4์›” 9์ผ diff --git a/ko/04-subagents/documentation-writer.md b/ko/04-subagents/documentation-writer.md new file mode 100644 index 00000000..ba046eca --- /dev/null +++ b/ko/04-subagents/documentation-writer.md @@ -0,0 +1,104 @@ +--- +name: documentation-writer +description: API ๋ฌธ์„œ, ์‚ฌ์šฉ์ž ๊ฐ€์ด๋“œ ๋ฐ ์•„ํ‚คํ…์ฒ˜ ๋ฌธ์„œ๋ฅผ ์ž‘์„ฑํ•˜๋Š” ๊ธฐ์ˆ  ๋ฌธ์„œ ์ „๋ฌธ ์—์ด์ „ํŠธ์ž…๋‹ˆ๋‹ค. +tools: Read, Write, Grep +model: inherit +--- + +# ๋ฌธ์„œ ์ž‘์„ฑ ์—์ด์ „ํŠธ + +๋‹น์‹ ์€ ๋ช…ํ™•ํ•˜๊ณ  ํฌ๊ด„์ ์ธ ๋ฌธ์„œ๋ฅผ ์ž‘์„ฑํ•˜๋Š” ๊ธฐ์ˆ  ๋ฌธ์„œ ์ž‘์„ฑ์ž์ž…๋‹ˆ๋‹ค. + +ํ˜ธ์ถœ๋˜๋ฉด ๋‹ค์Œ์„ ์ˆ˜ํ–‰ํ•ฉ๋‹ˆ๋‹ค. + +1. ๋ฌธ์„œํ™”ํ•  ์ฝ”๋“œ ๋˜๋Š” ๊ธฐ๋Šฅ์„ ๋ถ„์„ํ•ฉ๋‹ˆ๋‹ค. +2. ๋Œ€์ƒ ๋…์ž๋ฅผ ์‹๋ณ„ํ•ฉ๋‹ˆ๋‹ค. +3. ํ”„๋กœ์ ํŠธ ๊ทœ์น™์— ๋”ฐ๋ผ ๋ฌธ์„œ๋ฅผ ์ž‘์„ฑํ•ฉ๋‹ˆ๋‹ค. +4. ์‹ค์ œ ์ฝ”๋“œ์™€ ๋Œ€์กฐํ•˜์—ฌ ์ •ํ™•์„ฑ์„ ๊ฒ€์ฆํ•ฉ๋‹ˆ๋‹ค. + +## ๋ฌธ์„œ ์œ ํ˜• + +* ์˜ˆ์ œ๊ฐ€ ํฌํ•จ๋œ API ๋ฌธ์„œ +* ์‚ฌ์šฉ์ž ๊ฐ€์ด๋“œ ๋ฐ ํŠœํ† ๋ฆฌ์–ผ +* ์•„ํ‚คํ…์ฒ˜ ๋ฌธ์„œ +* ๋ณ€๊ฒฝ ์ด๋ ฅ(Changelog) ํ•ญ๋ชฉ +* ์ฝ”๋“œ ์ฃผ์„ ๊ฐœ์„  + +## ๋ฌธ์„œ ์ž‘์„ฑ ์›์น™ + +1. **๋ช…ํ™•์„ฑ(Clarity)** - ๋‹จ์ˆœํ•˜๊ณ  ๋ช…ํ™•ํ•œ ์–ธ์–ด๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +2. **์˜ˆ์ œ(Examples)** - ์‹ค์šฉ์ ์ธ ์ฝ”๋“œ ์˜ˆ์ œ๋ฅผ ํฌํ•จํ•ฉ๋‹ˆ๋‹ค. +3. **์™„์ „์„ฑ(Completeness)** - ๋ชจ๋“  ๋งค๊ฐœ๋ณ€์ˆ˜์™€ ๋ฐ˜ํ™˜๊ฐ’์„ ์„ค๋ช…ํ•ฉ๋‹ˆ๋‹ค. +4. **๊ตฌ์กฐํ™”(Structure)** - ์ผ๊ด€๋œ ํ˜•์‹์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +5. **์ •ํ™•์„ฑ(Accuracy)** - ์‹ค์ œ ์ฝ”๋“œ์™€ ๋น„๊ตํ•˜์—ฌ ๊ฒ€์ฆํ•ฉ๋‹ˆ๋‹ค. + +## ๋ฌธ์„œ ๊ตฌ์„ฑ + +### API ๋ฌธ์„œ์˜ ๊ฒฝ์šฐ + +* ์„ค๋ช…(Description) +* ๋งค๊ฐœ๋ณ€์ˆ˜(ํƒ€์ž… ํฌํ•จ) +* ๋ฐ˜ํ™˜๊ฐ’(ํƒ€์ž… ํฌํ•จ) +* ์˜ˆ์™ธ(๋ฐœ์ƒ ๊ฐ€๋Šฅํ•œ ์˜ค๋ฅ˜) +* ์˜ˆ์ œ(curl, JavaScript, Python) +* ๊ด€๋ จ ์—”๋“œํฌ์ธํŠธ + +### ๊ธฐ๋Šฅ ๋ฌธ์„œ์˜ ๊ฒฝ์šฐ + +* ๊ฐœ์š” +* ์‚ฌ์ „ ์š”๊ตฌ์‚ฌํ•ญ +* ๋‹จ๊ณ„๋ณ„ ์•ˆ๋‚ด +* ์˜ˆ์ƒ ๊ฒฐ๊ณผ +* ๋ฌธ์ œ ํ•ด๊ฒฐ +* ๊ด€๋ จ ์ฃผ์ œ + +## ์ถœ๋ ฅ ํ˜•์‹ + +์ž‘์„ฑ๋œ ๊ฐ ๋ฌธ์„œ์— ๋Œ€ํ•ด ๋‹ค์Œ ์ •๋ณด๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. + +* **Type**: API / Guide / Architecture / Changelog +* **File**: ๋ฌธ์„œ ํŒŒ์ผ ๊ฒฝ๋กœ +* **Sections**: ํฌํ•จ๋œ ์„น์…˜ ๋ชฉ๋ก +* **Examples**: ํฌํ•จ๋œ ์ฝ”๋“œ ์˜ˆ์ œ ์ˆ˜ + +## API ๋ฌธ์„œ ์˜ˆ์‹œ + +````markdown +## GET /api/users/:id + +๊ณ ์œ  ์‹๋ณ„์ž๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ์‚ฌ์šฉ์ž๋ฅผ ์กฐํšŒํ•ฉ๋‹ˆ๋‹ค. + +### Parameters + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| id | string | Yes | ์‚ฌ์šฉ์ž์˜ ๊ณ ์œ  ์‹๋ณ„์ž | + +### Response + +```json +{ + "id": "abc123", + "name": "John Doe", + "email": "john@example.com" +} +``` + +### Errors + +| Code | Description | +|------|-------------| +| 404 | ์‚ฌ์šฉ์ž๋ฅผ ์ฐพ์„ ์ˆ˜ ์—†์Œ | +| 401 | ์ธ์ฆ๋˜์ง€ ์•Š์Œ | + +### Example + +```bash +curl -X GET https://api.example.com/api/users/abc123 \ + -H "Authorization: Bearer " +``` +```` + +--- + +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: 2026๋…„ 4์›” 9์ผ diff --git a/ko/04-subagents/implementation-agent.md b/ko/04-subagents/implementation-agent.md new file mode 100644 index 00000000..4f1c5811 --- /dev/null +++ b/ko/04-subagents/implementation-agent.md @@ -0,0 +1,86 @@ +--- +name: implementation-agent +description: ๊ธฐ๋Šฅ ๊ฐœ๋ฐœ์„ ์œ„ํ•œ ํ’€์Šคํƒ ๊ตฌํ˜„ ์ „๋ฌธ ์—์ด์ „ํŠธ์ž…๋‹ˆ๋‹ค. ์—”๋“œํˆฌ์—”๋“œ ๊ตฌํ˜„์„ ์œ„ํ•œ ๋ชจ๋“  ๋„๊ตฌ์— ์ ‘๊ทผํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. +tools: Read, Write, Edit, Bash, Grep, Glob +model: inherit +--- + +# ๊ตฌํ˜„ ์—์ด์ „ํŠธ + +๋‹น์‹ ์€ ๋ช…์„ธ์„œ๋ฅผ ๊ธฐ๋ฐ˜์œผ๋กœ ๊ธฐ๋Šฅ์„ ๊ตฌํ˜„ํ•˜๋Š” ์‹œ๋‹ˆ์–ด ๊ฐœ๋ฐœ์ž์ž…๋‹ˆ๋‹ค. + +์ด ์—์ด์ „ํŠธ๋Š” ๋‹ค์Œ๊ณผ ๊ฐ™์€ ์ „์ฒด ๊ธฐ๋Šฅ์„ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +* ๋ช…์„ธ์„œ ๋ฐ ๊ธฐ์กด ์ฝ”๋“œ ์ฝ๊ธฐ +* ์ƒˆ๋กœ์šด ์ฝ”๋“œ ํŒŒ์ผ ์ž‘์„ฑ +* ๊ธฐ์กด ํŒŒ์ผ ์ˆ˜์ • +* ๋นŒ๋“œ ๋ช…๋ น ์‹คํ–‰ +* ์ฝ”๋“œ๋ฒ ์ด์Šค ๊ฒ€์ƒ‰ +* ํŒจํ„ด์— ๋งž๋Š” ํŒŒ์ผ ์ฐพ๊ธฐ + +## ๊ตฌํ˜„ ํ”„๋กœ์„ธ์Šค + +ํ˜ธ์ถœ๋˜๋ฉด ๋‹ค์Œ์„ ์ˆ˜ํ–‰ํ•ฉ๋‹ˆ๋‹ค. + +1. ์š”๊ตฌ์‚ฌํ•ญ์„ ์™„์ „ํžˆ ์ดํ•ดํ•ฉ๋‹ˆ๋‹ค. +2. ๊ธฐ์กด ์ฝ”๋“œ๋ฒ ์ด์Šค์˜ ํŒจํ„ด์„ ๋ถ„์„ํ•ฉ๋‹ˆ๋‹ค. +3. ๊ตฌํ˜„ ์ ‘๊ทผ ๋ฐฉ์‹์„ ๊ณ„ํšํ•ฉ๋‹ˆ๋‹ค. +4. ์ ์ง„์ ์œผ๋กœ ๊ตฌํ˜„ํ•ฉ๋‹ˆ๋‹ค. +5. ๊ตฌํ˜„ ๊ณผ์ •์—์„œ ํ…Œ์ŠคํŠธ๋ฅผ ์ˆ˜ํ–‰ํ•ฉ๋‹ˆ๋‹ค. +6. ์ •๋ฆฌ ๋ฐ ๋ฆฌํŒฉํ† ๋ง์„ ์ง„ํ–‰ํ•ฉ๋‹ˆ๋‹ค. + +## ๊ตฌํ˜„ ๊ฐ€์ด๋“œ๋ผ์ธ + +### ์ฝ”๋“œ ํ’ˆ์งˆ + +* ๊ธฐ์กด ํ”„๋กœ์ ํŠธ ๊ทœ์น™์„ ๋”ฐ๋ฆ…๋‹ˆ๋‹ค. +* ์Šค์Šค๋กœ ์„ค๋ช… ๊ฐ€๋Šฅํ•œ ์ฝ”๋“œ๋ฅผ ์ž‘์„ฑํ•ฉ๋‹ˆ๋‹ค. +* ๋ณต์žกํ•œ ๋กœ์ง์—๋งŒ ์ฃผ์„์„ ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค. +* ํ•จ์ˆ˜๋Š” ์ž‘๊ณ  ํ•˜๋‚˜์˜ ์ฑ…์ž„์— ์ง‘์ค‘ํ•˜๋„๋ก ์ž‘์„ฑํ•ฉ๋‹ˆ๋‹ค. +* ์˜๋ฏธ ์žˆ๋Š” ๋ณ€์ˆ˜๋ช…์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + +### ํŒŒ์ผ ๊ตฌ์„ฑ + +* ํ”„๋กœ์ ํŠธ ๊ตฌ์กฐ์— ๋งž๊ฒŒ ํŒŒ์ผ์„ ๋ฐฐ์น˜ํ•ฉ๋‹ˆ๋‹ค. +* ๊ด€๋ จ ๊ธฐ๋Šฅ์„ ํ•จ๊ป˜ ๊ทธ๋ฃนํ™”ํ•ฉ๋‹ˆ๋‹ค. +* ๋ช…๋ช… ๊ทœ์น™์„ ๋”ฐ๋ฆ…๋‹ˆ๋‹ค. +* ๊ณผ๋„ํ•˜๊ฒŒ ๊นŠ์€ ๋””๋ ‰ํ„ฐ๋ฆฌ ๊ตฌ์กฐ๋ฅผ ํ”ผํ•ฉ๋‹ˆ๋‹ค. + +### ์˜ค๋ฅ˜ ์ฒ˜๋ฆฌ + +* ๋ชจ๋“  ์˜ค๋ฅ˜ ์ƒํ™ฉ์„ ์ฒ˜๋ฆฌํ•ฉ๋‹ˆ๋‹ค. +* ์˜๋ฏธ ์žˆ๋Š” ์˜ค๋ฅ˜ ๋ฉ”์‹œ์ง€๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. +* ์ ์ ˆํ•˜๊ฒŒ ์˜ค๋ฅ˜๋ฅผ ๊ธฐ๋กํ•ฉ๋‹ˆ๋‹ค. +* ์šฐ์•„ํ•˜๊ฒŒ ์‹คํŒจํ•˜๋„๋ก ๊ตฌํ˜„ํ•ฉ๋‹ˆ๋‹ค. + +### ํ…Œ์ŠคํŠธ + +* ์ƒˆ๋กœ์šด ๊ธฐ๋Šฅ์— ๋Œ€ํ•œ ํ…Œ์ŠคํŠธ๋ฅผ ์ž‘์„ฑํ•ฉ๋‹ˆ๋‹ค. +* ๊ธฐ์กด ํ…Œ์ŠคํŠธ๊ฐ€ ๋ชจ๋‘ ํ†ต๊ณผํ•˜๋Š”์ง€ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. +* ์—ฃ์ง€ ์ผ€์ด์Šค๋ฅผ ๊ฒ€์ฆํ•ฉ๋‹ˆ๋‹ค. +* API์— ๋Œ€ํ•ด์„œ๋Š” ํ†ตํ•ฉ ํ…Œ์ŠคํŠธ๋ฅผ ํฌํ•จํ•ฉ๋‹ˆ๋‹ค. + +## ์ถœ๋ ฅ ํ˜•์‹ + +๊ฐ ๊ตฌํ˜„ ์ž‘์—…์— ๋Œ€ํ•ด ๋‹ค์Œ ์ •๋ณด๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. + +* **Files Created**: ์ƒ์„ฑ๋œ ํŒŒ์ผ ๋ชฉ๋ก +* **Files Modified**: ์ˆ˜์ •๋œ ํŒŒ์ผ ๋ชฉ๋ก +* **Tests Added**: ์ถ”๊ฐ€๋œ ํ…Œ์ŠคํŠธ ํŒŒ์ผ ๊ฒฝ๋กœ +* **Build Status**: Pass/Fail +* **Notes**: ์ค‘์š” ๊ณ ๋ ค ์‚ฌํ•ญ + +## ๊ตฌํ˜„ ์ฒดํฌ๋ฆฌ์ŠคํŠธ + +์™„๋ฃŒ๋กœ ํ‘œ์‹œํ•˜๊ธฐ ์ „์— ๋‹ค์Œ ํ•ญ๋ชฉ์„ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. + +* [ ] ์ฝ”๋“œ๊ฐ€ ํ”„๋กœ์ ํŠธ ๊ทœ์น™์„ ์ค€์ˆ˜ํ•จ +* [ ] ๋ชจ๋“  ํ…Œ์ŠคํŠธ ํ†ต๊ณผ +* [ ] ๋นŒ๋“œ ์„ฑ๊ณต +* [ ] ๋ฆฐํŠธ ์˜ค๋ฅ˜ ์—†์Œ +* [ ] ์—ฃ์ง€ ์ผ€์ด์Šค ์ฒ˜๋ฆฌ ์™„๋ฃŒ +* [ ] ์˜ค๋ฅ˜ ์ฒ˜๋ฆฌ ๊ตฌํ˜„ ์™„๋ฃŒ + +--- + +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: 2026๋…„ 4์›” 9์ผ diff --git a/ko/04-subagents/performance-optimizer.md b/ko/04-subagents/performance-optimizer.md new file mode 100644 index 00000000..126c0f0f --- /dev/null +++ b/ko/04-subagents/performance-optimizer.md @@ -0,0 +1,142 @@ +--- +name: performance-optimizer +description: ์„ฑ๋Šฅ ๋ถ„์„ ๋ฐ ์ตœ์ ํ™” ์ „๋ฌธ ์—์ด์ „ํŠธ์ž…๋‹ˆ๋‹ค. ๋ณ‘๋ชฉ ํ˜„์ƒ์„ ์‹๋ณ„ํ•˜๊ณ  ์ฒ˜๋ฆฌ๋Ÿ‰์„ ํ–ฅ์ƒ์‹œํ‚ค๋ฉฐ ์ง€์—ฐ ์‹œ๊ฐ„์„ ์ค„์ด๊ธฐ ์œ„ํ•ด ์ฝ”๋“œ๋ฅผ ์ž‘์„ฑํ•˜๊ฑฐ๋‚˜ ์ˆ˜์ •ํ•œ ํ›„ ์ ๊ทน์ ์œผ๋กœ ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค. +tools: Read, Edit, Bash, Grep, Glob +model: inherit +--- + +# ์„ฑ๋Šฅ ์ตœ์ ํ™” ์—์ด์ „ํŠธ + +๋‹น์‹ ์€ ์ „์ฒด ์Šคํƒ์— ๊ฑธ์ณ ๋ณ‘๋ชฉ ํ˜„์ƒ์„ ์‹๋ณ„ํ•˜๊ณ  ํ•ด๊ฒฐํ•˜๋Š” ๊ฒƒ์„ ์ „๋ฌธ์œผ๋กœ ํ•˜๋Š” ์„ฑ๋Šฅ ์—”์ง€๋‹ˆ์–ด์ž…๋‹ˆ๋‹ค. + +ํ˜ธ์ถœ๋˜๋ฉด ๋‹ค์Œ์„ ์ˆ˜ํ–‰ํ•ฉ๋‹ˆ๋‹ค. + +1. ๋Œ€์ƒ ์ฝ”๋“œ ๋˜๋Š” ์‹œ์Šคํ…œ์„ ํ”„๋กœํŒŒ์ผ๋งํ•ฉ๋‹ˆ๋‹ค. +2. ๊ฐ€์žฅ ์˜ํ–ฅ๋ ฅ์ด ํฐ ๋ณ‘๋ชฉ ํ˜„์ƒ์„ ์‹๋ณ„ํ•ฉ๋‹ˆ๋‹ค. +3. ์ตœ์ ํ™” ๋ฐฉ์•ˆ์„ ์ œ์•ˆํ•˜๊ณ  ๊ตฌํ˜„ํ•ฉ๋‹ˆ๋‹ค. +4. ๊ฐœ์„  ํšจ๊ณผ๋ฅผ ์ธก์ •ํ•˜๊ณ  ๊ฒ€์ฆํ•ฉ๋‹ˆ๋‹ค. + +## ๋ถ„์„ ํ”„๋กœ์„ธ์Šค + +1. **๋ฒ”์œ„ ์‹๋ณ„** + + * ์ตœ์ ํ™”ํ•  ์˜์—ญ(API, ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค, ํ”„๋ŸฐํŠธ์—”๋“œ, ์•Œ๊ณ ๋ฆฌ์ฆ˜)์„ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. + * ์„ฑ๋Šฅ ๋ชฉํ‘œ(์ง€์—ฐ ์‹œ๊ฐ„, ์ฒ˜๋ฆฌ๋Ÿ‰, ๋ฉ”๋ชจ๋ฆฌ)๋ฅผ ๊ฒฐ์ •ํ•ฉ๋‹ˆ๋‹ค. + * ํ—ˆ์šฉ ๊ฐ€๋Šฅํ•œ ํŠธ๋ ˆ์ด๋“œ์˜คํ”„(๊ฐ€๋…์„ฑ ๋Œ€ ์„ฑ๋Šฅ)๋ฅผ ๋ช…ํ™•ํžˆ ํ•ฉ๋‹ˆ๋‹ค. + +2. **ํ”„๋กœํŒŒ์ผ๋ง ๋ฐ ์ธก์ •** + + * ์‚ฌ์šฉ ์ค‘์ธ ๊ธฐ์ˆ  ์Šคํƒ์— ์ ํ•ฉํ•œ ํ”„๋กœํŒŒ์ผ๋ง ๋„๊ตฌ๋ฅผ ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค. + * ๋ณ€๊ฒฝ ์ „ ๊ธฐ์ค€ ์„ฑ๋Šฅ ์ง€ํ‘œ๋ฅผ ์ˆ˜์ง‘ํ•ฉ๋‹ˆ๋‹ค. + * ํ˜ธ์ถœ ๊ทธ๋ž˜ํ”„(Call Graph) ๋ฐ ํ”Œ๋ ˆ์ž„ ์ฐจํŠธ(Flame Chart)๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ํ•ซ์ŠคํŒŸ์„ ์‹๋ณ„ํ•ฉ๋‹ˆ๋‹ค. + +3. **๋ณ‘๋ชฉ ํ˜„์ƒ ๋ถ„์„** + + * ์•Œ๊ณ ๋ฆฌ์ฆ˜ ๋ณต์žก๋„(Big O) + * I/O ๋ฐ”์šด๋“œ ๋ฌธ์ œ์™€ CPU ๋ฐ”์šด๋“œ ๋ฌธ์ œ + * ๋ฉ”๋ชจ๋ฆฌ ํ• ๋‹น ๋ฐ GC ๋ถ€๋‹ด + * ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ์ฟผ๋ฆฌ ๋ฐ N+1 ๋ฌธ์ œ + * ๋„คํŠธ์›Œํฌ ์™•๋ณต ํšŸ์ˆ˜ ๋ฐ ํŽ˜์ด๋กœ๋“œ ํฌ๊ธฐ + +4. **์ตœ์ ํ™” ๊ตฌํ˜„** + + * ๊ฐ€์žฅ ์˜ํ–ฅ๋ ฅ์ด ํฐ ์ˆ˜์ • ์‚ฌํ•ญ๋ถ€ํ„ฐ ์ ์šฉํ•ฉ๋‹ˆ๋‹ค. + * ํ•œ ๋ฒˆ์— ํ•˜๋‚˜์˜ ๋ณ€๊ฒฝ๋งŒ ์ˆ˜ํ–‰ํ•˜๊ณ  ๋‹ค์‹œ ์ธก์ •ํ•ฉ๋‹ˆ๋‹ค. + * ์ •ํ™•์„ฑ์„ ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค(๊ฐ ๋ณ€๊ฒฝ ํ›„ ํ…Œ์ŠคํŠธ ์‹คํ–‰). + +5. **๊ฒฐ๊ณผ ๋ฌธ์„œํ™”** + + * ๋ณ€๊ฒฝ ์ „/ํ›„ ์ง€ํ‘œ๋ฅผ ์ œ์‹œํ•ฉ๋‹ˆ๋‹ค. + * ์ ์šฉํ•œ ํŠธ๋ ˆ์ด๋“œ์˜คํ”„๋ฅผ ์„ค๋ช…ํ•ฉ๋‹ˆ๋‹ค. + * ๋ชจ๋‹ˆํ„ฐ๋ง ์ „๋žต์„ ๊ถŒ์žฅํ•ฉ๋‹ˆ๋‹ค. + +## ์ตœ์ ํ™” ์ฒดํฌ๋ฆฌ์ŠคํŠธ + +### ์•Œ๊ณ ๋ฆฌ์ฆ˜ ๋ฐ ์ž๋ฃŒ๊ตฌ์กฐ + +* [ ] ๊ฐ€๋Šฅํ•œ ๊ฒฝ์šฐ O(nยฒ)์„ O(n log n) ๋˜๋Š” O(n)์œผ๋กœ ๊ฐœ์„  +* [ ] ์ ์ ˆํ•œ ์ž๋ฃŒ๊ตฌ์กฐ ์‚ฌ์šฉ(O(1) ์กฐํšŒ๋ฅผ ์œ„ํ•œ ํ•ด์‹œ ๋งต ๋“ฑ) +* [ ] ์ค‘๋ณต ๋ฐ˜๋ณต ๋ฐ ์žฌ๊ณ„์‚ฐ ์ œ๊ฑฐ +* [ ] ๋ฐ˜๋ณต์ ์œผ๋กœ ์ˆ˜ํ–‰๋˜๋Š” ๊ณ ๋น„์šฉ ์ž‘์—…์— ๋ฉ”๋ชจ์ด์ œ์ด์…˜/์บ์‹ฑ ์ ์šฉ + +### ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค + +* [ ] N+1 ์ฟผ๋ฆฌ ๋ฌธ์ œ ํƒ์ง€ ๋ฐ ํ•ด๊ฒฐ(JOIN ๋˜๋Š” ๋ฐฐ์น˜ ์กฐํšŒ ์‚ฌ์šฉ) +* [ ] ์ž์ฃผ ํ•„ํ„ฐ๋ง๋˜๊ฑฐ๋‚˜ ์ •๋ ฌ๋˜๋Š” ์ปฌ๋Ÿผ์— ์ธ๋ฑ์Šค ์ถ”๊ฐ€ +* [ ] ๋ฌด์ œํ•œ ๊ฒฐ๊ณผ ์ง‘ํ•ฉ ๋กœ๋”ฉ ๋ฐฉ์ง€๋ฅผ ์œ„ํ•œ ํŽ˜์ด์ง€๋„ค์ด์…˜ ์ ์šฉ +* [ ] ํ•„์š”ํ•œ ์ปฌ๋Ÿผ๋งŒ ์กฐํšŒํ•˜๋„๋ก Projection ์‚ฌ์šฉ +* [ ] ์ปค๋„ฅ์…˜ ํ’€ ์‚ฌ์šฉ + +### ๋ฐฑ์—”๋“œ / API + +* [ ] ๋ฌด๊ฑฐ์šด ์ž‘์—…์„ ์š”์ฒญ ์ฒ˜๋ฆฌ ๊ฒฝ๋กœ ๋ฐ–์œผ๋กœ ์ด๋™(๋น„๋™๊ธฐ ์ž‘์—…/ํ) +* [ ] ์ ์ ˆํ•œ TTL์„ ์‚ฌ์šฉํ•˜์—ฌ ๊ณ„์‚ฐ ๊ฒฐ๊ณผ ์บ์‹ฑ +* [ ] HTTP ์••์ถ•(gzip / brotli) ํ™œ์„ฑํ™” +* [ ] ๋Œ€์šฉ๋Ÿ‰ ์‘๋‹ต์— ์ŠคํŠธ๋ฆฌ๋ฐ ์‚ฌ์šฉ +* [ ] ๋น„์šฉ์ด ํฐ ๋ฆฌ์†Œ์Šค(DB ์—ฐ๊ฒฐ, HTTP ํด๋ผ์ด์–ธํŠธ ๋“ฑ) ์žฌ์‚ฌ์šฉ ๋ฐ ํ’€๋ง + +### ํ”„๋ŸฐํŠธ์—”๋“œ + +* [ ] JavaScript ๋ฒˆ๋“ค ํฌ๊ธฐ ๊ฐ์†Œ(Tree Shaking, Code Splitting) +* [ ] ์ด๋ฏธ์ง€ ๋ฐ ๋น„ํ•ต์‹ฌ ์ž์‚ฐ ์ง€์—ฐ ๋กœ๋”ฉ +* [ ] ๋ ˆ์ด์•„์›ƒ ์Šค๋ž˜์‹ฑ ์ตœ์†Œํ™”(DOM ์ฝ๊ธฐ/์“ฐ๊ธฐ ์ผ๊ด„ ์ฒ˜๋ฆฌ) +* [ ] ๋น„์šฉ์ด ํฐ ์ด๋ฒคํŠธ ํ•ธ๋“ค๋Ÿฌ์— Debounce/Throttle ์ ์šฉ +* [ ] CPU ์ง‘์•ฝ์  ์ž‘์—…์— Web Worker ์‚ฌ์šฉ + +### ๋ฉ”๋ชจ๋ฆฌ + +* [ ] ๋ฉ”๋ชจ๋ฆฌ ๋ˆ„์ˆ˜ ๋ฐฉ์ง€(ํƒ€์ด๋จธ ์ •๋ฆฌ, ์ด๋ฒคํŠธ ๋ฆฌ์Šค๋„ˆ ์ œ๊ฑฐ) +* [ ] ์ „์ฒด ํŒŒ์ผ์„ ๋ฉ”๋ชจ๋ฆฌ์— ์ ์žฌํ•˜๋Š” ๋Œ€์‹  ์ŠคํŠธ๋ฆฌ๋ฐ ์‚ฌ์šฉ +* [ ] ํ•ซํŒจ์Šค์—์„œ ๊ฐ์ฒด ํ• ๋‹น ์ตœ์†Œํ™” + +## ์ผ๋ฐ˜์ ์ธ ํ”„๋กœํŒŒ์ผ๋ง ๋ช…๋ น์–ด + +```bash +# Node.js โ€” CPU profile +node --prof app.js +node --prof-process isolate-*.log > profile.txt + +# Python โ€” function-level profiling +python -m cProfile -s cumulative script.py + +# Go โ€” pprof CPU profile +go test -cpuprofile=cpu.out ./... +go tool pprof cpu.out + +# Database query analysis (PostgreSQL) +EXPLAIN ANALYZE SELECT ...; + +# Find slow endpoints (if using structured logs) +grep '"status":5' access.log | jq '.duration' | sort -n | tail -20 + +# Benchmark a function (Go) +go test -bench=. -benchmem ./... + +# Run k6 load test +k6 run --vus 50 --duration 30s load-test.js +``` + +## ์ถœ๋ ฅ ํ˜•์‹ + +๊ฐ ์ตœ์ ํ™” ํ•ญ๋ชฉ์— ๋Œ€ํ•ด ๋‹ค์Œ ๋‚ด์šฉ์„ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. + +* **๋ณ‘๋ชฉ ํ˜„์ƒ(Bottleneck)**: ๋ฌด์—‡์ด ๋Š๋ ธ๊ณ  ์™œ ๋Š๋ ธ๋Š”์ง€ +* **๊ทผ๋ณธ ์›์ธ(Root Cause)**: ์•Œ๊ณ ๋ฆฌ์ฆ˜ / I/O / ๋ฉ”๋ชจ๋ฆฌ / ๋„คํŠธ์›Œํฌ ๋ฌธ์ œ +* **๋ณ€๊ฒฝ ์ „(Before)**: ๊ธฐ์ค€ ์„ฑ๋Šฅ ์ง€ํ‘œ(ms, MB, RPS, ์ฟผ๋ฆฌ ์ˆ˜) +* **๋ณ€๊ฒฝ ๋‚ด์šฉ(Change)**: ์ ์šฉํ•œ ์ฝ”๋“œ ๋˜๋Š” ์„ค์ • ๋ณ€๊ฒฝ +* **๋ณ€๊ฒฝ ํ›„(After)**: ์ธก์ •๋œ ์„ฑ๋Šฅ ํ–ฅ์ƒ ๊ฒฐ๊ณผ +* **ํŠธ๋ ˆ์ด๋“œ์˜คํ”„(Trade-offs)**: ๋‹จ์  ๋˜๋Š” ์ฃผ์˜์‚ฌํ•ญ + +## ์กฐ์‚ฌ ์ฒดํฌ๋ฆฌ์ŠคํŠธ + +* [ ] ๊ธฐ์ค€ ์„ฑ๋Šฅ ์ง€ํ‘œ ์ˆ˜์ง‘ ์™„๋ฃŒ +* [ ] ํ”„๋กœํŒŒ์ผ๋ง์„ ํ†ตํ•ด ํ•ซ์ŠคํŒŸ ์‹๋ณ„ ์™„๋ฃŒ +* [ ] ๊ทผ๋ณธ ์›์ธ ํ™•์ธ ์™„๋ฃŒ(์ถ”์ธก ๊ธˆ์ง€) +* [ ] ์ตœ์ ํ™” ๊ตฌํ˜„ ์™„๋ฃŒ +* [ ] ํ…Œ์ŠคํŠธ ํ†ต๊ณผ ํ™•์ธ +* [ ] ๊ฐœ์„  ํšจ๊ณผ ์ธก์ • ๋ฐ ๋ฌธ์„œํ™” ์™„๋ฃŒ +* [ ] ๋ชจ๋‹ˆํ„ฐ๋ง/์•Œ๋ฆผ ์ „๋žต ๊ถŒ์žฅ ์™„๋ฃŒ + +--- + +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: 2026๋…„ 4์›” 9์ผ diff --git a/ko/04-subagents/secure-reviewer.md b/ko/04-subagents/secure-reviewer.md new file mode 100644 index 00000000..89e15e94 --- /dev/null +++ b/ko/04-subagents/secure-reviewer.md @@ -0,0 +1,86 @@ +--- +name: secure-reviewer +description: ์ตœ์†Œ ๊ถŒํ•œ์œผ๋กœ ๋™์ž‘ํ•˜๋Š” ๋ณด์•ˆ ์ค‘์‹ฌ ์ฝ”๋“œ ๋ฆฌ๋ทฐ ์ „๋ฌธ ์—์ด์ „ํŠธ์ž…๋‹ˆ๋‹ค. ์ฝ๊ธฐ ์ „์šฉ ์ ‘๊ทผ ๊ถŒํ•œ์„ ํ†ตํ•ด ์•ˆ์ „ํ•œ ๋ณด์•ˆ ๊ฐ์‚ฌ๋ฅผ ์ˆ˜ํ–‰ํ•ฉ๋‹ˆ๋‹ค. +tools: Read, Grep +model: inherit +--- + +# ๋ณด์•ˆ ์ฝ”๋“œ ๋ฆฌ๋ทฐ์–ด + +๋‹น์‹ ์€ ์ทจ์•ฝ์  ์‹๋ณ„์—๋งŒ ์ง‘์ค‘ํ•˜๋Š” ๋ณด์•ˆ ์ „๋ฌธ๊ฐ€์ž…๋‹ˆ๋‹ค. + +์ด ์—์ด์ „ํŠธ๋Š” ์˜๋„์ ์œผ๋กœ ์ตœ์†Œ ๊ถŒํ•œ๋งŒ ๋ถ€์—ฌ๋ฐ›์•˜์Šต๋‹ˆ๋‹ค. + +* ํŒŒ์ผ์„ ์ฝ์–ด ๋ถ„์„ํ•  ์ˆ˜ ์žˆ์Œ +* ํŒจํ„ด ๊ฒ€์ƒ‰ ๊ฐ€๋Šฅ +* ์ฝ”๋“œ ์‹คํ–‰ ๋ถˆ๊ฐ€ +* ํŒŒ์ผ ์ˆ˜์ • ๋ถˆ๊ฐ€ +* ํ…Œ์ŠคํŠธ ์‹คํ–‰ ๋ถˆ๊ฐ€ + +์ด๋ฅผ ํ†ตํ•ด ๋ณด์•ˆ ๊ฐ์‚ฌ ์ค‘ ์‹ค์ˆ˜๋กœ ์‹œ์Šคํ…œ์— ์˜ํ–ฅ์„ ์ฃผ๋Š” ์ผ์„ ๋ฐฉ์ง€ํ•ฉ๋‹ˆ๋‹ค. + +## ๋ณด์•ˆ ๋ฆฌ๋ทฐ ์ค‘์  ํ•ญ๋ชฉ + +### 1. ์ธ์ฆ(Authentication) ๋ฌธ์ œ + +* ์ทจ์•ฝํ•œ ๋น„๋ฐ€๋ฒˆํ˜ธ ์ •์ฑ… +* ๋‹ค์ค‘ ์ธ์ฆ(MFA) ๋ฏธ์ ์šฉ +* ์„ธ์…˜ ๊ด€๋ฆฌ ์ทจ์•ฝ์  + +### 2. ์ธ๊ฐ€(Authorization) ๋ฌธ์ œ + +* ์ ‘๊ทผ ์ œ์–ด ์ทจ์•ฝ์ (Broken Access Control) +* ๊ถŒํ•œ ์ƒ์Šน(Privilege Escalation) +* ์—ญํ• (Role) ๊ฒ€์ฆ ๋ˆ„๋ฝ + +### 3. ๋ฐ์ดํ„ฐ ๋…ธ์ถœ(Data Exposure) + +* ๋กœ๊ทธ์— ํฌํ•จ๋œ ๋ฏผ๊ฐ ์ •๋ณด +* ์•”ํ˜ธํ™”๋˜์ง€ ์•Š์€ ์ €์žฅ์†Œ +* API ํ‚ค ๋…ธ์ถœ +* ๊ฐœ์ธ์ •๋ณด(PII) ์ฒ˜๋ฆฌ ๋ฌธ์ œ + +### 4. ์ธ์ ์…˜ ์ทจ์•ฝ์ (Injection Vulnerabilities) + +* SQL Injection +* Command Injection +* XSS(Cross-Site Scripting) +* LDAP Injection + +### 5. ์„ค์ •(Configuration) ๋ฌธ์ œ + +* ์šด์˜ ํ™˜๊ฒฝ์—์„œ Debug ๋ชจ๋“œ ํ™œ์„ฑํ™” +* ๊ธฐ๋ณธ ์ž๊ฒฉ ์ฆ๋ช…(Default Credentials) +* ์•ˆ์ „ํ•˜์ง€ ์•Š์€ ๊ธฐ๋ณธ ์„ค์ • + +## ๊ฒ€์ƒ‰ํ•  ํŒจํ„ด + +```bash +# Hardcoded secrets +grep -r "password\s*=" --include="*.js" --include="*.ts" +grep -r "api_key\s*=" --include="*.py" +grep -r "SECRET" --include="*.env*" + +# SQL injection risks +grep -r "query.*\$" --include="*.js" +grep -r "execute.*%" --include="*.py" + +# Command injection risks +grep -r "exec(" --include="*.js" +grep -r "os.system" --include="*.py" +``` + +## ์ถœ๋ ฅ ํ˜•์‹ + +๊ฐ ์ทจ์•ฝ์ ์— ๋Œ€ํ•ด ๋‹ค์Œ ์ •๋ณด๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. + +* **Severity**: Critical / High / Medium / Low +* **Type**: OWASP ์นดํ…Œ๊ณ ๋ฆฌ +* **Location**: ํŒŒ์ผ ๊ฒฝ๋กœ ๋ฐ ๋ผ์ธ ๋ฒˆํ˜ธ +* **Description**: ์ทจ์•ฝ์ ์— ๋Œ€ํ•œ ์„ค๋ช… +* **Risk**: ์•…์šฉ๋  ๊ฒฝ์šฐ์˜ ์ž ์žฌ์  ์˜ํ–ฅ +* **Remediation**: ์ˆ˜์ • ๋ฐฉ๋ฒ• + +--- + +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: 2026๋…„ 4์›” 9์ผ diff --git a/ko/04-subagents/test-engineer.md b/ko/04-subagents/test-engineer.md new file mode 100644 index 00000000..91af0ce9 --- /dev/null +++ b/ko/04-subagents/test-engineer.md @@ -0,0 +1,79 @@ +--- +name: test-engineer +description: ํฌ๊ด„์ ์ธ ํ…Œ์ŠคํŠธ ์ž‘์„ฑ์„ ์œ„ํ•œ ํ…Œ์ŠคํŠธ ์ž๋™ํ™” ์ „๋ฌธ๊ฐ€์ž…๋‹ˆ๋‹ค. ์ƒˆ๋กœ์šด ๊ธฐ๋Šฅ์ด ๊ตฌํ˜„๋˜๊ฑฐ๋‚˜ ์ฝ”๋“œ๊ฐ€ ์ˆ˜์ •๋  ๋•Œ ์ ๊ทน์ ์œผ๋กœ ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค. +tools: Read, Write, Bash, Grep +model: inherit +--- +# ํ…Œ์ŠคํŠธ ์—”์ง€๋‹ˆ์–ด ์—์ด์ „ํŠธ + +๋‹น์‹ ์€ ํฌ๊ด„์ ์ธ ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€๋ฅผ ์ „๋ฌธ์œผ๋กœ ํ•˜๋Š” ํ…Œ์ŠคํŠธ ์—”์ง€๋‹ˆ์–ด์ž…๋‹ˆ๋‹ค. + +ํ˜ธ์ถœ๋˜๋ฉด ๋‹ค์Œ์„ ์ˆ˜ํ–‰ํ•ฉ๋‹ˆ๋‹ค. + +1. ํ…Œ์ŠคํŠธ๊ฐ€ ํ•„์š”ํ•œ ์ฝ”๋“œ๋ฅผ ๋ถ„์„ํ•ฉ๋‹ˆ๋‹ค. +2. ํ•ต์‹ฌ ๊ฒฝ๋กœ์™€ ์—ฃ์ง€ ์ผ€์ด์Šค๋ฅผ ์‹๋ณ„ํ•ฉ๋‹ˆ๋‹ค. +3. ํ”„๋กœ์ ํŠธ ๊ทœ์น™์— ๋”ฐ๋ผ ํ…Œ์ŠคํŠธ๋ฅผ ์ž‘์„ฑํ•ฉ๋‹ˆ๋‹ค. +4. ํ…Œ์ŠคํŠธ๋ฅผ ์‹คํ–‰ํ•˜์—ฌ ์ •์ƒ์ ์œผ๋กœ ํ†ต๊ณผํ•˜๋Š”์ง€ ๊ฒ€์ฆํ•ฉ๋‹ˆ๋‹ค. + +## ํ…Œ์ŠคํŠธ ์ „๋žต + +1. **๋‹จ์œ„ ํ…Œ์ŠคํŠธ(Unit Tests)** - ๊ฐœ๋ณ„ ํ•จ์ˆ˜/๋ฉ”์„œ๋“œ๋ฅผ ๋…๋ฆฝ์ ์œผ๋กœ ๊ฒ€์ฆ +2. **ํ†ตํ•ฉ ํ…Œ์ŠคํŠธ(Integration Tests)** - ์ปดํฌ๋„ŒํŠธ ๊ฐ„ ์ƒํ˜ธ์ž‘์šฉ ๊ฒ€์ฆ +3. **์ข…๋‹จ ๊ฐ„ ํ…Œ์ŠคํŠธ(End-to-End Tests)** - ์ „์ฒด ์›Œํฌํ”Œ๋กœ์šฐ ๊ฒ€์ฆ +4. **์—ฃ์ง€ ์ผ€์ด์Šค(Edge Cases)** - ๊ฒฝ๊ณ„ ์กฐ๊ฑด, null ๊ฐ’, ๋นˆ ์ปฌ๋ ‰์…˜ ๊ฒ€์ฆ +5. **์˜ค๋ฅ˜ ์‹œ๋‚˜๋ฆฌ์˜ค(Error Scenarios)** - ์‹คํŒจ ์ฒ˜๋ฆฌ ๋ฐ ์ž˜๋ชป๋œ ์ž…๋ ฅ ๊ฒ€์ฆ + +## ํ…Œ์ŠคํŠธ ์š”๊ตฌ์‚ฌํ•ญ + +* ํ”„๋กœ์ ํŠธ์—์„œ ์‚ฌ์šฉ ์ค‘์ธ ํ…Œ์ŠคํŠธ ํ”„๋ ˆ์ž„์›Œํฌ(Jest, pytest ๋“ฑ)๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +* ๊ฐ ํ…Œ์ŠคํŠธ์— ์„ค์ •(setup) ๋ฐ ์ •๋ฆฌ(teardown) ์ฝ”๋“œ๋ฅผ ํฌํ•จํ•ฉ๋‹ˆ๋‹ค. +* ์™ธ๋ถ€ ์˜์กด์„ฑ์„ Mock ์ฒ˜๋ฆฌํ•ฉ๋‹ˆ๋‹ค. +* ๋ช…ํ™•ํ•œ ์„ค๋ช…์„ ํ†ตํ•ด ํ…Œ์ŠคํŠธ ๋ชฉ์ ์„ ๋ฌธ์„œํ™”ํ•ฉ๋‹ˆ๋‹ค. +* ํ•„์š”ํ•œ ๊ฒฝ์šฐ ์„ฑ๋Šฅ ๊ด€๋ จ ๊ฒ€์ฆ(assertion)์„ ํฌํ•จํ•ฉ๋‹ˆ๋‹ค. + +## ์ปค๋ฒ„๋ฆฌ์ง€ ์š”๊ตฌ์‚ฌํ•ญ + +* ์ตœ์†Œ 80% ์ฝ”๋“œ ์ปค๋ฒ„๋ฆฌ์ง€ +* ํ•ต์‹ฌ ๊ฒฝ๋กœ(์ธ์ฆ, ๊ฒฐ์ œ, ๋ฐ์ดํ„ฐ ์ฒ˜๋ฆฌ)๋Š” 100% ์ปค๋ฒ„๋ฆฌ์ง€ +* ๋ˆ„๋ฝ๋œ ์ปค๋ฒ„๋ฆฌ์ง€ ์˜์—ญ์„ ๋ณด๊ณ ํ•ฉ๋‹ˆ๋‹ค. + +## ํ…Œ์ŠคํŠธ ์ถœ๋ ฅ ํ˜•์‹ + +์ƒ์„ฑ๋œ ๊ฐ ํ…Œ์ŠคํŠธ ํŒŒ์ผ์— ๋Œ€ํ•ด ๋‹ค์Œ ์ •๋ณด๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. + +* **File**: ํ…Œ์ŠคํŠธ ํŒŒ์ผ ๊ฒฝ๋กœ +* **Tests**: ํ…Œ์ŠคํŠธ ์ผ€์ด์Šค ์ˆ˜ +* **Coverage**: ์˜ˆ์ƒ ์ปค๋ฒ„๋ฆฌ์ง€ ํ–ฅ์ƒ ์ˆ˜์ค€ +* **Critical Paths**: ์ปค๋ฒ„๋œ ํ•ต์‹ฌ ๊ฒฝ๋กœ + +## ํ…Œ์ŠคํŠธ ๊ตฌ์กฐ ์˜ˆ์‹œ + +```javascript +describe('Feature: User Authentication', () => { + beforeEach(() => { + // Setup + }); + + afterEach(() => { + // Cleanup + }); + + it('should authenticate valid credentials', async () => { + // Arrange + // Act + // Assert + }); + + it('should reject invalid credentials', async () => { + // Test error case + }); + + it('should handle edge case: empty password', async () => { + // Test edge case + }); +}); +``` + +--- + +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: 2026๋…„ 4์›” 9์ผ diff --git a/ko/05-mcp/README.md b/ko/05-mcp/README.md new file mode 100644 index 00000000..846c21b5 --- /dev/null +++ b/ko/05-mcp/README.md @@ -0,0 +1,1192 @@ + + + Claude How To + + +# MCP (๋ชจ๋ธ ์ปจํ…์ŠคํŠธ ํ”„๋กœํ† ์ฝœ) + +์ด ํด๋”์—๋Š” MCP ์„œ๋ฒ„ ๊ตฌ์„ฑ ๋ฐ Claude Code์™€ ํ•จ๊ป˜ ์‚ฌ์šฉํ•˜๋Š” ๋ฐฉ๋ฒ•์— ๋Œ€ํ•œ ํฌ๊ด„์ ์ธ ๋ฌธ์„œ์™€ ์˜ˆ์‹œ๊ฐ€ ํฌํ•จ๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. + +## ๊ฐœ์š” + +MCP (Model Context Protocol)๋Š” Claude๊ฐ€ ์™ธ๋ถ€ ๋„๊ตฌ, API ๋ฐ ์‹ค์‹œ๊ฐ„ ๋ฐ์ดํ„ฐ ์†Œ์Šค์— ์ ‘๊ทผํ•˜๋Š” ํ‘œ์ค€ํ™”๋œ ๋ฐฉ๋ฒ•์ž…๋‹ˆ๋‹ค. Memory์™€ ๋‹ฌ๋ฆฌ MCP๋Š” ๋ณ€ํ™”ํ•˜๋Š” ๋ฐ์ดํ„ฐ์— ๋Œ€ํ•œ ์‹ค์‹œ๊ฐ„ ์ ‘๊ทผ์„ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. + +์ฃผ์š” ํŠน์ง•: +- ์™ธ๋ถ€ ์„œ๋น„์Šค์— ๋Œ€ํ•œ ์‹ค์‹œ๊ฐ„ ์ ‘๊ทผ +- ์‹ค์‹œ๊ฐ„ ๋ฐ์ดํ„ฐ ๋™๊ธฐํ™” +- ํ™•์žฅ ๊ฐ€๋Šฅํ•œ ์•„ํ‚คํ…์ฒ˜ +- ์•ˆ์ „ํ•œ ์ธ์ฆ +- ๋„๊ตฌ ๊ธฐ๋ฐ˜ ์ƒํ˜ธ ์ž‘์šฉ + +## MCP ์•„ํ‚คํ…์ฒ˜ + +```mermaid +graph TB + A["Claude"] + B["MCP Server"] + C["External Service"] + + A -->|Request: list_issues| B + B -->|Query| C + C -->|Data| B + B -->|Response| A + + A -->|Request: create_issue| B + B -->|Action| C + C -->|Result| B + B -->|Response| A + + style A fill:#e1f5fe,stroke:#333,color:#333 + style B fill:#f3e5f5,stroke:#333,color:#333 + style C fill:#e8f5e9,stroke:#333,color:#333 +``` + +## MCP ์ƒํƒœ๊ณ„ + +```mermaid +graph TB + A["Claude"] -->|MCP| B["Filesystem
MCP Server"] + A -->|MCP| C["GitHub
MCP Server"] + A -->|MCP| D["Database
MCP Server"] + A -->|MCP| E["Slack
MCP Server"] + A -->|MCP| F["Google Docs
MCP Server"] + + B -->|File I/O| G["Local Files"] + C -->|API| H["GitHub Repos"] + D -->|Query| I["PostgreSQL/MySQL"] + E -->|Messages| J["Slack Workspace"] + F -->|Docs| K["Google Drive"] + + style A fill:#e1f5fe,stroke:#333,color:#333 + style B fill:#f3e5f5,stroke:#333,color:#333 + style C fill:#f3e5f5,stroke:#333,color:#333 + style D fill:#f3e5f5,stroke:#333,color:#333 + style E fill:#f3e5f5,stroke:#333,color:#333 + style F fill:#f3e5f5,stroke:#333,color:#333 + style G fill:#e8f5e9,stroke:#333,color:#333 + style H fill:#e8f5e9,stroke:#333,color:#333 + style I fill:#e8f5e9,stroke:#333,color:#333 + style J fill:#e8f5e9,stroke:#333,color:#333 + style K fill:#e8f5e9,stroke:#333,color:#333 +``` + +## MCP ์„ค์น˜ ๋ฐฉ๋ฒ• + +Claude Code๋Š” MCP ์„œ๋ฒ„ ์—ฐ๊ฒฐ์„ ์œ„ํ•ด ์—ฌ๋Ÿฌ ์ „์†ก ํ”„๋กœํ† ์ฝœ์„ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค. + +### HTTP ์ „์†ก (๊ถŒ์žฅ) + +```bash +# Basic HTTP connection +claude mcp add --transport http notion https://mcp.notion.com/mcp + +# HTTP with authentication header +claude mcp add --transport http secure-api https://api.example.com/mcp \ + --header "Authorization: Bearer your-token" +``` + +### Stdio ์ „์†ก (๋กœ์ปฌ) + +๋กœ์ปฌ์—์„œ ์‹คํ–‰๋˜๋Š” MCP ์„œ๋ฒ„์˜ ๊ฒฝ์šฐ: + +```bash +# Local Node.js server +claude mcp add --transport stdio myserver -- npx @myorg/mcp-server + +# With environment variables +claude mcp add --transport stdio myserver --env KEY=value -- npx server +``` + +#### stdio ์„œ๋ฒ„์šฉ CLAUDE_PROJECT_DIR (v2.1.139 ์ด์ƒ) + +๋ชจ๋“  MCP stdio ์„œ๋ฒ„๋Š” ํ™˜๊ฒฝ์— `CLAUDE_PROJECT_DIR=`๊ฐ€ ์ด๋ฏธ ์„ค์ •๋œ ์ƒํƒœ๋กœ ์ƒ์„ฑ๋ฉ๋‹ˆ๋‹ค. ์ด๋Š” ํ›„ํฌ(hook)์— ์‚ฌ์šฉ๋˜๋Š” ๊ฒƒ๊ณผ ๋™์ผํ•œ ๊ทœ์น™์ž…๋‹ˆ๋‹ค. ํ”Œ๋Ÿฌ๊ทธ์ธ ๋ฐ ํ”„๋กœ์ ํŠธ์˜ `.mcp.json` ํŒŒ์ผ์€ `command`, `args`, `env` ๊ฐ’์—์„œ `${CLAUDE_PROJECT_DIR}`๋ฅผ ์ฐธ์กฐํ•  ์ˆ˜ ์žˆ์œผ๋ฉฐ, ์ด ๋Œ€์ฒด๋Š” `execve()` ์ „์— ์ด๋ฃจ์–ด์ง‘๋‹ˆ๋‹ค. + +```json +{ + "mcpServers": { + "repo-tools": { + "type": "stdio", + "command": "node", + "args": ["${CLAUDE_PROJECT_DIR}/.claude/mcp/repo-tools.js"], + "env": { + "REPO_ROOT": "${CLAUDE_PROJECT_DIR}" + } + } + } +} +``` + +Claude Code๊ฐ€ ์–ด๋””์—์„œ ์‹คํ–‰๋˜์—ˆ๋Š”์ง€์— ๊ด€๊ณ„์—†์ด stdio ์„œ๋ฒ„๊ฐ€ ํ”„๋กœ์ ํŠธ ๋ฃจํŠธ์— ์ƒ๋Œ€์ ์ธ ํŒŒ์ผ์„ ์ฝ์–ด์•ผ ํ•  ๋•Œ ์ด ๊ธฐ๋Šฅ์„ ์‚ฌ์šฉํ•˜์„ธ์š”. + +stdio MCP ์„œ๋ฒ„๋Š” ๋˜ํ•œ `CLAUDE_CODE_SESSION_ID`๋ฅผ ์ˆ˜์‹ ํ•ฉ๋‹ˆ๋‹ค (ํ›„ํฌ ๋ฐ Bash์— ์ „๋‹ฌ๋œ ๊ฐ’๊ณผ ์ผ์น˜). ์„ธ์…˜์ด `--resume`์œผ๋กœ ์žฌ๊ฐœ๋  ๋•Œ๋„ ๋งˆ์ฐฌ๊ฐ€์ง€์ž…๋‹ˆ๋‹ค (v2.1.163 ์ด์ƒ). + +### SSE ์ „์†ก (์‚ฌ์šฉ ์ค‘๋‹จ) + +Server-Sent Events ์ „์†ก์€ `http` ๋ฐฉ์‹์— ๋น„ํ•ด ์‚ฌ์šฉ์ด ์ค‘๋‹จ๋˜์—ˆ์ง€๋งŒ ์—ฌ์ „ํžˆ ์ง€์›๋ฉ๋‹ˆ๋‹ค. + +```bash +claude mcp add --transport sse legacy-server https://example.com/sse +``` + +### Windows ํŠน์ • ์ฐธ๊ณ  ์‚ฌํ•ญ + +๋„ค์ดํ‹ฐ๋ธŒ Windows (WSL ์•„๋‹˜)์—์„œ๋Š” npx ๋ช…๋ น์— `cmd /c`๋ฅผ ์‚ฌ์šฉํ•˜์„ธ์š”. + +```bash +claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package +``` + +### OAuth 2.0 ์ธ์ฆ + +Claude Code๋Š” OAuth 2.0์ด ํ•„์š”ํ•œ MCP ์„œ๋ฒ„๋ฅผ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค. OAuth๋ฅผ ์‚ฌ์šฉํ•˜๋Š” ์„œ๋ฒ„์— ์—ฐ๊ฒฐํ•  ๋•Œ Claude Code๋Š” ์ „์ฒด ์ธ์ฆ ํ๋ฆ„์„ ์ฒ˜๋ฆฌํ•ฉ๋‹ˆ๋‹ค. + +```bash +# Connect to an OAuth-enabled MCP server (interactive flow) +claude mcp add --transport http my-service https://my-service.example.com/mcp + +# Pre-configure OAuth credentials for non-interactive setup +claude mcp add --transport http my-service https://my-service.example.com/mcp \ + --client-id "your-client-id" \ + --client-secret "your-client-secret" \ + --callback-port 8080 +``` + +| Feature | Description | +|---------|-------------| +| **Interactive OAuth** | `/mcp`๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ๋ธŒ๋ผ์šฐ์ € ๊ธฐ๋ฐ˜ OAuth ํ๋ฆ„์„ ํŠธ๋ฆฌ๊ฑฐํ•ฉ๋‹ˆ๋‹ค. | +| **Pre-configured OAuth clients** | Notion, Stripe ๋“ฑ ์ผ๋ฐ˜ ์„œ๋น„์Šค์šฉ ๋‚ด์žฅ OAuth ํด๋ผ์ด์–ธํŠธ (v2.1.30 ์ด์ƒ) | +| **Pre-configured credentials** | ์ž๋™ ์„ค์ •์„ ์œ„ํ•œ `--client-id`, `--client-secret`, `--callback-port` ํ”Œ๋ž˜๊ทธ | +| **Token storage** | ํ† ํฐ์€ ์‹œ์Šคํ…œ ํ‚ค์ฒด์ธ์— ์•ˆ์ „ํ•˜๊ฒŒ ์ €์žฅ๋ฉ๋‹ˆ๋‹ค. | +| **Step-up auth** | ๊ถŒํ•œ์ด ํ•„์š”ํ•œ ์ž‘์—…์— ๋Œ€ํ•œ ๋‹จ๊ณ„๋ณ„ ์ธ์ฆ์„ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค. | +| **Discovery caching** | OAuth ๊ฒ€์ƒ‰ ๋ฉ”ํƒ€๋ฐ์ดํ„ฐ๋Š” ๋” ๋น ๋ฅธ ์žฌ์—ฐ๊ฒฐ์„ ์œ„ํ•ด ์บ์‹œ๋ฉ๋‹ˆ๋‹ค. | +| **Metadata override** | `.mcp.json`์˜ `oauth.authServerMetadataUrl`์„ ์‚ฌ์šฉํ•˜์—ฌ ๊ธฐ๋ณธ OAuth ๋ฉ”ํƒ€๋ฐ์ดํ„ฐ ๊ฒ€์ƒ‰์„ ์žฌ์ •์˜ํ•ฉ๋‹ˆ๋‹ค. | + +#### OAuth ๋ฉ”ํƒ€๋ฐ์ดํ„ฐ ๊ฒ€์ƒ‰ ์žฌ์ •์˜ + +MCP ์„œ๋ฒ„๊ฐ€ ํ‘œ์ค€ OAuth ๋ฉ”ํƒ€๋ฐ์ดํ„ฐ ์—”๋“œํฌ์ธํŠธ (`/.well-known/oauth-authorization-server`)์—์„œ ์˜ค๋ฅ˜๋ฅผ ๋ฐ˜ํ™˜ํ•˜์ง€๋งŒ ์ž‘๋™ํ•˜๋Š” OIDC ์—”๋“œํฌ์ธํŠธ๋ฅผ ๋…ธ์ถœํ•˜๋Š” ๊ฒฝ์šฐ, Claude Code์— ํŠน์ • URL์—์„œ OAuth ๋ฉ”ํƒ€๋ฐ์ดํ„ฐ๋ฅผ ๊ฐ€์ ธ์˜ค๋„๋ก ์ง€์‹œํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์„œ๋ฒ„ ๊ตฌ์„ฑ์˜ `oauth` ๊ฐ์ฒด์— `authServerMetadataUrl`์„ ์„ค์ •ํ•˜์„ธ์š”. + +```json +{ + "mcpServers": { + "my-server": { + "type": "http", + "url": "https://mcp.example.com/mcp", + "oauth": { + "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration" + } + } + } +} +``` + +URL์€ `https://`๋ฅผ ์‚ฌ์šฉํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. ์ด ์˜ต์…˜์€ Claude Code v2.1.64 ์ด์ƒ์—์„œ ํ•„์š”ํ•ฉ๋‹ˆ๋‹ค. + +#### ์ธ์ฆ ์‹œ์ž‘ ์•Œ๋ฆผ ๋ฐ ๋™์  ํ—ค๋” ์ƒˆ๋กœ ๊ณ ์นจ (v2.1.193) + +- **์‹œ์ž‘ ์ธ์ฆ ์•Œ๋ฆผ (v2.1.193 ์ด์ƒ)**: ์‹œ์ž‘ ์‹œ Claude Code๋Š” ์•„์ง ์ธ์ฆ์ด ํ•„์š”ํ•œ MCP ์„œ๋ฒ„ ๋ชฉ๋ก์„ ์•Œ๋ฆผ์œผ๋กœ ํ‘œ์‹œํ•˜์—ฌ, ๋กœ๊ทธ์ธ์ด ํ•„์š”ํ•œ ์„œ๋ฒ„๊ฐ€ ์กฐ์šฉํžˆ ์ž‘๋™ํ•˜์ง€ ์•Š๋Š” ์ƒํƒœ๋กœ ๋ฐฉ์น˜๋˜์ง€ ์•Š๋„๋ก ํ•ฉ๋‹ˆ๋‹ค. +- **`headersHelper` ์ž๋™ ์ƒˆ๋กœ ๊ณ ์นจ (v2.1.193 ์ด์ƒ)**: `headersHelper`๋ฅผ ํ†ตํ•ด ์‚ฌ์šฉ์ž ์ง€์ • ์ธ์ฆ์„ ์ œ๊ณตํ•˜๋Š” ๊ฒฝ์šฐ, ์„œ๋ฒ„๊ฐ€ HTTP 401 ๋˜๋Š” 403์„ ๋ฐ˜ํ™˜ํ•˜๋ฉด ๋„์šฐ๋ฏธ๊ฐ€ ์ž๋™์œผ๋กœ ๋‹ค์‹œ ํ˜ธ์ถœ๋ฉ๋‹ˆ๋‹ค. ์ˆ˜๋™ ์žฌ์—ฐ๊ฒฐ ์—†์ด ์ž๊ฒฉ ์ฆ๋ช…์ด ์ฆ‰์‹œ ์ƒˆ๋กœ ๊ณ ์ณ์ง‘๋‹ˆ๋‹ค. [์‚ฌ์šฉ์ž ์ง€์ • ์ธ์ฆ์„ ์œ„ํ•ด ๋™์  ํ—ค๋” ์‚ฌ์šฉ](https://code.claude.com/docs/en/mcp)์„ ์ฐธ์กฐํ•˜์„ธ์š”. + +### Claude.ai MCP ์ปค๋„ฅํ„ฐ + +Claude.ai ๊ณ„์ •์—์„œ ๊ตฌ์„ฑ๋œ MCP ์„œ๋ฒ„๋Š” Claude Code์—์„œ ์ž๋™์œผ๋กœ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์ด๋Š” Claude.ai ์›น ์ธํ„ฐํŽ˜์ด์Šค๋ฅผ ํ†ตํ•ด ์„ค์ •ํ•œ ๋ชจ๋“  MCP ์—ฐ๊ฒฐ์ด ์ถ”๊ฐ€ ๊ตฌ์„ฑ ์—†์ด ์ ‘๊ทผ ๊ฐ€๋Šฅํ•˜๋‹ค๋Š” ๊ฒƒ์„ ์˜๋ฏธํ•ฉ๋‹ˆ๋‹ค. + +Claude.ai MCP ์ปค๋„ฅํ„ฐ๋Š” `--print` ๋ชจ๋“œ์—์„œ๋„ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค (v2.1.83 ์ด์ƒ). ์ด๋ฅผ ํ†ตํ•ด ๋น„๋Œ€ํ™”ํ˜• ๋ฐ ์Šคํฌ๋ฆฝํŠธ ๊ธฐ๋ฐ˜ ์‚ฌ์šฉ์ด ๊ฐ€๋Šฅํ•ฉ๋‹ˆ๋‹ค. + +> **์‹œ์ž‘ ์ฐธ๊ณ  ์‚ฌํ•ญ (v2.1.117 ์ด์ƒ):** ๋กœ์ปฌ ๋ฐ claude.ai MCP ์„œ๋ฒ„๊ฐ€ ๋ชจ๋‘ ๊ตฌ์„ฑ๋œ ๊ฒฝ์šฐ ๋™์‹œ ์—ฐ๊ฒฐ์ด ๊ธฐ๋ณธ๊ฐ’์ž…๋‹ˆ๋‹ค (์ด์ „์—๋Š” ์ˆœ์ฐจ์ ). ์ด๋Š” ์—ฌ๋Ÿฌ ์„œ๋ฒ„๋ฅผ ์‚ฌ์šฉํ•  ๋•Œ ์‹œ์ž‘ ๋Œ€๊ธฐ ์‹œ๊ฐ„์„ ์ค„์—ฌ์ค๋‹ˆ๋‹ค. + +Claude Code์—์„œ Claude.ai MCP ์„œ๋ฒ„๋ฅผ ๋น„ํ™œ์„ฑํ™”ํ•˜๋ ค๋ฉด `ENABLE_CLAUDEAI_MCP_SERVERS` ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋ฅผ `false`๋กœ ์„ค์ •ํ•˜์„ธ์š”. + +```bash +ENABLE_CLAUDEAI_MCP_SERVERS=false claude +``` + +> **์ฐธ๊ณ :** ์ด ๊ธฐ๋Šฅ์€ Claude.ai ๊ณ„์ •์œผ๋กœ ๋กœ๊ทธ์ธํ•œ ์‚ฌ์šฉ์ž์—๊ฒŒ๋งŒ ์ œ๊ณต๋ฉ๋‹ˆ๋‹ค. + +## MCP ์„ค์ • ํ”„๋กœ์„ธ์Šค + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude Code + participant Config as Config File + participant Service as External Service + + User->>Claude: Type /mcp + Claude->>Claude: List available MCP servers + Claude->>User: Show options + User->>Claude: Select GitHub MCP + Claude->>Config: Update configuration + Config->>Claude: Activate connection + Claude->>Service: Test connection + Service-->>Claude: Authentication successful + Claude->>User: โœ… MCP connected! +``` + +### /mcp ๋ช…๋ น + +์„ธ์…˜ ๋‚ด์—์„œ `/mcp`๋ฅผ ์ž…๋ ฅํ•˜์—ฌ ์—ฐ๊ฒฐ๋œ ์„œ๋ฒ„๋ฅผ ๋‚˜์—ดํ•˜๊ณ , OAuth ํ๋ฆ„์„ ํŠธ๋ฆฌ๊ฑฐํ•˜๋ฉฐ, ์—ฐ๊ฒฐ ์ƒํƒœ๋ฅผ ๊ฒ€์‚ฌํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +- **v2.1.121๋ถ€ํ„ฐ**, MCP๋Š” ์ผ์‹œ์ ์ธ ์˜ค๋ฅ˜ ๋ฐœ์ƒ ์‹œ ์ดˆ๊ธฐ ์—ฐ๊ฒฐ์„ ์ตœ๋Œ€ 3๋ฒˆ ์žฌ์‹œ๋„ํ•ฉ๋‹ˆ๋‹ค. +- **v2.1.128๋ถ€ํ„ฐ**, `/mcp`๋Š” ์—ฐ๊ฒฐ๋œ ๊ฐ ์„œ๋ฒ„์˜ **๋„๊ตฌ ๊ฐœ์ˆ˜**๋ฅผ ํ‘œ์‹œํ•˜๊ณ  **0๊ฐœ ๋„๊ตฌ**๋ฅผ ๋ณด๊ณ ํ•˜๋Š” ์„œ๋ฒ„๋ฅผ ์‹œ๊ฐ์ ์œผ๋กœ ํ‘œ์‹œํ•˜์—ฌ ์ž˜๋ชป ๊ตฌ์„ฑ๋œ ์„œ๋ฒ„๋ฅผ ํ•œ๋ˆˆ์— ์•Œ์•„๋ณผ ์ˆ˜ ์žˆ๋„๋ก ํ•ฉ๋‹ˆ๋‹ค. + +## MCP ๋„๊ตฌ ๊ฒ€์ƒ‰ + +MCP ๋„๊ตฌ ์„ค๋ช…์ด ์ปจํ…์ŠคํŠธ ์ฐฝ์˜ 10%๋ฅผ ์ดˆ๊ณผํ•  ๋•Œ, Claude Code๋Š” ๋ชจ๋ธ ์ปจํ…์ŠคํŠธ๋ฅผ ์••๋„ํ•˜์ง€ ์•Š๊ณ  ์˜ฌ๋ฐ”๋ฅธ ๋„๊ตฌ๋ฅผ ํšจ์œจ์ ์œผ๋กœ ์„ ํƒํ•˜๊ธฐ ์œ„ํ•ด ์ž๋™์œผ๋กœ ๋„๊ตฌ ๊ฒ€์ƒ‰์„ ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค. + +| Setting | Value | Description | +|---------|-------|-------------| +| `ENABLE_TOOL_SEARCH` | `auto` (๊ธฐ๋ณธ๊ฐ’) | ๋„๊ตฌ ์„ค๋ช…์ด ์ปจํ…์ŠคํŠธ์˜ 10%๋ฅผ ์ดˆ๊ณผํ•  ๋•Œ ์ž๋™์œผ๋กœ ํ™œ์„ฑํ™”๋ฉ๋‹ˆ๋‹ค. | +| `ENABLE_TOOL_SEARCH` | `auto:` | `N`๊ฐœ ๋„๊ตฌ์˜ ์‚ฌ์šฉ์ž ์ง€์ • ์ž„๊ณ„๊ฐ’์—์„œ ์ž๋™์œผ๋กœ ํ™œ์„ฑํ™”๋ฉ๋‹ˆ๋‹ค. | +| `ENABLE_TOOL_SEARCH` | `true` | ๋„๊ตฌ ๊ฐœ์ˆ˜์™€ ๊ด€๊ณ„์—†์ด ํ•ญ์ƒ ํ™œ์„ฑํ™”๋ฉ๋‹ˆ๋‹ค. | +| `ENABLE_TOOL_SEARCH` | `false` | ๋น„ํ™œ์„ฑํ™”๋ฉ๋‹ˆ๋‹ค; ๋ชจ๋“  ๋„๊ตฌ ์„ค๋ช…์ด ์ „์ฒด๋กœ ์ „์†ก๋ฉ๋‹ˆ๋‹ค. | + +> **์ฐธ๊ณ :** ๋„๊ตฌ ๊ฒ€์ƒ‰์€ Sonnet 4 ์ด์ƒ ๋˜๋Š” Opus 4 ์ด์ƒ์ด ํ•„์š”ํ•ฉ๋‹ˆ๋‹ค. Haiku ๋ชจ๋ธ์€ ๋„๊ตฌ ๊ฒ€์ƒ‰์— ์ง€์›๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. + +### ์„œ๋ฒ„๋ณ„ ๋„๊ตฌ ๊ฒ€์ƒ‰ ์šฐํšŒ (v2.1.121 ์ด์ƒ) + +ํŠน์ • MCP ์„œ๋ฒ„์˜ ๋„๊ตฌ๊ฐ€ ๋ชจ๋“  ๋‹จ๊ณ„์—์„œ ํ•„์š”ํ•œ ๊ฒฝ์šฐ, ํ•ด๋‹น ๊ตฌ์„ฑ์— `"alwaysLoad": true`๋ฅผ ํ‘œ์‹œํ•˜์—ฌ ๋„๊ตฌ ๊ฒ€์ƒ‰ ์—ฐ๊ธฐ๋ฅผ ๊ฑด๋„ˆ๋›ฐ๊ณ  ๋„๊ตฌ๋ฅผ ํ•ญ์ƒ ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•˜๊ฒŒ ์œ ์ง€ํ•˜์„ธ์š”. + +```json +{ + "mcpServers": { + "always-on-tool": { + "command": "node", + "args": ["./tools/always.js"], + "alwaysLoad": true + } + } +} +``` + +ํ•ญ์ƒ ๋กœ๋“œ๋˜๋Š” ๊ฐ ๋„๊ตฌ๋Š” ๋” ๊ด€๋ จ์„ฑ ๋†’์€ ๋„๊ตฌ๋ฅผ ํ‘œ์‹œํ•˜๋Š” ๋ฐ ์‚ฌ์šฉ๋  ์ˆ˜ ์žˆ๋Š” ์ปจํ…์ŠคํŠธ๋ฅผ ์†Œ๋น„ํ•˜๋ฏ€๋กœ ์•„๊ปด์„œ ์‚ฌ์šฉํ•˜์„ธ์š”. + +## ๋™์  ๋„๊ตฌ ์—…๋ฐ์ดํŠธ + +Claude Code๋Š” MCP `list_changed` ์•Œ๋ฆผ์„ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค. MCP ์„œ๋ฒ„๊ฐ€ ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ๋„๊ตฌ๋ฅผ ๋™์ ์œผ๋กœ ์ถ”๊ฐ€, ์ œ๊ฑฐ ๋˜๋Š” ์ˆ˜์ •ํ•˜๋ฉด Claude Code๋Š” ์—…๋ฐ์ดํŠธ๋ฅผ ์ˆ˜์‹ ํ•˜๊ณ  ๋„๊ตฌ ๋ชฉ๋ก์„ ์ž๋™์œผ๋กœ ์กฐ์ •ํ•ฉ๋‹ˆ๋‹ค. ์žฌ์—ฐ๊ฒฐ์ด๋‚˜ ๋‹ค์‹œ ์‹œ์ž‘์ด ํ•„์š” ์—†์Šต๋‹ˆ๋‹ค. + +## MCP ์•ฑ + +MCP ์•ฑ์€ ์ตœ์ดˆ์˜ ๊ณต์‹ MCP ํ™•์žฅ์œผ๋กœ, MCP ๋„๊ตฌ ํ˜ธ์ถœ์ด ์ฑ„ํŒ… ์ธํ„ฐํŽ˜์ด์Šค์— ์ง์ ‘ ๋ Œ๋”๋ง๋˜๋Š” ๋Œ€ํ™”ํ˜• UI ๊ตฌ์„ฑ ์š”์†Œ๋ฅผ ๋ฐ˜ํ™˜ํ•  ์ˆ˜ ์žˆ๋„๋ก ํ•ฉ๋‹ˆ๋‹ค. ์ผ๋ฐ˜ ํ…์ŠคํŠธ ์‘๋‹ต ๋Œ€์‹  MCP ์„œ๋ฒ„๋Š” ๋Œ€ํ™”์—์„œ ๋ฒ—์–ด๋‚˜์ง€ ์•Š๊ณ ๋„ ํ’๋ถ€ํ•œ ๋Œ€์‹œ๋ณด๋“œ, ์–‘์‹, ๋ฐ์ดํ„ฐ ์‹œ๊ฐํ™” ๋ฐ ๋‹ค๋‹จ๊ณ„ ์›Œํฌํ”Œ๋กœ์šฐ๋ฅผ ์ธ๋ผ์ธ์œผ๋กœ ์ œ๊ณตํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +

MCP ์ •๋ณด ์š”์ฒญ

+ +MCP ์„œ๋ฒ„๋Š” ๋Œ€ํ™”ํ˜• ๋Œ€ํ™” ์ƒ์ž๋ฅผ ํ†ตํ•ด ์‚ฌ์šฉ์ž์—๊ฒŒ ๊ตฌ์กฐํ™”๋œ ์ž…๋ ฅ์„ ์š”์ฒญํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค (v2.1.49 ์ด์ƒ). ์ด๋ฅผ ํ†ตํ•ด MCP ์„œ๋ฒ„๋Š” ์›Œํฌํ”Œ๋กœ์šฐ ์ค‘๊ฐ„์— ์ถ”๊ฐ€ ์ •๋ณด๋ฅผ ์š”์ฒญํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์˜ˆ๋ฅผ ๋“ค์–ด, ํ™•์ธ์„ ์š”์ฒญํ•˜๊ฑฐ๋‚˜, ์˜ต์…˜ ๋ชฉ๋ก์—์„œ ์„ ํƒํ•˜๊ฑฐ๋‚˜, ํ•„์ˆ˜ ํ•„๋“œ๋ฅผ ์ฑ„์›Œ MCP ์„œ๋ฒ„ ์ƒํ˜ธ ์ž‘์šฉ์— ๋Œ€ํ™”ํ˜• ๊ธฐ๋Šฅ์„ ์ถ”๊ฐ€ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +## ๋„๊ตฌ ์„ค๋ช… ๋ฐ ์ง€์‹œ ์ƒํ•œ + +v2.1.84๋ถ€ํ„ฐ Claude Code๋Š” MCP ์„œ๋ฒ„๋‹น ๋„๊ตฌ ์„ค๋ช… ๋ฐ ์ง€์‹œ์— ๋Œ€ํ•ด **2KB ์ƒํ•œ์„ **์„ ์ ์šฉํ•ฉ๋‹ˆ๋‹ค. ์ด๋Š” ๊ฐœ๋ณ„ ์„œ๋ฒ„๊ฐ€ ์ง€๋‚˜์น˜๊ฒŒ ์žฅํ™ฉํ•œ ๋„๊ตฌ ์ •์˜๋กœ ๊ณผ๋„ํ•œ ์ปจํ…์ŠคํŠธ๋ฅผ ์†Œ๋น„ํ•˜๋Š” ๊ฒƒ์„ ๋ฐฉ์ง€ํ•˜์—ฌ ์ปจํ…์ŠคํŠธ ๋น„๋Œ€ํ™”๋ฅผ ์ค„์ด๊ณ  ์ƒํ˜ธ ์ž‘์šฉ์„ ํšจ์œจ์ ์œผ๋กœ ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. + +## ์Šฌ๋ž˜์‹œ ๋ช…๋ น์œผ๋กœ์„œ์˜ MCP ํ”„๋กฌํ”„ํŠธ + +MCP ์„œ๋ฒ„๋Š” Claude Code์—์„œ ์Šฌ๋ž˜์‹œ ๋ช…๋ น์œผ๋กœ ๋‚˜ํƒ€๋‚˜๋Š” ํ”„๋กฌํ”„ํŠธ๋ฅผ ๋…ธ์ถœํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ํ”„๋กฌํ”„ํŠธ๋Š” ๋‹ค์Œ ๋ช…๋ช… ๊ทœ์น™์„ ์‚ฌ์šฉํ•˜์—ฌ ์ ‘๊ทผํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +``` +/mcp____ +``` + +์˜ˆ๋ฅผ ๋“ค์–ด, `github`๋ผ๋Š” ์„œ๋ฒ„๊ฐ€ `review`๋ผ๋Š” ํ”„๋กฌํ”„ํŠธ๋ฅผ ๋…ธ์ถœํ•˜๋Š” ๊ฒฝ์šฐ `/mcp__github__review`๋กœ ํ˜ธ์ถœํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +## ์„œ๋ฒ„ ์ค‘๋ณต ์ œ๊ฑฐ + +๋™์ผํ•œ MCP ์„œ๋ฒ„๊ฐ€ ์—ฌ๋Ÿฌ ์Šค์ฝ”ํ”„(๋กœ์ปฌ, ํ”„๋กœ์ ํŠธ, ์‚ฌ์šฉ์ž)์— ์ •์˜๋œ ๊ฒฝ์šฐ, ๋กœ์ปฌ ๊ตฌ์„ฑ์ด ์šฐ์„ ๊ถŒ์„ ๊ฐ€์ง‘๋‹ˆ๋‹ค. ์ด๋ฅผ ํ†ตํ•ด ์ถฉ๋Œ ์—†์ด ํ”„๋กœ์ ํŠธ ์ˆ˜์ค€ ๋˜๋Š” ์‚ฌ์šฉ์ž ์ˆ˜์ค€ MCP ์„ค์ •์„ ๋กœ์ปฌ ์‚ฌ์šฉ์ž ์ง€์ •์œผ๋กœ ์žฌ์ •์˜ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +## ์ตœ๊ทผ ์ˆ˜๋ช… ์ฃผ๊ธฐ ์ˆ˜์ • ์‚ฌํ•ญ (v2.1.136) + +v2.1.136์—์„œ ์˜ค๋žซ๋™์•ˆ ์ง€์†๋œ MCP ์ˆ˜๋ช… ์ฃผ๊ธฐ ๋ฒ„๊ทธ ๋‘ ๊ฐ€์ง€๊ฐ€ ์ˆ˜์ •๋˜์—ˆ์Šต๋‹ˆ๋‹ค. ๋‹ค์ค‘ ์„œ๋ฒ„ ์„ค์ •์„ ์‹คํ–‰ํ•˜๋Š” ๊ฒฝ์šฐ ์—…๊ทธ๋ ˆ์ด๋“œํ•  ๊ฐ€์น˜๊ฐ€ ์žˆ์Šต๋‹ˆ๋‹ค. + +- **MCP ์„œ๋ฒ„๊ฐ€ `/clear` ํ›„์—๋„ ์œ ์ง€๋ฉ๋‹ˆ๋‹ค**: `.mcp.json`, ํ”Œ๋Ÿฌ๊ทธ์ธ ๋˜๋Š” claude.ai ์ปค๋„ฅํ„ฐ๋ฅผ ํ†ตํ•ด ๊ตฌ์„ฑ๋œ ์„œ๋ฒ„๋Š” VS Code, JetBrains ๋˜๋Š” Agent SDK์—์„œ `/clear` ํ›„ ๋” ์ด์ƒ ์‚ฌ๋ผ์ง€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ์ด์ „ ๋ฒ„์ „์€ ์ž๋™์œผ๋กœ ์„œ๋ฒ„๋ฅผ ์‚ญ์ œํ•˜๊ณ  ๋‹ค์‹œ ์‹œ์ž‘ํ•ด์•ผ ํ–ˆ์Šต๋‹ˆ๋‹ค. +- **OAuth ์ƒˆ๋กœ ๊ณ ์นจ ํ† ํฐ ๋™์‹œ ์ƒˆ๋กœ ๊ณ ์นจ ์ˆ˜์ •**: ์—ฌ๋Ÿฌ ์„œ๋ฒ„๊ฐ€ ๋™์‹œ์— ์ƒˆ๋กœ ๊ณ ์นจ์„ ๊ฒฝ์Ÿํ•  ๋•Œ ๋‹ค์ค‘ ์„œ๋ฒ„ OAuth ์„ค์ •์—์„œ ๋” ์ด์ƒ ์ƒˆ๋กœ ๊ณ ์นจ ํ† ํฐ์ด ์†์‹ค๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ์ด๋กœ์จ ์—ฌ๋Ÿฌ OAuth ๋ณดํ˜ธ MCP ์„œ๋ฒ„ ์„ค์ •์— ์˜ํ–ฅ์„ ๋ฏธ์น˜๋˜ "๋งค์ผ ์•„์นจ ๋‹ค์‹œ ์ธ์ฆํ•ด์•ผ ํ•˜๋Š”" ํŒจํ„ด์ด ์‚ฌ๋ผ์ง‘๋‹ˆ๋‹ค. + +## @ ๋ฉ˜์…˜์„ ํ†ตํ•œ MCP ๋ฆฌ์†Œ์Šค + +`@` ๋ฉ˜์…˜ ๊ตฌ๋ฌธ์„ ์‚ฌ์šฉํ•˜์—ฌ ํ”„๋กฌํ”„ํŠธ์—์„œ MCP ๋ฆฌ์†Œ์Šค๋ฅผ ์ง์ ‘ ์ฐธ์กฐํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +``` +@server-name:protocol://resource/path +``` + +์˜ˆ๋ฅผ ๋“ค์–ด, ํŠน์ • ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ๋ฆฌ์†Œ์Šค๋ฅผ ์ฐธ์กฐํ•˜๋ ค๋ฉด ๋‹ค์Œ๊ณผ ๊ฐ™์ด ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +``` +@database:postgres://mydb/users +``` + +์ด๋ฅผ ํ†ตํ•ด Claude๋Š” ๋Œ€ํ™” ์ปจํ…์ŠคํŠธ์˜ ์ผ๋ถ€๋กœ MCP ๋ฆฌ์†Œ์Šค ์ฝ˜ํ…์ธ ๋ฅผ ์ธ๋ผ์ธ์œผ๋กœ ๊ฐ€์ ธ์™€ ํฌํ•จํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +## MCP ์Šค์ฝ”ํ”„ + +MCP ๊ตฌ์„ฑ์€ ๋‹ค์–‘ํ•œ ์ˆ˜์ค€์˜ ๊ณต์œ ๋ฅผ ํ†ตํ•ด ์—ฌ๋Ÿฌ ์Šค์ฝ”ํ”„์— ์ €์žฅ๋  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +| Scope | Location | Description | Shared With | Requires Approval | +|-------|----------|-------------|-------------|------------------| +| **Local** (๊ธฐ๋ณธ๊ฐ’) | `~/.claude.json` (ํ”„๋กœ์ ํŠธ ๊ฒฝ๋กœ ์•„๋ž˜) | ํ˜„์žฌ ์‚ฌ์šฉ์ž, ํ˜„์žฌ ํ”„๋กœ์ ํŠธ์—๋งŒ ๋น„๊ณต๊ฐœ (์ด์ „ ๋ฒ„์ „์—์„œ๋Š” `project`๋ผ๊ณ  ๋ถˆ๋ฆผ) | ๋ณธ์ธ๋งŒ | ์•„๋‹ˆ์š” | +| **Project** | `.mcp.json` | git ์ €์žฅ์†Œ์— ์ฒดํฌ์ธ๋จ | ํŒ€์› | ์˜ˆ (์ฒซ ์‚ฌ์šฉ ์‹œ) | +| **User** | `~/.claude.json` | ๋ชจ๋“  ํ”„๋กœ์ ํŠธ์—์„œ ์‚ฌ์šฉ ๊ฐ€๋Šฅ (์ด์ „ ๋ฒ„์ „์—์„œ๋Š” `global`์ด๋ผ๊ณ  ๋ถˆ๋ฆผ) | ๋ณธ์ธ๋งŒ | ์•„๋‹ˆ์š” | + +### ํ”„๋กœ์ ํŠธ ์Šค์ฝ”ํ”„ ์‚ฌ์šฉ + +ํ”„๋กœ์ ํŠธ๋ณ„ MCP ๊ตฌ์„ฑ์„ `.mcp.json`์— ์ €์žฅํ•˜์„ธ์š”. + +```json +{ + "mcpServers": { + "github": { + "type": "http", + "url": "https://api.github.com/mcp" + } + } +} +``` + +ํŒ€์›๋“ค์€ ํ”„๋กœ์ ํŠธ MCP๋ฅผ ์ฒ˜์Œ ์‚ฌ์šฉํ•  ๋•Œ ์Šน์ธ ํ”„๋กฌํ”„ํŠธ๋ฅผ ๋ณด๊ฒŒ ๋  ๊ฒƒ์ž…๋‹ˆ๋‹ค. + +## MCP ๊ตฌ์„ฑ ๊ด€๋ฆฌ + +### MCP ์„œ๋ฒ„ ์ถ”๊ฐ€ + +```bash +# Add HTTP-based server +claude mcp add --transport http github https://api.github.com/mcp + +# Add local stdio server +claude mcp add --transport stdio database -- npx @company/db-server + +# List all MCP servers +claude mcp list + +# Get details on specific server +claude mcp get github + +# Remove an MCP server +claude mcp remove github + +# Reset project-specific approval choices +claude mcp reset-project-choices + +# Authenticate an MCP server from the CLI (v2.1.186+) +claude mcp login github + +# Sign out of an MCP server (v2.1.186+) +claude mcp logout github + +# Import from Claude Desktop +claude mcp add-from-claude-desktop +``` + +`claude mcp login ` / `claude mcp logout `์€ `/mcp` ๋ฉ”๋‰ด์˜ OAuth ํ๋ฆ„๊ณผ ์ƒํ˜ธ ์ž‘์šฉ ์—†์ด ์ธ์ฆํ•˜๊ฑฐ๋‚˜ ๋กœ๊ทธ์•„์›ƒํ•˜๋Š” ๋น„๋Œ€ํ™”ํ˜• ๋ฐฉ์‹์ž…๋‹ˆ๋‹ค. `login`์— `--no-browser`๋ฅผ ์ถ”๊ฐ€ํ•˜๋ฉด SSH ๋˜๋Š” ํ—ค๋“œ๋ฆฌ์Šค ์„ธ์…˜์—์„œ OAuth๋ฅผ stdin์„ ํ†ตํ•ด ์™„๋ฃŒํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +## ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ MCP ์„œ๋ฒ„ ํ‘œ + +| MCP Server | Purpose | Common Tools | Auth | Real-time | +|------------|---------|--------------|------|-----------| +| **Filesystem** | ํŒŒ์ผ ์ž‘์—… | read, write, delete | OS ๊ถŒํ•œ | โœ… ์˜ˆ | +| **GitHub** | ์ €์žฅ์†Œ ๊ด€๋ฆฌ | list_prs, create_issue, push | OAuth | โœ… ์˜ˆ | +| **Slack** | ํŒ€ ์ปค๋ฎค๋‹ˆ์ผ€์ด์…˜ | send_message, list_channels | Token | โœ… ์˜ˆ | +| **Database** | SQL ์ฟผ๋ฆฌ | query, insert, update | ์ž๊ฒฉ ์ฆ๋ช… | โœ… ์˜ˆ | +| **Google Docs** | ๋ฌธ์„œ ์ ‘๊ทผ | read, write, share | OAuth | โœ… ์˜ˆ | +| **Asana** | ํ”„๋กœ์ ํŠธ ๊ด€๋ฆฌ | create_task, update_status | API Key | โœ… ์˜ˆ | +| **Stripe** | ๊ฒฐ์ œ ๋ฐ์ดํ„ฐ | list_charges, create_invoice | API Key | โœ… ์˜ˆ | +| **Memory** | ์˜๊ตฌ ๋ฉ”๋ชจ๋ฆฌ | store, retrieve, delete | ๋กœ์ปฌ | โŒ ์•„๋‹ˆ์š” | + +## ์‹ค์ œ ์˜ˆ์‹œ + +### ์˜ˆ์‹œ 1: GitHub MCP ๊ตฌ์„ฑ + +**ํŒŒ์ผ:** `.mcp.json` (ํ”„๋กœ์ ํŠธ ๋ฃจํŠธ) + +```json +{ + "mcpServers": { + "github": { + "command": "npx", + "args": ["@modelcontextprotocol/server-github"], + "env": { + "GITHUB_TOKEN": "${GITHUB_TOKEN}" + } + } + } +} +``` + +**์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ GitHub MCP ๋„๊ตฌ:** + +#### Pull Request ๊ด€๋ฆฌ +- `list_prs` - ์ €์žฅ์†Œ์˜ ๋ชจ๋“  PR ๋‚˜์—ด +- `get_pr` - diff๋ฅผ ํฌํ•จํ•œ PR ์„ธ๋ถ€ ์ •๋ณด ๊ฐ€์ ธ์˜ค๊ธฐ +- `create_pr` - ์ƒˆ PR ์ƒ์„ฑ +- `update_pr` - PR ์„ค๋ช…/์ œ๋ชฉ ์—…๋ฐ์ดํŠธ +- `merge_pr` - PR์„ ๋ฉ”์ธ ๋ธŒ๋žœ์น˜๋กœ ๋ณ‘ํ•ฉ +- `review_pr` - ๊ฒ€ํ†  ์˜๊ฒฌ ์ถ”๊ฐ€ + +**์˜ˆ์‹œ ์š”์ฒญ:** +``` +/mcp__github__get_pr 456 + +# Returns: +Title: Add dark mode support +Author: @alice +Description: Implements dark theme using CSS variables +Status: OPEN +Reviewers: @bob, @charlie +``` + +#### ์ด์Šˆ ๊ด€๋ฆฌ +- `list_issues` - ๋ชจ๋“  ์ด์Šˆ ๋‚˜์—ด +- `get_issue` - ์ด์Šˆ ์„ธ๋ถ€ ์ •๋ณด ๊ฐ€์ ธ์˜ค๊ธฐ +- `create_issue` - ์ƒˆ ์ด์Šˆ ์ƒ์„ฑ +- `close_issue` - ์ด์Šˆ ๋‹ซ๊ธฐ +- `add_comment` - ์ด์Šˆ์— ๋Œ“๊ธ€ ์ถ”๊ฐ€ + +#### ์ €์žฅ์†Œ ์ •๋ณด +- `get_repo_info` - ์ €์žฅ์†Œ ์„ธ๋ถ€ ์ •๋ณด +- `list_files` - ํŒŒ์ผ ํŠธ๋ฆฌ ๊ตฌ์กฐ +- `get_file_content` - ํŒŒ์ผ ๋‚ด์šฉ ์ฝ๊ธฐ +- `search_code` - ์ฝ”๋“œ๋ฒ ์ด์Šค ์ „์ฒด ๊ฒ€์ƒ‰ + +#### ์ปค๋ฐ‹ ์ž‘์—… +- `list_commits` - ์ปค๋ฐ‹ ๊ธฐ๋ก +- `get_commit` - ํŠน์ • ์ปค๋ฐ‹ ์„ธ๋ถ€ ์ •๋ณด +- `create_commit` - ์ƒˆ ์ปค๋ฐ‹ ์ƒ์„ฑ + +**์„ค์ •**: +```bash +export GITHUB_TOKEN="your_github_token" +# Or use the CLI to add directly: +claude mcp add --transport stdio github -- npx @modelcontextprotocol/server-github +``` + +### ๊ตฌ์„ฑ์˜ ํ™˜๊ฒฝ ๋ณ€์ˆ˜ ํ™•์žฅ + +MCP ๊ตฌ์„ฑ์€ ๋Œ€์ฒด ๊ธฐ๋ณธ๊ฐ’๊ณผ ํ•จ๊ป˜ ํ™˜๊ฒฝ ๋ณ€์ˆ˜ ํ™•์žฅ์„ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค. `${VAR}` ๋ฐ `${VAR:-default}` ๊ตฌ๋ฌธ์€ `command`, `args`, `env`, `url`, `headers` ํ•„๋“œ์—์„œ ์ž‘๋™ํ•ฉ๋‹ˆ๋‹ค. + +```json +{ + "mcpServers": { + "api-server": { + "type": "http", + "url": "${API_BASE_URL:-https://api.example.com}/mcp", + "headers": { + "Authorization": "Bearer ${API_KEY}", + "X-Custom-Header": "${CUSTOM_HEADER:-default-value}" + } + }, + "local-server": { + "command": "${MCP_BIN_PATH:-npx}", + "args": ["${MCP_PACKAGE:-@company/mcp-server}"], + "env": { + "DB_URL": "${DATABASE_URL:-postgresql://localhost/dev}" + } + } + } +} +``` + +๋ณ€์ˆ˜๋Š” ๋Ÿฐํƒ€์ž„์— ํ™•์žฅ๋ฉ๋‹ˆ๋‹ค. +- `${VAR}` - ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋ฅผ ์‚ฌ์šฉํ•˜๋ฉฐ, ์„ค์ •๋˜์ง€ ์•Š์€ ๊ฒฝ์šฐ ์˜ค๋ฅ˜ ๋ฐœ์ƒ +- `${VAR:-default}` - ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋ฅผ ์‚ฌ์šฉํ•˜๋ฉฐ, ์„ค์ •๋˜์ง€ ์•Š์€ ๊ฒฝ์šฐ ๊ธฐ๋ณธ๊ฐ’์œผ๋กœ ๋Œ€์ฒด + +### ์˜ˆ์‹œ 2: ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค MCP ์„ค์ • + +**๊ตฌ์„ฑ:** + +```json +{ + "mcpServers": { + "database": { + "command": "npx", + "args": ["@modelcontextprotocol/server-database"], + "env": { + "DATABASE_URL": "postgresql://user:pass@localhost/mydb" + } + } + } +} +``` + +**์˜ˆ์‹œ ์‚ฌ์šฉ๋ฒ•:** + +```markdown +User: Fetch all users with more than 10 orders + +Claude: I'll query your database to find that information. + +# Using MCP database tool: +SELECT u.*, COUNT(o.id) as order_count +FROM users u +LEFT JOIN orders o ON u.id = o.user_id +GROUP BY u.id +HAVING COUNT(o.id) > 10 +ORDER BY order_count DESC; + +# Results: +- Alice: 15 orders +- Bob: 12 orders +- Charlie: 11 orders +``` + +**์„ค์ •**: +```bash +export DATABASE_URL="postgresql://user:pass@localhost/mydb" +# Or use the CLI to add directly: +claude mcp add --transport stdio database -- npx @modelcontextprotocol/server-database +``` + +### ์˜ˆ์‹œ 3: ๋‹ค์ค‘ MCP ์›Œํฌํ”Œ๋กœ์šฐ + +**์‹œ๋‚˜๋ฆฌ์˜ค: ์ผ์ผ ๋ณด๊ณ ์„œ ์ƒ์„ฑ** + +```markdown +# Daily Report Workflow using Multiple MCPs + +## Setup +1. GitHub MCP - fetch PR metrics +2. Database MCP - query sales data +3. Slack MCP - post report +4. Filesystem MCP - save report + +## Workflow + +### Step 1: Fetch GitHub Data +/mcp__github__list_prs completed:true last:7days + +Output: +- Total PRs: 42 +- Average merge time: 2.3 hours +- Review turnaround: 1.1 hours + +### Step 2: Query Database +SELECT COUNT(*) as sales, SUM(amount) as revenue +FROM orders +WHERE created_at > NOW() - INTERVAL '1 day' + +Output: +- Sales: 247 +- Revenue: $12,450 + +### Step 3: Generate Report +Combine data into HTML report + +### Step 4: Save to Filesystem +Write report.html to /reports/ + +### Step 5: Post to Slack +Send summary to #daily-reports channel + +Final Output: +โœ… Report generated and posted +๐Ÿ“Š 47 PRs merged this week +๐Ÿ’ฐ $12,450 in daily sales +``` + +**์„ค์ •**: +```bash +export GITHUB_TOKEN="your_github_token" +export DATABASE_URL="postgresql://user:pass@localhost/mydb" +export SLACK_TOKEN="your_slack_token" +# Add each MCP server via the CLI or configure them in .mcp.json +``` + +### ์˜ˆ์‹œ 4: ํŒŒ์ผ ์‹œ์Šคํ…œ MCP ์ž‘์—… + +**๊ตฌ์„ฑ:** + +```json +{ + "mcpServers": { + "filesystem": { + "command": "npx", + "args": ["@modelcontextprotocol/server-filesystem", "/home/user/projects"] + } + } +} +``` + +**์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ์ž‘์—…:** + +| Operation | Command | Purpose | +|-----------|---------|---------| +| ํŒŒ์ผ ๋‚˜์—ด | `ls ~/projects` | ๋””๋ ‰ํ„ฐ๋ฆฌ ๋‚ด์šฉ ํ‘œ์‹œ | +| ํŒŒ์ผ ์ฝ๊ธฐ | `cat src/main.ts` | ํŒŒ์ผ ๋‚ด์šฉ ์ฝ๊ธฐ | +| ํŒŒ์ผ ์“ฐ๊ธฐ | `create docs/api.md` | ์ƒˆ ํŒŒ์ผ ์ƒ์„ฑ | +| ํŒŒ์ผ ํŽธ์ง‘ | `edit src/app.ts` | ํŒŒ์ผ ์ˆ˜์ • | +| ๊ฒ€์ƒ‰ | `grep "async function"` | ํŒŒ์ผ ๋‚ด ๊ฒ€์ƒ‰ | +| ์‚ญ์ œ | `rm old-file.js` | ํŒŒ์ผ ์‚ญ์ œ | + +**์„ค์ •**: +```bash +# Use the CLI to add directly: +claude mcp add --transport stdio filesystem -- npx @modelcontextprotocol/server-filesystem /home/user/projects +``` + +## MCP vs Memory: ์˜์‚ฌ ๊ฒฐ์ • ๋งคํŠธ๋ฆญ์Šค + +```mermaid +graph TD + A["Need external data?"] + A -->|No| B["Use Memory"] + A -->|Yes| C["Does it change frequently?"] + C -->|No/Rarely| B + C -->|Yes/Often| D["Use MCP"] + + B -->|Stores| E["Preferences
Context
History"] + D -->|Accesses| F["Live APIs
Databases
Services"] + + style A fill:#fff3e0,stroke:#333,color:#333 + style B fill:#e1f5fe,stroke:#333,color:#333 + style C fill:#fff3e0,stroke:#333,color:#333 + style D fill:#f3e5f5,stroke:#333,color:#333 + style E fill:#e8f5e9,stroke:#333,color:#333 + style F fill:#e8f5e9,stroke:#333,color:#333 +``` + +## ์š”์ฒญ/์‘๋‹ต ํŒจํ„ด + +```mermaid +sequenceDiagram + participant App as Claude + participant MCP as MCP Server + participant DB as Database + + App->>MCP: Request: "SELECT * FROM users WHERE id=1" + MCP->>DB: Execute query + DB-->>MCP: Result set + MCP-->>App: Return parsed data + App->>App: Process result + App->>App: Continue task + + Note over MCP,DB: Real-time access
No caching +``` + +## ํ™˜๊ฒฝ ๋ณ€์ˆ˜ + +๋ฏผ๊ฐํ•œ ์ž๊ฒฉ ์ฆ๋ช…์€ ํ™˜๊ฒฝ ๋ณ€์ˆ˜์— ์ €์žฅํ•˜์„ธ์š”. + +```bash +# ~/.bashrc or ~/.zshrc +export GITHUB_TOKEN="ghp_xxxxxxxxxxxxx" +export DATABASE_URL="postgresql://user:pass@localhost/mydb" +export SLACK_TOKEN="xoxb-xxxxxxxxxxxxx" +``` + +๊ทธ๋Ÿฐ ๋‹ค์Œ MCP ๊ตฌ์„ฑ์—์„œ ์ฐธ์กฐํ•˜์„ธ์š”. + +```json +{ + "env": { + "GITHUB_TOKEN": "${GITHUB_TOKEN}" + } +} +``` + +## MCP ์„œ๋ฒ„๋กœ์„œ์˜ Claude (claude mcp serve) + +Claude Code ์ž์ฒด๋Š” ๋‹ค๋ฅธ ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜์„ ์œ„ํ•œ MCP ์„œ๋ฒ„ ์—ญํ• ์„ ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์ด๋ฅผ ํ†ตํ•ด ์™ธ๋ถ€ ๋„๊ตฌ, ํŽธ์ง‘๊ธฐ ๋ฐ ์ž๋™ํ™” ์‹œ์Šคํ…œ์ด ํ‘œ์ค€ MCP ํ”„๋กœํ† ์ฝœ์„ ํ†ตํ•ด Claude์˜ ๊ธฐ๋Šฅ์„ ํ™œ์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +```bash +# Start Claude Code as an MCP server on stdio +claude mcp serve +``` + +๋‹ค๋ฅธ ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜์€ ๋‹ค๋ฅธ stdio ๊ธฐ๋ฐ˜ MCP ์„œ๋ฒ„์™€ ๋งˆ์ฐฌ๊ฐ€์ง€๋กœ ์ด ์„œ๋ฒ„์— ์—ฐ๊ฒฐํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์˜ˆ๋ฅผ ๋“ค์–ด, ๋‹ค๋ฅธ Claude Code ์ธ์Šคํ„ด์Šค์— Claude Code๋ฅผ MCP ์„œ๋ฒ„๋กœ ์ถ”๊ฐ€ํ•˜๋ ค๋ฉด ๋‹ค์Œ์„ ์ˆ˜ํ–‰ํ•ฉ๋‹ˆ๋‹ค. + +```bash +claude mcp add --transport stdio claude-agent -- claude mcp serve +``` + +์ด๋Š” ํ•˜๋‚˜์˜ Claude ์ธ์Šคํ„ด์Šค๊ฐ€ ๋‹ค๋ฅธ ์ธ์Šคํ„ด์Šค๋ฅผ ์กฐ์œจํ•˜๋Š” ๋‹ค์ค‘ ์—์ด์ „ํŠธ ์›Œํฌํ”Œ๋กœ์šฐ๋ฅผ ๊ตฌ์ถ•ํ•˜๋Š” ๋ฐ ์œ ์šฉํ•ฉ๋‹ˆ๋‹ค. + +## ๊ด€๋ฆฌํ˜• MCP ๊ตฌ์„ฑ (์—”ํ„ฐํ”„๋ผ์ด์ฆˆ) + +์—”ํ„ฐํ”„๋ผ์ด์ฆˆ ๋ฐฐํฌ์˜ ๊ฒฝ์šฐ, IT ๊ด€๋ฆฌ์ž๋Š” `managed-mcp.json` ๊ตฌ์„ฑ ํŒŒ์ผ์„ ํ†ตํ•ด MCP ์„œ๋ฒ„ ์ •์ฑ…์„ ์ ์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์ด ํŒŒ์ผ์€ ์กฐ์ง ์ „์ฒด์—์„œ ์–ด๋–ค MCP ์„œ๋ฒ„๊ฐ€ ํ—ˆ์šฉ๋˜๊ฑฐ๋‚˜ ์ฐจ๋‹จ๋˜๋Š”์ง€์— ๋Œ€ํ•œ ๋…์ ์ ์ธ ์ œ์–ด๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. + +**์œ„์น˜:** +- macOS: `/Library/Application Support/ClaudeCode/managed-mcp.json` +- Linux: `~/.config/ClaudeCode/managed-mcp.json` +- Windows: `%APPDATA%\ClaudeCode\managed-mcp.json` + +**ํŠน์ง•:** +- `allowedMcpServers` -- ํ—ˆ์šฉ๋œ ์„œ๋ฒ„์˜ ํ™”์ดํŠธ๋ฆฌ์ŠคํŠธ +- `deniedMcpServers` -- ๊ธˆ์ง€๋œ ์„œ๋ฒ„์˜ ๋ธ”๋ž™๋ฆฌ์ŠคํŠธ +- `allowAllClaudeAiMcps` -- claude.ai ํด๋ผ์šฐ๋“œ MCP ์ปค๋„ฅํ„ฐ์˜ ์กฐ์ง ์ „์ฒด ๋กœ๋“œ๋ฅผ ํ—ˆ์šฉํ•˜๋Š” ๊ด€๋ฆฌ ์„ค์ • (v2.1.149 ์ด์ƒ) +- ์„œ๋ฒ„ ์ด๋ฆ„, ๋ช…๋ น ๋ฐ URL ํŒจํ„ด๋ณ„ ์ผ์น˜ ์ง€์› +- ์‚ฌ์šฉ์ž ๊ตฌ์„ฑ๋ณด๋‹ค ์šฐ์„ ์ ์œผ๋กœ ์ ์šฉ๋˜๋Š” ์กฐ์ง ์ „์ฒด MCP ์ •์ฑ… +- ์Šน์ธ๋˜์ง€ ์•Š์€ ์„œ๋ฒ„ ์—ฐ๊ฒฐ ๋ฐฉ์ง€ + +**์˜ˆ์‹œ ๊ตฌ์„ฑ:** + +```json +{ + "allowedMcpServers": [ + { + "serverName": "github", + "serverUrl": "https://api.github.com/mcp" + }, + { + "serverName": "company-internal", + "serverCommand": "company-mcp-server" + } + ], + "deniedMcpServers": [ + { + "serverName": "untrusted-*" + }, + { + "serverUrl": "http://*" + } + ] +} +``` + +> **์ฐธ๊ณ :** `allowedMcpServers`์™€ `deniedMcpServers`๊ฐ€ ๋ชจ๋‘ ์„œ๋ฒ„์™€ ์ผ์น˜ํ•  ๊ฒฝ์šฐ, ๊ฑฐ๋ถ€ ๊ทœ์น™์ด ์šฐ์„ ๊ถŒ์„ ๊ฐ€์ง‘๋‹ˆ๋‹ค. + +## ํ”Œ๋Ÿฌ๊ทธ์ธ ์ œ๊ณต MCP ์„œ๋ฒ„ + +ํ”Œ๋Ÿฌ๊ทธ์ธ์€ ์ž์ฒด MCP ์„œ๋ฒ„๋ฅผ ๋ฒˆ๋“ค๋กœ ์ œ๊ณตํ•˜์—ฌ ํ”Œ๋Ÿฌ๊ทธ์ธ ์„ค์น˜ ์‹œ ์ž๋™์œผ๋กœ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ๋„๋ก ํ•ฉ๋‹ˆ๋‹ค. ํ”Œ๋Ÿฌ๊ทธ์ธ ์ œ๊ณต MCP ์„œ๋ฒ„๋Š” ๋‘ ๊ฐ€์ง€ ๋ฐฉ์‹์œผ๋กœ ์ •์˜ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +1. **๋…๋ฆฝํ˜• `.mcp.json`** -- ํ”Œ๋Ÿฌ๊ทธ์ธ ๋ฃจํŠธ ๋””๋ ‰ํ† ๋ฆฌ์— `.mcp.json` ํŒŒ์ผ์„ ๋ฐฐ์น˜ +2. **`plugin.json` ๋‚ด ์ธ๋ผ์ธ** -- ํ”Œ๋Ÿฌ๊ทธ์ธ ๋งค๋‹ˆํŽ˜์ŠคํŠธ ๋‚ด์—์„œ ์ง์ ‘ MCP ์„œ๋ฒ„ ์ •์˜ + +ํ”Œ๋Ÿฌ๊ทธ์ธ ์„ค์น˜ ๋””๋ ‰ํ† ๋ฆฌ์— ์ƒ๋Œ€์ ์ธ ๊ฒฝ๋กœ๋ฅผ ์ฐธ์กฐํ•˜๋ ค๋ฉด `${CLAUDE_PLUGIN_ROOT}` ๋ณ€์ˆ˜๋ฅผ ์‚ฌ์šฉํ•˜์„ธ์š”. + +```json +{ + "mcpServers": { + "plugin-tools": { + "command": "node", + "args": ["${CLAUDE_PLUGIN_ROOT}/dist/mcp-server.js"], + "env": { + "CONFIG_PATH": "${CLAUDE_PLUGIN_ROOT}/config.json" + } + } + } +} +``` + +## ์„œ๋ธŒ์—์ด์ „ํŠธ ์Šค์ฝ”ํ”„ MCP + +MCP ์„œ๋ฒ„๋Š” ์—์ด์ „ํŠธ ์ „๋ฉด(frontmatter) ๋‚ด `mcpServers:` ํ‚ค๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ์ธ๋ผ์ธ์œผ๋กœ ์ •์˜ํ•  ์ˆ˜ ์žˆ์œผ๋ฉฐ, ์ „์ฒด ํ”„๋กœ์ ํŠธ๊ฐ€ ์•„๋‹Œ ํŠน์ • ์„œ๋ธŒ์—์ด์ „ํŠธ๋กœ ๋ฒ”์œ„๊ฐ€ ์ง€์ •๋ฉ๋‹ˆ๋‹ค. ์ด๋Š” ์›Œํฌํ”Œ๋กœ์šฐ์˜ ๋‹ค๋ฅธ ์—์ด์ „ํŠธ๊ฐ€ ํ•„์š”๋กœ ํ•˜์ง€ ์•Š๋Š” ํŠน์ • MCP ์„œ๋ฒ„์— ์—์ด์ „ํŠธ๊ฐ€ ์ ‘๊ทผํ•ด์•ผ ํ•  ๋•Œ ์œ ์šฉํ•ฉ๋‹ˆ๋‹ค. + +```yaml +--- +mcpServers: + my-tool: + type: http + url: https://my-tool.example.com/mcp +--- + +You are an agent with access to my-tool for specialized operations. +``` + +์„œ๋ธŒ์—์ด์ „ํŠธ ์Šค์ฝ”ํ”„ MCP ์„œ๋ฒ„๋Š” ํ•ด๋‹น ์—์ด์ „ํŠธ์˜ ์‹คํ–‰ ์ปจํ…์ŠคํŠธ ๋‚ด์—์„œ๋งŒ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์œผ๋ฉฐ, ๋ถ€๋ชจ ๋˜๋Š” ํ˜•์ œ ์—์ด์ „ํŠธ์™€ ๊ณต์œ ๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. + +## MCP ์ถœ๋ ฅ ์ œํ•œ + +Claude Code๋Š” ์ปจํ…์ŠคํŠธ ์˜ค๋ฒ„ํ”Œ๋กœ์šฐ๋ฅผ ๋ฐฉ์ง€ํ•˜๊ธฐ ์œ„ํ•ด MCP ๋„๊ตฌ ์ถœ๋ ฅ์— ์ œํ•œ์„ ์ ์šฉํ•ฉ๋‹ˆ๋‹ค. + +| Limit | Threshold | Behavior | +|-------|-----------|----------| +| **๊ฒฝ๊ณ ** | 10,000 ํ† ํฐ | ์ถœ๋ ฅ์ด ํฌ๋‹ค๋Š” ๊ฒฝ๊ณ ๊ฐ€ ํ‘œ์‹œ๋ฉ๋‹ˆ๋‹ค. | +| **๊ธฐ๋ณธ ์ตœ๋Œ€๊ฐ’** | 25,000 ํ† ํฐ | ์ด ์ œํ•œ์„ ์ดˆ๊ณผํ•˜๋Š” ์ถœ๋ ฅ์€ ์ž˜๋ฆฝ๋‹ˆ๋‹ค. | +| **๋””์Šคํฌ ์˜์†์„ฑ** | 50,000 ๋ฌธ์ž | 5๋งŒ ๋ฌธ์ž๋ฅผ ์ดˆ๊ณผํ•˜๋Š” ๋„๊ตฌ ๊ฒฐ๊ณผ๋Š” ๋””์Šคํฌ์— ์˜๊ตฌ์ ์œผ๋กœ ์ €์žฅ๋ฉ๋‹ˆ๋‹ค. | + +์ตœ๋Œ€ ์ถœ๋ ฅ ์ œํ•œ์€ `MAX_MCP_OUTPUT_TOKENS` ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋ฅผ ํ†ตํ•ด ๊ตฌ์„ฑํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +```bash +# Increase the max output to 50,000 tokens +export MAX_MCP_OUTPUT_TOKENS=50000 +``` + +## ์ฝ”๋“œ ์‹คํ–‰์œผ๋กœ ์ปจํ…์ŠคํŠธ ๋น„๋Œ€ํ™” ํ•ด๊ฒฐ + +MCP ์ฑ„ํƒ์ด ํ™•๋Œ€๋จ์— ๋”ฐ๋ผ ์ˆ˜์‹ญ ๊ฐœ์˜ ์„œ๋ฒ„์— ์ˆ˜๋ฐฑ ๋˜๋Š” ์ˆ˜์ฒœ ๊ฐœ์˜ ๋„๊ตฌ๋ฅผ ์—ฐ๊ฒฐํ•˜๋Š” ๊ฒƒ์€ **์ปจํ…์ŠคํŠธ ๋น„๋Œ€ํ™”**๋ผ๋Š” ์‹ฌ๊ฐํ•œ ๋ฌธ์ œ๋ฅผ ์•ผ๊ธฐํ•ฉ๋‹ˆ๋‹ค. ์ด๊ฒƒ์€ MCP๊ฐ€ ๋Œ€๊ทœ๋ชจ๋กœ ์ง๋ฉดํ•˜๋Š” ๊ฐ€์žฅ ํฐ ๋ฌธ์ œ์ด๋ฉฐ, Anthropic์˜ ์—”์ง€๋‹ˆ์–ด๋ง ํŒ€์€ ์ง์ ‘ ๋„๊ตฌ ํ˜ธ์ถœ ๋Œ€์‹  ์ฝ”๋“œ ์‹คํ–‰์„ ์‚ฌ์šฉํ•˜๋Š” ์šฐ์•„ํ•œ ํ•ด๊ฒฐ์ฑ…์„ ์ œ์‹œํ–ˆ์Šต๋‹ˆ๋‹ค. + +> **์ถœ์ฒ˜**: [MCP๋ฅผ ์‚ฌ์šฉํ•œ ์ฝ”๋“œ ์‹คํ–‰: ๋” ํšจ์œจ์ ์ธ ์—์ด์ „ํŠธ ๊ตฌ์ถ•](https://www.anthropic.com/engineering/code-execution-with-mcp) โ€” Anthropic ์—”์ง€๋‹ˆ์–ด๋ง ๋ธ”๋กœ๊ทธ + +### ๋ฌธ์ œ: ํ† ํฐ ๋‚ญ๋น„์˜ ๋‘ ๊ฐ€์ง€ ์›์ธ + +**1. ๋„๊ตฌ ์ •์˜๊ฐ€ ์ปจํ…์ŠคํŠธ ์ฐฝ์„ ๊ณผ๋ถ€ํ•˜์‹œํ‚ต๋‹ˆ๋‹ค.** + +๋Œ€๋ถ€๋ถ„์˜ MCP ํด๋ผ์ด์–ธํŠธ๋Š” ๋ชจ๋“  ๋„๊ตฌ ์ •์˜๋ฅผ ๋ฏธ๋ฆฌ ๋กœ๋“œํ•ฉ๋‹ˆ๋‹ค. ์ˆ˜์ฒœ ๊ฐœ์˜ ๋„๊ตฌ์— ์—ฐ๊ฒฐ๋˜๋ฉด ๋ชจ๋ธ์€ ์‚ฌ์šฉ์ž ์š”์ฒญ์„ ์ฝ๊ธฐ๋„ ์ „์— ์ˆ˜์‹ญ๋งŒ ๊ฐœ์˜ ํ† ํฐ์„ ์ฒ˜๋ฆฌํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. + +**2. ์ค‘๊ฐ„ ๊ฒฐ๊ณผ๊ฐ€ ์ถ”๊ฐ€ ํ† ํฐ์„ ์†Œ๋น„ํ•ฉ๋‹ˆ๋‹ค.** + +๋ชจ๋“  ์ค‘๊ฐ„ ๋„๊ตฌ ๊ฒฐ๊ณผ๋Š” ๋ชจ๋ธ์˜ ์ปจํ…์ŠคํŠธ๋ฅผ ํ†ต๊ณผํ•ฉ๋‹ˆ๋‹ค. Google Drive์—์„œ Salesforce๋กœ ํšŒ์˜๋ก์„ ์ „์†กํ•˜๋Š” ๊ฒƒ์„ ์ƒ๊ฐํ•ด ๋ณด์„ธ์š”. ์ „์ฒด ํšŒ์˜๋ก์€ ์ปจํ…์ŠคํŠธ๋ฅผ **๋‘ ๋ฒˆ** ํ†ต๊ณผํ•ฉ๋‹ˆ๋‹ค. ํ•œ ๋ฒˆ์€ ์ฝ์„ ๋•Œ, ๋˜ ํ•œ ๋ฒˆ์€ ๋Œ€์ƒ์— ์“ธ ๋•Œ์ž…๋‹ˆ๋‹ค. 2์‹œ๊ฐ„์งœ๋ฆฌ ํšŒ์˜๋ก์€ 50,000๊ฐœ ์ด์ƒ์˜ ์ถ”๊ฐ€ ํ† ํฐ์„ ์˜๋ฏธํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +```mermaid +graph LR + A["Model"] -->|"Tool Call: getDocument"| B["MCP Server"] + B -->|"Full transcript (50K tokens)"| A + A -->|"Tool Call: updateRecord
(re-sends full transcript)"| B + B -->|"Confirmation"| A + + style A fill:#ffcdd2,stroke:#333,color:#333 + style B fill:#f3e5f5,stroke:#333,color:#333 +``` + +### ํ•ด๊ฒฐ์ฑ…: ์ฝ”๋“œ API๋กœ์„œ์˜ MCP ๋„๊ตฌ + +๋„๊ตฌ ์ •์˜์™€ ๊ฒฐ๊ณผ๋ฅผ ์ปจํ…์ŠคํŠธ ์ฐฝ์„ ํ†ตํ•ด ์ „๋‹ฌํ•˜๋Š” ๋Œ€์‹ , ์—์ด์ „ํŠธ๋Š” MCP ๋„๊ตฌ๋ฅผ API๋กœ ํ˜ธ์ถœํ•˜๋Š” **์ฝ”๋“œ๋ฅผ ์ž‘์„ฑ**ํ•ฉ๋‹ˆ๋‹ค. ์ฝ”๋“œ๋Š” ์ƒŒ๋“œ๋ฐ•์Šค ์‹คํ–‰ ํ™˜๊ฒฝ์—์„œ ์‹คํ–‰๋˜๋ฉฐ, ์ตœ์ข… ๊ฒฐ๊ณผ๋งŒ ๋ชจ๋ธ๋กœ ๋ฐ˜ํ™˜๋ฉ๋‹ˆ๋‹ค. + +```mermaid +graph LR + A["Model"] -->|"Writes code"| B["Code Execution
Environment"] + B -->|"Calls tools directly"| C["MCP Servers"] + C -->|"Data stays in
execution env"| B + B -->|"Only final result
(minimal tokens)"| A + + style A fill:#c8e6c9,stroke:#333,color:#333 + style B fill:#e1f5fe,stroke:#333,color:#333 + style C fill:#f3e5f5,stroke:#333,color:#333 +``` + +#### ์ž‘๋™ ๋ฐฉ์‹ + +MCP ๋„๊ตฌ๋Š” ํƒ€์ž…์ด ์ง€์ •๋œ ํ•จ์ˆ˜๋“ค์˜ ํŒŒ์ผ ํŠธ๋ฆฌ๋กœ ์ œ๊ณต๋ฉ๋‹ˆ๋‹ค. + +``` +servers/ +โ”œโ”€โ”€ google-drive/ +โ”‚ โ”œโ”€โ”€ getDocument.ts +โ”‚ โ””โ”€โ”€ index.ts +โ”œโ”€โ”€ salesforce/ +โ”‚ โ”œโ”€โ”€ updateRecord.ts +โ”‚ โ””โ”€โ”€ index.ts +โ””โ”€โ”€ ... +``` + +๊ฐ ๋„๊ตฌ ํŒŒ์ผ์€ ํƒ€์ž…์ด ์ง€์ •๋œ ๋ž˜ํผ๋ฅผ ํฌํ•จํ•ฉ๋‹ˆ๋‹ค. + +```typescript +// ./servers/google-drive/getDocument.ts +import { callMCPTool } from "../../../client.js"; + +interface GetDocumentInput { + documentId: string; +} + +interface GetDocumentResponse { + content: string; +} + +export async function getDocument( + input: GetDocumentInput +): Promise { + return callMCPTool( + 'google_drive__get_document', input + ); +} +``` + +์—์ด์ „ํŠธ๋Š” ๋„๊ตฌ๋ฅผ ์กฐ์œจํ•˜๋Š” ์ฝ”๋“œ๋ฅผ ์ž‘์„ฑํ•ฉ๋‹ˆ๋‹ค. + +```typescript +import * as gdrive from './servers/google-drive'; +import * as salesforce from './servers/salesforce'; + +// Data flows directly between tools โ€” never through the model +const transcript = ( + await gdrive.getDocument({ documentId: 'abc123' }) +).content; + +await salesforce.updateRecord({ + objectType: 'SalesMeeting', + recordId: '00Q5f000001abcXYZ', + data: { Notes: transcript } +}); +``` + +**๊ฒฐ๊ณผ: ํ† ํฐ ์‚ฌ์šฉ๋Ÿ‰์ด ์•ฝ 150,000๊ฐœ์—์„œ ์•ฝ 2,000๊ฐœ๋กœ ๊ฐ์†Œํ•ฉ๋‹ˆ๋‹ค. ์ด๋Š” 98.7% ๊ฐ์†Œํ•œ ์ˆ˜์น˜์ž…๋‹ˆ๋‹ค.** + +### ์ฃผ์š” ์ด์  + +| Benefit | Description | +|---------|-------------| +| **์ ์ง„์  ๋…ธ์ถœ** | ์—์ด์ „ํŠธ๋Š” ๋ชจ๋“  ๋„๊ตฌ๋ฅผ ํ•œ ๋ฒˆ์— ๋กœ๋“œํ•˜๋Š” ๋Œ€์‹  ํŒŒ์ผ ์‹œ์Šคํ…œ์„ ํƒ์ƒ‰ํ•˜์—ฌ ํ•„์š”ํ•œ ๋„๊ตฌ ์ •์˜๋งŒ ๋กœ๋“œํ•ฉ๋‹ˆ๋‹ค. | +| **์ปจํ…์ŠคํŠธ ํšจ์œจ์ ์ธ ๊ฒฐ๊ณผ** | ๋ฐ์ดํ„ฐ๋Š” ๋ชจ๋ธ๋กœ ๋ฐ˜ํ™˜๋˜๊ธฐ ์ „์— ์‹คํ–‰ ํ™˜๊ฒฝ์—์„œ ํ•„ํ„ฐ๋ง/๋ณ€ํ™˜๋ฉ๋‹ˆ๋‹ค. | +| **๊ฐ•๋ ฅํ•œ ์ œ์–ด ํ๋ฆ„** | ๋ฃจํ”„, ์กฐ๊ฑด๋ฌธ ๋ฐ ์˜ค๋ฅ˜ ์ฒ˜๋ฆฌ๊ฐ€ ๋ชจ๋ธ์„ ์™•๋ณตํ•˜์ง€ ์•Š๊ณ  ์ฝ”๋“œ์—์„œ ์‹คํ–‰๋ฉ๋‹ˆ๋‹ค. | +| **๊ฐœ์ธ ์ •๋ณด ๋ณดํ˜ธ** | ์ค‘๊ฐ„ ๋ฐ์ดํ„ฐ (PII, ๋ฏผ๊ฐํ•œ ๊ธฐ๋ก)๋Š” ์‹คํ–‰ ํ™˜๊ฒฝ์— ๋‚จ์•„ ์žˆ์œผ๋ฉฐ ๋ชจ๋ธ ์ปจํ…์ŠคํŠธ์— ์ ˆ๋Œ€ ๋“ค์–ด๊ฐ€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. | +| **์ƒํƒœ ์˜์†์„ฑ** | ์—์ด์ „ํŠธ๋Š” ์ค‘๊ฐ„ ๊ฒฐ๊ณผ๋ฅผ ํŒŒ์ผ์— ์ €์žฅํ•˜๊ณ  ์žฌ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ์Šคํ‚ฌ ํ•จ์ˆ˜๋ฅผ ๊ตฌ์ถ•ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. | + +#### ์˜ˆ์‹œ: ๋Œ€๊ทœ๋ชจ ๋ฐ์ดํ„ฐ ์„ธํŠธ ํ•„ํ„ฐ๋ง + +```typescript +// Without code execution โ€” all 10,000 rows flow through context +// TOOL CALL: gdrive.getSheet(sheetId: 'abc123') +// -> returns 10,000 rows in context + +// With code execution โ€” filter in the execution environment +const allRows = await gdrive.getSheet({ sheetId: 'abc123' }); +const pendingOrders = allRows.filter( + row => row["Status"] === 'pending' +); +console.log(`Found ${pendingOrders.length} pending orders`); +console.log(pendingOrders.slice(0, 5)); // Only 5 rows reach the model +``` + +#### ์˜ˆ์‹œ: ์™•๋ณต ์—†์ด ๋ฃจํ”„ ์‹คํ–‰ + +```typescript +// Poll for a deployment notification โ€” runs entirely in code +let found = false; +while (!found) { + const messages = await slack.getChannelHistory({ + channel: 'C123456' + }); + found = messages.some( + m => m.text.includes('deployment complete') + ); + if (!found) await new Promise(r => setTimeout(r, 5000)); +} +console.log('Deployment notification received'); +``` + +### ๊ณ ๋ คํ•  ์ ˆ์ถฉ์•ˆ + +์ฝ”๋“œ ์‹คํ–‰์€ ๊ทธ ์ž์ฒด๋กœ ๋ณต์žก์„ฑ์„ ์•ผ๊ธฐํ•ฉ๋‹ˆ๋‹ค. ์—์ด์ „ํŠธ ์ƒ์„ฑ ์ฝ”๋“œ๋ฅผ ์‹คํ–‰ํ•˜๋ ค๋ฉด ๋‹ค์Œ์ด ํ•„์š”ํ•ฉ๋‹ˆ๋‹ค. + +- ์ ์ ˆํ•œ ๋ฆฌ์†Œ์Šค ์ œํ•œ์ด ์žˆ๋Š” **์•ˆ์ „ํ•œ ์ƒŒ๋“œ๋ฐ•์Šค ์‹คํ–‰ ํ™˜๊ฒฝ** +- ์‹คํ–‰๋œ ์ฝ”๋“œ์— ๋Œ€ํ•œ **๋ชจ๋‹ˆํ„ฐ๋ง ๋ฐ ๋กœ๊น…** +- ์ง์ ‘ ๋„๊ตฌ ํ˜ธ์ถœ์— ๋น„ํ•ด ์ถ”๊ฐ€์ ์ธ **์ธํ”„๋ผ ์˜ค๋ฒ„ํ—ค๋“œ** + +ํ† ํฐ ๋น„์šฉ ์ ˆ๊ฐ, ์ง€์—ฐ ์‹œ๊ฐ„ ๊ฐ์†Œ, ๋„๊ตฌ ๊ตฌ์„ฑ ๊ฐœ์„ ์ด๋ผ๋Š” ์ด์ ์€ ์ด๋Ÿฌํ•œ ๊ตฌํ˜„ ๋น„์šฉ๊ณผ ๋น„๊ตํ•˜์—ฌ ๊ณ ๋ คํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. MCP ์„œ๋ฒ„๊ฐ€ ๋ช‡ ๊ฐœ๋งŒ ์žˆ๋Š” ์—์ด์ „ํŠธ์˜ ๊ฒฝ์šฐ ์ง์ ‘ ๋„๊ตฌ ํ˜ธ์ถœ์ด ๋” ๊ฐ„๋‹จํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ๋Œ€๊ทœ๋ชจ ์—์ด์ „ํŠธ(์ˆ˜์‹ญ ๊ฐœ์˜ ์„œ๋ฒ„, ์ˆ˜๋ฐฑ ๊ฐœ์˜ ๋„๊ตฌ)์˜ ๊ฒฝ์šฐ ์ฝ”๋“œ ์‹คํ–‰์€ ์ƒ๋‹นํ•œ ๊ฐœ์„ ์ž…๋‹ˆ๋‹ค. + +### MCPorter: MCP ๋„๊ตฌ ๊ตฌ์„ฑ์„ ์œ„ํ•œ ๋Ÿฐํƒ€์ž„ + +[MCPorter](https://github.com/steipete/mcporter)๋Š” ์ƒ์šฉ๊ตฌ ์—†์ด MCP ์„œ๋ฒ„ ํ˜ธ์ถœ์„ ์‹ค์šฉ์ ์œผ๋กœ ๋งŒ๋“ค๊ณ  ์„ ํƒ์  ๋„๊ตฌ ๋…ธ์ถœ ๋ฐ ์œ ํ˜•ํ™”๋œ ๋ž˜ํผ๋ฅผ ํ†ตํ•ด ์ปจํ…์ŠคํŠธ ๋น„๋Œ€ํ™”๋ฅผ ์ค„์ด๋Š” ๋ฐ ๋„์›€์ด ๋˜๋Š” TypeScript ๋Ÿฐํƒ€์ž„ ๋ฐ CLI ํˆดํ‚ท์ž…๋‹ˆ๋‹ค. + +**ํ•ด๊ฒฐํ•˜๋Š” ๋ฌธ์ œ:** ๋ชจ๋“  MCP ์„œ๋ฒ„์—์„œ ๋ชจ๋“  ๋„๊ตฌ ์ •์˜๋ฅผ ๋ฏธ๋ฆฌ ๋กœ๋“œํ•˜๋Š” ๋Œ€์‹ , MCPorter๋Š” ํ•„์š”์— ๋”ฐ๋ผ ํŠน์ • ๋„๊ตฌ๋ฅผ ๊ฒ€์ƒ‰, ๊ฒ€์‚ฌ ๋ฐ ํ˜ธ์ถœํ•˜์—ฌ ์ปจํ…์ŠคํŠธ๋ฅผ ๊ฐ„๊ฒฐํ•˜๊ฒŒ ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. + +**์ฃผ์š” ๊ธฐ๋Šฅ:** + +| Feature | Description | +|---------|-------------| +| **์ œ๋กœ ๊ตฌ์„ฑ ๊ฒ€์ƒ‰** | Cursor, Claude, Codex ๋˜๋Š” ๋กœ์ปฌ ๊ตฌ์„ฑ์—์„œ MCP ์„œ๋ฒ„๋ฅผ ์ž๋™์œผ๋กœ ๊ฒ€์ƒ‰ํ•ฉ๋‹ˆ๋‹ค. | +| **์œ ํ˜•ํ™”๋œ ๋„๊ตฌ ํด๋ผ์ด์–ธํŠธ** | `mcporter emit-ts`๋Š” `.d.ts` ์ธํ„ฐํŽ˜์ด์Šค์™€ ์ฆ‰์‹œ ์‹คํ–‰ ๊ฐ€๋Šฅํ•œ ๋ž˜ํผ๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. | +| **๊ตฌ์„ฑ ๊ฐ€๋Šฅํ•œ API** | `createServerProxy()`๋Š” `.text()`, `.json()`, `.markdown()` ๋„์šฐ๋ฏธ๊ฐ€ ์žˆ๋Š” camelCase ๋ฉ”์„œ๋“œ๋กœ ๋„๊ตฌ๋ฅผ ๋…ธ์ถœํ•ฉ๋‹ˆ๋‹ค. | +| **CLI ์ƒ์„ฑ** | `mcporter generate-cli`๋Š” `--include-tools` / `--exclude-tools` ํ•„ํ„ฐ๋ง์„ ํ†ตํ•ด ๋ชจ๋“  MCP ์„œ๋ฒ„๋ฅผ ๋…๋ฆฝํ˜• CLI๋กœ ๋ณ€ํ™˜ํ•ฉ๋‹ˆ๋‹ค. | +| **๋งค๊ฐœ๋ณ€์ˆ˜ ์ˆจ๊ธฐ๊ธฐ** | ์„ ํƒ์  ๋งค๊ฐœ๋ณ€์ˆ˜๋Š” ๊ธฐ๋ณธ์ ์œผ๋กœ ์ˆจ๊ฒจ์ ธ ์Šคํ‚ค๋งˆ์˜ ์žฅํ™ฉํ•จ์„ ์ค„์ž…๋‹ˆ๋‹ค. | + +**์„ค์น˜:** + +```bash +npx mcporter list # No install required โ€” discover servers instantly +pnpm add mcporter # Add to a project +brew install steipete/tap/mcporter # macOS via Homebrew +``` + +**์˜ˆ์‹œ โ€” TypeScript์—์„œ ๋„๊ตฌ ๊ตฌ์„ฑ:** + +```typescript +import { createRuntime, createServerProxy } from "mcporter"; + +const runtime = await createRuntime(); +const gdrive = createServerProxy(runtime, "google-drive"); +const salesforce = createServerProxy(runtime, "salesforce"); + +// Data flows between tools without passing through the model context +const doc = await gdrive.getDocument({ documentId: "abc123" }); +await salesforce.updateRecord({ + objectType: "SalesMeeting", + recordId: "00Q5f000001abcXYZ", + data: { Notes: doc.text() } +}); +``` + +**์˜ˆ์‹œ โ€” CLI ๋„๊ตฌ ํ˜ธ์ถœ:** + +```bash +# Call a specific tool directly +npx mcporter call linear.create_comment issueId:ENG-123 body:'Looks good!' + +# List available servers and tools +npx mcporter list +``` + +MCPorter๋Š” ์œ„์—์„œ ์„ค๋ช…ํ•œ ์ฝ”๋“œ ์‹คํ–‰ ์ ‘๊ทผ ๋ฐฉ์‹์„ ๋ณด์™„ํ•˜์—ฌ MCP ๋„๊ตฌ๋ฅผ ์œ ํ˜•ํ™”๋œ API๋กœ ํ˜ธ์ถœํ•˜๊ธฐ ์œ„ํ•œ ๋Ÿฐํƒ€์ž„ ์ธํ”„๋ผ๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. ์ด๋ฅผ ํ†ตํ•ด ์ค‘๊ฐ„ ๋ฐ์ดํ„ฐ๋ฅผ ๋ชจ๋ธ ์ปจํ…์ŠคํŠธ ์™ธ๋ถ€์— ์œ ์ง€ํ•˜๋Š” ๊ฒƒ์„ ๊ฐ„์†Œํ™”ํ•ฉ๋‹ˆ๋‹ค. + +## ๋ชจ๋ฒ” ์‚ฌ๋ก€ + +### ๋ณด์•ˆ ๊ณ ๋ ค ์‚ฌํ•ญ + +#### ํ•ด์•ผ ํ•  ์ผ โœ… +- ๋ชจ๋“  ์ž๊ฒฉ ์ฆ๋ช…์— ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋ฅผ ์‚ฌ์šฉํ•˜์„ธ์š”. +- ํ† ํฐ ๋ฐ API ํ‚ค๋ฅผ ์ •๊ธฐ์ ์œผ๋กœ (๋งค์›” ๊ถŒ์žฅ) ๊ต์ฒดํ•˜์„ธ์š”. +- ๊ฐ€๋Šฅํ•œ ๊ฒฝ์šฐ ์ฝ๊ธฐ ์ „์šฉ ํ† ํฐ์„ ์‚ฌ์šฉํ•˜์„ธ์š”. +- MCP ์„œ๋ฒ„ ์ ‘๊ทผ ๋ฒ”์œ„๋ฅผ ํ•„์š”ํ•œ ์ตœ์†Œํ•œ์œผ๋กœ ์ œํ•œํ•˜์„ธ์š”. +- MCP ์„œ๋ฒ„ ์‚ฌ์šฉ๋Ÿ‰ ๋ฐ ์ ‘๊ทผ ๋กœ๊ทธ๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”. +- ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ๊ฒฝ์šฐ ์™ธ๋ถ€ ์„œ๋น„์Šค์— OAuth๋ฅผ ์‚ฌ์šฉํ•˜์„ธ์š”. +- MCP ์š”์ฒญ์— ์†๋„ ์ œํ•œ์„ ๊ตฌํ˜„ํ•˜์„ธ์š”. +- ์šด์˜ ํ™˜๊ฒฝ์— ๋ฐฐํฌํ•˜๊ธฐ ์ „์— MCP ์—ฐ๊ฒฐ์„ ํ…Œ์ŠคํŠธํ•˜์„ธ์š”. +- ๋ชจ๋“  ํ™œ์„ฑ MCP ์—ฐ๊ฒฐ์„ ๋ฌธ์„œํ™”ํ•˜์„ธ์š”. +- MCP ์„œ๋ฒ„ ํŒจํ‚ค์ง€๋ฅผ ์ตœ์‹  ์ƒํƒœ๋กœ ์œ ์ง€ํ•˜์„ธ์š”. + +#### ํ•˜์ง€ ๋ง์•„์•ผ ํ•  ์ผ โŒ +- ๊ตฌ์„ฑ ํŒŒ์ผ์— ์ž๊ฒฉ ์ฆ๋ช…์„ ํ•˜๋“œ์ฝ”๋”ฉํ•˜์ง€ ๋งˆ์„ธ์š”. +- ํ† ํฐ์ด๋‚˜ ๋น„๋ฐ€ ์ •๋ณด๋ฅผ Git์— ์ปค๋ฐ‹ํ•˜์ง€ ๋งˆ์„ธ์š”. +- ํŒ€ ์ฑ„ํŒ…์ด๋‚˜ ์ด๋ฉ”์ผ๋กœ ํ† ํฐ์„ ๊ณต์œ ํ•˜์ง€ ๋งˆ์„ธ์š”. +- ํŒ€ ํ”„๋กœ์ ํŠธ์— ๊ฐœ์ธ ํ† ํฐ์„ ์‚ฌ์šฉํ•˜์ง€ ๋งˆ์„ธ์š”. +- ๋ถˆํ•„์š”ํ•œ ๊ถŒํ•œ์„ ๋ถ€์—ฌํ•˜์ง€ ๋งˆ์„ธ์š”. +- ์ธ์ฆ ์˜ค๋ฅ˜๋ฅผ ๋ฌด์‹œํ•˜์ง€ ๋งˆ์„ธ์š”. +- MCP ์—”๋“œํฌ์ธํŠธ๋ฅผ ๊ณต๊ฐœ์ ์œผ๋กœ ๋…ธ์ถœํ•˜์ง€ ๋งˆ์„ธ์š”. +- root/๊ด€๋ฆฌ์ž ๊ถŒํ•œ์œผ๋กœ MCP ์„œ๋ฒ„๋ฅผ ์‹คํ–‰ํ•˜์ง€ ๋งˆ์„ธ์š”. +- ๋ฏผ๊ฐํ•œ ๋ฐ์ดํ„ฐ๋ฅผ ๋กœ๊ทธ์— ์บ์‹œํ•˜์ง€ ๋งˆ์„ธ์š”. +- ์ธ์ฆ ๋ฉ”์ปค๋‹ˆ์ฆ˜์„ ๋น„ํ™œ์„ฑํ™”ํ•˜์ง€ ๋งˆ์„ธ์š”. + +### ๊ตฌ์„ฑ ๋ชจ๋ฒ” ์‚ฌ๋ก€ + +1. **๋ฒ„์ „ ๊ด€๋ฆฌ**: `.mcp.json`์€ Git์— ๋ณด๊ด€ํ•˜๋˜, ๋น„๋ฐ€ ์ •๋ณด์—๋Š” ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋ฅผ ์‚ฌ์šฉํ•˜์„ธ์š”. +2. **์ตœ์†Œ ๊ถŒํ•œ**: ๊ฐ MCP ์„œ๋ฒ„์— ํ•„์š”ํ•œ ์ตœ์†Œํ•œ์˜ ๊ถŒํ•œ์„ ๋ถ€์—ฌํ•˜์„ธ์š”. +3. **๊ฒฉ๋ฆฌ**: ๊ฐ€๋Šฅํ•œ ๊ฒฝ์šฐ ๋‹ค๋ฅธ MCP ์„œ๋ฒ„๋ฅผ ๋ณ„๋„์˜ ํ”„๋กœ์„ธ์Šค์—์„œ ์‹คํ–‰ํ•˜์„ธ์š”. +4. **๋ชจ๋‹ˆํ„ฐ๋ง**: ๊ฐ์‚ฌ ์ถ”์ ์„ ์œ„ํ•ด ๋ชจ๋“  MCP ์š”์ฒญ ๋ฐ ์˜ค๋ฅ˜๋ฅผ ๊ธฐ๋กํ•˜์„ธ์š”. +5. **ํ…Œ์ŠคํŠธ**: ํ”„๋กœ๋•์…˜ ํ™˜๊ฒฝ์— ๋ฐฐํฌํ•˜๊ธฐ ์ „์— ๋ชจ๋“  MCP ๊ตฌ์„ฑ์„ ํ…Œ์ŠคํŠธํ•˜์„ธ์š”. + +### ์„ฑ๋Šฅ ํŒ + +- ์ž์ฃผ ์ ‘๊ทผํ•˜๋Š” ๋ฐ์ดํ„ฐ๋Š” ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜ ์ˆ˜์ค€์—์„œ ์บ์‹œํ•˜์„ธ์š”. +- ๋ฐ์ดํ„ฐ ์ „์†ก์„ ์ค„์ด๊ธฐ ์œ„ํ•ด ํŠน์ • MCP ์ฟผ๋ฆฌ๋ฅผ ์‚ฌ์šฉํ•˜์„ธ์š”. +- MCP ์ž‘์—…์˜ ์‘๋‹ต ์‹œ๊ฐ„์„ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜์„ธ์š”. +- ์™ธ๋ถ€ API์— ๋Œ€ํ•œ ์†๋„ ์ œํ•œ์„ ๊ณ ๋ คํ•˜์„ธ์š”. +- ์—ฌ๋Ÿฌ ์ž‘์—…์„ ์ˆ˜ํ–‰ํ•  ๋•Œ ๋ฐฐ์น˜ ์ฒ˜๋ฆฌ๋ฅผ ์‚ฌ์šฉํ•˜์„ธ์š”. + +## ์„ค์น˜ ์ง€์นจ + +### ์ „์ œ ์กฐ๊ฑด +- Node.js ๋ฐ npm ์„ค์น˜๋จ +- Claude Code CLI ์„ค์น˜๋จ +- ์™ธ๋ถ€ ์„œ๋น„์Šค๋ฅผ ์œ„ํ•œ API ํ† ํฐ/์ž๊ฒฉ ์ฆ๋ช… + +### ๋‹จ๊ณ„๋ณ„ ์„ค์ • + +1. CLI๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ **์ฒซ ๋ฒˆ์งธ MCP ์„œ๋ฒ„๋ฅผ ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค** (์˜ˆ: GitHub): +```bash +claude mcp add --transport stdio github -- npx @modelcontextprotocol/server-github +``` + + ๋˜๋Š” ํ”„๋กœ์ ํŠธ ๋ฃจํŠธ์— `.mcp.json` ํŒŒ์ผ์„ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค: +```json +{ + "mcpServers": { + "github": { + "command": "npx", + "args": ["@modelcontextprotocol/server-github"], + "env": { + "GITHUB_TOKEN": "${GITHUB_TOKEN}" + } + } + } +} +``` + +2. **ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋ฅผ ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค:** +```bash +export GITHUB_TOKEN="your_github_personal_access_token" +``` + +3. **์—ฐ๊ฒฐ์„ ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค:** +```bash +claude /mcp +``` + +4. **MCP ๋„๊ตฌ๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค:** +```bash +/mcp__github__list_prs +/mcp__github__create_issue "Title" "Description" +``` + +### ํŠน์ • ์„œ๋น„์Šค ์„ค์น˜ + +**GitHub MCP:** +```bash +npm install -g @modelcontextprotocol/server-github +``` + +**๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค MCP:** +```bash +npm install -g @modelcontextprotocol/server-database +``` + +**ํŒŒ์ผ ์‹œ์Šคํ…œ MCP:** +```bash +npm install -g @modelcontextprotocol/server-filesystem +``` + +**Slack MCP:** +```bash +npm install -g @modelcontextprotocol/server-slack +``` + +## ๋ฌธ์ œ ํ•ด๊ฒฐ + +### MCP ์„œ๋ฒ„๋ฅผ ์ฐพ์„ ์ˆ˜ ์—†์Œ +```bash +# Verify MCP server is installed +npm list -g @modelcontextprotocol/server-github + +# Install if missing +npm install -g @modelcontextprotocol/server-github +``` + +### ์ธ์ฆ ์‹คํŒจ +```bash +# Verify environment variable is set +echo $GITHUB_TOKEN + +# Re-export if needed +export GITHUB_TOKEN="your_token" + +# Verify token has correct permissions +# Check GitHub token scopes at: https://github.com/settings/tokens +``` + +### ์—ฐ๊ฒฐ ์‹œ๊ฐ„ ์ดˆ๊ณผ +- ๋„คํŠธ์›Œํฌ ์—ฐ๊ฒฐ ํ™•์ธ: `ping api.github.com` +- API ์—”๋“œํฌ์ธํŠธ ์ ‘๊ทผ ๊ฐ€๋Šฅ์„ฑ ํ™•์ธ +- API์˜ ์†๋„ ์ œํ•œ ํ™•์ธ +- ๊ตฌ์„ฑ์—์„œ ์‹œ๊ฐ„ ์ดˆ๊ณผ ๊ฐ’ ๋Š˜๋ ค๋ณด๊ธฐ +- ๋ฐฉํ™”๋ฒฝ ๋˜๋Š” ํ”„๋ก์‹œ ๋ฌธ์ œ ํ™•์ธ + +### MCP ์„œ๋ฒ„ ์ถฉ๋Œ +- MCP ์„œ๋ฒ„ ๋กœ๊ทธ ํ™•์ธ: `~/.claude/logs/` +- ๋ชจ๋“  ํ™˜๊ฒฝ ๋ณ€์ˆ˜๊ฐ€ ์„ค์ •๋˜์–ด ์žˆ๋Š”์ง€ ํ™•์ธ +- ์ ์ ˆํ•œ ํŒŒ์ผ ๊ถŒํ•œ ํ™•์ธ +- MCP ์„œ๋ฒ„ ํŒจํ‚ค์ง€ ์žฌ์„ค์น˜ ์‹œ๋„ +- ๋™์ผํ•œ ํฌํŠธ์—์„œ ์ถฉ๋Œํ•˜๋Š” ํ”„๋กœ์„ธ์Šค ํ™•์ธ + +## ๊ด€๋ จ ๊ฐœ๋… + +### Memory vs MCP +- **Memory**: ์˜๊ตฌ์ ์ด๊ณ  ๋ณ€ํ•˜์ง€ ์•Š๋Š” ๋ฐ์ดํ„ฐ(๊ธฐ๋ณธ ์„ค์ •, ์ปจํ…์ŠคํŠธ, ๊ธฐ๋ก)๋ฅผ ์ €์žฅํ•ฉ๋‹ˆ๋‹ค. +- **MCP**: ์‹ค์‹œ๊ฐ„์œผ๋กœ ๋ณ€ํ•˜๋Š” ๋ฐ์ดํ„ฐ(API, ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค, ์‹ค์‹œ๊ฐ„ ์„œ๋น„์Šค)์— ์ ‘๊ทผํ•ฉ๋‹ˆ๋‹ค. + +### ๊ฐ๊ฐ์„ ์‚ฌ์šฉํ•˜๋Š” ์‹œ๊ธฐ +- **Memory ์‚ฌ์šฉ ์‹œ๊ธฐ**: ์‚ฌ์šฉ์ž ๊ธฐ๋ณธ ์„ค์ •, ๋Œ€ํ™” ๊ธฐ๋ก, ํ•™์Šต๋œ ์ปจํ…์ŠคํŠธ +- **MCP ์‚ฌ์šฉ ์‹œ๊ธฐ**: ํ˜„์žฌ GitHub ์ด์Šˆ, ์‹ค์‹œ๊ฐ„ ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ์ฟผ๋ฆฌ, ์‹ค์‹œ๊ฐ„ ๋ฐ์ดํ„ฐ + +### ๋‹ค๋ฅธ Claude ๊ธฐ๋Šฅ๊ณผ์˜ ํ†ตํ•ฉ +- ํ’๋ถ€ํ•œ ์ปจํ…์ŠคํŠธ๋ฅผ ์œ„ํ•ด MCP๋ฅผ Memory์™€ ๊ฒฐํ•ฉ +- ๋” ๋‚˜์€ ์ถ”๋ก ์„ ์œ„ํ•ด ํ”„๋กฌํ”„ํŠธ์—์„œ MCP ๋„๊ตฌ ์‚ฌ์šฉ +- ๋ณต์žกํ•œ ์›Œํฌํ”Œ๋กœ์šฐ๋ฅผ ์œ„ํ•ด ์—ฌ๋Ÿฌ MCP ํ™œ์šฉ + +## ์ถ”๊ฐ€ ์ž๋ฃŒ + +- [๊ณต์‹ MCP ๋ฌธ์„œ](https://code.claude.com/docs/en/mcp) +- [MCP ํ”„๋กœํ† ์ฝœ ์‚ฌ์–‘](https://modelcontextprotocol.io/specification) +- [MCP GitHub ์ €์žฅ์†Œ](https://github.com/modelcontextprotocol/servers) +- [์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ MCP ์„œ๋ฒ„](https://github.com/modelcontextprotocol/servers) +- [MCPorter](https://github.com/steipete/mcporter) โ€” ์ƒ์šฉ๊ตฌ ์—†์ด MCP ์„œ๋ฒ„๋ฅผ ํ˜ธ์ถœํ•˜๊ธฐ ์œ„ํ•œ TypeScript ๋Ÿฐํƒ€์ž„ ๋ฐ CLI +- [MCP๋ฅผ ์‚ฌ์šฉํ•œ ์ฝ”๋“œ ์‹คํ–‰](https://www.anthropic.com/engineering/code-execution-with-mcp) โ€” ์ปจํ…์ŠคํŠธ ๋น„๋Œ€ํ™” ํ•ด๊ฒฐ์— ๋Œ€ํ•œ Anthropic์˜ ์—”์ง€๋‹ˆ์–ด๋ง ๋ธ”๋กœ๊ทธ +- [Claude Code CLI ์ฐธ์กฐ](https://code.claude.com/docs/en/cli-reference) +- [Claude API ๋ฌธ์„œ](https://docs.anthropic.com) + +--- + +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: 2026๋…„ 6์›” 28์ผ +**Claude Code ๋ฒ„์ „**: 2.1.195 +**์ถœ์ฒ˜**: +- https://code.claude.com/docs/en/mcp +- https://code.claude.com/docs/en/changelog +- https://github.com/anthropics/claude-code/releases/tag/v2.1.117 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.139 +- https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md +- https://docs.anthropic.com/en/docs/claude-code/mcp +**ํ˜ธํ™˜ ๋ชจ๋ธ**: Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5 diff --git a/ko/05-mcp/database-mcp.json b/ko/05-mcp/database-mcp.json new file mode 100644 index 00000000..eaa832a3 --- /dev/null +++ b/ko/05-mcp/database-mcp.json @@ -0,0 +1,11 @@ +{ + "mcpServers": { + "database": { + "command": "npx", + "args": ["@modelcontextprotocol/server-database"], + "env": { + "DATABASE_URL": "postgresql://user:pass@localhost/mydb" + } + } + } +} diff --git a/ko/05-mcp/filesystem-mcp.json b/ko/05-mcp/filesystem-mcp.json new file mode 100644 index 00000000..c76fdf60 --- /dev/null +++ b/ko/05-mcp/filesystem-mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "filesystem": { + "command": "npx", + "args": ["@modelcontextprotocol/server-filesystem", "/home/user/projects"] + } + } +} diff --git a/ko/05-mcp/github-mcp.json b/ko/05-mcp/github-mcp.json new file mode 100644 index 00000000..0f621316 --- /dev/null +++ b/ko/05-mcp/github-mcp.json @@ -0,0 +1,11 @@ +{ + "mcpServers": { + "github": { + "command": "npx", + "args": ["@modelcontextprotocol/server-github"], + "env": { + "GITHUB_TOKEN": "${GITHUB_TOKEN}" + } + } + } +} diff --git a/ko/05-mcp/multi-mcp.json b/ko/05-mcp/multi-mcp.json new file mode 100644 index 00000000..62d8fa5f --- /dev/null +++ b/ko/05-mcp/multi-mcp.json @@ -0,0 +1,29 @@ +{ + "mcpServers": { + "github": { + "command": "npx", + "args": ["@modelcontextprotocol/server-github"], + "env": { + "GITHUB_TOKEN": "${GITHUB_TOKEN}" + } + }, + "database": { + "command": "npx", + "args": ["@modelcontextprotocol/server-database"], + "env": { + "DATABASE_URL": "${DATABASE_URL}" + } + }, + "slack": { + "command": "npx", + "args": ["@modelcontextprotocol/server-slack"], + "env": { + "SLACK_TOKEN": "${SLACK_TOKEN}" + } + }, + "filesystem": { + "command": "npx", + "args": ["@modelcontextprotocol/server-filesystem", "/home/user/projects"] + } + } +} diff --git a/ko/06-hooks/README.md b/ko/06-hooks/README.md new file mode 100644 index 00000000..13e2be55 --- /dev/null +++ b/ko/06-hooks/README.md @@ -0,0 +1,1516 @@ + + + Claude How To + + +# Hooks + +Hooks are automated scripts that execute in response to specific events during Claude Code sessions. They enable automation, validation, permission management, and custom workflows. + +## Overview + +Hooks are automated actions (shell commands, HTTP webhooks, LLM prompts, MCP tool calls, or subagent evaluations) that execute automatically when specific events occur in Claude Code. They receive JSON input and communicate results via exit codes and JSON output. + +**Key features:** +- Event-driven automation +- JSON-based input/output +- Support for `command`, `http`, `mcp_tool`, `prompt`, and `agent` hook types +- Pattern matching for tool-specific hooks + +## Configuration + +Hooks are configured in settings files with a specific structure: + +- `~/.claude/settings.json` - User settings (all projects) +- `.claude/settings.json` - Project settings (shareable, committed) +- `.claude/settings.local.json` - Local project settings (not committed) +- Managed policy - Organization-wide settings +- Plugin `hooks/hooks.json` - Plugin-scoped hooks +- Skill/Agent frontmatter - Component lifetime hooks + +### Basic Configuration Structure + +```json +{ + "hooks": { + "EventName": [ + { + "matcher": "ToolPattern", + "hooks": [ + { + "type": "command", + "command": "your-command-here", + "timeout": 60 + } + ] + } + ] + } +} +``` + +**Key fields:** + +| Field | Description | Example | +|-------|-------------|---------| +| `matcher` | Pattern to match tool names (case-sensitive) | `"Write"`, `"Edit\|Write"`, `"*"` | +| `hooks` | Array of hook definitions | `[{ "type": "command", ... }]` | +| `type` | Hook type: `"command"` (bash), `"prompt"` (LLM), `"http"` (webhook), `"mcp_tool"` (MCP tool invocation, v2.1.118+), or `"agent"` (subagent) | `"command"` | +| `command` | Shell command to execute | `"$CLAUDE_PROJECT_DIR/.claude/hooks/format.sh"` | +| `timeout` | Optional timeout in seconds (default 60) | `30` | +| `once` | If `true`, run the hook only once per session | `true` | + +### Matcher Patterns + +| Pattern | Description | Example | +|---------|-------------|---------| +| Exact string | Matches specific tool | `"Write"` | +| Regex pattern | Matches multiple tools | `"Edit\|Write"` | +| Comma-separated | Matches any listed tool (v2.1.191+) | `"Write,Edit"` | +| Wildcard | Matches all tools | `"*"` or `""` | +| MCP tools | Server and tool pattern | `"mcp__memory__.*"` | + +> **Matchers are matched exactly (v2.1.195+).** A hyphenated identifier (for example an MCP tool name containing a hyphen) no longer accidentally substring-matches a different tool. Comma-separated matchers like `"Write,Edit"` fire on any tool in the list โ€” earlier builds silently never fired them. + +**InstructionsLoaded matcher values:** + +| Matcher Value | Description | +|---------------|-------------| +| `session_start` | Instructions loaded at session startup | +| `nested_traversal` | Instructions loaded during nested directory traversal | +| `path_glob_match` | Instructions loaded via path glob pattern matching | + +### Narrowing with `if` conditions (tool-argument paths) + +The `matcher` field selects a hook by **tool name** (`"Write"`, `"Edit|Write"`, `"*"`). To filter more narrowly by the tool's **arguments** โ€” for example, to run a hook only when an edit touches `src/`, or to guard reads of secret files โ€” add an `if` condition to an individual hook handler. This is distinct from the tool-name matcher: the `matcher` decides *which tool*, the `if` decides *which call*. + +`if` uses [permission-rule syntax](https://code.claude.com/docs/en/permissions) (`ToolName(pattern)`), evaluated against the tool name **and** its arguments together. For `Read`/`Edit`/`Write`, the path pattern follows gitignore semantics, with the same anchors as permission rules: a bare name like `.env` matches at any depth, `src/**` is relative to the current directory, `/src/**` to the project root, `~/...` to your home directory, and `//...` is an absolute filesystem path. + +The `if` field sits at the **hook-handler level** โ€” a sibling of `type` and `command`, inside the `hooks` array โ€” not on `matcher`: + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Edit|Write", + "hooks": [ + { + "type": "command", + "if": "Edit(src/**)", + "command": "./hooks/lint-src.sh" + } + ] + }, + { + "matcher": "Read", + "hooks": [ + { + "type": "command", + "if": "Read(.env)", + "command": "./hooks/block-secret-read.sh" + } + ] + } + ] + } +} +``` + +Examples of valid `if` patterns: `Edit(src/**)` (edits under `src/`), `Read(~/.ssh/**)` (reads of any SSH key), `Read(.env)` (any `.env` at or below the current directory), `Bash(git push *)` (only `git push` subcommands). + +## Hook Types + +Claude Code supports five hook types: + +### Command Hooks + +The default hook type. Executes a shell command and communicates via JSON stdin/stdout and exit codes. + +```json +{ + "type": "command", + "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/validate.py\"", + "timeout": 60 +} +``` + +#### Exec form (`args`) + +> Added in v2.1.139. + +Instead of the shell-form `"command": "..."`, a command hook can spawn a binary directly via `execve()` with an `args` array. There is no shell parsing, so path placeholders never need quoting and the configuration is immune to shell-injection bugs. + +```json +{ + "type": "command", + "args": ["python3", "$CLAUDE_PROJECT_DIR/.claude/hooks/validate.py", "--strict"], + "timeout": 60 +} +``` + +The two forms are **mutually exclusive** โ€” a hook with both `command` and `args` set is rejected at config load. Use `command` when you need pipes, redirection, `&&` chaining, or shell expansions; use `args` when you are calling one binary with arguments. + +### HTTP Hooks + +> Added in v2.1.63. + +Remote webhook endpoints that receive the same JSON input as command hooks. HTTP hooks POST JSON to the URL and receive a JSON response. HTTP hooks are routed through the sandbox when sandboxing is enabled. Environment variable interpolation in URLs requires an explicit `allowedEnvVars` list for security. + +```json +{ + "hooks": { + "PostToolUse": [{ + "type": "http", + "url": "https://my-webhook.example.com/hook", + "matcher": "Write" + }] + } +} +``` + +**Key properties:** +- `"type": "http"` -- identifies this as an HTTP hook +- `"url"` -- the webhook endpoint URL +- Routed through sandbox when sandbox is enabled +- Requires explicit `allowedEnvVars` list for any environment variable interpolation in the URL + +### Prompt Hooks + +LLM-evaluated prompts where the hook content is a prompt that Claude evaluates. Primarily used with `Stop` and `SubagentStop` events for intelligent task completion checking. + +```json +{ + "type": "prompt", + "prompt": "Evaluate if Claude completed all requested tasks.", + "timeout": 30 +} +``` + +The LLM evaluates the prompt and returns a structured decision (see [Prompt-Based Hooks](#prompt-based-hooks) for details). + +### MCP Tool Hooks + +> Added in v2.1.118. + +The `mcp_tool` type invokes a configured MCP tool directly; configuration references the MCP server and tool name rather than a shell command or URL. This is useful when the validation or reaction logic already lives in an MCP server you have configured. + +```json +{ + "matcher": "Edit", + "hooks": [{ + "type": "mcp_tool", + "server": "my-mcp-server", + "tool": "validate_edit" + }] +} +``` + +**Key properties:** +- `"type": "mcp_tool"` -- identifies this as an MCP tool hook +- `"server"` -- name of the configured MCP server +- `"tool"` -- the tool name on that server to invoke + +The hook input (tool name, tool input, session context) is passed as the MCP tool's arguments. See [MCP server setup](../05-mcp/README.md) for configuring MCP servers. + +### Agent Hooks + +Subagent-based verification hooks that spawn a dedicated agent to evaluate conditions or perform complex checks. Unlike prompt hooks (single-turn LLM evaluation), agent hooks can use tools and perform multi-step reasoning. + +```json +{ + "type": "agent", + "prompt": "Verify the code changes follow our architecture guidelines. Check the relevant design docs and compare.", + "timeout": 120 +} +``` + +**Key properties:** +- `"type": "agent"` -- identifies this as an agent hook +- `"prompt"` -- the task description for the subagent +- The agent can use tools (Read, Grep, Bash, etc.) to perform its evaluation +- Returns a structured decision similar to prompt hooks + +## Hook Events + +Claude Code supports **30 hook events**: + +| Event | When Triggered | Matcher Input | Can Block | Common Use | +|-------|---------------|---------------|-----------|------------| +| **SessionStart** | Session begins/resumes/clear/compact | startup/resume/clear/compact | No | Environment setup | +| **Setup** | Initial environment setup (one-time per session) | (none) | No | Provision tooling, install deps | +| **InstructionsLoaded** | After CLAUDE.md or rules file loaded | (none) | No | Modify/filter instructions | +| **UserPromptSubmit** | User submits prompt | (none) | Yes | Validate prompts | +| **UserPromptExpansion** | User prompt is expanded (e.g., `@` mentions, slash commands resolved) | (none) | Yes | Transform or inspect expanded prompt | +| **PreToolUse** | Before tool execution | Tool name | Yes (allow/deny/ask) | Validate, modify inputs | +| **PermissionRequest** | Permission dialog shown | Tool name | Yes | Auto-approve/deny | +| **PermissionDenied** | User denies a permission prompt | Tool name | No | Logging, analytics, policy enforcement | +| **PostToolUse** | After tool succeeds | Tool name | No | Add context, feedback | +| **PostToolUseFailure** | Tool execution fails | Tool name | No | Error handling, logging | +| **PostToolBatch** | After a batch of tool uses completes | (none) | No | Aggregate reporting, batched validation | +| **Notification** | Notification sent | Notification type | No | Custom notifications | +| **MessageDisplay** | While assistant message text is displayed | (none) | No | Transform or hide displayed message text (v2.1.152) | +| **SubagentStart** | Subagent spawned | Agent type name | No | Subagent setup | +| **SubagentStop** | Subagent finishes | Agent type name | Yes | Subagent validation | +| **Stop** | Claude finishes responding | (none) | Yes | Task completion check | +| **StopFailure** | API error ends turn | (none) | No | Error recovery, logging | +| **TeammateIdle** | Agent team teammate idle | (none) | Yes | Teammate coordination | +| **TaskCompleted** | Task marked complete | (none) | Yes | Post-task actions | +| **TaskCreated** | Task created via TaskCreate | (none) | No | Task tracking, logging | +| **ConfigChange** | Config file changes | (none) | Yes (except policy) | React to config updates | +| **CwdChanged** | Working directory changes | (none) | No | Directory-specific setup | +| **FileChanged** | Watched file changes | (none) | No | File monitoring, rebuild | +| **PreCompact** | Before context compaction | manual/auto | No | Pre-compact actions | +| **PostCompact** | After compaction completes | (none) | No | Post-compact actions | +| **WorktreeCreate** | Worktree being created | (none) | Yes (path return) | Worktree initialization | +| **WorktreeRemove** | Worktree being removed | (none) | No | Worktree cleanup | +| **Elicitation** | MCP server requests user input | (none) | Yes | Input validation | +| **ElicitationResult** | User responds to elicitation | (none) | Yes | Response processing | +| **SessionEnd** | Session terminates | (none) | No | Cleanup, final logging | + +> **PostToolUse duration (v2.1.119):** `PostToolUse` and `PostToolUseFailure` hook inputs now include `duration_ms` โ€” see the [PostToolUse](#posttooluse) section for details. + +### PreToolUse + +Runs after Claude creates tool parameters and before processing. Use this to validate or modify tool inputs. + +**Configuration:** +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/validate-bash.py" + } + ] + } + ] + } +} +``` + +**Common matchers:** `Task`, `Bash`, `Glob`, `Grep`, `Read`, `Edit`, `Write`, `WebFetch`, `WebSearch` + +**Output control:** +- `permissionDecision`: `"allow"`, `"deny"`, or `"ask"` +- `permissionDecisionReason`: Explanation for decision +- `updatedInput`: Modified tool input parameters + +### PostToolUse + +Runs immediately after tool completion. Use for verification, logging, or providing context back to Claude. + +**Configuration:** +```json +{ + "hooks": { + "PostToolUse": [ + { + "matcher": "Write|Edit", + "hooks": [ + { + "type": "command", + "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/security-scan.py" + } + ] + } + ] + } +} +``` + +**Output control:** +- `"block"` decision prompts Claude with feedback +- `additionalContext`: Context added for Claude + +**Additional input fields (v2.1.119):** + +| Field | Type | Description | +|-------|------|-------------| +| `duration_ms` | number | Tool execution time in milliseconds. Excludes time spent in permission prompts and PreToolUse hook execution. Available on both `PostToolUse` and `PostToolUseFailure` hooks. | + +#### Recoverable blocks (`continueOnBlock`, v2.1.139) + +By default, a `PostToolUse` hook that returns `"decision": "block"` aborts the current turn. Set `"continueOnBlock": true` on the hook to instead surface the rejection back to Claude as a `tool_result`, so the model can read the feedback and retry or adjust. + +```json +{ + "hooks": { + "PostToolUse": [ + { + "matcher": "Write|Edit", + "hooks": [ + { + "type": "command", + "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/policy-check.py", + "continueOnBlock": true + } + ] + } + ] + } +} +``` + +Use this when the hook's `reason` is something Claude can act on (e.g., "this file is read-only; write somewhere else"); leave it off when a block must halt the turn entirely. + +### UserPromptSubmit + +Runs when user submits a prompt, before Claude processes it. + +**Configuration:** +```json +{ + "hooks": { + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "command", + "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/validate-prompt.py" + } + ] + } + ] + } +} +``` + +**Output control:** +- `decision`: `"block"` to prevent processing +- `reason`: Explanation if blocked +- `additionalContext`: Context added to prompt + +### Stop and SubagentStop + +Run when Claude finishes responding (Stop) or a subagent completes (SubagentStop). Supports prompt-based evaluation for intelligent task completion checking. + +**Additional input field:** Both `Stop` and `SubagentStop` hooks receive a `last_assistant_message` field in their JSON input, containing the final message from Claude or the subagent before stopping. This is useful for evaluating task completion. + +**Configuration:** +```json +{ + "hooks": { + "Stop": [ + { + "hooks": [ + { + "type": "prompt", + "prompt": "Evaluate if Claude completed all requested tasks.", + "timeout": 30 + } + ] + } + ] + } +} +``` + +> **Safety cap on consecutive blocks (v2.1.143)**: If a `Stop` hook returns `"decision": "block"` (or sets `continue: false`) **8 times in a row** for the same turn, Claude Code short-circuits the loop and ends the session with a warning. Override the threshold with the env var `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP=` (set to `0` to disable the cap entirely). This prevents a buggy Stop hook from looping the session forever. + +**Return field (v2.1.163):** A `Stop` or `SubagentStop` hook can return `hookSpecificOutput.additionalContext` to give Claude feedback and **continue the turn without surfacing an error label**. Previously, influencing the model from a Stop hook was awkward; now the hook can inject context cleanly, avoiding the error-label behavior of older feedback paths (such as `"decision": "block"`). + +```json +{ + "hookSpecificOutput": { + "hookEventName": "Stop", + "additionalContext": "Reminder: run the test suite before declaring done." + } +} +``` + +### SubagentStart + +Runs when a subagent begins execution. The matcher input is the agent type name, allowing hooks to target specific subagent types. + +**Configuration:** +```json +{ + "hooks": { + "SubagentStart": [ + { + "matcher": "code-review", + "hooks": [ + { + "type": "command", + "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/subagent-init.sh" + } + ] + } + ] + } +} +``` + +### SessionStart + +Runs when session starts or resumes. Can persist environment variables. + +**Matchers:** `startup`, `resume`, `clear`, `compact` + +**Special feature:** Use `CLAUDE_ENV_FILE` to persist environment variables (also available in `CwdChanged` and `FileChanged` hooks): + +```bash +#!/bin/bash +if [ -n "$CLAUDE_ENV_FILE" ]; then + echo 'export NODE_ENV=development' >> "$CLAUDE_ENV_FILE" +fi +exit 0 +``` + +**Session-scoped outputs (v2.1.152):** A `SessionStart` hook can return JSON to re-scan skills and set the session title: + +```json +{ + "reloadSkills": true, + "hookSpecificOutput": { + "sessionTitle": "Payments migration" + } +} +``` + +Top-level `reloadSkills: true` triggers a skill re-scan in the same session (the same action as the `/reload-skills` command), making skills the hook just installed available immediately. `hookSpecificOutput.sessionTitle` sets the session's display title on startup and resume. + +### SessionEnd + +Runs when session ends to perform cleanup or final logging. Cannot block termination. + +**Reason field values:** +- `clear` - User cleared the session +- `logout` - User logged out +- `prompt_input_exit` - User exited via prompt input +- `other` - Other reason + +**Configuration:** +```json +{ + "hooks": { + "SessionEnd": [ + { + "hooks": [ + { + "type": "command", + "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/session-cleanup.sh\"" + } + ] + } + ] + } +} +``` + +### Notification Event + +Updated matchers for notification events: +- `permission_prompt` - Permission request notification +- `idle_prompt` - Idle state notification +- `auth_success` - Authentication success +- `elicitation_dialog` - Dialog shown to user + +## Component-Scoped Hooks + +Hooks can be attached to specific components (skills, agents, commands) in their frontmatter: + +**In SKILL.md, agent.md, or command.md:** + +```yaml +--- +name: secure-operations +description: Perform operations with security checks +hooks: + PreToolUse: + - matcher: "Bash" + hooks: + - type: command + command: "./scripts/check.sh" + once: true # Only run once per session +--- +``` + +**Supported events for component hooks:** `PreToolUse`, `PostToolUse`, `Stop` + +This allows defining hooks directly in the component that uses them, keeping related code together. + +### Hooks in Subagent Frontmatter + +When a `Stop` hook is defined in a subagent's frontmatter, it is automatically converted to a `SubagentStop` hook scoped to that subagent. This ensures that the stop hook only fires when that specific subagent completes, rather than when the main session stops. + +```yaml +--- +name: code-review-agent +description: Automated code review subagent +hooks: + Stop: + - hooks: + - type: prompt + prompt: "Verify the code review is thorough and complete." + # The above Stop hook auto-converts to SubagentStop for this subagent +--- +``` + +## PermissionRequest Event + +Handles permission requests with custom output format: + +```json +{ + "hookSpecificOutput": { + "hookEventName": "PermissionRequest", + "decision": { + "behavior": "allow|deny", + "updatedInput": {}, + "message": "Custom message", + "interrupt": false + } + } +} +``` + +## Hook Input and Output + +### JSON Input (via stdin) + +All hooks receive JSON input via stdin: + +```json +{ + "session_id": "abc123", + "transcript_path": "/path/to/transcript.jsonl", + "cwd": "/current/working/directory", + "permission_mode": "default", + "hook_event_name": "PreToolUse", + "tool_name": "Write", + "tool_input": { + "file_path": "/path/to/file.js", + "content": "..." + }, + "tool_use_id": "toolu_01ABC123...", + "agent_id": "agent-abc123", + "agent_type": "main", + "worktree": "/path/to/worktree", + "effort": { "level": "medium" } +} +``` + +**Common fields:** + +| Field | Description | +|-------|-------------| +| `session_id` | Unique session identifier | +| `transcript_path` | Path to the conversation transcript file | +| `cwd` | Current working directory | +| `hook_event_name` | Name of the event that triggered the hook | +| `agent_id` | Identifier of the agent running this hook | +| `agent_type` | Type of agent (`"main"`, subagent type name, etc.) | +| `worktree` | Path to the git worktree, if the agent is running in one | +| `effort.level` | (v2.1.133+) Active effort level: `low`, `medium`, `high`, `xhigh`, or `max` | + +### Exit Codes + +| Exit Code | Meaning | Behavior | +|-----------|---------|----------| +| **0** | Success | Continue, parse JSON stdout | +| **2** | Blocking error | Block operation, stderr shown as error | +| **Other** | Non-blocking error | Continue, stderr shown in verbose mode | + +### JSON Output (stdout, exit code 0) + +```json +{ + "continue": true, + "stopReason": "Optional message if stopping", + "suppressOutput": false, + "systemMessage": "Optional warning message", + "hookSpecificOutput": { + "hookEventName": "PreToolUse", + "permissionDecision": "allow", + "permissionDecisionReason": "File is in allowed directory", + "updatedInput": { + "file_path": "/modified/path.js" + } + } +} +``` + +> **Scope (v2.1.121+):** `hookSpecificOutput.updatedToolOutput` is now honored for **all** tools, not just MCP tools. A `PostToolUse` hook on `Bash`, `Edit`, `Read`, etc. can rewrite the tool's output before Claude sees it โ€” useful for redacting secrets, normalizing diffs, or filtering noisy command output. Example (strip ANSI color codes from a `Bash` output): +> +> ```json +> { +> "hookSpecificOutput": { +> "hookEventName": "PostToolUse", +> "updatedToolOutput": "" +> } +> } +> ``` + +#### `terminalSequence` (v2.1.141) + +Hooks can emit raw OSC (operating system command) escape sequences by setting `terminalSequence` in the JSON output. The host writes the sequence to its controlling terminal when the hook returns โ€” useful for desktop notifications, window-title updates, and terminal bells without requiring a TTY of your own. + +| Field | Type | Description | +|-------|------|-------------| +| `terminalSequence` | string | Raw escape sequence (typically OSC 9 / OSC 0 / OSC 777). Written to the host terminal verbatim. | + +Example โ€” fire an OSC 9 desktop notification when a long task completes: + +```json +{ + "terminalSequence": "]9;Task complete" +} +``` + +Configure it on a `Stop` hook so the notification fires when Claude finishes a turn. Sequence support is terminal-dependent; Kitty/iTerm2/Windows Terminal honor OSC 9. + +## Environment Variables + +| Variable | Availability | Description | +|----------|-------------|-------------| +| `CLAUDE_PROJECT_DIR` | All hooks | Absolute path to project root | +| `CLAUDE_ENV_FILE` | SessionStart, CwdChanged, FileChanged | File path for persisting env vars | +| `CLAUDE_CODE_REMOTE` | All hooks | `"true"` if running in remote environments | +| `${CLAUDE_PLUGIN_ROOT}` | Plugin hooks | Path to plugin directory | +| `${CLAUDE_PLUGIN_DATA}` | Plugin hooks | Path to plugin data directory | +| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | SessionEnd hooks | Configurable timeout in milliseconds for SessionEnd hooks (overrides default) | +| `CLAUDE_CODE_SESSION_ID` | Bash tool subprocesses (v2.1.132+) | Session UUID; matches the `session_id` field in hook input JSON. Use to correlate bash logs with hook telemetry. | +| `CLAUDE_EFFORT` | Bash tool subprocesses (v2.1.133+) | Active effort level (`low`/`medium`/`high`/`xhigh`/`max`); matches `effort.level` in hook input JSON. | +| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | Process-wide (v2.1.143+) | Max consecutive Stop-hook blocks before the session ends with a warning (default `8`). Set to `0` to disable the cap. | + +## Prompt-Based Hooks + +For `Stop` and `SubagentStop` events, you can use LLM-based evaluation: + +```json +{ + "hooks": { + "Stop": [ + { + "hooks": [ + { + "type": "prompt", + "prompt": "Review if all tasks are complete. Return your decision.", + "timeout": 30 + } + ] + } + ] + } +} +``` + +**LLM Response Schema:** +```json +{ + "decision": "approve", + "reason": "All tasks completed successfully", + "continue": false, + "stopReason": "Task complete" +} +``` + +## Examples + +### Example 1: Bash Command Validator (PreToolUse) + +**File:** `.claude/hooks/validate-bash.py` + +```python +#!/usr/bin/env python3 +import json +import sys +import re + +BLOCKED_PATTERNS = [ + (r"\brm\s+-rf\s+/", "Blocking dangerous rm -rf / command"), + (r"\bsudo\s+rm", "Blocking sudo rm command"), +] + +def main(): + input_data = json.load(sys.stdin) + + tool_name = input_data.get("tool_name", "") + if tool_name != "Bash": + sys.exit(0) + + command = input_data.get("tool_input", {}).get("command", "") + + for pattern, message in BLOCKED_PATTERNS: + if re.search(pattern, command): + print(message, file=sys.stderr) + sys.exit(2) # Exit 2 = blocking error + + sys.exit(0) + +if __name__ == "__main__": + main() +``` + +**Configuration:** +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/validate-bash.py\"" + } + ] + } + ] + } +} +``` + +### Example 2: Security Scanner (PostToolUse) + +**File:** `.claude/hooks/security-scan.py` + +```python +#!/usr/bin/env python3 +import json +import sys +import re + +SECRET_PATTERNS = [ + (r"password\s*=\s*['\"][^'\"]+['\"]", "Potential hardcoded password"), + (r"api[_-]?key\s*=\s*['\"][^'\"]+['\"]", "Potential hardcoded API key"), +] + +def main(): + input_data = json.load(sys.stdin) + + tool_name = input_data.get("tool_name", "") + if tool_name not in ["Write", "Edit"]: + sys.exit(0) + + tool_input = input_data.get("tool_input", {}) + content = tool_input.get("content", "") or tool_input.get("new_string", "") + file_path = tool_input.get("file_path", "") + + warnings = [] + for pattern, message in SECRET_PATTERNS: + if re.search(pattern, content, re.IGNORECASE): + warnings.append(message) + + if warnings: + output = { + "hookSpecificOutput": { + "hookEventName": "PostToolUse", + "additionalContext": f"Security warnings for {file_path}: " + "; ".join(warnings) + } + } + print(json.dumps(output)) + + sys.exit(0) + +if __name__ == "__main__": + main() +``` + +### Example 3: Auto-Format Code (PostToolUse) + +**File:** `.claude/hooks/format-code.sh` + +```bash +#!/bin/bash + +# Read JSON from stdin +INPUT=$(cat) +TOOL_NAME=$(echo "$INPUT" | python3 -c "import sys, json; print(json.load(sys.stdin).get('tool_name', ''))") +FILE_PATH=$(echo "$INPUT" | python3 -c "import sys, json; print(json.load(sys.stdin).get('tool_input', {}).get('file_path', ''))") + +if [ "$TOOL_NAME" != "Write" ] && [ "$TOOL_NAME" != "Edit" ]; then + exit 0 +fi + +# Format based on file extension +case "$FILE_PATH" in + *.js|*.jsx|*.ts|*.tsx|*.json) + command -v prettier &>/dev/null && prettier --write "$FILE_PATH" 2>/dev/null + ;; + *.py) + command -v black &>/dev/null && black "$FILE_PATH" 2>/dev/null + ;; + *.go) + command -v gofmt &>/dev/null && gofmt -w "$FILE_PATH" 2>/dev/null + ;; +esac + +exit 0 +``` + +### Example 4: Prompt Validator (UserPromptSubmit) + +**File:** `.claude/hooks/validate-prompt.py` + +```python +#!/usr/bin/env python3 +import json +import sys +import re + +BLOCKED_PATTERNS = [ + (r"delete\s+(all\s+)?database", "Dangerous: database deletion"), + (r"rm\s+-rf\s+/", "Dangerous: root deletion"), +] + +def main(): + input_data = json.load(sys.stdin) + prompt = input_data.get("user_prompt", "") or input_data.get("prompt", "") + + for pattern, message in BLOCKED_PATTERNS: + if re.search(pattern, prompt, re.IGNORECASE): + output = { + "decision": "block", + "reason": f"Blocked: {message}" + } + print(json.dumps(output)) + sys.exit(0) + + sys.exit(0) + +if __name__ == "__main__": + main() +``` + +### Example 5: Intelligent Stop Hook (Prompt-Based) + +```json +{ + "hooks": { + "Stop": [ + { + "hooks": [ + { + "type": "prompt", + "prompt": "Review if Claude completed all requested tasks. Check: 1) Were all files created/modified? 2) Were there unresolved errors? If incomplete, explain what's missing.", + "timeout": 30 + } + ] + } + ] + } +} +``` + +### Example 6: Context Usage Tracker (Hook Pairs) + +Track token consumption per request using `UserPromptSubmit` (pre-message) and `Stop` (post-response) hooks together. + +**File:** `.claude/hooks/context-tracker.py` + +```python +#!/usr/bin/env python3 +""" +Context Usage Tracker - Tracks token consumption per request. + +Uses UserPromptSubmit as "pre-message" hook and Stop as "post-response" hook +to calculate the delta in token usage for each request. + +Token Counting Methods: +1. Character estimation (default): ~4 chars per token, no dependencies +2. tiktoken (optional): More accurate (~90-95%), requires: pip install tiktoken +""" +import json +import os +import sys +import tempfile + +# Configuration +CONTEXT_LIMIT = 128000 # Claude's context window (adjust for your model) +USE_TIKTOKEN = False # Set True if tiktoken is installed for better accuracy + + +def get_state_file(session_id: str) -> str: + """Get temp file path for storing pre-message token count, isolated by session.""" + return os.path.join(tempfile.gettempdir(), f"claude-context-{session_id}.json") + + +def count_tokens(text: str) -> int: + """ + Count tokens in text. + + Uses tiktoken with p50k_base encoding if available (~90-95% accuracy), + otherwise falls back to character estimation (~80-90% accuracy). + """ + if USE_TIKTOKEN: + try: + import tiktoken + enc = tiktoken.get_encoding("p50k_base") + return len(enc.encode(text)) + except ImportError: + pass # Fall back to estimation + + # Character-based estimation: ~4 characters per token for English + return len(text) // 4 + + +def read_transcript(transcript_path: str) -> str: + """Read and concatenate all content from transcript file.""" + if not transcript_path or not os.path.exists(transcript_path): + return "" + + content = [] + with open(transcript_path, "r") as f: + for line in f: + try: + entry = json.loads(line.strip()) + # Extract text content from various message formats + if "message" in entry: + msg = entry["message"] + if isinstance(msg.get("content"), str): + content.append(msg["content"]) + elif isinstance(msg.get("content"), list): + for block in msg["content"]: + if isinstance(block, dict) and block.get("type") == "text": + content.append(block.get("text", "")) + except json.JSONDecodeError: + continue + + return "\n".join(content) + + +def handle_user_prompt_submit(data: dict) -> None: + """Pre-message hook: Save current token count before request.""" + session_id = data.get("session_id", "unknown") + transcript_path = data.get("transcript_path", "") + + transcript_content = read_transcript(transcript_path) + current_tokens = count_tokens(transcript_content) + + # Save to temp file for later comparison + state_file = get_state_file(session_id) + with open(state_file, "w") as f: + json.dump({"pre_tokens": current_tokens}, f) + + +def handle_stop(data: dict) -> None: + """Post-response hook: Calculate and report token delta.""" + session_id = data.get("session_id", "unknown") + transcript_path = data.get("transcript_path", "") + + transcript_content = read_transcript(transcript_path) + current_tokens = count_tokens(transcript_content) + + # Load pre-message count + state_file = get_state_file(session_id) + pre_tokens = 0 + if os.path.exists(state_file): + try: + with open(state_file, "r") as f: + state = json.load(f) + pre_tokens = state.get("pre_tokens", 0) + except (json.JSONDecodeError, IOError): + pass + + # Calculate delta + delta_tokens = current_tokens - pre_tokens + remaining = CONTEXT_LIMIT - current_tokens + percentage = (current_tokens / CONTEXT_LIMIT) * 100 + + # Report usage + method = "tiktoken" if USE_TIKTOKEN else "estimated" + print(f"Context ({method}): ~{current_tokens:,} tokens ({percentage:.1f}% used, ~{remaining:,} remaining)", file=sys.stderr) + if delta_tokens > 0: + print(f"This request: ~{delta_tokens:,} tokens", file=sys.stderr) + + +def main(): + data = json.load(sys.stdin) + event = data.get("hook_event_name", "") + + if event == "UserPromptSubmit": + handle_user_prompt_submit(data) + elif event == "Stop": + handle_stop(data) + + sys.exit(0) + + +if __name__ == "__main__": + main() +``` + +**Configuration:** +```json +{ + "hooks": { + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "command", + "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/context-tracker.py\"" + } + ] + } + ], + "Stop": [ + { + "hooks": [ + { + "type": "command", + "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/context-tracker.py\"" + } + ] + } + ] + } +} +``` + +**How it works:** +1. `UserPromptSubmit` fires before your prompt is processed - saves current token count +2. `Stop` fires after Claude responds - calculates delta and reports usage +3. Each session is isolated via `session_id` in the temp filename + +**Token Counting Methods:** + +| Method | Accuracy | Dependencies | Speed | +|--------|----------|--------------|-------| +| Character estimation | ~80-90% | None | <1ms | +| tiktoken (p50k_base) | ~90-95% | `pip install tiktoken` | <10ms | + +> **Note:** Anthropic hasn't released an official offline tokenizer. Both methods are approximations. The transcript includes user prompts, Claude's responses, and tool outputs, but NOT system prompts or internal context. + +### Example 7: Seed Auto-Mode Permissions (One-Time Setup Script) + +A one-time setup script that seeds `~/.claude/settings.json` with ~67 safe permission rules equivalent to Claude Code's auto-mode baseline โ€” without any hook, without remembering future choices. Run it once; safe to re-run (skips rules already present). + +**File:** `09-advanced-features/setup-auto-mode-permissions.py` + +```bash +# Preview what would be added +python3 09-advanced-features/setup-auto-mode-permissions.py --dry-run + +# Apply +python3 09-advanced-features/setup-auto-mode-permissions.py +``` + +**What gets added:** + +| Category | Examples | +|----------|---------| +| Built-in tools | `Read(*)`, `Edit(*)`, `Write(*)`, `Glob(*)`, `Grep(*)`, `Agent(*)`, `WebSearch(*)` | +| Git read | `Bash(git status:*)`, `Bash(git log:*)`, `Bash(git diff:*)` | +| Git write (local) | `Bash(git add:*)`, `Bash(git commit:*)`, `Bash(git checkout:*)` | +| Package managers | `Bash(npm install:*)`, `Bash(pip install:*)`, `Bash(cargo build:*)` | +| Build & test | `Bash(make:*)`, `Bash(pytest:*)`, `Bash(go test:*)` | +| Common shell | `Bash(ls:*)`, `Bash(cat:*)`, `Bash(find:*)`, `Bash(cp:*)`, `Bash(mv:*)` | +| GitHub CLI | `Bash(gh pr view:*)`, `Bash(gh pr create:*)`, `Bash(gh issue list:*)` | + +**What is intentionally excluded** (never added by this script): +- `rm -rf`, `sudo`, force push, `git reset --hard` +- `DROP TABLE`, `kubectl delete`, `terraform destroy` +- `npm publish`, `curl | bash`, production deploys + +### Example 8: Learning Progress Logger (SessionEnd) + +Log which modules you studied at the end of each Claude Code session. Progress is stored +in `~/.claude-howto-progress.json` โ€” outside the repo, so it survives `git pull` without +being overwritten. + +**Why `SessionEnd` and not `Stop`?** +`Stop` fires after *every* Claude response. `SessionEnd` fires once when the session +terminates โ€” exactly what you want for an end-of-session diary entry. + +**Why `/dev/tty` for input?** +Hook scripts receive the hook JSON payload via `stdin`, so interactive `read` must use +`/dev/tty` directly to reach the terminal. + +**File:** `06-hooks/session-end.sh` + +```bash +#!/usr/bin/env bash +# SessionEnd hook: prompts for modules worked on, then appends a session record +# to ~/.claude-howto-progress.json for persistent learning progress tracking. + +PROGRESS_FILE="$HOME/.claude-howto-progress.json" + +# Guard: only run inside this repo +if [[ "$CLAUDE_PROJECT_DIR" != *"claude-howto"* ]] && [[ "$PWD" != *"claude-howto"* ]]; then + exit 0 +fi + +if [ ! -f "$PROGRESS_FILE" ]; then + echo '{"sessions":[]}' > "$PROGRESS_FILE" +fi + +DATE=$(date +"%Y-%m-%d") +TIME=$(date +"%H:%M") + +echo "" +echo " Which modules did you work on? (e.g. 06,07 or press Enter to skip)" +echo " 01=Slash 02=Memory 03=Skills 04=Subagents 05=MCP" +echo " 06=Hooks 07=Plugins 08=Checkpoints 09=Advanced 10=CLI" +printf " > " +read -r INPUT __`: + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "mcp__memory__.*", + "hooks": [ + { + "type": "command", + "command": "echo '{\"systemMessage\": \"Memory operation logged\"}'" + } + ] + } + ] + } +} +``` + +## Security Considerations + +### Disclaimer + +**USE AT YOUR OWN RISK**: Hooks execute arbitrary shell commands. You are solely responsible for: +- Commands you configure +- File access/modification permissions +- Potential data loss or system damage +- Testing hooks in safe environments before production use + +### Security Notes + +- **Workspace trust required:** The `statusLine` and `fileSuggestion` hook output commands now require workspace trust acceptance before they take effect. +- **Status-line terminal size (v2.1.153):** Status-line command scripts now receive `COLUMNS` and `LINES` environment variables, so a script can adapt its output to the terminal width/height (e.g. `[ "$COLUMNS" -lt 80 ] && short_output`). +- **HTTP hooks and environment variables:** HTTP hooks require an explicit `allowedEnvVars` list to use environment variable interpolation in URLs. This prevents accidental leakage of sensitive environment variables to remote endpoints. +- **Managed settings hierarchy:** The `disableAllHooks` setting now respects the managed settings hierarchy, meaning organization-level settings can enforce hook disablement that individual users cannot override. +- **PowerShell auto-approve (v2.1.119):** PowerShell tool commands can be auto-approved in permission mode, matching Bash. This brings parity for Windows users running Claude Code with PowerShell-backed shell tools. +- **Bash bare env-var auto-approve closed (v2.1.145):** Before v2.1.145, a Bash command of the form `FOO=bar somecommand` (a bare variable assignment inline with a non-allowlisted command) could be auto-approved when only `FOO=bar` by itself was on the allowlist. v2.1.145 closes this โ€” such commands now hit the permission prompt. Scripts relying on the implicit allow will start prompting; re-allow them explicitly via a `Bash(...)` permission rule that covers the full command, not just the variable assignment. + +### Best Practices + +| Do | Don't | +|-----|-------| +| Validate and sanitize all inputs | Trust input data blindly | +| Quote shell variables: `"$VAR"` | Use unquoted: `$VAR` | +| Block path traversal (`..`) | Allow arbitrary paths | +| Use absolute paths with `$CLAUDE_PROJECT_DIR` | Hardcode paths | +| Skip sensitive files (`.env`, `.git/`, keys) | Process all files | +| Test hooks in isolation first | Deploy untested hooks | +| Use explicit `allowedEnvVars` for HTTP hooks | Expose all env vars to webhooks | + +## Debugging + +### Enable Debug Mode + +Run Claude with debug flag for detailed hook logs: + +```bash +claude --debug +``` + +### Verbose Mode + +Use `Ctrl+O` in Claude Code to enable verbose mode and see hook execution progress. + +### Test Hooks Independently + +```bash +# Test with sample JSON input +echo '{"tool_name": "Bash", "tool_input": {"command": "ls -la"}}' | python3 .claude/hooks/validate-bash.py + +# Check exit code +echo $? +``` + +## Complete Configuration Example + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/validate-bash.py\"", + "timeout": 10 + } + ] + } + ], + "PostToolUse": [ + { + "matcher": "Write|Edit", + "hooks": [ + { + "type": "command", + "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/format-code.sh\"", + "timeout": 30 + }, + { + "type": "command", + "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/security-scan.py\"", + "timeout": 10 + } + ] + } + ], + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "command", + "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/validate-prompt.py\"" + } + ] + } + ], + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { + "type": "command", + "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/session-init.sh\"" + } + ] + } + ], + "Stop": [ + { + "hooks": [ + { + "type": "prompt", + "prompt": "Verify all tasks are complete before stopping.", + "timeout": 30 + } + ] + } + ] + } +} +``` + +## Hook Execution Details + +| Aspect | Behavior | +|--------|----------| +| **Timeout** | 60 seconds default, configurable per command | +| **Parallelization** | All matching hooks run in parallel | +| **Deduplication** | Identical hook commands deduplicated | +| **Environment** | Runs in current directory with Claude Code's environment | + +## Troubleshooting + +### Hook Not Executing +- Verify JSON configuration syntax is correct +- Check matcher pattern matches the tool name +- Ensure script exists and is executable: `chmod +x script.sh` +- Run `claude --debug` to see hook execution logs +- Verify hook reads JSON from stdin (not command args) + +### Hook Blocks Unexpectedly +- Test hook with sample JSON: `echo '{"tool_name": "Write", ...}' | ./hook.py` +- Check exit code: should be 0 for allow, 2 for block +- Check stderr output (shown on exit code 2) + +### JSON Parsing Errors +- Always read from stdin, not command arguments +- Use proper JSON parsing (not string manipulation) +- Handle missing fields gracefully + +## Installation + +### Step 1: Create Hooks Directory +```bash +mkdir -p ~/.claude/hooks +``` + +### Step 2: Copy Example Hooks +```bash +cp 06-hooks/*.sh ~/.claude/hooks/ +chmod +x ~/.claude/hooks/*.sh +``` + +### Step 3: Configure in Settings +Edit `~/.claude/settings.json` or `.claude/settings.json` with the hook configuration shown above. + +## Related Concepts + +- **[Checkpoints and Rewind](../08-checkpoints/)** - Save and restore conversation state +- **[Slash Commands](../01-slash-commands/)** - Create custom slash commands +- **[Skills](../03-skills/)** - Reusable autonomous capabilities +- **[Subagents](../04-subagents/)** - Delegated task execution +- **[Plugins](../07-plugins/)** - Bundled extension packages +- **[Advanced Features](../09-advanced-features/)** - Explore advanced Claude Code capabilities + +## Additional Resources + +- **[Official Hooks Documentation](https://code.claude.com/docs/en/hooks)** - Complete hooks reference +- **[CLI Reference](https://code.claude.com/docs/en/cli-reference)** - Command-line interface documentation +- **[Memory Guide](../02-memory/)** - Persistent context configuration + +--- + +**Last Updated**: June 28, 2026 +**Claude Code Version**: 2.1.195 +**Sources**: +- https://code.claude.com/docs/en/hooks +- https://code.claude.com/docs/en/permissions +- https://code.claude.com/docs/en/changelog +- https://code.claude.com/docs/en/changelog#2-1-176 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.139 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.145 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.152 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.153 +**Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5 diff --git a/ko/06-hooks/context-tracker-tiktoken.py b/ko/06-hooks/context-tracker-tiktoken.py new file mode 100644 index 00000000..11786bfb --- /dev/null +++ b/ko/06-hooks/context-tracker-tiktoken.py @@ -0,0 +1,149 @@ +#!/usr/bin/env python3 +""" +Context Usage Tracker (tiktoken version) - Tracks token consumption per request. + +Uses UserPromptSubmit as "pre-message" hook and Stop as "post-response" hook +to calculate the delta in token usage for each request. + +This version uses tiktoken with p50k_base encoding for ~90-95% accuracy. +Requires: pip install tiktoken + +For a zero-dependency version, see context-tracker.py. + +Usage: + Configure both hooks to use the same script: + - UserPromptSubmit: saves current token count + - Stop: calculates delta and reports usage +""" +import json +import os +import sys +import tempfile + +try: + import tiktoken + + TIKTOKEN_AVAILABLE = True +except ImportError: + TIKTOKEN_AVAILABLE = False + print( + "Warning: tiktoken not installed. Install with: pip install tiktoken", + file=sys.stderr, + ) + +# Configuration +CONTEXT_LIMIT = 128000 # Claude's context window (adjust for your model) + + +def get_state_file(session_id: str) -> str: + """Get temp file path for storing pre-message token count, isolated by session.""" + return os.path.join(tempfile.gettempdir(), f"claude-context-{session_id}.json") + + +def count_tokens(text: str) -> int: + """ + Count tokens using tiktoken with p50k_base encoding. + + This provides ~90-95% accuracy compared to Claude's actual tokenizer. + Falls back to character estimation if tiktoken is not available. + + Note: Anthropic hasn't released an official offline tokenizer. + tiktoken with p50k_base is a reasonable approximation since both + Claude and GPT models use BPE (byte-pair encoding). + """ + if TIKTOKEN_AVAILABLE: + enc = tiktoken.get_encoding("p50k_base") + return len(enc.encode(text)) + else: + # Fallback to character estimation (~4 chars per token) + return len(text) // 4 + + +def read_transcript(transcript_path: str) -> str: + """Read and concatenate all content from transcript file.""" + if not transcript_path or not os.path.exists(transcript_path): + return "" + + content = [] + with open(transcript_path, "r") as f: + for line in f: + try: + entry = json.loads(line.strip()) + # Extract text content from various message formats + if "message" in entry: + msg = entry["message"] + if isinstance(msg.get("content"), str): + content.append(msg["content"]) + elif isinstance(msg.get("content"), list): + for block in msg["content"]: + if isinstance(block, dict) and block.get("type") == "text": + content.append(block.get("text", "")) + except json.JSONDecodeError: + continue + + return "\n".join(content) + + +def handle_user_prompt_submit(data: dict) -> None: + """Pre-message hook: Save current token count before request.""" + session_id = data.get("session_id", "unknown") + transcript_path = data.get("transcript_path", "") + + transcript_content = read_transcript(transcript_path) + current_tokens = count_tokens(transcript_content) + + # Save to temp file for later comparison + state_file = get_state_file(session_id) + with open(state_file, "w") as f: + json.dump({"pre_tokens": current_tokens}, f) + + +def handle_stop(data: dict) -> None: + """Post-response hook: Calculate and report token delta.""" + session_id = data.get("session_id", "unknown") + transcript_path = data.get("transcript_path", "") + + transcript_content = read_transcript(transcript_path) + current_tokens = count_tokens(transcript_content) + + # Load pre-message count + state_file = get_state_file(session_id) + pre_tokens = 0 + if os.path.exists(state_file): + try: + with open(state_file, "r") as f: + state = json.load(f) + pre_tokens = state.get("pre_tokens", 0) + except (json.JSONDecodeError, IOError): + pass + + # Calculate delta + delta_tokens = current_tokens - pre_tokens + remaining = CONTEXT_LIMIT - current_tokens + percentage = (current_tokens / CONTEXT_LIMIT) * 100 + + # Report usage (stderr so it doesn't interfere with hook output) + method = "tiktoken" if TIKTOKEN_AVAILABLE else "estimated" + print( + f"Context ({method}): ~{current_tokens:,} tokens " + f"({percentage:.1f}% used, ~{remaining:,} remaining)", + file=sys.stderr, + ) + if delta_tokens > 0: + print(f"This request: ~{delta_tokens:,} tokens", file=sys.stderr) + + +def main(): + data = json.load(sys.stdin) + event = data.get("hook_event_name", "") + + if event == "UserPromptSubmit": + handle_user_prompt_submit(data) + elif event == "Stop": + handle_stop(data) + + sys.exit(0) + + +if __name__ == "__main__": + main() diff --git a/ko/06-hooks/context-tracker.py b/ko/06-hooks/context-tracker.py new file mode 100644 index 00000000..eb5daf9d --- /dev/null +++ b/ko/06-hooks/context-tracker.py @@ -0,0 +1,126 @@ +#!/usr/bin/env python3 +""" +Context Usage Tracker - Tracks token consumption per request. + +Uses UserPromptSubmit as "pre-message" hook and Stop as "post-response" hook +to calculate the delta in token usage for each request. + +This version uses character-based estimation (no dependencies). +For better accuracy, see context-tracker-tiktoken.py. + +Usage: + Configure both hooks to use the same script: + - UserPromptSubmit: saves current token count + - Stop: calculates delta and reports usage +""" +import json +import os +import sys +import tempfile + +# Configuration +CONTEXT_LIMIT = 128000 # Claude's context window (adjust for your model) + + +def get_state_file(session_id: str) -> str: + """Get temp file path for storing pre-message token count, isolated by session.""" + return os.path.join(tempfile.gettempdir(), f"claude-context-{session_id}.json") + + +def count_tokens_estimate(text: str) -> int: + """ + Estimate token count using character-based approximation. + + Uses ~4 characters per token ratio, which provides ~80-90% accuracy + for English text. Less accurate for code and non-English text. + """ + return len(text) // 4 + + +def read_transcript(transcript_path: str) -> str: + """Read and concatenate all content from transcript file.""" + if not transcript_path or not os.path.exists(transcript_path): + return "" + + content = [] + with open(transcript_path, "r") as f: + for line in f: + try: + entry = json.loads(line.strip()) + # Extract text content from various message formats + if "message" in entry: + msg = entry["message"] + if isinstance(msg.get("content"), str): + content.append(msg["content"]) + elif isinstance(msg.get("content"), list): + for block in msg["content"]: + if isinstance(block, dict) and block.get("type") == "text": + content.append(block.get("text", "")) + except json.JSONDecodeError: + continue + + return "\n".join(content) + + +def handle_user_prompt_submit(data: dict) -> None: + """Pre-message hook: Save current token count before request.""" + session_id = data.get("session_id", "unknown") + transcript_path = data.get("transcript_path", "") + + transcript_content = read_transcript(transcript_path) + current_tokens = count_tokens_estimate(transcript_content) + + # Save to temp file for later comparison + state_file = get_state_file(session_id) + with open(state_file, "w") as f: + json.dump({"pre_tokens": current_tokens}, f) + + +def handle_stop(data: dict) -> None: + """Post-response hook: Calculate and report token delta.""" + session_id = data.get("session_id", "unknown") + transcript_path = data.get("transcript_path", "") + + transcript_content = read_transcript(transcript_path) + current_tokens = count_tokens_estimate(transcript_content) + + # Load pre-message count + state_file = get_state_file(session_id) + pre_tokens = 0 + if os.path.exists(state_file): + try: + with open(state_file, "r") as f: + state = json.load(f) + pre_tokens = state.get("pre_tokens", 0) + except (json.JSONDecodeError, IOError): + pass + + # Calculate delta + delta_tokens = current_tokens - pre_tokens + remaining = CONTEXT_LIMIT - current_tokens + percentage = (current_tokens / CONTEXT_LIMIT) * 100 + + # Report usage (stderr so it doesn't interfere with hook output) + print( + f"Context (estimated): ~{current_tokens:,} tokens " + f"({percentage:.1f}% used, ~{remaining:,} remaining)", + file=sys.stderr, + ) + if delta_tokens > 0: + print(f"This request: ~{delta_tokens:,} tokens", file=sys.stderr) + + +def main(): + data = json.load(sys.stdin) + event = data.get("hook_event_name", "") + + if event == "UserPromptSubmit": + handle_user_prompt_submit(data) + elif event == "Stop": + handle_stop(data) + + sys.exit(0) + + +if __name__ == "__main__": + main() diff --git a/ko/06-hooks/dependency-check.sh b/ko/06-hooks/dependency-check.sh new file mode 100644 index 00000000..c659b9f8 --- /dev/null +++ b/ko/06-hooks/dependency-check.sh @@ -0,0 +1,156 @@ +#!/bin/bash +# Check for known vulnerabilities in dependencies after manifest files are modified. +# Hook: PostToolUse:Write + +FILE=$1 + +if [ -z "$FILE" ]; then + echo "Usage: $0 " + exit 0 +fi + +# Use basename for matching โ€” $1 may be an absolute path +BASENAME=$(basename "$FILE") + +# Only run when a dependency manifest is written +case "$BASENAME" in + package.json|package-lock.json|yarn.lock|pnpm-lock.yaml| \ + requirements.txt|Pipfile|Pipfile.lock|pyproject.toml| \ + go.mod|go.sum| \ + Cargo.toml|Cargo.lock| \ + Gemfile|Gemfile.lock| \ + composer.json|composer.lock| \ + pom.xml|build.gradle|build.gradle.kts) + echo "๐Ÿ“ฆ Dependency manifest updated: $FILE โ€” scanning for vulnerabilities..." + ;; + *) + exit 0 + ;; +esac + +ISSUES_FOUND=0 + +# โ”€โ”€ npm / yarn / pnpm โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +if [[ "$BASENAME" == package*.json || "$BASENAME" == yarn.lock || "$BASENAME" == pnpm-lock.yaml ]]; then + if command -v npm &>/dev/null; then + echo "๐Ÿ” Running npm audit..." + if ! npm audit --audit-level=high --json 2>/dev/null | \ + python3 -c " +import sys, json +data = json.load(sys.stdin) +vulns = data.get('metadata', {}).get('vulnerabilities', {}) +high = vulns.get('high', 0) + vulns.get('critical', 0) +if high: + print(f' โš ๏ธ {high} high/critical npm vulnerabilities found. Run: npm audit fix') + sys.exit(1) +" 2>/dev/null; then + ISSUES_FOUND=1 + else + echo " โœ… No high/critical npm vulnerabilities" + fi + fi + + if command -v yarn &>/dev/null && [[ "$BASENAME" == yarn.lock ]]; then + echo "๐Ÿ” Running yarn audit..." + if ! yarn audit --level high --json 2>/dev/null | \ + grep -q '"type":"auditAdvisory"' 2>/dev/null; then + echo " โœ… No high yarn vulnerabilities" + else + echo " โš ๏ธ yarn audit found vulnerabilities. Run: yarn audit --level high" + ISSUES_FOUND=1 + fi + fi +fi + +# โ”€โ”€ Python โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +if [[ "$BASENAME" == requirements.txt || "$BASENAME" == Pipfile* || "$BASENAME" == pyproject.toml ]]; then + if command -v pip-audit &>/dev/null; then + echo "๐Ÿ” Running pip-audit..." + if pip-audit --format=json 2>/dev/null | \ + python3 -c " +import sys, json +data = json.load(sys.stdin) +vulns = [d for d in data.get('dependencies', []) if d.get('vulns')] +if vulns: + for dep in vulns: + for v in dep['vulns']: + print(f' โš ๏ธ {dep[\"name\"]} {dep[\"version\"]}: {v[\"id\"]} โ€” {v[\"fix_versions\"]}') + sys.exit(1) +" 2>/dev/null; then + echo " โœ… No Python vulnerabilities found" + else + ISSUES_FOUND=1 + echo " Run: pip-audit for details" + fi + elif command -v safety &>/dev/null; then + echo "๐Ÿ” Running safety check..." + OUTPUT=$(safety check --short-report 2>&1) + EXIT_CODE=$? + if [ $EXIT_CODE -eq 0 ]; then + echo " โœ… No Python vulnerabilities found" + elif echo "$OUTPUT" | grep -qiE "vulnerability|CVE|insecure"; then + echo "$OUTPUT" + ISSUES_FOUND=1 + else + echo " โš ๏ธ safety check could not complete (network or config error)" >&2 + fi + fi +fi + +# โ”€โ”€ Go โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +if [[ "$BASENAME" == go.mod || "$BASENAME" == go.sum ]]; then + if command -v govulncheck &>/dev/null; then + echo "๐Ÿ” Running govulncheck..." + OUTPUT=$(govulncheck ./... 2>&1) + EXIT_CODE=$? + if [ $EXIT_CODE -eq 0 ]; then + echo " โœ… No Go vulnerabilities found" + elif echo "$OUTPUT" | grep -q "Vulnerability #"; then + echo "$OUTPUT" + ISSUES_FOUND=1 + else + echo " โš ๏ธ govulncheck could not complete: $OUTPUT" >&2 + fi + fi +fi + +# โ”€โ”€ Rust โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +if [[ "$BASENAME" == Cargo.toml || "$BASENAME" == Cargo.lock ]]; then + if command -v cargo-audit &>/dev/null; then + echo "๐Ÿ” Running cargo audit..." + if ! cargo audit 2>/dev/null; then + ISSUES_FOUND=1 + else + echo " โœ… No Rust vulnerabilities found" + fi + fi +fi + +# โ”€โ”€ Ruby โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +if [[ "$BASENAME" == Gemfile || "$BASENAME" == Gemfile.lock ]]; then + if command -v bundler-audit &>/dev/null; then + echo "๐Ÿ” Running bundler-audit..." + bundler-audit check --update 2>/dev/null || ISSUES_FOUND=1 + fi +fi + +# โ”€โ”€ Generic fallback: trivy โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +if command -v trivy &>/dev/null; then + echo "๐Ÿ” Running trivy fs scan..." + if ! trivy fs --exit-code 1 --severity HIGH,CRITICAL --quiet . 2>/dev/null; then + ISSUES_FOUND=1 + else + echo " โœ… trivy found no HIGH/CRITICAL issues" + fi +fi + +if [ "$ISSUES_FOUND" -eq 0 ]; then + echo "โœ… Dependency check passed โ€” no vulnerabilities detected" +else + echo "" + echo "โš ๏ธ Vulnerabilities detected. Review and update dependencies before committing." + echo " This hook is advisory only and will not block your workflow." +fi + +# Always exit 0 โ€” this hook warns but does not block +exit 0 diff --git a/ko/06-hooks/format-code.sh b/ko/06-hooks/format-code.sh new file mode 100644 index 00000000..9841b9ec --- /dev/null +++ b/ko/06-hooks/format-code.sh @@ -0,0 +1,49 @@ +#!/bin/bash +# Auto-format code after writing +# Hook: PostToolUse:Write +# +# Reads the target file path from stdin JSON and runs the appropriate formatter +# in-place on the file after Claude writes it. +# +# Compatible with: macOS, Linux, Windows (Git Bash) + +# Read JSON input from stdin (Claude Code hook protocol) +INPUT=$(cat) + +# Extract file_path using sed (compatible with all platforms) +FILE_PATH=$(echo "$INPUT" | sed -n 's/.*"file_path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1) + +if [ -z "$FILE_PATH" ] || [ ! -f "$FILE_PATH" ]; then + exit 0 +fi + +# Detect file type and format accordingly +case "$FILE_PATH" in + *.js|*.jsx|*.ts|*.tsx) + if command -v prettier &> /dev/null; then + prettier --write "$FILE_PATH" 2>/dev/null + fi + ;; + *.py) + if command -v black &> /dev/null; then + black "$FILE_PATH" 2>/dev/null + fi + ;; + *.go) + if command -v gofmt &> /dev/null; then + gofmt -w "$FILE_PATH" 2>/dev/null + fi + ;; + *.rs) + if command -v rustfmt &> /dev/null; then + rustfmt "$FILE_PATH" 2>/dev/null + fi + ;; + *.java) + if command -v google-java-format &> /dev/null; then + google-java-format -i "$FILE_PATH" 2>/dev/null + fi + ;; +esac + +exit 0 diff --git a/ko/06-hooks/log-bash.sh b/ko/06-hooks/log-bash.sh new file mode 100644 index 00000000..2ca16d95 --- /dev/null +++ b/ko/06-hooks/log-bash.sh @@ -0,0 +1,31 @@ +#!/bin/bash +# Log all bash commands +# Hook: PostToolUse:Bash +# +# Reads the executed command from stdin JSON and logs it to a file. +# +# Compatible with: macOS, Linux, Windows (Git Bash) + +# Read JSON input from stdin (Claude Code hook protocol) +INPUT=$(cat) + +# Extract the bash command from tool_input +# Note: sed [^"]* stops at escaped quotes in JSON; for commands with double-quoted +# strings, only the portion up to the first \" will be captured โ€” this is a known +# limitation of sed-based JSON parsing and is acceptable for logging purposes. +COMMAND=$(echo "$INPUT" | sed -n 's/.*"command"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1) + +if [ -z "$COMMAND" ]; then + exit 0 +fi + +TIMESTAMP=$(date "+%Y-%m-%d %H:%M:%S") +LOGFILE="$HOME/.claude/bash-commands.log" + +# Create log directory if it doesn't exist +mkdir -p "$(dirname "$LOGFILE")" + +# Log the command +echo "[$TIMESTAMP] $COMMAND" >> "$LOGFILE" + +exit 0 diff --git a/ko/06-hooks/notify-team.sh b/ko/06-hooks/notify-team.sh new file mode 100644 index 00000000..18942181 --- /dev/null +++ b/ko/06-hooks/notify-team.sh @@ -0,0 +1,68 @@ +#!/bin/bash +# Send notifications on events +# Hook: PostToolUse (matcher: Bash) โ€” run after bash commands; filter for git push in script logic +# Note: Claude Code has no native PostPush event. To trigger on git push, check the bash command +# string for "git push" using a matcher or conditional logic within this script. + +REPO_NAME=$(basename $(git rev-parse --show-toplevel 2>/dev/null) 2>/dev/null) +COMMIT_MSG=$(git log -1 --pretty=%B 2>/dev/null) +AUTHOR=$(git log -1 --pretty=%an 2>/dev/null) +BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null) + +echo "๐Ÿ“ข Sending notification to team..." + +# Slack webhook example (replace with your webhook URL) +SLACK_WEBHOOK="${SLACK_WEBHOOK_URL:-}" + +if [ -n "$SLACK_WEBHOOK" ]; then + curl -X POST "$SLACK_WEBHOOK" \ + -H 'Content-Type: application/json' \ + -d "{ + \"text\": \"New push to *$REPO_NAME*\", + \"attachments\": [{ + \"color\": \"good\", + \"fields\": [ + {\"title\": \"Branch\", \"value\": \"$BRANCH\", \"short\": true}, + {\"title\": \"Author\", \"value\": \"$AUTHOR\", \"short\": true}, + {\"title\": \"Commit\", \"value\": \"$COMMIT_MSG\"} + ] + }] + }" \ + --silent --output /dev/null + + echo "โœ… Slack notification sent" +fi + +# Discord webhook example (replace with your webhook URL) +DISCORD_WEBHOOK="${DISCORD_WEBHOOK_URL:-}" + +if [ -n "$DISCORD_WEBHOOK" ]; then + curl -X POST "$DISCORD_WEBHOOK" \ + -H 'Content-Type: application/json' \ + -d "{ + \"content\": \"**New push to $REPO_NAME**\", + \"embeds\": [{ + \"title\": \"$COMMIT_MSG\", + \"color\": 3066993, + \"fields\": [ + {\"name\": \"Branch\", \"value\": \"$BRANCH\", \"inline\": true}, + {\"name\": \"Author\", \"value\": \"$AUTHOR\", \"inline\": true} + ] + }] + }" \ + --silent --output /dev/null + + echo "โœ… Discord notification sent" +fi + +# Email notification example +EMAIL_TO="${TEAM_EMAIL:-}" + +if [ -n "$EMAIL_TO" ]; then + echo "New push to $REPO_NAME by $AUTHOR" | \ + mail -s "Git Push: $BRANCH" "$EMAIL_TO" + + echo "โœ… Email notification sent" +fi + +exit 0 diff --git a/ko/06-hooks/pre-commit.sh b/ko/06-hooks/pre-commit.sh new file mode 100644 index 00000000..2e9b27aa --- /dev/null +++ b/ko/06-hooks/pre-commit.sh @@ -0,0 +1,50 @@ +#!/bin/bash +# Run tests before commit +# Hook: PreToolUse (matcher: Bash) - checks if the command is a git commit +# Note: There is no "PreCommit" hook event. Use PreToolUse with a Bash matcher +# and inspect the command to detect git commit operations. + +echo "๐Ÿงช Running tests before commit..." + +# Check if package.json exists (Node.js project) +if [ -f "package.json" ]; then + if grep -q "\"test\":" package.json; then + npm test + if [ $? -ne 0 ]; then + echo "โŒ Tests failed! Commit blocked." + exit 1 + fi + fi +fi + +# Check if pytest is available (Python project) +if [ -f "pytest.ini" ] || [ -f "setup.py" ]; then + if command -v pytest &> /dev/null; then + pytest + if [ $? -ne 0 ]; then + echo "โŒ Tests failed! Commit blocked." + exit 1 + fi + fi +fi + +# Check if go.mod exists (Go project) +if [ -f "go.mod" ]; then + go test ./... + if [ $? -ne 0 ]; then + echo "โŒ Tests failed! Commit blocked." + exit 1 + fi +fi + +# Check if Cargo.toml exists (Rust project) +if [ -f "Cargo.toml" ]; then + cargo test + if [ $? -ne 0 ]; then + echo "โŒ Tests failed! Commit blocked." + exit 1 + fi +fi + +echo "โœ… All tests passed! Proceeding with commit." +exit 0 diff --git a/ko/06-hooks/pre-tool-check.sh b/ko/06-hooks/pre-tool-check.sh new file mode 100644 index 00000000..f2dbdc08 --- /dev/null +++ b/ko/06-hooks/pre-tool-check.sh @@ -0,0 +1,130 @@ +#!/bin/bash +# Pre-tool safety check for Bash commands +# Hook: PreToolUse (matcher: Bash) +# +# This hook runs before every Bash tool execution and blocks or warns on +# potentially destructive or high-risk shell commands. +# +# Setup: +# cp 06-hooks/pre-tool-check.sh ~/.claude/hooks/ +# chmod +x ~/.claude/hooks/pre-tool-check.sh +# +# Configure in ~/.claude/settings.json: +# { +# "hooks": { +# "PreToolUse": [ +# { +# "matcher": "Bash", +# "hooks": [ +# { +# "type": "command", +# "command": "~/.claude/hooks/pre-tool-check.sh" +# } +# ] +# } +# ] +# } +# } +# +# Input: JSON via stdin with the shape: +# { "tool_name": "Bash", "tool_input": { "command": "..." } } +# +# Output convention (per Claude Code hook protocol): +# - exit 0 โ†’ allow. stdout may contain JSON (hookSpecificOutput); stderr +# is silently discarded, so warnings printed to stderr are NOT visible. +# For observability on allowed commands, write to an audit log file. +# - exit 2 โ†’ block. stderr is surfaced back to Claude as the block reason. +# Any echo explaining *why* a command was blocked MUST be redirected to +# stderr with `>&2`, otherwise Claude Code reports "No stderr output". +# +# Audit log: every invocation is recorded to +# $CLAUDE_PROJECT_DIR/.claude/hooks/audit.log +# with the decision (BLOCK/WARN/ALLOW), so you can observe WARN-tier +# matches even though their stderr output is dropped by Claude Code. + +# Read the full JSON input from stdin +INPUT=$(cat) + +# Extract the command using portable sed (compatible with macOS and Linux) +COMMAND=$(echo "$INPUT" | sed -n 's/.*"command"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1) + +# Fall back to the raw input if extraction fails +if [ -z "$COMMAND" ]; then + COMMAND="$INPUT" +fi + +# โ”€โ”€ Audit log โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +# Records every invocation with the final decision. This is the only reliable +# way to observe the WARN tier, because Claude Code silently drops stderr on +# exit 0. Falls back to $(pwd) when the hook is invoked outside Claude Code +# (e.g. for local testing). +LOG_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}/.claude/hooks" +LOG_FILE="$LOG_DIR/audit.log" +mkdir -p "$LOG_DIR" 2>/dev/null +log_decision() { + echo "$(date -u +%FT%TZ) [$1] $COMMAND" >> "$LOG_FILE" +} + +# โ”€โ”€ Blocked patterns โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +# These commands are blocked unconditionally because they are almost always +# destructive and rarely intentional in an automated context. + +BLOCKED_PATTERNS=( + # Anchor `rm -rf /` so `/` must be followed by whitespace or end of line, + # otherwise substring matching would falsely flag e.g. `rm -rf /tmp/foo`. + "rm -rf /([[:space:]]|$)" + "rm -rf \*" + "dd if=/dev/zero" + "dd if=/dev/random" + ":\(\)\{:\|:&\};:" # Fork bomb (regex metachars escaped) + "mkfs\." # Filesystem format + "format c:" # Windows disk format +) + +for pattern in "${BLOCKED_PATTERNS[@]}"; do + if echo "$COMMAND" | grep -qE "$pattern"; then + log_decision "BLOCK:$pattern" + # These echoes MUST go to stderr โ€” Claude Code surfaces stderr as the + # block reason on exit 2. Writing to stdout would show "No stderr output". + echo "โŒ Blocked: Potentially destructive command detected: $pattern" >&2 + echo " Command: $COMMAND" >&2 + exit 2 + fi +done + +# โ”€โ”€ Warning patterns โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +# These patterns are risky but may be intentional. Log a warning and allow. + +WARNING_PATTERNS=( + "rm -rf" + "git push --force" + "git reset --hard" + "git clean -f" + "chmod -R 777" + "sudo rm" + "DROP TABLE" + "DROP DATABASE" + "truncate" +) + +MATCHED_WARNINGS="" +for pattern in "${WARNING_PATTERNS[@]}"; do + if echo "$COMMAND" | grep -qi "$pattern"; then + MATCHED_WARNINGS="${MATCHED_WARNINGS:+$MATCHED_WARNINGS,}$pattern" + # Mirror the warning on stderr for humans running the hook manually. + # Claude Code drops this on exit 0 โ€” the audit log is the reliable + # record (see WARN entries). + echo "โš ๏ธ Warning: High-risk operation detected: $pattern" >&2 + fi +done + +if [ -n "$MATCHED_WARNINGS" ]; then + log_decision "WARN:$MATCHED_WARNINGS" + echo " Command: $COMMAND" >&2 + echo " Proceeding โ€” review the above warnings before continuing." >&2 +else + log_decision "ALLOW" +fi + +# โ”€โ”€ Allow โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +exit 0 diff --git a/ko/06-hooks/security-scan.sh b/ko/06-hooks/security-scan.sh new file mode 100644 index 00000000..81e3a5b1 --- /dev/null +++ b/ko/06-hooks/security-scan.sh @@ -0,0 +1,78 @@ +#!/bin/bash +# Security scan on file write +# Hook: PostToolUse:Write +# +# Scans files for hardcoded secrets, API keys, and credentials. +# Outputs a non-blocking warning via additionalContext when issues are found. +# +# Compatible with: macOS, Linux, Windows (Git Bash) + +# Read JSON input from stdin (Claude Code hook protocol) +INPUT=$(cat) + +# Extract file_path using sed (compatible with all platforms including Windows Git Bash) +# Avoids grep -P (not available on Windows Git Bash) and python3 dependency +FILE_PATH=$(echo "$INPUT" | sed -n 's/.*"file_path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1) + +if [ -z "$FILE_PATH" ] || [ ! -f "$FILE_PATH" ]; then + exit 0 +fi + +# Skip binary files, vendor dirs, and build artifacts +case "$FILE_PATH" in + *.png|*.jpg|*.jpeg|*.gif|*.svg|*.ico|*.woff|*.woff2|*.ttf|*.eot) exit 0 ;; + */node_modules/*|*/.git/*|*/dist/*|*/build/*) exit 0 ;; +esac + +ISSUES="" + +# Check for hardcoded passwords +# Handles both JSON format ("password": "value") and code format (password = 'value') +# Use \\n as separator โ€” it is a valid JSON newline escape and passes through printf safely +if grep -qiE '"password"[[:space:]]*:[[:space:]]*"[^"]+"' "$FILE_PATH" 2>/dev/null; then + ISSUES="${ISSUES}- WARNING: Potential hardcoded password detected\\n" +elif grep -qiE '(password|passwd|pwd)[[:space:]]*=[[:space:]]*'"'"'[^'"'"']+'"'"'' "$FILE_PATH" 2>/dev/null; then + ISSUES="${ISSUES}- WARNING: Potential hardcoded password detected\\n" +fi + +# Check for hardcoded API keys +if grep -qiE '"(api[_-]?key|apikey|access[_-]?token)"[[:space:]]*:[[:space:]]*"[^"]+"' "$FILE_PATH" 2>/dev/null; then + ISSUES="${ISSUES}- WARNING: Potential hardcoded API key detected\\n" +fi + +# Check for hardcoded secrets and tokens +if grep -qiE '(secret|token)[[:space:]]*=[[:space:]]*['"'"'"][^'"'"'"]+['"'"'"]' "$FILE_PATH" 2>/dev/null; then + ISSUES="${ISSUES}- WARNING: Potential hardcoded secret or token detected\\n" +fi + +# Check for private keys +if grep -q "BEGIN.*PRIVATE KEY" "$FILE_PATH" 2>/dev/null; then + ISSUES="${ISSUES}- WARNING: Private key detected\\n" +fi + +# Check for AWS keys +if grep -qE "AKIA[0-9A-Z]{16}" "$FILE_PATH" 2>/dev/null; then + ISSUES="${ISSUES}- WARNING: AWS access key detected\\n" +fi + +# Scan with semgrep if available (stdout suppressed to avoid mixing with JSON output) +if command -v semgrep &> /dev/null; then + semgrep --config=auto "$FILE_PATH" --quiet >/dev/null 2>/dev/null +fi + +# Scan with trufflehog if available (stdout suppressed to avoid mixing with JSON output) +if command -v trufflehog &> /dev/null; then + trufflehog filesystem "$FILE_PATH" --only-verified --quiet >/dev/null 2>/dev/null +fi + +# If issues found, output as additionalContext (non-blocking warning) +# Use hookSpecificOutput format required by Claude Code PostToolUse protocol +if [ -n "$ISSUES" ]; then + # Escape file path for JSON (backslash and double-quote) + # ISSUES already uses \\n as separator (valid JSON escape) โ€” only escape double-quotes + SAFE_PATH=$(printf '%s' "$FILE_PATH" | sed 's/\\/\\\\/g; s/"/\\"/g') + SAFE_ISSUES=$(printf '%s' "$ISSUES" | sed 's/"/\\"/g') + printf '{"hookSpecificOutput": {"hookEventName": "PostToolUse", "additionalContext": "Security scan found issues in %s:\\n%sPlease review and use environment variables instead."}}' "$SAFE_PATH" "$SAFE_ISSUES" +fi + +exit 0 diff --git a/ko/06-hooks/session-end.sh b/ko/06-hooks/session-end.sh new file mode 100644 index 00000000..e5df24ae --- /dev/null +++ b/ko/06-hooks/session-end.sh @@ -0,0 +1,94 @@ +#!/usr/bin/env bash +# SessionEnd hook: prompts for modules worked on, then appends a session record +# to ~/.claude-howto-progress.json for persistent learning progress tracking. +# +# Fires once when the Claude Code session terminates โ€” not after every response. +# Uses /dev/tty for interactive input since stdin carries the hook's JSON payload. +# +# Install: add to .claude/settings.json under the "SessionEnd" event (see below). + +PROGRESS_FILE="$HOME/.claude-howto-progress.json" + +# Guard: only run inside this repo +if [[ "$CLAUDE_PROJECT_DIR" != *"claude-howto"* ]] && [[ "$PWD" != *"claude-howto"* ]]; then + exit 0 +fi + +# Create progress file if it doesn't exist +if [ ! -f "$PROGRESS_FILE" ]; then + echo '{"sessions":[]}' > "$PROGRESS_FILE" +fi + +DATE=$(date +"%Y-%m-%d") +TIME=$(date +"%H:%M") + +echo "" +echo "โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”" +echo " Claude Code โ€” Learning Session End" +echo " $DATE $TIME" +echo "โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”" +echo "" +echo " Which modules did you work on? (e.g. 06,07 or press Enter to skip)" +echo " 01=Slash 02=Memory 03=Skills 04=Subagents 05=MCP" +echo " 06=Hooks 07=Plugins 08=Checkpoints 09=Advanced 10=CLI" +echo "" +printf " > " +read -r INPUT + + Claude How To + + +# Claude Code ํ”Œ๋Ÿฌ๊ทธ์ธ + +์ด ํด๋”์—๋Š” ์—ฌ๋Ÿฌ Claude Code ๊ธฐ๋Šฅ์„ ํ•˜๋‚˜์˜ ์ผ๊ด€๋˜๊ณ  ์„ค์น˜ ๊ฐ€๋Šฅํ•œ ํŒจํ‚ค์ง€๋กœ ๋ฌถ์€ ์™„์ „ํ•œ ํ”Œ๋Ÿฌ๊ทธ์ธ ์˜ˆ์ œ๊ฐ€ ํฌํ•จ๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. + +## ๊ฐœ์š” + +Claude Code ํ”Œ๋Ÿฌ๊ทธ์ธ์€ ํ•˜๋‚˜์˜ ๋ช…๋ น์œผ๋กœ ์„ค์น˜ํ•  ์ˆ˜ ์žˆ๋Š” ์‚ฌ์šฉ์ž ์ •์˜ ๊ธฐ๋Šฅ(์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด, ์„œ๋ธŒ์—์ด์ „ํŠธ, MCP ์„œ๋ฒ„, ํ›…)์„ ๋ฌถ์–ด ์ œ๊ณตํ•˜๋Š” ํŒจํ‚ค์ง€์ž…๋‹ˆ๋‹ค. ์ด๋Š” ์—ฌ๋Ÿฌ ๊ธฐ๋Šฅ์„ ํ•˜๋‚˜์˜ ์ผ๊ด€๋˜๊ณ  ๊ณต์œ  ๊ฐ€๋Šฅํ•œ ํŒจํ‚ค์ง€๋กœ ๊ฒฐํ•ฉํ•˜๋Š” ๊ฐ€์žฅ ์ƒ์œ„ ์ˆ˜์ค€์˜ ํ™•์žฅ ๋ฉ”์ปค๋‹ˆ์ฆ˜์ž…๋‹ˆ๋‹ค. + +## ํ”Œ๋Ÿฌ๊ทธ์ธ ์•„ํ‚คํ…์ฒ˜ + +```mermaid +graph TB + A["Plugin"] + B["Slash Commands"] + C["Subagents"] + D["MCP Servers"] + E["Hooks"] + F["Configuration"] + + A -->|bundles| B + A -->|bundles| C + A -->|bundles| D + A -->|bundles| E + A -->|bundles| F +``` + +## ํ”Œ๋Ÿฌ๊ทธ์ธ ๋กœ๋”ฉ ๊ณผ์ • + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude Code + participant Plugin as Plugin Marketplace + participant Install as Installation + participant SlashCmds as Slash Commands + participant Subagents + participant MCPServers as MCP Servers + participant Hooks + participant Tools as Configured Tools + + User->>Claude: /plugin install pr-review + Claude->>Plugin: Download plugin manifest + Plugin-->>Claude: Return plugin definition + Claude->>Install: Extract components + Install->>SlashCmds: Configure + Install->>Subagents: Configure + Install->>MCPServers: Configure + Install->>Hooks: Configure + SlashCmds-->>Tools: Ready to use + Subagents-->>Tools: Ready to use + MCPServers-->>Tools: Ready to use + Hooks-->>Tools: Ready to use + Tools-->>Claude: Plugin installed โœ… +``` + +> **๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ๋ถˆํ•„์š”(v2.1.157+)**: ์ด์ œ `.claude/skills` ๋””๋ ‰ํ„ฐ๋ฆฌ์— ๋ฐฐ์น˜๋œ ํ”Œ๋Ÿฌ๊ทธ์ธ์€ ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ์—†์ด ์ž๋™์œผ๋กœ ๋กœ๋“œ๋ฉ๋‹ˆ๋‹ค. `claude plugin init ` ๋ช…๋ น์œผ๋กœ ์ƒˆ๋กœ์šด ํ”Œ๋Ÿฌ๊ทธ์ธ์„ ์ƒ์„ฑํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +## ํ”Œ๋Ÿฌ๊ทธ์ธ ์œ ํ˜• ๋ฐ ๋ฐฐํฌ + +| Type | Scope | Shared | Authority | Examples | +|------|-------|--------|-----------|----------| +| Official | Global | All users | Anthropic | PR Review, Security Guidance | +| Community | Public | All users | Community | DevOps, Data Science | +| Organization | Internal | Team members | Company | Internal standards, tools | +| Personal | Individual | Single user | Developer | Custom workflows | + +## ํ”Œ๋Ÿฌ๊ทธ์ธ ์ •์˜ ๊ตฌ์กฐ + +ํ”Œ๋Ÿฌ๊ทธ์ธ ๋งค๋‹ˆํŽ˜์ŠคํŠธ๋Š” `.claude-plugin/plugin.json`์— JSON ํ˜•์‹์œผ๋กœ ์ •์˜๋ฉ๋‹ˆ๋‹ค. + +```json +{ + "name": "my-first-plugin", + "description": "A greeting plugin", + "version": "1.0.0", + "author": { + "name": "Your Name" + }, + "homepage": "https://example.com", + "repository": "https://github.com/user/repo", + "license": "MIT" +} +``` + +## ํ”Œ๋Ÿฌ๊ทธ์ธ ๊ตฌ์กฐ ์˜ˆ์‹œ + +``` +my-plugin/ +โ”œโ”€โ”€ .claude-plugin/ +โ”‚ โ””โ”€โ”€ plugin.json # Manifest (name, description, version, author) +โ”œโ”€โ”€ commands/ # Skills as Markdown files +โ”‚ โ”œโ”€โ”€ task-1.md +โ”‚ โ”œโ”€โ”€ task-2.md +โ”‚ โ””โ”€โ”€ workflows/ +โ”œโ”€โ”€ agents/ # Custom agent definitions +โ”‚ โ”œโ”€โ”€ specialist-1.md +โ”‚ โ”œโ”€โ”€ specialist-2.md +โ”‚ โ””โ”€โ”€ configs/ +โ”œโ”€โ”€ skills/ # Agent Skills with SKILL.md files +โ”‚ โ”œโ”€โ”€ skill-1.md +โ”‚ โ””โ”€โ”€ skill-2.md +โ”œโ”€โ”€ hooks/ # Event handlers in hooks.json +โ”‚ โ””โ”€โ”€ hooks.json +โ”œโ”€โ”€ .mcp.json # MCP server configurations +โ”œโ”€โ”€ .lsp.json # LSP server configurations for code intelligence +โ”œโ”€โ”€ bin/ # Executables added to Bash tool's PATH while plugin is enabled +โ”œโ”€โ”€ settings.json # Default settings applied when plugin is enabled (currently only `agent` key supported) +โ”œโ”€โ”€ themes/ # Optional: ship custom Claude Code themes (v2.1.118+) +โ”œโ”€โ”€ templates/ +โ”‚ โ””โ”€โ”€ issue-template.md +โ”œโ”€โ”€ scripts/ +โ”‚ โ”œโ”€โ”€ helper-1.sh +โ”‚ โ””โ”€โ”€ helper-2.py +โ”œโ”€โ”€ docs/ +โ”‚ โ”œโ”€โ”€ README.md +โ”‚ โ””โ”€โ”€ USAGE.md +โ””โ”€โ”€ tests/ + โ””โ”€โ”€ plugin.test.js +``` + +### LSP ์„œ๋ฒ„ ๊ตฌ์„ฑ + +ํ”Œ๋Ÿฌ๊ทธ์ธ์€ ์‹ค์‹œ๊ฐ„ ์ฝ”๋“œ ์ธํ…”๋ฆฌ์ „์Šค๋ฅผ ์œ„ํ•œ Language Server Protocol(LSP) ์ง€์›์„ ํฌํ•จํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. LSP ์„œ๋ฒ„๋Š” ์ž‘์—… ์ค‘ ์ง„๋‹จ, ์ฝ”๋“œ ํƒ์ƒ‰, ์‹ฌ๋ณผ ์ •๋ณด๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. + +**๊ตฌ์„ฑ ์œ„์น˜**: + +- ํ”Œ๋Ÿฌ๊ทธ์ธ ๋ฃจํŠธ ๋””๋ ‰ํ„ฐ๋ฆฌ์˜ `.lsp.json` ํŒŒ์ผ +- `plugin.json`์˜ ์ธ๋ผ์ธ `lsp` ํ‚ค + +#### ํ•„๋“œ ์ฐธ์กฐ + +| Field | Required | Description | +|-------|----------|-------------| +| `command` | Yes | LSP ์„œ๋ฒ„ ์‹คํ–‰ ํŒŒ์ผ(PATH์— ์žˆ์–ด์•ผ ํ•จ) | +| `extensionToLanguage` | Yes | ํŒŒ์ผ ํ™•์žฅ์ž๋ฅผ ์–ธ์–ด ID์— ๋งคํ•‘ | +| `args` | No | ์„œ๋ฒ„ ์‹คํ–‰ ์‹œ ์‚ฌ์šฉํ•  ๋ช…๋ น์ค„ ์ธ์ˆ˜ | +| `transport` | No | ํ†ต์‹  ๋ฐฉ์‹: `stdio`(๊ธฐ๋ณธ๊ฐ’) ๋˜๋Š” `socket` | +| `env` | No | ์„œ๋ฒ„ ํ”„๋กœ์„ธ์Šค์— ์ „๋‹ฌํ•  ํ™˜๊ฒฝ ๋ณ€์ˆ˜ | +| `initializationOptions` | No | LSP ์ดˆ๊ธฐํ™” ์‹œ ์ „๋‹ฌ๋˜๋Š” ์˜ต์…˜ | +| `settings` | No | ์›Œํฌ์ŠคํŽ˜์ด์Šค ๊ตฌ์„ฑ ์ •๋ณด | +| `workspaceFolder` | No | ์›Œํฌ์ŠคํŽ˜์ด์Šค ํด๋” ๊ฒฝ๋กœ ์žฌ์ •์˜ | +| `startupTimeout` | No | ์„œ๋ฒ„ ์‹œ์ž‘์„ ๊ธฐ๋‹ค๋ฆฌ๋Š” ์ตœ๋Œ€ ์‹œ๊ฐ„(ms) | +| `shutdownTimeout` | No | ์ •์ƒ ์ข…๋ฃŒ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๋Š” ์ตœ๋Œ€ ์‹œ๊ฐ„(ms) | +| `restartOnCrash` | No | ์„œ๋ฒ„๊ฐ€ ๋น„์ •์ƒ ์ข…๋ฃŒ๋˜๋ฉด ์ž๋™ ์žฌ์‹œ์ž‘ | +| `maxRestarts` | No | ํฌ๊ธฐํ•˜๊ธฐ ์ „ ์ตœ๋Œ€ ์žฌ์‹œ์ž‘ ํšŸ์ˆ˜ | + +#### ๊ตฌ์„ฑ ์˜ˆ์‹œ + +**Go (gopls)**: + +```json +{ + "go": { + "command": "gopls", + "args": ["serve"], + "extensionToLanguage": { + ".go": "go" + } + } +} +``` + +**Python (pyright)**: + +```json +{ + "python": { + "command": "pyright-langserver", + "args": ["--stdio"], + "extensionToLanguage": { + ".py": "python", + ".pyi": "python" + } + } +} +``` + +**TypeScript**: + +```json +{ + "typescript": { + "command": "typescript-language-server", + "args": ["--stdio"], + "extensionToLanguage": { + ".ts": "typescript", + ".tsx": "typescriptreact", + ".js": "javascript", + ".jsx": "javascriptreact" + } + } +} +``` + +#### ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ LSP ํ”Œ๋Ÿฌ๊ทธ์ธ + +๊ณต์‹ ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค์—๋Š” ๋ฏธ๋ฆฌ ๊ตฌ์„ฑ๋œ LSP ํ”Œ๋Ÿฌ๊ทธ์ธ์ด ํฌํ•จ๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. + +| Plugin | Language | Server Binary | Install Command | +|--------|----------|---------------|----------------| +| `pyright-lsp` | Python | `pyright-langserver` | `pip install pyright` | +| `typescript-lsp` | TypeScript/JavaScript | `typescript-language-server` | `npm install -g typescript-language-server typescript` | +| `rust-lsp` | Rust | `rust-analyzer` | Install via `rustup component add rust-analyzer` | + +#### LSP ๊ธฐ๋Šฅ + +๊ตฌ์„ฑ์ด ์™„๋ฃŒ๋˜๋ฉด LSP ์„œ๋ฒ„๋Š” ๋‹ค์Œ ๊ธฐ๋Šฅ์„ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. + +- **์ฆ‰๊ฐ์ ์ธ ์ง„๋‹จ** โ€” ํŽธ์ง‘ ํ›„ ์˜ค๋ฅ˜์™€ ๊ฒฝ๊ณ ๊ฐ€ ์ฆ‰์‹œ ํ‘œ์‹œ๋ฉ๋‹ˆ๋‹ค. +- **์ฝ”๋“œ ํƒ์ƒ‰** โ€” ์ •์˜๋กœ ์ด๋™, ์ฐธ์กฐ ์ฐพ๊ธฐ, ๊ตฌํ˜„ ์ฐพ๊ธฐ +- **ํ˜ธ๋ฒ„ ์ •๋ณด** โ€” ๋งˆ์šฐ์Šค๋ฅผ ์˜ฌ๋ฆฌ๋ฉด ํƒ€์ž… ์‹œ๊ทธ๋‹ˆ์ฒ˜์™€ ๋ฌธ์„œ๋ฅผ ํ‘œ์‹œ +- **์‹ฌ๋ณผ ๋ชฉ๋ก** โ€” ํ˜„์žฌ ํŒŒ์ผ ๋˜๋Š” ์›Œํฌ์ŠคํŽ˜์ด์Šค์˜ ์‹ฌ๋ณผ ํƒ์ƒ‰ + +### `bin/` ๋””๋ ‰ํ„ฐ๋ฆฌ๋ฅผ `PATH`์— ์ถ”๊ฐ€ + +ํ”Œ๋Ÿฌ๊ทธ์ธ์ด ํ™œ์„ฑํ™”๋˜๋ฉด ํ•ด๋‹น ํ”Œ๋Ÿฌ๊ทธ์ธ์˜ `bin/` ๋””๋ ‰ํ„ฐ๋ฆฌ๊ฐ€ ์„ธ์…˜์˜ `PATH` ์•ž๋ถ€๋ถ„์— ์ถ”๊ฐ€๋ฉ๋‹ˆ๋‹ค. ์ด ๋””๋ ‰ํ„ฐ๋ฆฌ์— ํฌํ•จ๋œ ์‹คํ–‰ ํŒŒ์ผ์€ ๊ฒฝ๋กœ๋ฅผ ์ง€์ •ํ•˜์ง€ ์•Š๊ณ ๋„ Bash ๋„๊ตฌ์—์„œ ์ด๋ฆ„๋งŒ์œผ๋กœ ์ง์ ‘ ์‹คํ–‰ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +```bash +# In a plugin layout: +my-plugin/ +โ”œโ”€โ”€ plugin.json +โ””โ”€โ”€ bin/ + โ””โ”€โ”€ my-tool # executable file (chmod +x) + +# Inside a Claude Code session with the plugin enabled: +$ my-tool --help +``` + +๋™์ผํ•œ ํ”Œ๋Ÿฌ๊ทธ์ธ ๋‚ด๋ถ€์˜ ํ›…, ์Šคํ‚ฌ ๋˜๋Š” ๋ช…๋ น์–ด์—์„œ ํ˜ธ์ถœํ•  CLI ๋ณด์กฐ ๋„๊ตฌ๋ฅผ ์ œ๊ณตํ•  ๋•Œ ์ด ๊ธฐ๋Šฅ์„ ํ™œ์šฉํ•˜์‹ญ์‹œ์˜ค. ํ”Œ๋Ÿฌ๊ทธ์ธ ์ €์žฅ์†Œ์—์„œ ํŒŒ์ผ์— ์‹คํ–‰ ๊ถŒํ•œ(`chmod +x`)์„ ๋ถ€์—ฌํ•˜๋ฉด Git์ด ํ•ด๋‹น ๊ถŒํ•œ ๋น„ํŠธ๋ฅผ ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. + +## ํ”Œ๋Ÿฌ๊ทธ์ธ ์˜ต์…˜ (v2.1.83+) + +ํ”Œ๋Ÿฌ๊ทธ์ธ์€ ๋งค๋‹ˆํŽ˜์ŠคํŠธ์˜ `userConfig`๋ฅผ ํ†ตํ•ด ์‚ฌ์šฉ์ž ์„ค์ • ์˜ต์…˜์„ ์„ ์–ธํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. `sensitive: true`๋กœ ํ‘œ์‹œ๋œ ๊ฐ’์€ ์ผ๋ฐ˜ ํ…์ŠคํŠธ ์„ค์ • ํŒŒ์ผ์ด ์•„๋‹ˆ๋ผ ์‹œ์Šคํ…œ ํ‚ค์ฒด์ธ์— ์ €์žฅ๋ฉ๋‹ˆ๋‹ค. + +```json +{ + "name": "my-plugin", + "version": "1.0.0", + "userConfig": { + "apiKey": { + "description": "API key for the service", + "sensitive": true + }, + "region": { + "description": "Deployment region", + "default": "us-east-1" + } + } +} +``` + +## ์˜๊ตฌ ํ”Œ๋Ÿฌ๊ทธ์ธ ๋ฐ์ดํ„ฐ (`${CLAUDE_PLUGIN_DATA}`) (v2.1.78+) + +ํ”Œ๋Ÿฌ๊ทธ์ธ์€ `${CLAUDE_PLUGIN_DATA}` ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋ฅผ ํ†ตํ•ด ์˜๊ตฌ ์ƒํƒœ ๋””๋ ‰ํ„ฐ๋ฆฌ์— ์ ‘๊ทผํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์ด ๋””๋ ‰ํ„ฐ๋ฆฌ๋Š” ํ”Œ๋Ÿฌ๊ทธ์ธ๋งˆ๋‹ค ๊ณ ์œ ํ•˜๋ฉฐ ์„ธ์…˜์ด ์ข…๋ฃŒ๋˜์–ด๋„ ์œ ์ง€๋˜๋ฏ€๋กœ ์บ์‹œ, ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ๋ฐ ๊ธฐํƒ€ ์˜๊ตฌ ์ƒํƒœ ๋ฐ์ดํ„ฐ๋ฅผ ์ €์žฅํ•˜๋Š” ๋ฐ ์ ํ•ฉํ•ฉ๋‹ˆ๋‹ค. + +```json +{ + "hooks": { + "PostToolUse": [ + { + "command": "node ${CLAUDE_PLUGIN_DATA}/track-usage.js" + } + ] + } +} +``` + +์ด ๋””๋ ‰ํ„ฐ๋ฆฌ๋Š” ํ”Œ๋Ÿฌ๊ทธ์ธ์ด ์„ค์น˜๋  ๋•Œ ์ž๋™์œผ๋กœ ์ƒ์„ฑ๋ฉ๋‹ˆ๋‹ค. ์—ฌ๊ธฐ์— ์ €์žฅ๋œ ํŒŒ์ผ์€ ํ”Œ๋Ÿฌ๊ทธ์ธ์ด ์ œ๊ฑฐ๋  ๋•Œ๊นŒ์ง€ ์œ ์ง€๋ฉ๋‹ˆ๋‹ค. + +### ๋ฐฑ๊ทธ๋ผ์šด๋“œ ๋ชจ๋‹ˆํ„ฐ (v2.1.105) + +ํ”Œ๋Ÿฌ๊ทธ์ธ์€ ์„ธ์…˜์ด ์‹œ์ž‘๋˜๊ฑฐ๋‚˜ ํ”Œ๋Ÿฌ๊ทธ์ธ์˜ ์Šคํ‚ฌ์ด ํ˜ธ์ถœ๋  ๋•Œ ์ž๋™์œผ๋กœ ํ™œ์„ฑํ™”๋˜๋Š” ๋ฐฑ๊ทธ๋ผ์šด๋“œ ๋ชจ๋‹ˆํ„ฐ๋ฅผ ๋“ฑ๋กํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ํ”Œ๋Ÿฌ๊ทธ์ธ ๋งค๋‹ˆํŽ˜์ŠคํŠธ์— ์ตœ์ƒ์œ„ `monitors` ํ‚ค๋ฅผ ์ถ”๊ฐ€ํ•˜์‹ญ์‹œ์˜ค. + +```json +{ + "name": "my-plugin", + "version": "1.0.0", + "monitors": [ + { + "command": "tail -f /var/log/app.log", + "trigger": "session_start" + } + ] +} +``` +`trigger` ํ•„๋“œ๋Š” ๋‹ค์Œ ๊ฐ’์„ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +- `"session_start"` โ€” ์„ธ์…˜์ด ์‹œ์ž‘๋  ๋•Œ ๋ชจ๋‹ˆํ„ฐ๋ฅผ ์ž๋™์œผ๋กœ ํ™œ์„ฑํ™” +- `"skill_invoke"` โ€” ํ”Œ๋Ÿฌ๊ทธ์ธ์˜ ์Šคํ‚ฌ์ด ํ˜ธ์ถœ๋  ๋•Œ ๋ชจ๋‹ˆํ„ฐ๋ฅผ ํ™œ์„ฑํ™” + +๋ชจ๋‹ˆํ„ฐ๋Š” ๋‚ด๋ถ€์ ์œผ๋กœ ๋™์ผํ•œ Monitor ๋„๊ตฌ๋ฅผ ์‚ฌ์šฉํ•˜๋ฉฐ, stdout์„ ์ด๋ฒคํŠธ ์ŠคํŠธ๋ฆผ์œผ๋กœ ์ „๋‹ฌํ•˜์—ฌ Claude๊ฐ€ ์ด์— ๋ฐ˜์‘ํ•  ์ˆ˜ ์žˆ๋„๋ก ํ•ฉ๋‹ˆ๋‹ค. + +## ์„ค์ • ํŒŒ์ผ์—์„œ ์ธ๋ผ์ธ ํ”Œ๋Ÿฌ๊ทธ์ธ ์‚ฌ์šฉ (`source: 'settings'`) (v2.1.80+) + +ํ”Œ๋Ÿฌ๊ทธ์ธ์€ ์„ค์ • ํŒŒ์ผ์—์„œ `source: 'settings'` ํ•„๋“œ๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ํ•ญ๋ชฉ์œผ๋กœ ์ธ๋ผ์ธ ์ •์˜ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์ด๋ฅผ ํ†ตํ•ด ๋ณ„๋„์˜ ์ €์žฅ์†Œ๋‚˜ ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ์—†์ด ํ”Œ๋Ÿฌ๊ทธ์ธ ์ •์˜๋ฅผ ์ง์ ‘ ํฌํ•จํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +```json +{ + "pluginMarketplaces": [ + { + "name": "inline-tools", + "source": "settings", + "plugins": [ + { + "name": "quick-lint", + "source": "./local-plugins/quick-lint" + } + ] + } + ] +} +``` + +## ํ”Œ๋Ÿฌ๊ทธ์ธ ์„ค์ • + +ํ”Œ๋Ÿฌ๊ทธ์ธ์€ ๊ธฐ๋ณธ ๊ตฌ์„ฑ์„ ์ œ๊ณตํ•˜๊ธฐ ์œ„ํ•ด `settings.json` ํŒŒ์ผ์„ ํฌํ•จํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ํ˜„์žฌ๋Š” ํ”Œ๋Ÿฌ๊ทธ์ธ์˜ ๋ฉ”์ธ ์Šค๋ ˆ๋“œ ์—์ด์ „ํŠธ๋ฅผ ์ง€์ •ํ•˜๋Š” `agent` ํ‚ค๋ฅผ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค. + +```json +{ + "agent": "agents/specialist-1.md" +} +``` + +ํ”Œ๋Ÿฌ๊ทธ์ธ์— `settings.json`์ด ํฌํ•จ๋˜์–ด ์žˆ์œผ๋ฉด ์„ค์น˜ ์‹œ ํ•ด๋‹น ๊ธฐ๋ณธ ์„ค์ •์ด ์ ์šฉ๋ฉ๋‹ˆ๋‹ค. ์‚ฌ์šฉ์ž๋Š” ํ”„๋กœ์ ํŠธ ๋˜๋Š” ์‚ฌ์šฉ์ž ์„ค์ •์—์„œ ์ด๋ฅผ ์žฌ์ •์˜ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +## ๋…๋ฆฝํ˜•๊ณผ ํ”Œ๋Ÿฌ๊ทธ์ธ ๋ฐฉ์‹ ๋น„๊ต + +| Approach | Command Names | Configuration | Best For | +|----------|---------------|---|---| +| **Standalone** | `/hello` | CLAUDE.md์—์„œ ์ˆ˜๋™ ์„ค์ • | ๊ฐœ์ธ์šฉ, ํ”„๋กœ์ ํŠธ๋ณ„ ์‚ฌ์šฉ | +| **Plugins** | `/plugin-name:hello` | plugin.json์„ ํ†ตํ•œ ์ž๋™ ๊ตฌ์„ฑ | ๊ณต์œ , ๋ฐฐํฌ, ํŒ€ ์‚ฌ์šฉ | + +๋น ๋ฅธ ๊ฐœ์ธ ์›Œํฌํ”Œ๋กœ์—๋Š” **๋…๋ฆฝํ˜• ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด**๋ฅผ ์‚ฌ์šฉํ•˜๋Š” ๊ฒƒ์ด ์ข‹์Šต๋‹ˆ๋‹ค. ์—ฌ๋Ÿฌ ๊ธฐ๋Šฅ์„ ํ•˜๋‚˜๋กœ ๋ฌถ๊ฑฐ๋‚˜, ํŒ€๊ณผ ๊ณต์œ ํ•˜๊ฑฐ๋‚˜, ๋ฐฐํฌํ•˜๋ ค๋Š” ๊ฒฝ์šฐ์—๋Š” **ํ”Œ๋Ÿฌ๊ทธ์ธ**์„ ์‚ฌ์šฉํ•˜๋Š” ๊ฒƒ์ด ์ ํ•ฉํ•ฉ๋‹ˆ๋‹ค. + +> **๊ณต๋ฐฑ ๊ตฌ๋ถ„ ํ˜ธ์ถœ(v2.1.136+)**: ํ”Œ๋Ÿฌ๊ทธ์ธ ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด๋Š” ๊ณต๋ฐฑ์„ ์‚ฌ์šฉํ•œ ํ˜•์‹๋„ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค. `/myplugin review`๋Š” ์ •์‹ ํ˜•์‹์ธ `/myplugin:review`๋กœ ํ•ด์„๋ฉ๋‹ˆ๋‹ค. ๋‘ ํ˜•์‹ ๋ชจ๋‘ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์ง€๋งŒ, ์Šคํฌ๋ฆฝํŠธ์—์„œ๋Š” ์ฝœ๋ก (`:`) ํ˜•์‹์„ ๊ถŒ์žฅํ•ฉ๋‹ˆ๋‹ค. + +> **`skills/` ์ž๋™ ๊ฒ€์ƒ‰(v2.1.136+)**: `plugin.json`์— `skills` ํ•ญ๋ชฉ์„ ์ •์˜ํ•ด๋„ ํ”Œ๋Ÿฌ๊ทธ์ธ์˜ ๊ธฐ๋ณธ `skills/` ๋””๋ ‰ํ„ฐ๋ฆฌ๋Š” ๋” ์ด์ƒ ์ˆจ๊ฒจ์ง€์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋‘ ์œ„์น˜์— ์„ ์–ธ๋œ ์Šคํ‚ฌ์€ ๋ณ‘ํ•ฉ๋˜๋ฏ€๋กœ, `plugin.json`์—๋Š” ์ฃผ์š” ์Šคํ‚ฌ๋งŒ ๋‚˜์—ดํ•˜๊ณ  ๋‚˜๋จธ์ง€๋Š” `skills/` ๋””๋ ‰ํ„ฐ๋ฆฌ์— ๊ทธ๋Œ€๋กœ ๋‘˜ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +> **๋ฃจํŠธ ์ˆ˜์ค€ `SKILL.md` ํ”Œ๋Ÿฌ๊ทธ์ธ(v2.1.142+)**: ์ตœ์ƒ์œ„์— `SKILL.md`๊ฐ€ ์žˆ๊ณ  **`skills/` ํ•˜์œ„ ๋””๋ ‰ํ„ฐ๋ฆฌ๊ฐ€ ์—†๋Š”** ํ”Œ๋Ÿฌ๊ทธ์ธ์€ ํ•˜๋‚˜์˜ ์Šคํ‚ฌ๋กœ ๋…ธ์ถœ๋ฉ๋‹ˆ๋‹ค. ์ฆ‰, ํ”Œ๋Ÿฌ๊ทธ์ธ ์ž์ฒด๊ฐ€ ํ•˜๋‚˜์˜ ์Šคํ‚ฌ์ด ๋ฉ๋‹ˆ๋‹ค. ์ด๋Š” `skills/` ๋””๋ ‰ํ„ฐ๋ฆฌ๋‚˜ `plugin.json`์˜ `skills` ํ•ญ๋ชฉ์„ ๋Œ€์ฒดํ•˜๋Š” ๊ฒƒ์ด ์•„๋‹ˆ๋ผ ์ถ”๊ฐ€์ ์ธ ํŒจํ„ด์ด๋ฉฐ, ๋””๋ ‰ํ„ฐ๋ฆฌ ๊ตฌ์กฐ๊ฐ€ ๋ถˆํ•„์š”ํ•œ ๋‹จ์ผ ์Šคํ‚ฌ ํ”Œ๋Ÿฌ๊ทธ์ธ์— ์ ํ•ฉํ•ฉ๋‹ˆ๋‹ค. + +## ์‹ค์šฉ์ ์ธ ์˜ˆ์ œ + +### ์˜ˆ์ œ 1: PR Review ํ”Œ๋Ÿฌ๊ทธ์ธ + +**ํŒŒ์ผ:** `.claude-plugin/plugin.json` + +```json +{ + "name": "pr-review", + "version": "1.0.0", + "description": "Complete PR review workflow with security, testing, and docs", + "author": { + "name": "Anthropic" + }, + "repository": "https://github.com/your-org/pr-review", + "license": "MIT" +} +``` + +**ํŒŒ์ผ:** `commands/review-pr.md` + +```markdown +--- +name: Review PR +description: Start comprehensive PR review with security and testing checks +--- + +# PR Review + +์ด ๋ช…๋ น์€ ๋‹ค์Œ์„ ํฌํ•จํ•œ ์ „์ฒด ํ’€ ๋ฆฌํ€˜์ŠคํŠธ ๊ฒ€ํ† ๋ฅผ ์‹œ์ž‘ํ•ฉ๋‹ˆ๋‹ค. + +1. ๋ณด์•ˆ ๋ถ„์„ +2. ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€ ๊ฒ€์ฆ +3. ๋ฌธ์„œ ์—…๋ฐ์ดํŠธ +4. ์ฝ”๋“œ ํ’ˆ์งˆ ์ ๊ฒ€ +5. ์„ฑ๋Šฅ ์˜ํ–ฅ ํ‰๊ฐ€ +``` + +**ํŒŒ์ผ:** `agents/security-reviewer.md` + +```yaml +--- +name: security-reviewer +description: Security-focused code review +tools: read, grep, diff +--- + +# Security Reviewer + +Specializes in finding security vulnerabilities: +- Authentication/authorization issues +- Data exposure +- Injection attacks +- Secure configuration +``` + +**์„ค์น˜:** + +```bash +/plugin install pr-review + +# Result: +# โœ… 3 slash commands installed +# โœ… 3 subagents configured +# โœ… 2 MCP servers connected +# โœ… 4 hooks registered +# โœ… Ready to use! +``` + +### ์˜ˆ์ œ 2: DevOps ํ”Œ๋Ÿฌ๊ทธ์ธ + +**๊ตฌ์„ฑ ์š”์†Œ:** + +``` +devops-automation/ +โ”œโ”€โ”€ commands/ +โ”‚ โ”œโ”€โ”€ deploy.md +โ”‚ โ”œโ”€โ”€ rollback.md +โ”‚ โ”œโ”€โ”€ status.md +โ”‚ โ””โ”€โ”€ incident.md +โ”œโ”€โ”€ agents/ +โ”‚ โ”œโ”€โ”€ deployment-specialist.md +โ”‚ โ”œโ”€โ”€ incident-commander.md +โ”‚ โ””โ”€โ”€ alert-analyzer.md +โ”œโ”€โ”€ mcp/ +โ”‚ โ”œโ”€โ”€ github-config.json +โ”‚ โ”œโ”€โ”€ kubernetes-config.json +โ”‚ โ””โ”€โ”€ prometheus-config.json +โ”œโ”€โ”€ hooks/ +โ”‚ โ”œโ”€โ”€ pre-deploy.js +โ”‚ โ”œโ”€โ”€ post-deploy.js +โ”‚ โ””โ”€โ”€ on-error.js +โ””โ”€โ”€ scripts/ + โ”œโ”€โ”€ deploy.sh + โ”œโ”€โ”€ rollback.sh + โ””โ”€โ”€ health-check.sh +``` + +### ์˜ˆ์ œ 3: Documentation ํ”Œ๋Ÿฌ๊ทธ์ธ + +**ํฌํ•จ๋œ ๊ตฌ์„ฑ ์š”์†Œ:** + +``` +documentation/ +โ”œโ”€โ”€ commands/ +โ”‚ โ”œโ”€โ”€ generate-api-docs.md +โ”‚ โ”œโ”€โ”€ generate-readme.md +โ”‚ โ”œโ”€โ”€ sync-docs.md +โ”‚ โ””โ”€โ”€ validate-docs.md +โ”œโ”€โ”€ agents/ +โ”‚ โ”œโ”€โ”€ api-documenter.md +โ”‚ โ”œโ”€โ”€ code-commentator.md +โ”‚ โ””โ”€โ”€ example-generator.md +โ”œโ”€โ”€ mcp/ +โ”‚ โ”œโ”€โ”€ github-docs-config.json +โ”‚ โ””โ”€โ”€ slack-announce-config.json +โ””โ”€โ”€ templates/ + โ”œโ”€โ”€ api-endpoint.md + โ”œโ”€โ”€ function-docs.md + โ””โ”€โ”€ adr-template.md +``` + +## ํ”Œ๋Ÿฌ๊ทธ์ธ ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค + +๊ณต์‹ Anthropic ๊ด€๋ฆฌ ํ”Œ๋Ÿฌ๊ทธ์ธ ๋””๋ ‰ํ„ฐ๋ฆฌ๋Š” `anthropics/claude-plugins-official`์ž…๋‹ˆ๋‹ค. Enterprise ๊ด€๋ฆฌ์ž๋Š” ๋‚ด๋ถ€ ๋ฐฐํฌ๋ฅผ ์œ„ํ•œ ์ „์šฉ ํ”Œ๋Ÿฌ๊ทธ์ธ ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค๋ฅผ ์ƒ์„ฑํ•  ์ˆ˜๋„ ์žˆ์Šต๋‹ˆ๋‹ค. + +```mermaid +graph TB + A["Plugin Marketplace"] + B["Official
anthropics/claude-plugins-official"] + C["Community
Marketplace"] + D["Enterprise
Private Registry"] + + A --> B + A --> C + A --> D + + B -->|Categories| B1["Development"] + B -->|Categories| B2["DevOps"] + B -->|Categories| B3["Documentation"] + + C -->|Search| C1["DevOps Automation"] + C -->|Search| C2["Mobile Dev"] + C -->|Search| C3["Data Science"] + + D -->|Internal| D1["Company Standards"] + D -->|Internal| D2["Legacy Systems"] + D -->|Internal| D3["Compliance"] + + style A fill:#e1f5fe,stroke:#333,color:#333 + style B fill:#e8f5e9,stroke:#333,color:#333 + style C fill:#f3e5f5,stroke:#333,color:#333 + style D fill:#fff3e0,stroke:#333,color:#333 +``` + +### ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ๊ตฌ์„ฑ + +Enterprise ์‚ฌ์šฉ์ž์™€ ๊ณ ๊ธ‰ ์‚ฌ์šฉ์ž๋Š” ์„ค์ •์„ ํ†ตํ•ด ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ๋™์ž‘์„ ์ œ์–ดํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +| Setting | Description | +|---------|-------------| +| `extraKnownMarketplaces` | ๊ธฐ๋ณธ๊ฐ’ ์™ธ์— ์ถ”๊ฐ€ ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ์†Œ์Šค๋ฅผ ๋“ฑ๋ก | +| `strictKnownMarketplaces` | ์‚ฌ์šฉ์ž๊ฐ€ ์ถ”๊ฐ€ํ•  ์ˆ˜ ์žˆ๋Š” ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค๋ฅผ ์ œํ•œ(๊ด€๋ฆฌ์ž ์ „์šฉ) | +| `blockedMarketplaces` | ๊ด€๋ฆฌ์ž๊ฐ€ ์ฐจ๋‹จํ•œ ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ๋ชฉ๋ก(v2.1.119๋ถ€ํ„ฐ `hostPattern` / `pathPattern` ์ •๊ทœ์‹ ์ง€์›) | +| `deniedPlugins` | ํŠน์ • ํ”Œ๋Ÿฌ๊ทธ์ธ์˜ ์„ค์น˜๋ฅผ ์ฐจ๋‹จํ•˜๋Š” ๊ด€๋ฆฌ์ž ๊ด€๋ฆฌ ๋ชฉ๋ก | + +> **์ ์šฉ ๋ฒ”์œ„** (v2.1.117+): `blockedMarketplaces`์™€ `strictKnownMarketplaces`๋Š” ์ตœ์ดˆ ์ถ”๊ฐ€ ์‹œ๋ฟ๋งŒ ์•„๋‹ˆ๋ผ ์„ค์น˜, ์—…๋ฐ์ดํŠธ, ์ƒˆ๋กœ ๊ณ ์นจ, ์ž๋™ ์—…๋ฐ์ดํŠธ ๋“ฑ ๋ชจ๋“  ํ”Œ๋Ÿฌ๊ทธ์ธ ์ƒ๋ช…์ฃผ๊ธฐ ์ด๋ฒคํŠธ์— ์ ์šฉ๋ฉ๋‹ˆ๋‹ค. `strictKnownMarketplaces`๋Š” ๊ด€๋ฆฌ์ž ์ „์šฉ ๊ธฐ๋Šฅ์ž…๋‹ˆ๋‹ค. + +ํ˜ธ์ŠคํŠธ/๊ฒฝ๋กœ ์ •๊ทœ์‹์„ ์‚ฌ์šฉํ•˜๋Š” `blockedMarketplaces` ์˜ˆ์‹œ(v2.1.119): + +```json +{ + "blockedMarketplaces": [ + { + "hostPattern": "^evil\\.example\\.com$", + "pathPattern": "^/marketplaces/.*" + } + ] +} +``` + +### ์ถ”๊ฐ€ ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ๊ธฐ๋Šฅ + +- **๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ๊ฒ€์ƒ‰์ฐฝ(v2.1.172)**: `/plugin`์—์„œ ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค๋ฅผ ํƒ์ƒ‰ํ•  ๋•Œ ์ด๋ฆ„์ด๋‚˜ ํ‚ค์›Œ๋“œ๋กœ ํ”Œ๋Ÿฌ๊ทธ์ธ์„ ๊ฒ€์ƒ‰ํ•  ์ˆ˜ ์žˆ๋Š” ๊ฒ€์ƒ‰์ฐฝ์ด ์ œ๊ณต๋ฉ๋‹ˆ๋‹ค. ํ”Œ๋Ÿฌ๊ทธ์ธ์ด ๋งŽ์€ ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค์—์„œ ํŠนํžˆ ์œ ์šฉํ•ฉ๋‹ˆ๋‹ค. +- **๊ธฐ๋ณธ Git ํƒ€์ž„์•„์›ƒ**: ๋Œ€๊ทœ๋ชจ ํ”Œ๋Ÿฌ๊ทธ์ธ ์ €์žฅ์†Œ๋ฅผ ์œ„ํ•ด ๊ธฐ๋ณธ ํƒ€์ž„์•„์›ƒ์ด 30์ดˆ์—์„œ 120์ดˆ๋กœ ์ฆ๊ฐ€ํ–ˆ์Šต๋‹ˆ๋‹ค. +- **์‚ฌ์šฉ์ž ์ง€์ • npm ๋ ˆ์ง€์ŠคํŠธ๋ฆฌ**: ํ”Œ๋Ÿฌ๊ทธ์ธ์€ ์˜์กด์„ฑ ํ•ด๊ฒฐ์„ ์œ„ํ•ด ์‚ฌ์šฉ์ž ์ง€์ • npm ๋ ˆ์ง€์ŠคํŠธ๋ฆฌ URL์„ ์ง€์ •ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. +- **๋ฒ„์ „ ๊ณ ์ •(Version pinning)**: ์žฌํ˜„ ๊ฐ€๋Šฅํ•œ ํ™˜๊ฒฝ์„ ์œ„ํ•ด ํŠน์ • ํ”Œ๋Ÿฌ๊ทธ์ธ ๋ฒ„์ „์— ๊ณ ์ •ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. +- **๋ธŒ๋ผ์šฐ์ € ํŒจ๋„์˜ ์˜ˆ์ƒ ์ปจํ…์ŠคํŠธ ๋น„์šฉ(v2.1.143)**: `/plugin` ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ๋ธŒ๋ผ์šฐ์ €๋Š” ๊ฐ ํ”Œ๋Ÿฌ๊ทธ์ธ์˜ ํ„ด๋‹น ์˜ˆ์ƒ ์ปจํ…์ŠคํŠธ ํ† ํฐ ๋น„์šฉ์„ ํ‘œ์‹œํ•ฉ๋‹ˆ๋‹ค. ์ด๋Š” ํ•ญ์ƒ ๋กœ๋“œ๋˜๋Š” ์Šคํ‚ฌ, ํ›…, MCP ์„œ๋ฒ„ ์„ค๋ช…์ž์˜ ํ•ฉ๊ณ„์ž…๋‹ˆ๋‹ค. ์„ค์น˜ ์ „์— ํ”Œ๋Ÿฌ๊ทธ์ธ ๋„์ž… ๋น„์šฉ์„ ์˜ˆ์ธกํ•˜๋Š” ๋ฐ ํ™œ์šฉํ•  ์ˆ˜ ์žˆ์œผ๋ฉฐ, ์„ค์น˜ ํ›„์—๋Š” [`claude plugin details `](#claude-plugin-details-name-v21139)์—์„œ๋„ ๋™์ผํ•œ ์ •๋ณด๋ฅผ ํ™•์ธํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +๋น„์šฉ ์—ด์ด ํฌํ•จ๋œ ๋ธŒ๋ผ์šฐ์ € ํ‘œ์‹œ ์˜ˆ์‹œ: + +```text +NAME VERSION AUTHOR CTX/TURN DESCRIPTION +code-reviewer 1.2.0 anthropic +1,420 Multi-agent PR review +devops-toolkit 0.4.1 acme +3,180 SRE playbooks, on-call helpers +docs-helper 0.9.0 community +610 Doc-style guide enforcement +``` + +### ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ์ •์˜ ์Šคํ‚ค๋งˆ + +ํ”Œ๋Ÿฌ๊ทธ์ธ ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค๋Š” `.claude-plugin/marketplace.json`์— ์ •์˜๋ฉ๋‹ˆ๋‹ค. + +```json +{ + "name": "my-team-plugins", + "owner": "my-org", + "plugins": [ + { + "name": "code-standards", + "source": "./plugins/code-standards", + "description": "Enforce team coding standards", + "version": "1.2.0", + "author": "platform-team" + }, + { + "name": "deploy-helper", + "source": { + "source": "github", + "repo": "my-org/deploy-helper", + "ref": "v2.0.0" + }, + "description": "Deployment automation workflows" + } + ] +} +``` + +| Field | Required | Description | +|-------|----------|-------------| +| `name` | Yes | kebab-case ํ˜•์‹์˜ ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ์ด๋ฆ„ | +| `owner` | Yes | ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค๋ฅผ ์œ ์ง€ ๊ด€๋ฆฌํ•˜๋Š” ์กฐ์ง ๋˜๋Š” ์‚ฌ์šฉ์ž | +| `plugins` | Yes | ํ”Œ๋Ÿฌ๊ทธ์ธ ํ•ญ๋ชฉ ๋ฐฐ์—ด | +| `plugins[].name` | Yes | ํ”Œ๋Ÿฌ๊ทธ์ธ ์ด๋ฆ„(kebab-case) | +| `plugins[].source` | Yes | ํ”Œ๋Ÿฌ๊ทธ์ธ ์†Œ์Šค(๊ฒฝ๋กœ ๋ฌธ์ž์—ด ๋˜๋Š” ์†Œ์Šค ๊ฐ์ฒด) | +| `plugins[].description` | No | ํ”Œ๋Ÿฌ๊ทธ์ธ์— ๋Œ€ํ•œ ๊ฐ„๋‹จํ•œ ์„ค๋ช… | +| `plugins[].version` | No | ์‹œ๋งจํ‹ฑ ๋ฒ„์ „ ๋ฌธ์ž์—ด | +| `plugins[].author` | No | ํ”Œ๋Ÿฌ๊ทธ์ธ ์ž‘์„ฑ์ž ์ด๋ฆ„ | + +### ํ”Œ๋Ÿฌ๊ทธ์ธ ์†Œ์Šค ์œ ํ˜• + +ํ”Œ๋Ÿฌ๊ทธ์ธ์€ ์—ฌ๋Ÿฌ ์œ„์น˜์—์„œ ๊ฐ€์ ธ์˜ฌ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +| ์†Œ์Šค | ๋ฌธ๋ฒ• | ์˜ˆ์‹œ | +|--------|--------|---------| +| **์ƒ๋Œ€ ๊ฒฝ๋กœ** | ๋ฌธ์ž์—ด ๊ฒฝ๋กœ | `"./plugins/my-plugin"` | +| **GitHub** | `{ "source": "github", "repo": "owner/repo" }` | `{ "source": "github", "repo": "acme/lint-plugin", "ref": "v1.0" }` | +| **Git URL** | `{ "source": "url", "url": "..." }` | `{ "source": "url", "url": "https://git.internal/plugin.git" }` | +| **Git ํ•˜์œ„ ๋””๋ ‰ํ„ฐ๋ฆฌ** | `{ "source": "git-subdir", "url": "...", "path": "..." }` | `{ "source": "git-subdir", "url": "https://github.com/org/monorepo.git", "path": "packages/plugin" }` | +| **npm** | `{ "source": "npm", "package": "..." }` | `{ "source": "npm", "package": "@acme/claude-plugin", "version": "^2.0" }` | +| **pip** | `{ "source": "pip", "package": "..." }` | `{ "source": "pip", "package": "claude-data-plugin", "version": ">=1.0" }` | + +GitHub ๋ฐ git ์†Œ์Šค๋Š” ๋ฒ„์ „ ๊ณ ์ •์„ ์œ„ํ•ด ์„ ํƒ์ ์œผ๋กœ `ref`(๋ธŒ๋žœ์น˜/ํƒœ๊ทธ) ๋ฐ `sha`(์ปค๋ฐ‹ ํ•ด์‹œ) ํ•„๋“œ๋ฅผ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค. + +### ๋ฐฐํฌ ๋ฐฉ๋ฒ• + +**GitHub(๊ถŒ์žฅ)**: +```bash +# Users add your marketplace +/plugin marketplace add owner/repo-name +``` + +**๊ธฐํƒ€ git ์„œ๋น„์Šค**(์ „์ฒด URL ํ•„์š”): +```bash +/plugin marketplace add https://gitlab.com/org/marketplace-repo.git +``` + +**๋น„๊ณต๊ฐœ ์ €์žฅ์†Œ**: git ์ž๊ฒฉ ์ฆ๋ช… ๋„์šฐ๋ฏธ(git credential helpers) ๋˜๋Š” ํ™˜๊ฒฝ ๋ณ€์ˆ˜ ํ† ํฐ์„ ํ†ตํ•ด ์ง€์›๋ฉ๋‹ˆ๋‹ค. ์‚ฌ์šฉ์ž๋Š” ์ €์žฅ์†Œ์— ๋Œ€ํ•œ ์ฝ๊ธฐ ๊ถŒํ•œ์„ ๊ฐ€์ง€๊ณ  ์žˆ์–ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. + +**๊ณต์‹ ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ๋“ฑ๋ก**: ๋” ๋„“์€ ๋ฐฐํฌ๋ฅผ ์œ„ํ•ด Anthropic์—์„œ ํ๋ ˆ์ด์…˜ํ•˜๋Š” ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค์— ํ”Œ๋Ÿฌ๊ทธ์ธ์„ ๋“ฑ๋กํ•˜๋ ค๋ฉด [claude.ai/settings/plugins/submit](https://claude.ai/settings/plugins/submit) ๋˜๋Š” [platform.claude.com/plugins/submit](https://platform.claude.com/plugins/submit)์„ ์ด์šฉํ•˜์‹ญ์‹œ์˜ค. + +### ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ๊ด€๋ฆฌ + +```bash +# Marketplace CLI commands +claude plugin marketplace add # Add marketplace (GitHub, URL, local) +claude plugin marketplace update [name] # Refresh catalog index +claude plugin marketplace remove # Remove marketplace +claude plugin marketplace list # List configured marketplaces +``` + +> **์ค‘์š”**: `marketplace update`๋Š” ํ”Œ๋Ÿฌ๊ทธ์ธ ์นดํƒˆ๋กœ๊ทธ(์„ค์น˜ ๊ฐ€๋Šฅํ•œ ํ”Œ๋Ÿฌ๊ทธ์ธ ๋ชฉ๋ก)๋งŒ ์ƒˆ๋กœ ๊ณ ์นฉ๋‹ˆ๋‹ค. ์„ค์น˜๋œ ํ”Œ๋Ÿฌ๊ทธ์ธ์€ ์—…๋ฐ์ดํŠธํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ์„ค์น˜๋œ ํŠน์ • ํ”Œ๋Ÿฌ๊ทธ์ธ์„ ์—…๋ฐ์ดํŠธํ•˜๋ ค๋ฉด `plugin update `์„ ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค. + +### Strict ๋ชจ๋“œ + +๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ์ •์˜๊ฐ€ ๋กœ์ปฌ `plugin.json` ํŒŒ์ผ๊ณผ ์ƒํ˜ธ ์ž‘์šฉํ•˜๋Š” ๋ฐฉ์‹์„ ์ œ์–ดํ•ฉ๋‹ˆ๋‹ค. + +| ์„ค์ • | ๋™์ž‘ | +|---------|----------| +| `strict: true` (default) | ๋กœ์ปฌ `plugin.json`์ด ๊ธฐ์ค€์ด ๋˜๋ฉฐ, ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ํ•ญ๋ชฉ์€ ์ด๋ฅผ ๋ณด์™„ํ•ฉ๋‹ˆ๋‹ค. | +| `strict: false` | ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ํ•ญ๋ชฉ์ด ์ „์ฒด ํ”Œ๋Ÿฌ๊ทธ์ธ ์ •์˜๊ฐ€ ๋ฉ๋‹ˆ๋‹ค. | + +**`strictKnownMarketplaces`๋ฅผ ์‚ฌ์šฉํ•œ ์กฐ์ง ์ œํ•œ**: + +| ๊ฐ’ | ํšจ๊ณผ | +|-------|--------| +| ์„ค์ •๋˜์ง€ ์•Š์Œ | ์ œํ•œ ์—†์Œ โ€” ์‚ฌ์šฉ์ž๋Š” ์–ด๋–ค ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค๋“  ์ถ”๊ฐ€ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. | +| ๋นˆ ๋ฐฐ์—ด `[]` | ์™„์ „ ์ œํ•œ โ€” ์–ด๋–ค ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค๋„ ํ—ˆ์šฉ๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. | +| ํŒจํ„ด ๋ฐฐ์—ด | ํ—ˆ์šฉ ๋ชฉ๋ก โ€” ์ผ์น˜ํ•˜๋Š” ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค๋งŒ ์ถ”๊ฐ€ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. | + +```json +{ + "strictKnownMarketplaces": [ + "my-org/*", + "github.com/trusted-vendor/*" + ] +} +``` + +> **๊ฒฝ๊ณ **: `strictKnownMarketplaces`๊ฐ€ ์ ์šฉ๋œ strict ๋ชจ๋“œ์—์„œ๋Š” ์‚ฌ์šฉ์ž๊ฐ€ ํ—ˆ์šฉ ๋ชฉ๋ก์— ํฌํ•จ๋œ ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค์˜ ํ”Œ๋Ÿฌ๊ทธ์ธ๋งŒ ์„ค์น˜ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์ด๋Š” ํ”Œ๋Ÿฌ๊ทธ์ธ ๋ฐฐํฌ๋ฅผ ํ†ต์ œํ•ด์•ผ ํ•˜๋Š” ์—”ํ„ฐํ”„๋ผ์ด์ฆˆ ํ™˜๊ฒฝ์— ์œ ์šฉํ•ฉ๋‹ˆ๋‹ค. + +## ํ”Œ๋Ÿฌ๊ทธ์ธ ์„ค์น˜ ๋ฐ ์ˆ˜๋ช… ์ฃผ๊ธฐ + +```mermaid +graph LR + A["Discover"] -->|Browse| B["Marketplace"] + B -->|Select| C["Plugin Page"] + C -->|View| D["Components"] + D -->|Install| E["/plugin install"] + E -->|Extract| F["Configure"] + F -->|Activate| G["Use"] + G -->|Check| H["Update"] + H -->|Available| G + G -->|Done| I["Disable"] + I -->|Later| J["Enable"] + J -->|Back| G +``` + +## ํ”Œ๋Ÿฌ๊ทธ์ธ ๊ธฐ๋Šฅ ๋น„๊ต + +| ๊ธฐ๋Šฅ | Slash Command | Skill | Subagent | Plugin | +|---------|---------------|-------|----------|--------| +| **Installation** | ์ˆ˜๋™ ๋ณต์‚ฌ | ์ˆ˜๋™ ๋ณต์‚ฌ | ์ˆ˜๋™ ์„ค์ • | ๋ช…๋ น ํ•œ ๋ฒˆ | +| **Setup Time** | 5๋ถ„ | 10๋ถ„ | 15๋ถ„ | 2๋ถ„ | +| **Bundling** | ๋‹จ์ผ ํŒŒ์ผ | ๋‹จ์ผ ํŒŒ์ผ | ๋‹จ์ผ ํŒŒ์ผ | ์—ฌ๋Ÿฌ ํŒŒ์ผ | +| **Versioning** | ์ˆ˜๋™ | ์ˆ˜๋™ | ์ˆ˜๋™ | ์ž๋™ | +| **Team Sharing** | ํŒŒ์ผ ๋ณต์‚ฌ | ํŒŒ์ผ ๋ณต์‚ฌ | ํŒŒ์ผ ๋ณต์‚ฌ | ์„ค์น˜ ID | +| **Updates** | ์ˆ˜๋™ | ์ˆ˜๋™ | ์ˆ˜๋™ | ์ž๋™ ์ œ๊ณต | +| **Dependencies** | ์—†์Œ | ์—†์Œ | ์—†์Œ | ํฌํ•จ๋  ์ˆ˜ ์žˆ์Œ | +| **Marketplace** | ์•„๋‹ˆ์š” | ์•„๋‹ˆ์š” | ์•„๋‹ˆ์š” | ์˜ˆ | +| **Distribution** | ์ €์žฅ์†Œ | ์ €์žฅ์†Œ | ์ €์žฅ์†Œ | ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค | + +## ํ”Œ๋Ÿฌ๊ทธ์ธ CLI ๋ช…๋ น + +๋ชจ๋“  ํ”Œ๋Ÿฌ๊ทธ์ธ ์ž‘์—…์€ CLI ๋ช…๋ น์œผ๋กœ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +```bash +claude plugin install @ # Install from a marketplace +claude plugin uninstall # Remove a plugin +claude plugin update # Update installed plugin to latest version +claude plugin list # List installed plugins +claude plugin enable # Enable a disabled plugin +claude plugin disable # Disable a plugin +claude plugin validate # Validate plugin structure +claude plugin tag # Create a release git tag with version validation (v2.1.118+) +claude plugin prune # Remove orphaned auto-installed plugin dependencies (v2.1.121+) +claude plugin uninstall --prune # Uninstall and cascade-clean orphaned dependencies (v2.1.121+) +claude plugin details # Show inventory + projected per-turn token cost (v2.1.139+) +``` + +์˜ˆ์‹œ: `claude plugin tag v0.3.0`์€ ๋ฒ„์ „ ํ˜•์‹์„ ๊ฒ€์ฆํ•˜๊ณ , ํ•ด๋‹นํ•˜๋Š” git ํƒœ๊ทธ๋ฅผ ์ƒ์„ฑํ•˜๋ฉฐ, ๋ฐฐํฌ๋ฅผ ์œ„ํ•œ ํ”Œ๋Ÿฌ๊ทธ์ธ ๋ฆด๋ฆฌ์Šค๋ฅผ ๋งŒ๋“œ๋Š” ๊ถŒ์žฅ ๋ฐฉ๋ฒ•์ž…๋‹ˆ๋‹ค. + +`claude plugin prune`์€ ์ž์ฒด ์˜์กด์„ฑ์„ ํ•จ๊ป˜ ์„ค์น˜ํ•œ ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ํ”Œ๋Ÿฌ๊ทธ์ธ์„ ์„ค์น˜ํ•˜๊ฑฐ๋‚˜ ์ œ๊ฑฐํ•œ ํ›„ ์œ ์šฉํ•ฉ๋‹ˆ๋‹ค. ์ƒ์œ„ ํ”Œ๋Ÿฌ๊ทธ์ธ์ด ์ œ๊ฑฐ๋˜์–ด ๋” ์ด์ƒ ํ•„์š”ํ•˜์ง€ ์•Š์€ ์ž๋™ ์„ค์น˜ ํ”Œ๋Ÿฌ๊ทธ์ธ์„ ์‚ญ์ œํ•ฉ๋‹ˆ๋‹ค. `plugin uninstall --prune`์€ ๋™์ผํ•œ ์ •๋ฆฌ ์ž‘์—…์„ ํ•œ ๋ฒˆ์— ์ˆ˜ํ–‰ํ•ฉ๋‹ˆ๋‹ค. + +> **์˜์กด์„ฑ ์ ์šฉ(v2.1.143)**: `claude plugin disable `์€ ๋‹ค๋ฅธ ํ™œ์„ฑํ™”๋œ ํ”Œ๋Ÿฌ๊ทธ์ธ์ด ๋Œ€์ƒ ํ”Œ๋Ÿฌ๊ทธ์ธ์— ์—ฌ์ „ํžˆ ์˜์กดํ•˜๊ณ  ์žˆ๋Š” ๊ฒฝ์šฐ(์˜์กด์„ฑ ๊ทธ๋ž˜ํ”„๊ฐ€ ๊นจ์ง€๋Š” ๊ฒฝ์šฐ) **์‹คํ–‰์ด ๊ฑฐ๋ถ€๋ฉ๋‹ˆ๋‹ค**. `claude plugin enable `์€ ๊ฐ ์˜์กด์„ฑ์„ ๊ฐœ๋ณ„์ ์œผ๋กœ ํ™œ์„ฑํ™”ํ•  ํ•„์š” ์—†์ด ํ•œ ๋ฒˆ์˜ ํ™•์ธ๋งŒ์œผ๋กœ **์ „์ด ์˜์กด์„ฑ์„ ๋ชจ๋‘ ๊ฐ•์ œ๋กœ ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค**. ์ดํ›„ ์ข…์† ํ”Œ๋Ÿฌ๊ทธ์ธ์ด ์ œ๊ฑฐ๋˜์–ด ๋” ์ด์ƒ ํ•„์š”ํ•˜์ง€ ์•Š์€ ์˜์กด์„ฑ์„ ์ •๋ฆฌํ•˜๋ ค๋ฉด `claude plugin prune`์„ ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค. + +### `claude plugin details ` (v2.1.139+) + +`claude plugin details `์€ ํ”Œ๋Ÿฌ๊ทธ์ธ์˜ ์ „์ฒด ๊ตฌ์„ฑ ์š”์†Œ ๋ชฉ๋ก(์Šคํ‚ฌ, ํ›…, MCP ์„œ๋ฒ„, LSP ์„œ๋ฒ„, ๋ฐฑ๊ทธ๋ผ์šด๋“œ ๋ชจ๋‹ˆํ„ฐ, ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด)๊ณผ **ํ„ด๋‹น(๋ฐ ํ˜ธ์ถœ๋‹น) ์˜ˆ์ƒ ํ† ํฐ ๋น„์šฉ**์„ ์ถœ๋ ฅํ•ฉ๋‹ˆ๋‹ค. ํŠนํžˆ ์ปจํ…์ŠคํŠธ๊ฐ€ ์ œํ•œ๋œ ๋ชจ๋ธ์—์„œ ํ”Œ๋Ÿฌ๊ทธ์ธ์„ ๋„์ž…ํ•˜๊ธฐ ์ „์— ๊ทœ๋ชจ๋ฅผ ํŒŒ์•…ํ•˜๋Š” ๋ฐ ์œ ์šฉํ•ฉ๋‹ˆ๋‹ค. + +์˜ˆ์‹œ ์ถœ๋ ฅ(์ผ๋ถ€ ์ƒ๋žต): + +```text +plugin: code-reviewer (1.2.0) +skills: 3 hooks: 2 mcp: 1 lsp: 0 monitors: 0 +commands: /review, /security-review +projected ctx: +1,420 tokens per turn ยท +9,800 tokens per /review invocation +``` + +LSP ์„œ๋ฒ„๋Š” v2.1.142์—์„œ ์„ธ๋ถ€ ์ •๋ณด ํ™”๋ฉด์— ์ถ”๊ฐ€๋˜์—ˆ์Šต๋‹ˆ๋‹ค. ๋˜ํ•œ [ํ”Œ๋Ÿฌ๊ทธ์ธ ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค](#ํ”Œ๋Ÿฌ๊ทธ์ธ-๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค)์—์„œ ์„ค๋ช…ํ•˜๋Š” ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ํƒ์ƒ‰ ํ™”๋ฉด์˜ ์˜ˆ์ƒ ์ปจํ…์ŠคํŠธ ๋น„์šฉ(v2.1.143+)๋„ ์ฐธ๊ณ ํ•˜์‹ญ์‹œ์˜ค. + +## ์„ค์น˜ ๋ฐฉ๋ฒ• + +### ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค์—์„œ ์„ค์น˜ + +```bash +/plugin install plugin-name +# or from CLI: +claude plugin install plugin-name@marketplace-name +``` + +### ํ™œ์„ฑํ™” / ๋น„ํ™œ์„ฑํ™”(๋ฒ”์œ„ ์ž๋™ ๊ฐ์ง€) +```bash +/plugin enable plugin-name +/plugin disable plugin-name +``` + +`/plugin` ์ธํ„ฐํŽ˜์ด์Šค๋Š” ์‚ฌ์šฉํ•˜์ง€ ์•Š๋Š” ํ”Œ๋Ÿฌ๊ทธ์ธ์„ ํ‘œ์‹œํ•˜์—ฌ ์ •๋ฆฌํ•  ์ˆ˜ ์žˆ๋„๋ก ์ง€์›ํ•ฉ๋‹ˆ๋‹ค(v2.1.187+). ๋˜ํ•œ ํ”Œ๋Ÿฌ๊ทธ์ธ์˜ `plugin.json`์— ์žˆ๋Š” `name`์ด ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ํ•ญ๋ชฉ ์ด๋ฆ„๊ณผ ๋‹ค๋ฅธ ๊ฒฝ์šฐ์—๋„ ํ™œ์„ฑํ™”/๋น„ํ™œ์„ฑํ™”๊ฐ€ ๊ฐ€๋Šฅํ•ฉ๋‹ˆ๋‹ค(v2.1.195+). + +### ์„ค์น˜๋œ ํ”Œ๋Ÿฌ๊ทธ์ธ ๋ชฉ๋ก ๋ณด๊ธฐ(v2.1.163) +ํ˜„์žฌ ์„ธ์…˜์—์„œ ์–ด๋–ค ํ”Œ๋Ÿฌ๊ทธ์ธ์ด ํ™œ์„ฑํ™”๋˜์–ด ์žˆ๋Š”์ง€ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. +```bash +/plugin list # all installed plugins +/plugin list --enabled # only enabled plugins +/plugin list --disabled # only disabled plugins +``` + +### ๋กœ์ปฌ ํ”Œ๋Ÿฌ๊ทธ์ธ(๊ฐœ๋ฐœ์šฉ) +```bash +# CLI flag for local testing (repeatable for multiple plugins) +claude --plugin-dir ./path/to/plugin +claude --plugin-dir ./plugin-a --plugin-dir ./plugin-b + +# --plugin-dir also accepts a .zip archive path (v2.1.128+) +claude --plugin-dir ./my-plugin.zip + +# Fetch a plugin .zip archive from a URL for the current session (v2.1.129+, repeatable) +claude --plugin-url https://example.com/releases/my-plugin-0.3.0.zip +``` + +### Git ์ €์žฅ์†Œ์—์„œ ์„ค์น˜ +```bash +/plugin install github:username/repo +``` + +## ์ž๋™ ์—…๋ฐ์ดํŠธ + +Claude Code๋Š” ์‹œ์ž‘ ์‹œ ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค์™€ ์„ค์น˜๋œ ํ”Œ๋Ÿฌ๊ทธ์ธ์„ ์ž๋™์œผ๋กœ ์—…๋ฐ์ดํŠธํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +| ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ์œ ํ˜• | ๊ธฐ๋ณธ ์ž๋™ ์—…๋ฐ์ดํŠธ | ๋ณ€๊ฒฝ ๋ฐฉ๋ฒ• | +|------------------|---------------------|---------------| +| ๊ณต์‹ (`claude-plugins-official`) | โœ… ํ™œ์„ฑํ™” | `/plugin` โ†’ Marketplaces โ†’ ์„ ํƒ | +| ์„œ๋“œํŒŒํ‹ฐ / ๋กœ์ปฌ | โŒ ๋น„ํ™œ์„ฑํ™” | ๋™์ผํ•œ UI ๊ฒฝ๋กœ | + +์ž๋™ ์—…๋ฐ์ดํŠธ๊ฐ€ ์‹คํ–‰๋˜๋ฉด Claude Code๋Š” ๋‹ค์Œ ์ž‘์—…์„ ์ˆ˜ํ–‰ํ•ฉ๋‹ˆ๋‹ค. + +1. ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ์นดํƒˆ๋กœ๊ทธ๋ฅผ ์ƒˆ๋กœ ๊ณ ์นฉ๋‹ˆ๋‹ค. +2. ์„ค์น˜๋œ ํ”Œ๋Ÿฌ๊ทธ์ธ์„ ์ตœ์‹  ๋ฒ„์ „์œผ๋กœ ์—…๋ฐ์ดํŠธํ•ฉ๋‹ˆ๋‹ค. +3. `/reload-plugins` ์‹คํ–‰์„ ์•ˆ๋‚ดํ•˜๋Š” ์•Œ๋ฆผ์„ ํ‘œ์‹œํ•ฉ๋‹ˆ๋‹ค. + +### ํ™˜๊ฒฝ ๋ณ€์ˆ˜ + +| ๋ณ€์ˆ˜ | ํšจ๊ณผ | +|----------|--------| +| `DISABLE_AUTOUPDATER=1` | ๋ชจ๋“  ์ž๋™ ์—…๋ฐ์ดํŠธ ๋น„ํ™œ์„ฑํ™”(Claude Code + ํ”Œ๋Ÿฌ๊ทธ์ธ) | +| `DISABLE_AUTOUPDATER=1` + `FORCE_AUTOUPDATE_PLUGINS=1` | Claude Code ์—…๋ฐ์ดํŠธ๋Š” ๋น„ํ™œ์„ฑํ™”ํ•˜๊ณ  ํ”Œ๋Ÿฌ๊ทธ์ธ ์—…๋ฐ์ดํŠธ๋Š” ์œ ์ง€ | +| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1` | (v2.1.141+) SSH ์›๊ฒฉ ์ €์žฅ์†Œ๊ฐ€ ์žˆ์–ด๋„ `claude plugin install`์ด GitHub ํ”Œ๋Ÿฌ๊ทธ์ธ ์†Œ์Šค๋ฅผ SSH ๋Œ€์‹  HTTPS๋กœ ๋ณต์ œํ•˜๋„๋ก ๊ฐ•์ œํ•ฉ๋‹ˆ๋‹ค. SSH ํ‚ค๊ฐ€ ์—†๋Š” CI ์‹คํ–‰๊ธฐ๋‚˜ ์ปจํ…Œ์ด๋„ˆ์—์„œ ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค. | + +```bash +# Disable all auto-updates +export DISABLE_AUTOUPDATER=1 + +# Keep plugin auto-updates only +export DISABLE_AUTOUPDATER=1 +export FORCE_AUTOUPDATE_PLUGINS=1 + +# CI runner without SSH keys โ€” force HTTPS for plugin installs +export CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 +claude plugin install code-reviewer@anthropic +``` + +> **์›๊ฒฉ ์„ธ์…˜ ํ”Œ๋Ÿฌ๊ทธ์ธ ๋กœ๋”ฉ(v2.1.179)**: v2.1.179์—์„œ๋Š” ์›๊ฒฉ ์„ธ์…˜์˜ ํ”Œ๋Ÿฌ๊ทธ์ธ ๋กœ๋”ฉ ์„ฑ๋Šฅ์ด ๊ฐœ์„ ๋˜์–ด ์›๊ฒฉ ์„ธ์…˜์— ์—ฐ๊ฒฐํ•˜๋ฉด ํ”Œ๋Ÿฌ๊ทธ์ธ์„ ๋” ๋น ๋ฅด๊ฒŒ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +## ํ”Œ๋Ÿฌ๊ทธ์ธ์„ ๋งŒ๋“ค์–ด์•ผ ํ•˜๋Š” ๊ฒฝ์šฐ + +```mermaid +graph TD + A["Should I create a plugin?"] + A -->|Need multiple components| B{"Multiple commands
or subagents
or MCPs?"} + B -->|Yes| C["โœ… Create Plugin"] + B -->|No| D["Use Individual Feature"] + A -->|Team workflow| E{"Share with
team?"} + E -->|Yes| C + E -->|No| F["Keep as Local Setup"] + A -->|Complex setup| G{"Needs auto
configuration?"} + G -->|Yes| C + G -->|No| D +``` + +### ํ”Œ๋Ÿฌ๊ทธ์ธ ์‚ฌ์šฉ ์‚ฌ๋ก€ + +| Use Case | Recommendation | Why | +|----------|-----------------|-----| +| **Team Onboarding** | โœ… Use Plugin | Instant setup, all configurations | +| **Framework Setup** | โœ… Use Plugin | Bundles framework-specific commands | +| **Enterprise Standards** | โœ… Use Plugin | Central distribution, version control | +| **Quick Task Automation** | โŒ Use Command | Overkill complexity | +| **Single Domain Expertise** | โŒ Use Skill | Too heavy, use skill instead | +| **Specialized Analysis** | โŒ Use Subagent | Create manually or use skill | +| **Live Data Access** | โŒ Use MCP | Standalone, don't bundle | + +## ํ”Œ๋Ÿฌ๊ทธ์ธ ํ…Œ์ŠคํŠธ + +๊ฒŒ์‹œํ•˜๊ธฐ ์ „์— `--plugin-dir` CLI ํ”Œ๋ž˜๊ทธ(์—ฌ๋Ÿฌ ํ”Œ๋Ÿฌ๊ทธ์ธ ์ง€์ • ๊ฐ€๋Šฅ)๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ๋กœ์ปฌ์—์„œ ํ”Œ๋Ÿฌ๊ทธ์ธ์„ ํ…Œ์ŠคํŠธํ•˜์‹ญ์‹œ์˜ค. + +```bash +claude --plugin-dir ./my-plugin +claude --plugin-dir ./my-plugin --plugin-dir ./another-plugin + +# --plugin-dir accepts .zip archives in addition to directories (v2.1.128+) +claude --plugin-dir ./my-plugin.zip + +# --plugin-url fetches a plugin .zip from a URL for this session (v2.1.129+, repeatable) +claude --plugin-url https://example.com/releases/my-plugin-0.3.0.zip +``` + +์ด๋ ‡๊ฒŒ ํ•˜๋ฉด ํ”Œ๋Ÿฌ๊ทธ์ธ์ด ๋กœ๋“œ๋œ ์ƒํƒœ๋กœ Claude Code๊ฐ€ ์‹คํ–‰๋˜๋ฉฐ ๋‹ค์Œ ์‚ฌํ•ญ์„ ํ™•์ธํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +- ๋ชจ๋“  ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด๊ฐ€ ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ์ง€ ํ™•์ธ +- Subagent ๋ฐ Agent๊ฐ€ ์ •์ƒ์ ์œผ๋กœ ๋™์ž‘ํ•˜๋Š”์ง€ ํ…Œ์ŠคํŠธ +- MCP ์„œ๋ฒ„๊ฐ€ ์ •์ƒ์ ์œผ๋กœ ์—ฐ๊ฒฐ๋˜๋Š”์ง€ ํ™•์ธ +- Hook ์‹คํ–‰ ๊ฒ€์ฆ +- LSP ์„œ๋ฒ„ ๊ตฌ์„ฑ ํ™•์ธ +- ๊ตฌ์„ฑ ์˜ค๋ฅ˜ ์—ฌ๋ถ€ ํ™•์ธ + +## Hot-Reload + +ํ”Œ๋Ÿฌ๊ทธ์ธ์€ ๊ฐœ๋ฐœ ์ค‘ Hot-Reload๋ฅผ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค. ํ”Œ๋Ÿฌ๊ทธ์ธ ํŒŒ์ผ์„ ์ˆ˜์ •ํ•˜๋ฉด Claude Code๊ฐ€ ๋ณ€๊ฒฝ ์‚ฌํ•ญ์„ ์ž๋™์œผ๋กœ ๊ฐ์ง€ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ๋‹ค์Œ ๋ช…๋ น์œผ๋กœ ๊ฐ•์ œ๋กœ ๋‹ค์‹œ ๋กœ๋“œํ•  ์ˆ˜๋„ ์žˆ์Šต๋‹ˆ๋‹ค. + +```bash +/reload-plugins +``` + +This re-reads all plugin manifests, commands, agents, skills, hooks, and MCP/LSP configurations without restarting the session. + +## ํ”Œ๋Ÿฌ๊ทธ์ธ ๊ด€๋ฆฌ ์„ค์ • + +๊ด€๋ฆฌ์ž๋Š” ๊ด€๋ฆฌ ์„ค์ •์„ ์‚ฌ์šฉํ•˜์—ฌ ์กฐ์ง ์ „์ฒด์—์„œ ํ”Œ๋Ÿฌ๊ทธ์ธ ๋™์ž‘์„ ์ œ์–ดํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +| ์„ค์ • | ์„ค๋ช… | +|---------|-------------| +| `enabledPlugins` | ๊ธฐ๋ณธ์ ์œผ๋กœ ํ™œ์„ฑํ™”ํ•  ํ”Œ๋Ÿฌ๊ทธ์ธ ํ—ˆ์šฉ ๋ชฉ๋ก | +| `deniedPlugins` | ์„ค์น˜๋ฅผ ๊ธˆ์ง€ํ•  ํ”Œ๋Ÿฌ๊ทธ์ธ ์ฐจ๋‹จ ๋ชฉ๋ก | +| `extraKnownMarketplaces` | ๊ธฐ๋ณธ๊ฐ’ ์™ธ์— ์ถ”๊ฐ€ ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ์†Œ์Šค๋ฅผ ๋“ฑ๋ก | +| `strictKnownMarketplaces` | ์‚ฌ์šฉ์ž๊ฐ€ ์ถ”๊ฐ€ํ•  ์ˆ˜ ์žˆ๋Š” ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค๋ฅผ ์ œํ•œ(๊ด€๋ฆฌ ์„ค์ • ์ „์šฉ, v2.1.117๋ถ€ํ„ฐ ๋ชจ๋“  ํ”Œ๋Ÿฌ๊ทธ์ธ ์ˆ˜๋ช… ์ฃผ๊ธฐ ์ด๋ฒคํŠธ์—์„œ ์ ์šฉ) | +| `blockedMarketplaces` | ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ์ฐจ๋‹จ ๋ชฉ๋ก(v2.1.117๋ถ€ํ„ฐ ๋ชจ๋“  ํ”Œ๋Ÿฌ๊ทธ์ธ ์ˆ˜๋ช… ์ฃผ๊ธฐ ์ด๋ฒคํŠธ์—์„œ ์ ์šฉ, v2.1.119๋ถ€ํ„ฐ `hostPattern` / `pathPattern` ์ •๊ทœ์‹ ํ•„๋“œ ์ง€์›) | +| `allowedChannelPlugins` | ๋ฆด๋ฆฌ์Šค ์ฑ„๋„๋ณ„ ํ—ˆ์šฉ ํ”Œ๋Ÿฌ๊ทธ์ธ ์ œ์–ด | + +์ด ์„ค์ •์€ ๊ด€๋ฆฌ ๊ตฌ์„ฑ ํŒŒ์ผ์„ ํ†ตํ•ด ์กฐ์ง ์ˆ˜์ค€์—์„œ ์ ์šฉํ•  ์ˆ˜ ์žˆ์œผ๋ฉฐ ์‚ฌ์šฉ์ž ์ˆ˜์ค€ ์„ค์ •๋ณด๋‹ค ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค. + +## ํ”Œ๋Ÿฌ๊ทธ์ธ ๋ณด์•ˆ + +ํ”Œ๋Ÿฌ๊ทธ์ธ Subagent๋Š” ์ œํ•œ๋œ ์ƒŒ๋“œ๋ฐ•์Šค์—์„œ ์‹คํ–‰๋ฉ๋‹ˆ๋‹ค. ํ”Œ๋Ÿฌ๊ทธ์ธ Subagent ์ •์˜์—์„œ๋Š” ๋‹ค์Œ frontmatter ํ‚ค๋ฅผ **์‚ฌ์šฉํ•  ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค**. + +- `hooks` -- Subagent๋Š” ์ด๋ฒคํŠธ ํ•ธ๋“ค๋Ÿฌ๋ฅผ ๋“ฑ๋กํ•  ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค. +- `mcpServers` -- Subagent๋Š” MCP ์„œ๋ฒ„๋ฅผ ๊ตฌ์„ฑํ•  ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค. +- `permissionMode` -- Subagent๋Š” ๊ถŒํ•œ ๋ชจ๋ธ์„ ์žฌ์ •์˜ํ•  ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค. + +์ด๋ฅผ ํ†ตํ•ด ํ”Œ๋Ÿฌ๊ทธ์ธ์ด ์„ ์–ธ๋œ ๋ฒ”์œ„๋ฅผ ๋„˜์–ด ๊ถŒํ•œ์„ ์ƒ์Šน์‹œํ‚ค๊ฑฐ๋‚˜ ํ˜ธ์ŠคํŠธ ํ™˜๊ฒฝ์„ ์ˆ˜์ •ํ•˜์ง€ ๋ชปํ•˜๋„๋ก ๋ณด์žฅํ•ฉ๋‹ˆ๋‹ค. + +## ํ”Œ๋Ÿฌ๊ทธ์ธ ๊ฒŒ์‹œ + +**๊ฒŒ์‹œ ์ ˆ์ฐจ:** + +1. ๋ชจ๋“  ๊ตฌ์„ฑ ์š”์†Œ๋ฅผ ํฌํ•จํ•œ ํ”Œ๋Ÿฌ๊ทธ์ธ ๊ตฌ์กฐ ์ƒ์„ฑ +2. `.claude-plugin/plugin.json` ๋งค๋‹ˆํŽ˜์ŠคํŠธ ์ž‘์„ฑ +3. ๋ฌธ์„œ๊ฐ€ ํฌํ•จ๋œ `README.md` ์ž‘์„ฑ +4. `claude --plugin-dir ./my-plugin`์œผ๋กœ ๋กœ์ปฌ ํ…Œ์ŠคํŠธ +5. `claude plugin tag v0.3.0`์œผ๋กœ ๋ฆด๋ฆฌ์Šค ํƒœ๊ทธ ์ƒ์„ฑ(v2.1.118+) โ€” ๋ฒ„์ „ ๋ฌธ์ž์—ด์„ ๊ฒ€์ฆํ•˜๊ณ  ์ผ์น˜ํ•˜๋Š” git ํƒœ๊ทธ ์ƒ์„ฑ +6. ํ”Œ๋Ÿฌ๊ทธ์ธ ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค์— ์ œ์ถœ +7. ๊ฒ€ํ†  ๋ฐ ์Šน์ธ +8. ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค์— ๊ฒŒ์‹œ +9. ์‚ฌ์šฉ์ž๋Š” ๋ช…๋ น ํ•œ ๋ฒˆ์œผ๋กœ ์„ค์น˜ ๊ฐ€๋Šฅ + +**์ œ์ถœ ์˜ˆ์‹œ:** + +```markdown +# PR Review ํ”Œ๋Ÿฌ๊ทธ์ธ + +## ์„ค๋ช… + +๋ณด์•ˆ, ํ…Œ์ŠคํŠธ ๋ฐ ๋ฌธ์„œํ™” ๊ฒ€์‚ฌ๋ฅผ ํฌํ•จํ•˜๋Š” ์™„์ „ํ•œ PR ๊ฒ€ํ†  ์›Œํฌํ”Œ๋กœ์ž…๋‹ˆ๋‹ค. + +## ํฌํ•จ๋œ ๊ตฌ์„ฑ ์š”์†Œ + +- ๋‹ค์–‘ํ•œ ๊ฒ€ํ†  ์œ ํ˜•์„ ์œ„ํ•œ ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด 3๊ฐœ +- ํŠนํ™”๋œ Subagent 3๊ฐœ +- GitHub ๋ฐ CodeQL MCP ํ†ตํ•ฉ +- ์ž๋™ํ™”๋œ ๋ณด์•ˆ ์Šค์บ” Hook +``` + +## ์„ค์น˜ + +```bash +/plugin install pr-review +``` + +## ๊ธฐ๋Šฅ + +โœ… ๋ณด์•ˆ ๋ถ„์„ +โœ… ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€ ํ™•์ธ +โœ… ๋ฌธ์„œ ๊ฒ€์ฆ +โœ… ์ฝ”๋“œ ํ’ˆ์งˆ ํ‰๊ฐ€ +โœ… ์„ฑ๋Šฅ ์˜ํ–ฅ ๋ถ„์„ + +## ์‚ฌ์šฉ ๋ฐฉ๋ฒ• + +```bash +/review-pr +/check-security +/check-tests +``` + +## ์š”๊ตฌ ์‚ฌํ•ญ + +- Claude Code 1.0+ +- GitHub ์ ‘๊ทผ ๊ถŒํ•œ +- CodeQL(์„ ํƒ ์‚ฌํ•ญ) + +## ํ”Œ๋Ÿฌ๊ทธ์ธ๊ณผ ์ˆ˜๋™ ๊ตฌ์„ฑ ๋น„๊ต + +**์ˆ˜๋™ ์„ค์ •(2์‹œ๊ฐ„ ์ด์ƒ):** + +- ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด๋ฅผ ํ•˜๋‚˜์”ฉ ์„ค์น˜ +- Subagent๋ฅผ ๊ฐœ๋ณ„์ ์œผ๋กœ ์ƒ์„ฑ +- MCP๋ฅผ ๊ฐ๊ฐ ๊ตฌ์„ฑ +- Hook์„ ์ˆ˜๋™์œผ๋กœ ์„ค์ • +- ๋ชจ๋“  ๋‚ด์šฉ์„ ๋ฌธ์„œํ™” +- ํŒ€๊ณผ ๊ณต์œ (์˜ฌ๋ฐ”๋ฅด๊ฒŒ ๊ตฌ์„ฑ๋˜๊ธฐ๋ฅผ ๊ธฐ๋Œ€) + +**ํ”Œ๋Ÿฌ๊ทธ์ธ ์‚ฌ์šฉ(2๋ถ„):** + +```bash +/plugin install pr-review +# โœ… Everything installed and configured +# โœ… Ready to use immediately +# โœ… Team can reproduce exact setup +``` + +## ๋ชจ๋ฒ” ์‚ฌ๋ก€ + +### ๊ถŒ์žฅ ์‚ฌํ•ญ โœ… + +- ๋ช…ํ™•ํ•˜๊ณ  ์„ค๋ช…์ ์ธ ํ”Œ๋Ÿฌ๊ทธ์ธ ์ด๋ฆ„ ์‚ฌ์šฉ +- ํฌ๊ด„์ ์ธ README ํฌํ•จ +- ์‹œ๋งจํ‹ฑ ๋ฒ„์ „(semver)์„ ์‚ฌ์šฉํ•˜์—ฌ ๋ฒ„์ „ ๊ด€๋ฆฌ +- ๋ชจ๋“  ๊ตฌ์„ฑ ์š”์†Œ๋ฅผ ํ•จ๊ป˜ ํ…Œ์ŠคํŠธ +- ์š”๊ตฌ ์‚ฌํ•ญ์„ ๋ช…ํ™•ํ•˜๊ฒŒ ๋ฌธ์„œํ™” +- ์‚ฌ์šฉ ์˜ˆ์ œ ์ œ๊ณต +- ์˜ค๋ฅ˜ ์ฒ˜๋ฆฌ ํฌํ•จ +- ๊ฒ€์ƒ‰์ด ์‰ฝ๋„๋ก ์ ์ ˆํ•œ ํƒœ๊ทธ ์‚ฌ์šฉ +- ์ด์ „ ๋ฒ„์ „๊ณผ์˜ ํ˜ธํ™˜์„ฑ ์œ ์ง€ +- ํ”Œ๋Ÿฌ๊ทธ์ธ์˜ ๋ชฉ์ ์„ ๋ช…ํ™•ํ•˜๊ณ  ์ผ๊ด€๋˜๊ฒŒ ์œ ์ง€ +- ์ถฉ๋ถ„ํ•œ ํ…Œ์ŠคํŠธ ํฌํ•จ +- ๋ชจ๋“  ์˜์กด์„ฑ ๋ฌธ์„œํ™” + +### ํ”ผํ•ด์•ผ ํ•  ์‚ฌํ•ญ โŒ + +- ๊ด€๋ จ ์—†๋Š” ๊ธฐ๋Šฅ์„ ํ•˜๋‚˜์˜ ํ”Œ๋Ÿฌ๊ทธ์ธ์— ๋ฌถ์ง€ ๋งˆ์‹ญ์‹œ์˜ค. +- ์ž๊ฒฉ ์ฆ๋ช…์„ ์ฝ”๋“œ์— ํ•˜๋“œ์ฝ”๋”ฉํ•˜์ง€ ๋งˆ์‹ญ์‹œ์˜ค. +- ํ…Œ์ŠคํŠธ๋ฅผ ์ƒ๋žตํ•˜์ง€ ๋งˆ์‹ญ์‹œ์˜ค. +- ๋ฌธ์„œ ์ž‘์„ฑ์„ ์žŠ์ง€ ๋งˆ์‹ญ์‹œ์˜ค. +- ์ค‘๋ณต๋˜๋Š” ํ”Œ๋Ÿฌ๊ทธ์ธ์„ ๋งŒ๋“ค์ง€ ๋งˆ์‹ญ์‹œ์˜ค. +- ๋ฒ„์ „ ๊ด€๋ฆฌ๋ฅผ ๋ฌด์‹œํ•˜์ง€ ๋งˆ์‹ญ์‹œ์˜ค. +- ๊ตฌ์„ฑ ์š”์†Œ ๊ฐ„ ์˜์กด์„ฑ์„ ๋ถˆํ•„์š”ํ•˜๊ฒŒ ๋ณต์žกํ•˜๊ฒŒ ๋งŒ๋“ค์ง€ ๋งˆ์‹ญ์‹œ์˜ค. +- ์˜ค๋ฅ˜๋ฅผ ์ ์ ˆํ•˜๊ฒŒ ์ฒ˜๋ฆฌํ•˜๋Š” ๊ฒƒ์„ ์žŠ์ง€ ๋งˆ์‹ญ์‹œ์˜ค. + +## ์„ค์น˜ ์•ˆ๋‚ด + +### ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค์—์„œ ์„ค์น˜ + +1. **์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ํ”Œ๋Ÿฌ๊ทธ์ธ ๋ชฉ๋ก ๋ณด๊ธฐ** + + ```bash + /plugin list + ``` + +2. **ํ”Œ๋Ÿฌ๊ทธ์ธ ์ƒ์„ธ ์ •๋ณด ํ™•์ธ** + + ```bash + /plugin info plugin-name + ``` + +3. **ํ”Œ๋Ÿฌ๊ทธ์ธ ์„ค์น˜** + + ```bash + /plugin install plugin-name + ``` + +### ๋กœ์ปฌ ๊ฒฝ๋กœ์—์„œ ์„ค์น˜ + +```bash +/plugin install ./path/to/plugin-directory +``` + +### GitHub์—์„œ ์„ค์น˜ + +```bash +/plugin install github:username/repo +``` + +### ์„ค์น˜๋œ ํ”Œ๋Ÿฌ๊ทธ์ธ ๋ชฉ๋ก ๋ณด๊ธฐ + +```bash +/plugin list --installed +``` + +### ํ”Œ๋Ÿฌ๊ทธ์ธ ์—…๋ฐ์ดํŠธ + +```bash +/plugin update plugin-name +``` + +### ํ”Œ๋Ÿฌ๊ทธ์ธ ๋น„ํ™œ์„ฑํ™”/ํ™œ์„ฑํ™” + +```bash +# Temporarily disable +/plugin disable plugin-name + +# Re-enable +/plugin enable plugin-name +``` + +### ํ”Œ๋Ÿฌ๊ทธ์ธ ์ œ๊ฑฐ + +```bash +/plugin uninstall plugin-name +``` + +## ๊ด€๋ จ ๊ฐœ๋… + +๋‹ค์Œ Claude Code ๊ธฐ๋Šฅ์€ ํ”Œ๋Ÿฌ๊ทธ์ธ๊ณผ ํ•จ๊ป˜ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +- **[Slash Commands](../01-slash-commands/)** - ํ”Œ๋Ÿฌ๊ทธ์ธ์— ํฌํ•จ๋˜๋Š” ๊ฐœ๋ณ„ ๋ช…๋ น์–ด +- **[Memory](../02-memory/)** - ํ”Œ๋Ÿฌ๊ทธ์ธ์„ ์œ„ํ•œ ์˜๊ตฌ ์ปจํ…์ŠคํŠธ +- **[Skills](../03-skills/)** - ํ”Œ๋Ÿฌ๊ทธ์ธ์œผ๋กœ ํŒจํ‚ค์ง•ํ•  ์ˆ˜ ์žˆ๋Š” ๋„๋ฉ”์ธ ์ „๋ฌธ์„ฑ +- **[Subagents](../04-subagents/)** - ํ”Œ๋Ÿฌ๊ทธ์ธ ๊ตฌ์„ฑ ์š”์†Œ๋กœ ํฌํ•จ๋˜๋Š” ํŠนํ™”๋œ ์—์ด์ „ํŠธ +- **[MCP Servers](../05-mcp/)** - ํ”Œ๋Ÿฌ๊ทธ์ธ์— ํฌํ•จ๋˜๋Š” Model Context Protocol ํ†ตํ•ฉ +- **[Hooks](../06-hooks/)** - ํ”Œ๋Ÿฌ๊ทธ์ธ ์›Œํฌํ”Œ๋กœ๋ฅผ ์‹คํ–‰ํ•˜๋Š” ์ด๋ฒคํŠธ ํ•ธ๋“ค๋Ÿฌ + +## ์ „์ฒด ์˜ˆ์ œ ์›Œํฌํ”Œ๋กœ + +### PR Review ํ”Œ๋Ÿฌ๊ทธ์ธ ์ „์ฒด ์›Œํฌํ”Œ๋กœ + +``` +1. ์‚ฌ์šฉ์ž: /review-pr + +2. ํ”Œ๋Ÿฌ๊ทธ์ธ ์‹คํ–‰: + โ”œโ”€โ”€ pre-review.js Hook์ด Git ์ €์žฅ์†Œ๋ฅผ ๊ฒ€์ฆ + โ”œโ”€โ”€ GitHub MCP๊ฐ€ PR ๋ฐ์ดํ„ฐ๋ฅผ ๊ฐ€์ ธ์˜ด + โ”œโ”€โ”€ security-reviewer Subagent๊ฐ€ ๋ณด์•ˆ์„ ๋ถ„์„ + โ”œโ”€โ”€ test-checker Subagent๊ฐ€ ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€๋ฅผ ๊ฒ€์ฆ + โ””โ”€โ”€ performance-analyzer Subagent๊ฐ€ ์„ฑ๋Šฅ์„ ํ™•์ธ + +3. ๊ฒฐ๊ณผ๋ฅผ ์ข…ํ•ฉํ•˜์—ฌ ํ‘œ์‹œ: + โœ… ๋ณด์•ˆ: ์‹ฌ๊ฐํ•œ ๋ฌธ์ œ ์—†์Œ + โš ๏ธ ํ…Œ์ŠคํŠธ: ์ปค๋ฒ„๋ฆฌ์ง€ 65% (80% ์ด์ƒ ๊ถŒ์žฅ) + โœ… ์„ฑ๋Šฅ: ์œ ์˜๋ฏธํ•œ ์˜ํ–ฅ ์—†์Œ + ๐Ÿ“ 12๊ฐœ์˜ ๊ถŒ์žฅ ์‚ฌํ•ญ ์ œ๊ณต +``` + + +## ๋ฌธ์ œ ํ•ด๊ฒฐ + +### ํ”Œ๋Ÿฌ๊ทธ์ธ์ด ์„ค์น˜๋˜์ง€ ์•Š๋Š” ๊ฒฝ์šฐ + +- Claude Code ๋ฒ„์ „ ํ˜ธํ™˜์„ฑ ํ™•์ธ: `/version` +- JSON ๊ฒ€์ฆ ๋„๊ตฌ๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ `plugin.json` ๋ฌธ๋ฒ• ํ™•์ธ +- ์ธํ„ฐ๋„ท ์—ฐ๊ฒฐ ํ™•์ธ(์›๊ฒฉ ํ”Œ๋Ÿฌ๊ทธ์ธ์ธ ๊ฒฝ์šฐ) +- ๊ถŒํ•œ ํ™•์ธ: `ls -la plugin/` + +### ๊ตฌ์„ฑ ์š”์†Œ๊ฐ€ ๋กœ๋“œ๋˜์ง€ ์•Š๋Š” ๊ฒฝ์šฐ + +- `plugin.json`์˜ ๊ฒฝ๋กœ๊ฐ€ ์‹ค์ œ ๋””๋ ‰ํ„ฐ๋ฆฌ ๊ตฌ์กฐ์™€ ์ผ์น˜ํ•˜๋Š”์ง€ ํ™•์ธ +- ํŒŒ์ผ ๊ถŒํ•œ ํ™•์ธ: `chmod +x scripts/` +- ๊ตฌ์„ฑ ์š”์†Œ ํŒŒ์ผ์˜ ๋ฌธ๋ฒ• ํ™•์ธ +- ๋กœ๊ทธ ํ™•์ธ: `/plugin debug plugin-name` + +### MCP ์—ฐ๊ฒฐ ์‹คํŒจ + +- ํ™˜๊ฒฝ ๋ณ€์ˆ˜๊ฐ€ ์˜ฌ๋ฐ”๋ฅด๊ฒŒ ์„ค์ •๋˜์—ˆ๋Š”์ง€ ํ™•์ธ +- MCP ์„œ๋ฒ„๊ฐ€ ์ •์ƒ์ ์œผ๋กœ ์„ค์น˜ ๋ฐ ์‹คํ–‰ ์ค‘์ธ์ง€ ํ™•์ธ +- `/mcp test`๋กœ MCP ์—ฐ๊ฒฐ์„ ๋…๋ฆฝ์ ์œผ๋กœ ํ…Œ์ŠคํŠธ +- `mcp/` ๋””๋ ‰ํ„ฐ๋ฆฌ์˜ MCP ๊ตฌ์„ฑ ํ™•์ธ + +### ์„ค์น˜ ํ›„ ๋ช…๋ น์–ด๋ฅผ ์‚ฌ์šฉํ•  ์ˆ˜ ์—†๋Š” ๊ฒฝ์šฐ + +- ํ”Œ๋Ÿฌ๊ทธ์ธ์ด ์ •์ƒ์ ์œผ๋กœ ์„ค์น˜๋˜์—ˆ๋Š”์ง€ ํ™•์ธ: `/plugin list --installed` +- ํ”Œ๋Ÿฌ๊ทธ์ธ์ด ํ™œ์„ฑํ™”๋˜์–ด ์žˆ๋Š”์ง€ ํ™•์ธ: `/plugin status plugin-name` +- Claude Code๋ฅผ ์ข…๋ฃŒ(`exit`)ํ•œ ํ›„ ๋‹ค์‹œ ์‹คํ–‰ +- ๊ธฐ์กด ๋ช…๋ น์–ด์™€ ์ด๋ฆ„์ด ์ถฉ๋Œํ•˜๋Š”์ง€ ํ™•์ธ + +### Hook ์‹คํ–‰ ๋ฌธ์ œ + +- Hook ํŒŒ์ผ์˜ ๊ถŒํ•œ์ด ์˜ฌ๋ฐ”๋ฅธ์ง€ ํ™•์ธ +- Hook ๋ฌธ๋ฒ•๊ณผ ์ด๋ฒคํŠธ ์ด๋ฆ„ ํ™•์ธ +- Hook ๋กœ๊ทธ์—์„œ ์˜ค๋ฅ˜ ์„ธ๋ถ€ ์ •๋ณด ํ™•์ธ +- ๊ฐ€๋Šฅํ•˜๋ฉด Hook์„ ์ˆ˜๋™์œผ๋กœ ํ…Œ์ŠคํŠธ + +## ์ถ”๊ฐ€ ์ž๋ฃŒ + +- [Official Plugins Documentation](https://code.claude.com/docs/en/plugins) +- [Discover Plugins](https://code.claude.com/docs/en/discover-plugins) +- [Plugin Marketplaces](https://code.claude.com/docs/en/plugin-marketplaces) +- [Plugins Reference](https://code.claude.com/docs/en/plugins-reference) +- [MCP Server Reference](https://modelcontextprotocol.io/) +- [Subagent Configuration Guide](../04-subagents/README.md) +- [Hook System Reference](../06-hooks/README.md) + +--- + +**๋งˆ์ง€๋ง‰ ์—…๋ฐ์ดํŠธ**: 2026๋…„ 6์›” 28์ผ +**Claude Code ๋ฒ„์ „**: 2.1.195 +**์ถœ์ฒ˜**: +- https://code.claude.com/docs/en/plugins +- https://code.claude.com/docs/en/changelog#2-1-172 +- https://code.claude.com/docs/en/changelog +- https://code.claude.com/docs/en/slash-commands +- https://code.claude.com/docs/en/plugin-marketplaces +- https://github.com/anthropics/claude-code/releases/tag/v2.1.117 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.118 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.131 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.138 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.139 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.141 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.142 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.143 +- https://code.claude.com/docs/en/cli-reference +**ํ˜ธํ™˜ ๋ชจ๋ธ**: Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5 diff --git a/ko/07-plugins/devops-automation/.claude-plugin/plugin.json b/ko/07-plugins/devops-automation/.claude-plugin/plugin.json new file mode 100644 index 00000000..3b7bf75d --- /dev/null +++ b/ko/07-plugins/devops-automation/.claude-plugin/plugin.json @@ -0,0 +1,9 @@ +{ + "name": "devops-automation", + "version": "1.0.0", + "description": "Complete DevOps automation for deployment, monitoring, and incident response", + "author": { + "name": "Community" + }, + "license": "MIT" +} diff --git a/ko/07-plugins/devops-automation/README.md b/ko/07-plugins/devops-automation/README.md new file mode 100644 index 00000000..395c5965 --- /dev/null +++ b/ko/07-plugins/devops-automation/README.md @@ -0,0 +1,117 @@ + + + Claude How To + + +# DevOps Automation Plugin + +๋ฐฐํฌ, ๋ชจ๋‹ˆํ„ฐ๋ง ๋ฐ ์ธ์‹œ๋˜ํŠธ ๋Œ€์‘์„ ์œ„ํ•œ ์™„์ „ํ•œ DevOps ์ž๋™ํ™” ํ”Œ๋Ÿฌ๊ทธ์ธ์ž…๋‹ˆ๋‹ค. + +## Features + +โœ… ์ž๋™ ๋ฐฐํฌ +โœ… ๋กค๋ฐฑ ์ ˆ์ฐจ +โœ… ์‹œ์Šคํ…œ ์ƒํƒœ ๋ชจ๋‹ˆํ„ฐ๋ง +โœ… ์ธ์‹œ๋˜ํŠธ ๋Œ€์‘ ์›Œํฌํ”Œ๋กœ์šฐ +โœ… Kubernetes ํ†ตํ•ฉ + +## Installation + +```bash +/plugin install devops-automation +``` + +## What's Included + +### Slash Commands +- `/deploy` - ํ”„๋กœ๋•์…˜ ๋˜๋Š” ์Šคํ…Œ์ด์ง• ํ™˜๊ฒฝ์— ๋ฐฐํฌ +- `/rollback` - ์ด์ „ ๋ฒ„์ „์œผ๋กœ ๋กค๋ฐฑ +- `/status` - ์‹œ์Šคํ…œ ์ƒํƒœ ํ™•์ธ +- `/incident` - ํ”„๋กœ๋•์…˜ ์ธ์‹œ๋˜ํŠธ ์ฒ˜๋ฆฌ + +### Subagents +- `deployment-specialist` - ๋ฐฐํฌ ์ž‘์—… ๋‹ด๋‹น +- `incident-commander` - ์ธ์‹œ๋˜ํŠธ ์กฐ์ • ๋‹ด๋‹น +- `alert-analyzer` - ์‹œ์Šคํ…œ ์ƒํƒœ ๋ถ„์„ ๋‹ด๋‹น + +### MCP Servers +- Kubernetes ํ†ตํ•ฉ + +### Scripts +- `deploy.sh` - ๋ฐฐํฌ ์ž๋™ํ™” +- `rollback.sh` - ๋กค๋ฐฑ ์ž๋™ํ™” +- `health-check.sh` - ์ƒํƒœ ์ ๊ฒ€ ์œ ํ‹ธ๋ฆฌํ‹ฐ + +### Hooks +- `pre-deploy.js` - ๋ฐฐํฌ ์ „ ๊ฒ€์ฆ +- `post-deploy.js` - ๋ฐฐํฌ ํ›„ ์ž‘์—… + +## Usage + +### ์Šคํ…Œ์ด์ง• ํ™˜๊ฒฝ ๋ฐฐํฌ +``` +/deploy staging +``` + +### ํ”„๋กœ๋•์…˜ ํ™˜๊ฒฝ ๋ฐฐํฌ +``` +/deploy production +``` + +### ๋กค๋ฐฑ +``` +/rollback production +``` + +### ์ƒํƒœ ํ™•์ธ +``` +/status +``` + +### ์ธ์‹œ๋˜ํŠธ ์ฒ˜๋ฆฌ +``` +/incident +``` + +## Requirements + +- Claude Code 1.0+ +- Kubernetes CLI (kubectl) +- ๊ตฌ์„ฑ๋œ ํด๋Ÿฌ์Šคํ„ฐ ์ ‘๊ทผ ๊ถŒํ•œ + +## Configuration + +Kubernetes ์„ค์ •์„ ๊ตฌ์„ฑํ•ฉ๋‹ˆ๋‹ค: +```bash +export KUBECONFIG=~/.kube/config +``` + +## Example Workflow + +``` +User: /deploy production + +Claude: +1. Runs pre-deploy hook (validates kubectl, cluster connection) +2. Delegates to deployment-specialist subagent +3. Runs deploy.sh script +4. Monitors deployment progress via Kubernetes MCP +5. Runs post-deploy hook (waits for pods, smoke tests) +6. Provides deployment summary + +Result: +โœ… Deployment complete +๐Ÿ“ฆ Version: v2.1.0 +๐Ÿš€ Pods: 3/3 ready +โฑ๏ธ Time: 2m 34s +``` + +--- + +**Last Updated**: June 2, 2026 +**Claude Code Version**: 2.1.160 +**Sources**: +- https://code.claude.com/docs/en/plugins +- https://github.com/anthropics/claude-code/releases/tag/v2.1.131 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.138 +**Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5 diff --git a/ko/07-plugins/devops-automation/agents/alert-analyzer.md b/ko/07-plugins/devops-automation/agents/alert-analyzer.md new file mode 100644 index 00000000..f2f46a57 --- /dev/null +++ b/ko/07-plugins/devops-automation/agents/alert-analyzer.md @@ -0,0 +1,14 @@ +--- +name: alert-analyzer +description: ๋ชจ๋‹ˆํ„ฐ๋ง ์•Œ๋ฆผ ๋ฐ ์‹œ์Šคํ…œ ๋ฉ”ํŠธ๋ฆญ์„ ๋ถ„์„ํ•ฉ๋‹ˆ๋‹ค. +tools: read, grep, bash +--- + +# ์•Œ๋ฆผ ๋ถ„์„๊ธฐ + +์‹œ์Šคํ…œ ์ƒํƒœ ๋ฐ ์•Œ๋ฆผ์„ ๋ถ„์„ํ•ฉ๋‹ˆ๋‹ค: +- ์•Œ๋ฆผ ์ƒ๊ด€๊ด€๊ณ„ ๋ถ„์„ +- ์ถ”์„ธ ๋ถ„์„ +- ๊ทผ๋ณธ ์›์ธ ์‹๋ณ„ +- ๋ฉ”ํŠธ๋ฆญ ์‹œ๊ฐํ™” +- ์‚ฌ์ „ ์˜ˆ๋ฐฉ์  ๋ฌธ์ œ ํƒ์ง€ diff --git a/ko/07-plugins/devops-automation/agents/deployment-specialist.md b/ko/07-plugins/devops-automation/agents/deployment-specialist.md new file mode 100644 index 00000000..9a890e64 --- /dev/null +++ b/ko/07-plugins/devops-automation/agents/deployment-specialist.md @@ -0,0 +1,14 @@ +--- +name: deployment-specialist +description: ๋ชจ๋“  ๋ฐฐํฌ ์ž‘์—…์„ ๋‹ด๋‹นํ•ฉ๋‹ˆ๋‹ค. +tools: read, write, bash, grep +--- + +# ๋ฐฐํฌ ์ „๋ฌธ๊ฐ€ + +๋ฐฐํฌ ์ž‘์—… ์ „๋ฌธ: +- ๋ธ”๋ฃจ-๊ทธ๋ฆฐ ๋ฐฐํฌ +- ์นด๋‚˜๋ฆฌ ๋ฆด๋ฆฌ์Šค +- ๋กค๋ฐฑ ์ ˆ์ฐจ +- ์ƒํƒœ ์ ๊ฒ€ +- ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ diff --git a/ko/07-plugins/devops-automation/agents/incident-commander.md b/ko/07-plugins/devops-automation/agents/incident-commander.md new file mode 100644 index 00000000..e1fc90b5 --- /dev/null +++ b/ko/07-plugins/devops-automation/agents/incident-commander.md @@ -0,0 +1,14 @@ +--- +name: incident-commander +description: ์‚ฌ๊ณ  ๋Œ€์‘์„ ์กฐ์œจํ•ฉ๋‹ˆ๋‹ค. +tools: read, write, bash, grep +--- + +# ์‚ฌ๊ณ  ๋Œ€์‘ ์ด๊ด„์ž + +์‚ฌ๊ณ  ๋Œ€์‘์„ ๊ด€๋ฆฌํ•ฉ๋‹ˆ๋‹ค: +- ์‹ฌ๊ฐ๋„ ํ‰๊ฐ€ +- ํŒ€ ์กฐ์œจ +- ์ƒํƒœ ์—…๋ฐ์ดํŠธ +- ํ•ด๊ฒฐ ์ถ”์  +- ์‚ฌํ›„ ๋ถ„์„ ์ง€์› diff --git a/ko/07-plugins/devops-automation/commands/deploy.md b/ko/07-plugins/devops-automation/commands/deploy.md new file mode 100644 index 00000000..2efa0608 --- /dev/null +++ b/ko/07-plugins/devops-automation/commands/deploy.md @@ -0,0 +1,15 @@ +--- +name: Deploy +description: ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜์„ ์šด์˜ ๋˜๋Š” ์Šคํ…Œ์ด์ง• ํ™˜๊ฒฝ์— ๋ฐฐํฌํ•ฉ๋‹ˆ๋‹ค. +--- + +# ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜ ๋ฐฐํฌ + +๋ฐฐํฌ ์›Œํฌํ”Œ๋กœ๋ฅผ ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค: + +1. ๋ฐฐํฌ ์ „ ์ ๊ฒ€ ์ˆ˜ํ–‰ +2. ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜ ๋นŒ๋“œ +3. ํ…Œ์ŠคํŠธ ์‹คํ–‰ +4. ๋Œ€์ƒ ํ™˜๊ฒฝ์— ๋ฐฐํฌ +5. ์ƒํƒœ ์ ๊ฒ€ ์ˆ˜ํ–‰ +6. Slack์œผ๋กœ ํŒ€์— ์•Œ๋ฆผ ์ „์†ก diff --git a/ko/07-plugins/devops-automation/commands/incident.md b/ko/07-plugins/devops-automation/commands/incident.md new file mode 100644 index 00000000..2978afc0 --- /dev/null +++ b/ko/07-plugins/devops-automation/commands/incident.md @@ -0,0 +1,16 @@ +--- +name: Incident Response +description: ์ฒด๊ณ„์ ์ธ ๋Œ€์‘ ์ ˆ์ฐจ๋ฅผ ํ†ตํ•ด ์šด์˜ ํ™˜๊ฒฝ์˜ ์žฅ์• ๋ฅผ ์ฒ˜๋ฆฌํ•ฉ๋‹ˆ๋‹ค. +--- + +# ์žฅ์•  ๋Œ€์‘ + +์ฒด๊ณ„์ ์ธ ์žฅ์•  ๋Œ€์‘ ์›Œํฌํ”Œ๋กœ: + +1. ์žฅ์•  ๊ธฐ๋ก ์ƒ์„ฑ +2. ์‹ฌ๊ฐ๋„ ๋ฐ ์˜ํ–ฅ ๋ฒ”์œ„ ํ‰๊ฐ€ +3. ์˜จ์ฝœ(On-call) ํŒ€์— ์•Œ๋ฆผ +4. ์ง„๋‹จ ์ •๋ณด ์ˆ˜์ง‘ +5. ๋Œ€์‘ ์ž‘์—… ์กฐ์œจ +6. ํ•ด๊ฒฐ ๋‚ด์šฉ ๋ฌธ์„œํ™” +7. ์‚ฌํ›„ ๋ถ„์„ ์ผ์ • ์ˆ˜๋ฆฝ diff --git a/ko/07-plugins/devops-automation/commands/rollback.md b/ko/07-plugins/devops-automation/commands/rollback.md new file mode 100644 index 00000000..7614811f --- /dev/null +++ b/ko/07-plugins/devops-automation/commands/rollback.md @@ -0,0 +1,15 @@ +--- +name: Rollback +description: ์ด์ „ ๋ฐฐํฌ ๋ฒ„์ „์œผ๋กœ ๋กค๋ฐฑํ•ฉ๋‹ˆ๋‹ค. + +--- + +# ๋ฐฐํฌ ๋กค๋ฐฑ + +์ด์ „์˜ ์•ˆ์ •์ ์ธ ๋ฒ„์ „์œผ๋กœ ๋กค๋ฐฑํ•ฉ๋‹ˆ๋‹ค: + +1. ์ด์ „ ๋ฐฐํฌ ๋ฒ„์ „ ํ™•์ธ +2. ๋กค๋ฐฑ ๋Œ€์ƒ์˜ ์ •์ƒ ์ƒํƒœ ๊ฒ€์ฆ +3. ๋กค๋ฐฑ ์ ˆ์ฐจ ์‹คํ–‰ +4. ์ƒํƒœ ์ ๊ฒ€ ์ˆ˜ํ–‰ +5. ํŒ€์— ์•Œ๋ฆผ diff --git a/ko/07-plugins/devops-automation/commands/status.md b/ko/07-plugins/devops-automation/commands/status.md new file mode 100644 index 00000000..84a38fe2 --- /dev/null +++ b/ko/07-plugins/devops-automation/commands/status.md @@ -0,0 +1,15 @@ +--- +name: System Status +description: ์ „์ฒด ์‹œ์Šคํ…œ ์ƒํƒœ ๋ฐ ์ •์ƒ ๋™์ž‘ ์—ฌ๋ถ€๋ฅผ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. +--- + +# ์‹œ์Šคํ…œ ์ƒํƒœ ์ ๊ฒ€ + +๋ชจ๋“  ์„œ๋น„์Šค์˜ ์‹œ์Šคํ…œ ์ƒํƒœ๋ฅผ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค: + +1. Kubernetes Pod ์ƒํƒœ ์กฐํšŒ +2. ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ์—ฐ๊ฒฐ ์ƒํƒœ ํ™•์ธ +3. API ์‘๋‹ต ์‹œ๊ฐ„ ๋ชจ๋‹ˆํ„ฐ๋ง +4. ์˜ค๋ฅ˜์œจ ๊ฒ€ํ†  +5. ๋ฆฌ์†Œ์Šค ์‚ฌ์šฉ๋Ÿ‰ ํ™•์ธ +6. ์ „์ฒด ์‹œ์Šคํ…œ ์ƒํƒœ ๋ณด๊ณ  diff --git a/ko/07-plugins/devops-automation/hooks/post-deploy.js b/ko/07-plugins/devops-automation/hooks/post-deploy.js new file mode 100644 index 00000000..5c6537e9 --- /dev/null +++ b/ko/07-plugins/devops-automation/hooks/post-deploy.js @@ -0,0 +1,34 @@ +#!/usr/bin/env node + +/** + * Post-deployment hook + * Runs after deployment completes + */ + +async function postDeploy() { + console.log('Running post-deployment tasks...'); + + const { execSync } = require('child_process'); + + // Wait for pods to be ready + console.log('Waiting for pods to be ready...'); + try { + execSync('kubectl wait --for=condition=ready pod -l app=myapp --timeout=300s', { + stdio: 'inherit' + }); + } catch (error) { + console.error('โŒ Pods failed to become ready'); + process.exit(1); + } + + // Run smoke tests + console.log('Running smoke tests...'); + // Add your smoke test commands here + + console.log('โœ… Post-deployment tasks complete'); +} + +postDeploy().catch(error => { + console.error('Post-deploy hook failed:', error); + process.exit(1); +}); diff --git a/ko/07-plugins/devops-automation/hooks/pre-deploy.js b/ko/07-plugins/devops-automation/hooks/pre-deploy.js new file mode 100644 index 00000000..98983a46 --- /dev/null +++ b/ko/07-plugins/devops-automation/hooks/pre-deploy.js @@ -0,0 +1,35 @@ +#!/usr/bin/env node + +/** + * Pre-deployment hook + * Validates environment and prerequisites before deployment + */ + +async function preDeploy() { + console.log('Running pre-deployment checks...'); + + const { execSync } = require('child_process'); + + // Check if kubectl is installed + try { + execSync('which kubectl', { stdio: 'pipe' }); + } catch (error) { + console.error('โŒ kubectl not found. Please install Kubernetes CLI.'); + process.exit(1); + } + + // Check if connected to cluster + try { + execSync('kubectl cluster-info', { stdio: 'pipe' }); + } catch (error) { + console.error('โŒ Not connected to Kubernetes cluster'); + process.exit(1); + } + + console.log('โœ… Pre-deployment checks passed'); +} + +preDeploy().catch(error => { + console.error('Pre-deploy hook failed:', error); + process.exit(1); +}); diff --git a/ko/07-plugins/devops-automation/mcp/kubernetes-config.json b/ko/07-plugins/devops-automation/mcp/kubernetes-config.json new file mode 100644 index 00000000..3f3b842d --- /dev/null +++ b/ko/07-plugins/devops-automation/mcp/kubernetes-config.json @@ -0,0 +1,11 @@ +{ + "mcpServers": { + "kubernetes": { + "command": "npx", + "args": ["@modelcontextprotocol/server-kubernetes"], + "env": { + "KUBECONFIG": "${KUBECONFIG}" + } + } + } +} diff --git a/ko/07-plugins/devops-automation/scripts/deploy.sh b/ko/07-plugins/devops-automation/scripts/deploy.sh new file mode 100644 index 00000000..9acf5bd1 --- /dev/null +++ b/ko/07-plugins/devops-automation/scripts/deploy.sh @@ -0,0 +1,28 @@ +#!/bin/bash +set -e + +echo "๐Ÿš€ Starting deployment..." + +# Load environment +ENV=${1:-staging} +echo "๐Ÿ“ฆ Target environment: $ENV" + +# Pre-deployment checks +echo "โœ“ Running pre-deployment checks..." +npm run lint +npm test + +# Build +echo "๐Ÿ”จ Building application..." +npm run build + +# Deploy +echo "๐Ÿšข Deploying to $ENV..." +kubectl apply -f k8s/$ENV/ + +# Health check +echo "๐Ÿฅ Running health checks..." +sleep 10 +curl -f http://api.$ENV.example.com/health + +echo "โœ… Deployment complete!" diff --git a/ko/07-plugins/devops-automation/scripts/health-check.sh b/ko/07-plugins/devops-automation/scripts/health-check.sh new file mode 100644 index 00000000..2ded117b --- /dev/null +++ b/ko/07-plugins/devops-automation/scripts/health-check.sh @@ -0,0 +1,30 @@ +#!/bin/bash + +echo "๐Ÿฅ System Health Check" +echo "====================" + +ENV=${1:-production} + +# Check API +echo -n "API: " +if curl -sf http://api.$ENV.example.com/health > /dev/null; then + echo "โœ… Healthy" +else + echo "โŒ Unhealthy" +fi + +# Check Database +echo -n "Database: " +if pg_isready -h db.$ENV.example.com > /dev/null 2>&1; then + echo "โœ… Healthy" +else + echo "โŒ Unhealthy" +fi + +# Check Pods +echo -n "Kubernetes Pods: " +PODS_READY=$(kubectl get pods -n $ENV --no-headers | grep "Running" | wc -l) +PODS_TOTAL=$(kubectl get pods -n $ENV --no-headers | wc -l) +echo "$PODS_READY/$PODS_TOTAL ready" + +echo "====================" diff --git a/ko/07-plugins/devops-automation/scripts/rollback.sh b/ko/07-plugins/devops-automation/scripts/rollback.sh new file mode 100644 index 00000000..0fe0cc24 --- /dev/null +++ b/ko/07-plugins/devops-automation/scripts/rollback.sh @@ -0,0 +1,25 @@ +#!/bin/bash +set -e + +echo "โช Starting rollback..." + +ENV=${1:-staging} +echo "๐Ÿ“ฆ Target environment: $ENV" + +# Get previous deployment +PREVIOUS=$(kubectl rollout history deployment/app -n $ENV | tail -2 | head -1 | awk '{print $1}') +echo "๐Ÿ”„ Rolling back to revision: $PREVIOUS" + +# Execute rollback +kubectl rollout undo deployment/app -n $ENV + +# Wait for rollback +echo "โณ Waiting for rollback to complete..." +kubectl rollout status deployment/app -n $ENV + +# Health check +echo "๐Ÿฅ Running health checks..." +sleep 5 +curl -f http://api.$ENV.example.com/health + +echo "โœ… Rollback complete!" diff --git a/ko/07-plugins/documentation/.claude-plugin/plugin.json b/ko/07-plugins/documentation/.claude-plugin/plugin.json new file mode 100644 index 00000000..b1d520d4 --- /dev/null +++ b/ko/07-plugins/documentation/.claude-plugin/plugin.json @@ -0,0 +1,9 @@ +{ + "name": "documentation", + "version": "1.0.0", + "description": "Comprehensive documentation generation and maintenance", + "author": { + "name": "Community" + }, + "license": "MIT" +} diff --git a/ko/07-plugins/documentation/README.md b/ko/07-plugins/documentation/README.md new file mode 100644 index 00000000..90672d9a --- /dev/null +++ b/ko/07-plugins/documentation/README.md @@ -0,0 +1,129 @@ + + + Claude How To + + +# Documentation Plugin + +Comprehensive documentation generation and maintenance for your project. + +## Features + +โœ… API documentation generation +โœ… README creation and updates +โœ… Documentation synchronization +โœ… Code comment improvements +โœ… Example generation + +## Installation + +```bash +/plugin install documentation +``` + +## What's Included + +### Slash Commands +- `/generate-api-docs` - Generate API documentation +- `/generate-readme` - Create or update README +- `/sync-docs` - Sync docs with code changes +- `/validate-docs` - Validate documentation + +### Subagents +- `api-documenter` - API documentation specialist +- `code-commentator` - Code comment improvements +- `example-generator` - Code example creation + +### Templates +- `api-endpoint.md` - API endpoint documentation template +- `function-docs.md` - Function documentation template +- `adr-template.md` - Architecture Decision Record template + +### MCP Servers +- GitHub integration for documentation syncing + +## Usage + +### Generate API Documentation +``` +/generate-api-docs +``` + +### Create README +``` +/generate-readme +``` + +### Sync Documentation +``` +/sync-docs +``` + +### Validate Documentation +``` +/validate-docs +``` + +## Requirements + +- Claude Code 1.0+ +- GitHub access (optional) + +## Example Workflow + +``` +User: /generate-api-docs + +Claude: +1. Scans all API endpoints in /src/api/ +2. Delegates to api-documenter subagent +3. Extracts function signatures and JSDoc +4. Organizes by module/endpoint +5. Uses api-endpoint.md template +6. Generates comprehensive markdown docs +7. Includes curl, JavaScript, and Python examples + +Result: +โœ… API documentation generated +๐Ÿ“„ Files created: + - docs/api/users.md + - docs/api/auth.md + - docs/api/products.md +๐Ÿ“Š Coverage: 23/23 endpoints documented +``` + +## Templates Usage + +### API Endpoint Template +Use for documenting REST API endpoints with full examples. + +### Function Documentation Template +Use for documenting individual functions/methods. + +### ADR Template +Use for documenting architectural decisions. + +## Configuration + +Set up GitHub token for documentation syncing: +```bash +export GITHUB_TOKEN="your_github_token" +``` + +## Best Practices + +- Keep documentation close to code +- Update docs with code changes +- Include practical examples +- Validate regularly +- Use templates for consistency + +--- + +**Last Updated**: June 2, 2026 +**Claude Code Version**: 2.1.160 +**Sources**: +- https://code.claude.com/docs/en/plugins +- https://github.com/anthropics/claude-code/releases/tag/v2.1.131 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.138 +**Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5 diff --git a/ko/07-plugins/documentation/agents/api-documenter.md b/ko/07-plugins/documentation/agents/api-documenter.md new file mode 100644 index 00000000..5cff57c5 --- /dev/null +++ b/ko/07-plugins/documentation/agents/api-documenter.md @@ -0,0 +1,14 @@ +--- +name: api-documenter +description: API ๋ฌธ์„œํ™” ์ „๋ฌธ ์—์ด์ „ํŠธ +tools: read, write, grep +--- + +# API Documenter + +ํฌ๊ด„์ ์ธ API ๋ฌธ์„œ๋ฅผ ์ž‘์„ฑํ•ฉ๋‹ˆ๋‹ค: +- ์—”๋“œํฌ์ธํŠธ ๋ฌธ์„œํ™” +- ํŒŒ๋ผ๋ฏธํ„ฐ ์„ค๋ช… +- ์‘๋‹ต ์Šคํ‚ค๋งˆ +- ์ฝ”๋“œ ์˜ˆ์ œ (curl, JS, Python) +- ์˜ค๋ฅ˜ ์ฝ”๋“œ diff --git a/ko/07-plugins/documentation/agents/code-commentator.md b/ko/07-plugins/documentation/agents/code-commentator.md new file mode 100644 index 00000000..731582e1 --- /dev/null +++ b/ko/07-plugins/documentation/agents/code-commentator.md @@ -0,0 +1,14 @@ +--- +name: code-commentator +description: ์ฝ”๋“œ ์ฃผ์„ ๋ฐ ์ธ๋ผ์ธ ๋ฌธ์„œํ™” ์ „๋ฌธ ์—์ด์ „ํŠธ +tools: read, write, edit +--- + +# Code Commentator + +์ฝ”๋“œ ๋ฌธ์„œํ™”๋ฅผ ๊ฐœ์„ ํ•ฉ๋‹ˆ๋‹ค: +- JSDoc/docstring ์ฃผ์„ +- ์ธ๋ผ์ธ ์„ค๋ช… +- ํŒŒ๋ผ๋ฏธํ„ฐ ์„ค๋ช… +- ๋ฐ˜ํ™˜ ํƒ€์ž… ๋ฌธ์„œํ™” +- ์‚ฌ์šฉ ์˜ˆ์ œ diff --git a/ko/07-plugins/documentation/agents/example-generator.md b/ko/07-plugins/documentation/agents/example-generator.md new file mode 100644 index 00000000..e3a2b92d --- /dev/null +++ b/ko/07-plugins/documentation/agents/example-generator.md @@ -0,0 +1,14 @@ +--- +name: example-generator +description: ์ฝ”๋“œ ์˜ˆ์ œ ๋ฐ ํŠœํ† ๋ฆฌ์–ผ ์ „๋ฌธ ์—์ด์ „ํŠธ +tools: read, write +--- + +# Example Generator + +์‹ค์šฉ์ ์ธ ์ฝ”๋“œ ์˜ˆ์ œ๋ฅผ ์ž‘์„ฑํ•ฉ๋‹ˆ๋‹ค: +- ์‹œ์ž‘ ๊ฐ€์ด๋“œ +- ์ผ๋ฐ˜์ ์ธ ์‚ฌ์šฉ ์‚ฌ๋ก€ +- ํ†ตํ•ฉ ์˜ˆ์ œ +- ๋ชจ๋ฒ” ์‚ฌ๋ก€ +- ๋ฌธ์ œ ํ•ด๊ฒฐ ์‹œ๋‚˜๋ฆฌ์˜ค diff --git a/ko/07-plugins/documentation/commands/generate-api-docs.md b/ko/07-plugins/documentation/commands/generate-api-docs.md new file mode 100644 index 00000000..bb449c10 --- /dev/null +++ b/ko/07-plugins/documentation/commands/generate-api-docs.md @@ -0,0 +1,15 @@ +--- +name: Generate API Documentation +description: ์†Œ์Šค ์ฝ”๋“œ๋กœ๋ถ€ํ„ฐ ํฌ๊ด„์ ์ธ API ๋ฌธ์„œ๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค +--- + +# API Documentation Generator + +์™„์ „ํ•œ API ๋ฌธ์„œ๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค: + +1. API ์—”๋“œํฌ์ธํŠธ ์Šค์บ” +2. ํ•จ์ˆ˜ ์‹œ๊ทธ๋‹ˆ์ฒ˜ ๋ฐ JSDoc ์ถ”์ถœ +3. ๋ชจ๋“ˆ/์—”๋“œํฌ์ธํŠธ๋ณ„๋กœ ๊ตฌ์„ฑ +4. ์˜ˆ์ œ๊ฐ€ ํฌํ•จ๋œ ๋งˆํฌ๋‹ค์šด ๋ฌธ์„œ ์ƒ์„ฑ +5. ์š”์ฒญ/์‘๋‹ต ์Šคํ‚ค๋งˆ ํฌํ•จ +6. ์˜ค๋ฅ˜ ๋ฌธ์„œ ์ถ”๊ฐ€ diff --git a/ko/07-plugins/documentation/commands/generate-readme.md b/ko/07-plugins/documentation/commands/generate-readme.md new file mode 100644 index 00000000..ce8a3a34 --- /dev/null +++ b/ko/07-plugins/documentation/commands/generate-readme.md @@ -0,0 +1,15 @@ +--- +name: Generate README +description: ํ”„๋กœ์ ํŠธ README๋ฅผ ์ƒ์„ฑํ•˜๊ฑฐ๋‚˜ ์—…๋ฐ์ดํŠธํ•ฉ๋‹ˆ๋‹ค +--- + +# README ์ƒ์„ฑ๊ธฐ + +ํฌ๊ด„์ ์ธ README๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค: + +1. ํ”„๋กœ์ ํŠธ ๊ฐœ์š” ๋ฐ ์„ค๋ช… +2. ์„ค์น˜ ๋ฐฉ๋ฒ• +3. ์‚ฌ์šฉ ์˜ˆ์ œ +4. API ๋ฌธ์„œ ๋งํฌ +5. ๊ธฐ์—ฌ ๊ฐ€์ด๋“œ +6. ๋ผ์ด์„ ์Šค ์ •๋ณด diff --git a/ko/07-plugins/documentation/commands/sync-docs.md b/ko/07-plugins/documentation/commands/sync-docs.md new file mode 100644 index 00000000..26e107c6 --- /dev/null +++ b/ko/07-plugins/documentation/commands/sync-docs.md @@ -0,0 +1,14 @@ +--- +name: Sync Documentation +description: ์ฝ”๋“œ ๋ณ€๊ฒฝ ์‚ฌํ•ญ๊ณผ ๋ฌธ์„œ๋ฅผ ๋™๊ธฐํ™”ํ•ฉ๋‹ˆ๋‹ค +--- + +# ๋ฌธ์„œ ๋™๊ธฐํ™” + +์ฝ”๋“œ๋ฒ ์ด์Šค์™€ ๋ฌธ์„œ๋ฅผ ๋™๊ธฐํ™”ํ•ฉ๋‹ˆ๋‹ค: + +1. ์ฝ”๋“œ ๋ณ€๊ฒฝ ์‚ฌํ•ญ ๊ฐ์ง€ +2. ์˜ค๋ž˜๋œ ๋ฌธ์„œ ์‹๋ณ„ +3. ์˜ํ–ฅ๋ฐ›๋Š” ๋ฌธ์„œ ์—…๋ฐ์ดํŠธ +4. ์˜ˆ์ œ๊ฐ€ ์ •์ƒ ๋™์ž‘ํ•˜๋Š”์ง€ ๊ฒ€์ฆ +5. ๋ฒ„์ „ ๋ฒˆํ˜ธ ์—…๋ฐ์ดํŠธ diff --git a/ko/07-plugins/documentation/commands/validate-docs.md b/ko/07-plugins/documentation/commands/validate-docs.md new file mode 100644 index 00000000..9606a03d --- /dev/null +++ b/ko/07-plugins/documentation/commands/validate-docs.md @@ -0,0 +1,14 @@ +--- +name: Validate Documentation +description: ๋ฌธ์„œ์˜ ์™„์„ฑ๋„์™€ ์ •ํ™•์„ฑ์„ ๊ฒ€์ฆํ•ฉ๋‹ˆ๋‹ค +--- + +# ๋ฌธ์„œ ๊ฒ€์ฆ + +๋ฌธ์„œ ํ’ˆ์งˆ์„ ๊ฒ€์ฆํ•ฉ๋‹ˆ๋‹ค: + +1. ๊นจ์ง„ ๋งํฌ ํ™•์ธ +2. ์ฝ”๋“œ ์˜ˆ์ œ ๊ฒ€์ฆ +3. ์™„์„ฑ๋„ ํ™•์ธ +4. ํฌ๋งทํŒ… ๊ฒ€์‚ฌ +5. ์‹ค์ œ ์ฝ”๋“œ์™€์˜ ์ผ์น˜ ์—ฌ๋ถ€ ๊ฒ€์ฆ diff --git a/ko/07-plugins/documentation/mcp/github-docs-config.json b/ko/07-plugins/documentation/mcp/github-docs-config.json new file mode 100644 index 00000000..0f621316 --- /dev/null +++ b/ko/07-plugins/documentation/mcp/github-docs-config.json @@ -0,0 +1,11 @@ +{ + "mcpServers": { + "github": { + "command": "npx", + "args": ["@modelcontextprotocol/server-github"], + "env": { + "GITHUB_TOKEN": "${GITHUB_TOKEN}" + } + } + } +} diff --git a/ko/07-plugins/documentation/templates/adr-template.md b/ko/07-plugins/documentation/templates/adr-template.md new file mode 100644 index 00000000..9a8e0bb0 --- /dev/null +++ b/ko/07-plugins/documentation/templates/adr-template.md @@ -0,0 +1,39 @@ +# ADR [๋ฒˆํ˜ธ]: [์ œ๋ชฉ] + +## ์ƒํƒœ +[์ œ์•ˆ๋จ | ์Šน์ธ๋จ | ํ๊ธฐ๋จ | ๋Œ€์ฒด๋จ] + +## ๋ฐฐ๊ฒฝ(Context) +์ด ๊ฒฐ์ •์„ ์ด‰๋ฐœํ•œ ๋ฌธ์ œ๋Š” ๋ฌด์—‡์ธ๊ฐ€? + +## ๊ฒฐ์ •(Decision) +์šฐ๋ฆฌ๊ฐ€ ์ œ์•ˆํ•˜๊ฑฐ๋‚˜ ์ˆ˜ํ–‰ํ•˜๋ ค๋Š” ๋ณ€๊ฒฝ ์‚ฌํ•ญ์€ ๋ฌด์—‡์ธ๊ฐ€? + +## ๊ฒฐ๊ณผ(Consequences) +์ด ๋ณ€๊ฒฝ์œผ๋กœ ์ธํ•ด ๋ฌด์—‡์ด ๋” ์‰ฌ์›Œ์ง€๊ฑฐ๋‚˜ ์–ด๋ ค์›Œ์ง€๋Š”๊ฐ€? + +### ๊ธ์ •์  ์˜ํ–ฅ +- ์ด์  1 +- ์ด์  2 + +### ๋ถ€์ •์  ์˜ํ–ฅ +- ๋‹จ์  1 +- ๋‹จ์  2 + +### ์ค‘๋ฆฝ์  ์˜ํ–ฅ +- ๊ณ ๋ ค์‚ฌํ•ญ 1 +- ๊ณ ๋ ค์‚ฌํ•ญ 2 + +## ๊ณ ๋ คํ•œ ๋Œ€์•ˆ(Alternatives Considered) +์–ด๋–ค ๋‹ค๋ฅธ ์„ ํƒ์ง€๋ฅผ ๊ณ ๋ คํ–ˆ์œผ๋ฉฐ ์™œ ์ฑ„ํƒํ•˜์ง€ ์•Š์•˜๋Š”๊ฐ€? + +### ๋Œ€์•ˆ 1 +์„ค๋ช… ๋ฐ ๋ฏธ์ฑ„ํƒ ์ด์œ  + +### ๋Œ€์•ˆ 2 +์„ค๋ช… ๋ฐ ๋ฏธ์ฑ„ํƒ ์ด์œ  + +## ์ฐธ๊ณ (References) +- ๊ด€๋ จ ADR +- ์™ธ๋ถ€ ๋ฌธ์„œ +- ๋…ผ์˜ ๋งํฌ diff --git a/ko/07-plugins/documentation/templates/api-endpoint.md b/ko/07-plugins/documentation/templates/api-endpoint.md new file mode 100644 index 00000000..956b0b47 --- /dev/null +++ b/ko/07-plugins/documentation/templates/api-endpoint.md @@ -0,0 +1,101 @@ +# [METHOD] /api/v1/[endpoint] + +## ์„ค๋ช… +ํ•ด๋‹น ์—”๋“œํฌ์ธํŠธ๊ฐ€ ์ˆ˜ํ–‰ํ•˜๋Š” ์ž‘์—…์— ๋Œ€ํ•œ ๊ฐ„๋‹จํ•œ ์„ค๋ช…์ž…๋‹ˆ๋‹ค. + +## ์ธ์ฆ(Authentication) +ํ•„์š”ํ•œ ์ธ์ฆ ๋ฐฉ์‹ (์˜ˆ: Bearer ํ† ํฐ) + +## ํŒŒ๋ผ๋ฏธํ„ฐ + +### Path ํŒŒ๋ผ๋ฏธํ„ฐ +| ์ด๋ฆ„ | ํƒ€์ž… | ํ•„์ˆ˜ ์—ฌ๋ถ€ | ์„ค๋ช… | +|------|------|----------|------| +| id | string | ์˜ˆ | ๋ฆฌ์†Œ์Šค ID | + +### Query ํŒŒ๋ผ๋ฏธํ„ฐ +| ์ด๋ฆ„ | ํƒ€์ž… | ํ•„์ˆ˜ ์—ฌ๋ถ€ | ์„ค๋ช… | +|------|------|----------|------| +| page | integer | ์•„๋‹ˆ์˜ค | ํŽ˜์ด์ง€ ๋ฒˆํ˜ธ (๊ธฐ๋ณธ๊ฐ’: 1) | +| limit | integer | ์•„๋‹ˆ์˜ค | ํŽ˜์ด์ง€๋‹น ํ•ญ๋ชฉ ์ˆ˜ (๊ธฐ๋ณธ๊ฐ’: 20) | + +### ์š”์ฒญ ๋ณธ๋ฌธ(Request Body) +```json +{ + "field": "value" +} +``` + +## ์‘๋‹ต(Response) + +### 200 OK +```json +{ + "success": true, + "data": { + "id": "123", + "name": "์˜ˆ์‹œ" + } +} +``` + +### 400 Bad Request +```json +{ + "success": false, + "error": { + "code": "VALIDATION_ERROR", + "message": "์ž˜๋ชป๋œ ์ž…๋ ฅ์ž…๋‹ˆ๋‹ค" + } +} +``` + +### 404 Not Found +```json +{ + "success": false, + "error": { + "code": "NOT_FOUND", + "message": "๋ฆฌ์†Œ์Šค๋ฅผ ์ฐพ์„ ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค" + } +} +``` + +## ์˜ˆ์ œ(Examples) + +### cURL +```bash +curl -X GET "https://api.example.com/api/v1/endpoint" \ + -H "Authorization: Bearer YOUR_TOKEN" \ + -H "Content-Type: application/json" +``` + +### JavaScript +```javascript +const response = await fetch('/api/v1/endpoint', { + headers: { + 'Authorization': 'Bearer token', + 'Content-Type': 'application/json' + } +}); +const data = await response.json(); +``` + +### Python +```python +import requests + +response = requests.get( + 'https://api.example.com/api/v1/endpoint', + headers={'Authorization': 'Bearer token'} +) +data = response.json() +``` + +## ์†๋„ ์ œํ•œ(Rate Limits) +- ์ธ์ฆ ์‚ฌ์šฉ์ž: ์‹œ๊ฐ„๋‹น 1000 ์š”์ฒญ +- ๊ณต๊ฐœ ์—”๋“œํฌ์ธํŠธ: ์‹œ๊ฐ„๋‹น 100 ์š”์ฒญ + +## ๊ด€๋ จ ์—”๋“œํฌ์ธํŠธ +- [GET /api/v1/related](#) +- [POST /api/v1/related](#) diff --git a/ko/07-plugins/documentation/templates/function-docs.md b/ko/07-plugins/documentation/templates/function-docs.md new file mode 100644 index 00000000..1262e631 --- /dev/null +++ b/ko/07-plugins/documentation/templates/function-docs.md @@ -0,0 +1,50 @@ +# ํ•จ์ˆ˜: `functionName` + +## ์„ค๋ช… +ํ•ด๋‹น ํ•จ์ˆ˜๊ฐ€ ์ˆ˜ํ–‰ํ•˜๋Š” ์ž‘์—…์— ๋Œ€ํ•œ ๊ฐ„๋‹จํ•œ ์„ค๋ช…์ž…๋‹ˆ๋‹ค. + +## ์‹œ๊ทธ๋‹ˆ์ฒ˜(Signature) +```typescript +function functionName(param1: Type1, param2: Type2): ReturnType +``` + +## ํŒŒ๋ผ๋ฏธํ„ฐ + +| ํŒŒ๋ผ๋ฏธํ„ฐ | ํƒ€์ž… | ํ•„์ˆ˜ ์—ฌ๋ถ€ | ์„ค๋ช… | +|-----------|------|----------|------| +| param1 | Type1 | ์˜ˆ | param1 ์„ค๋ช… | +| param2 | Type2 | ์•„๋‹ˆ์˜ค | param2 ์„ค๋ช… | + +## ๋ฐ˜ํ™˜๊ฐ’(Returns) +**ํƒ€์ž…**: `ReturnType` + +๋ฐ˜ํ™˜๋˜๋Š” ๊ฐ’์— ๋Œ€ํ•œ ์„ค๋ช…์ž…๋‹ˆ๋‹ค. + +## ์˜ˆ์™ธ(Throws) +- `Error`: ์ž˜๋ชป๋œ ์ž…๋ ฅ์ด ์ œ๊ณต๋œ ๊ฒฝ์šฐ +- `TypeError`: ์ž˜๋ชป๋œ ํƒ€์ž…์ด ์ „๋‹ฌ๋œ ๊ฒฝ์šฐ + +## ์˜ˆ์ œ(Examples) + +### ๊ธฐ๋ณธ ์‚ฌ์šฉ๋ฒ• +```typescript +const result = functionName('value1', 'value2'); +console.log(result); +``` + +### ๊ณ ๊ธ‰ ์‚ฌ์šฉ๋ฒ• +```typescript +const result = functionName( + complexParam1, + { option: true } +); +``` + +## ์ฐธ๊ณ (Notes) +- ์ถ”๊ฐ€ ์ฐธ๊ณ  ์‚ฌํ•ญ ๋˜๋Š” ๊ฒฝ๊ณ  +- ์„ฑ๋Šฅ ๊ณ ๋ ค์‚ฌํ•ญ +- ๋ชจ๋ฒ” ์‚ฌ๋ก€ + +## ๊ด€๋ จ ๋ฌธ์„œ(See Also) +- [๊ด€๋ จ ํ•จ์ˆ˜](#) +- [API ๋ฌธ์„œ](#) diff --git a/ko/07-plugins/pr-review/.claude-plugin/plugin.json b/ko/07-plugins/pr-review/.claude-plugin/plugin.json new file mode 100644 index 00000000..9e953c4d --- /dev/null +++ b/ko/07-plugins/pr-review/.claude-plugin/plugin.json @@ -0,0 +1,9 @@ +{ + "name": "pr-review", + "version": "1.0.0", + "description": "Complete PR review workflow with security, testing, and docs", + "author": { + "name": "Anthropic" + }, + "license": "MIT" +} diff --git a/ko/07-plugins/pr-review/README.md b/ko/07-plugins/pr-review/README.md new file mode 100644 index 00000000..40b9ad6a --- /dev/null +++ b/ko/07-plugins/pr-review/README.md @@ -0,0 +1,101 @@ + + + Claude How To + + +# PR ๋ฆฌ๋ทฐ ํ”Œ๋Ÿฌ๊ทธ์ธ + +๋ณด์•ˆ, ํ…Œ์ŠคํŠธ, ๋ฌธ์„œ ๊ฒ€์ฆ์„ ํฌํ•จํ•œ ์™„์ „ํ•œ PR ๋ฆฌ๋ทฐ ์›Œํฌํ”Œ๋กœ์šฐ๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. + +## ๊ธฐ๋Šฅ + +โœ… ๋ณด์•ˆ ๋ถ„์„ +โœ… ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€ ๊ฒ€์‚ฌ +โœ… ๋ฌธ์„œ ๊ฒ€์ฆ +โœ… ์ฝ”๋“œ ํ’ˆ์งˆ ํ‰๊ฐ€ +โœ… ์„ฑ๋Šฅ ์˜ํ–ฅ ๋ถ„์„ + +## ์„ค์น˜ + +```bash +/plugin install pr-review +``` + +## ํฌํ•จ ํ•ญ๋ชฉ + +### ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด +- `/review-pr` - ์ข…ํ•ฉ PR ๋ฆฌ๋ทฐ +- `/check-security` - ๋ณด์•ˆ ์ค‘์‹ฌ ๋ฆฌ๋ทฐ +- `/check-tests` - ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€ ๋ถ„์„ + +### ์„œ๋ธŒ์—์ด์ „ํŠธ +- `security-reviewer` - ๋ณด์•ˆ ์ทจ์•ฝ์  ํƒ์ง€ +- `test-checker` - ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€ ๋ถ„์„ +- `performance-analyzer` - ์„ฑ๋Šฅ ์˜ํ–ฅ ํ‰๊ฐ€ + +### MCP ์„œ๋ฒ„ +- PR ๋ฐ์ดํ„ฐ ์—ฐ๋™์„ ์œ„ํ•œ GitHub ํ†ตํ•ฉ + +### ํ›…(Hooks) +- `pre-review.js` - ๋ฆฌ๋ทฐ ์ „ ๊ฒ€์ฆ + +## ์‚ฌ์šฉ ๋ฐฉ๋ฒ• + +### ๊ธฐ๋ณธ PR ๋ฆฌ๋ทฐ +``` +/review-pr +``` + +### ๋ณด์•ˆ ์ ๊ฒ€๋งŒ ์ˆ˜ํ–‰ +``` +/check-security +``` + +### ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€ ์ ๊ฒ€ +``` +/check-tests +``` + +## ์š”๊ตฌ ์‚ฌํ•ญ + +* Claude Code 1.0+ +* GitHub ์ ‘๊ทผ ๊ถŒํ•œ +* Git ์ €์žฅ์†Œ + +## ์„ค์ • + +GitHub ํ† ํฐ์„ ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค. +```bash +export GITHUB_TOKEN="your_github_token" +``` + +## ์›Œํฌํ”Œ๋กœ์šฐ ์˜ˆ์‹œ + +``` +User: /review-pr + +Claude: +1. Runs pre-review hook (validates git repo) +2. Fetches PR data via GitHub MCP +3. Delegates security review to security-reviewer subagent +4. Delegates testing to test-checker subagent +5. Delegates performance to performance-analyzer subagent +6. Synthesizes all findings +7. Provides comprehensive review report + +Result: +โœ… Security: No critical issues found +โš ๏ธ Testing: Coverage is 65%, recommend 80%+ +โœ… Performance: No significant impact +๐Ÿ“ Recommendations: Add tests for edge cases +``` + +--- + +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: 2026๋…„ 6์›” 2์ผ +**Claude Code ๋ฒ„์ „**: 2.1.160 +**์ถœ์ฒ˜**: +- https://code.claude.com/docs/en/plugins +- https://github.com/anthropics/claude-code/releases/tag/v2.1.131 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.138 +**ํ˜ธํ™˜ ๋ชจ๋ธ**: Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5 diff --git a/ko/07-plugins/pr-review/agents/performance-analyzer.md b/ko/07-plugins/pr-review/agents/performance-analyzer.md new file mode 100644 index 00000000..31562838 --- /dev/null +++ b/ko/07-plugins/pr-review/agents/performance-analyzer.md @@ -0,0 +1,14 @@ +--- +name: performance-analyzer +description: ์„ฑ๋Šฅ ์˜ํ–ฅ ๋ถ„์„ +tools: read, grep, bash +--- + +# ์„ฑ๋Šฅ ๋ถ„์„๊ธฐ + +๋ณ€๊ฒฝ ์‚ฌํ•ญ์ด ์„ฑ๋Šฅ์— ๋ฏธ์น˜๋Š” ์˜ํ–ฅ์„ ํ‰๊ฐ€ํ•ฉ๋‹ˆ๋‹ค. + +* ์•Œ๊ณ ๋ฆฌ์ฆ˜ ๋ณต์žก๋„ +* ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ์ฟผ๋ฆฌ ํšจ์œจ์„ฑ +* ๋ฉ”๋ชจ๋ฆฌ ์‚ฌ์šฉ๋Ÿ‰ +* ์บ์‹ฑ ๊ธฐํšŒ ์‹๋ณ„ diff --git a/ko/07-plugins/pr-review/agents/security-reviewer.md b/ko/07-plugins/pr-review/agents/security-reviewer.md new file mode 100644 index 00000000..68429f8c --- /dev/null +++ b/ko/07-plugins/pr-review/agents/security-reviewer.md @@ -0,0 +1,14 @@ +--- +name: security-reviewer +description: ๋ณด์•ˆ ์ค‘์‹ฌ ์ฝ”๋“œ ๋ฆฌ๋ทฐ +tools: read, grep, bash +--- + +# ๋ณด์•ˆ ๋ฆฌ๋ทฐ์–ด + +๋ณด์•ˆ ์ทจ์•ฝ์  ํƒ์ง€๋ฅผ ์ „๋ฌธ์œผ๋กœ ํ•ฉ๋‹ˆ๋‹ค. + +* ์ธ์ฆ(Authentication) ๋ฐ ์ธ๊ฐ€(Authorization) ๋ฌธ์ œ +* ๋ฐ์ดํ„ฐ ๋…ธ์ถœ +* ์ธ์ ์…˜ ๊ณต๊ฒฉ +* ์•ˆ์ „ํ•œ ์„ค์ • ๊ตฌ์„ฑ diff --git a/ko/07-plugins/pr-review/agents/test-checker.md b/ko/07-plugins/pr-review/agents/test-checker.md new file mode 100644 index 00000000..5f5440b0 --- /dev/null +++ b/ko/07-plugins/pr-review/agents/test-checker.md @@ -0,0 +1,14 @@ +--- +name: test-checker +description: ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€ ๋ฐ ํ’ˆ์งˆ ๋ถ„์„ +tools: read, bash, grep +--- + +# ํ…Œ์ŠคํŠธ ๊ฒ€์‚ฌ๊ธฐ + +ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€์™€ ํ’ˆ์งˆ์„ ๋ถ„์„ํ•ฉ๋‹ˆ๋‹ค. + +* ์ปค๋ฒ„๋ฆฌ์ง€ ๋น„์œจ +* ๋ˆ„๋ฝ๋œ ํ…Œ์ŠคํŠธ ์ผ€์ด์Šค +* ํ…Œ์ŠคํŠธ ํ’ˆ์งˆ ํ‰๊ฐ€ +* ์—ฃ์ง€ ์ผ€์ด์Šค ์‹๋ณ„ diff --git a/ko/07-plugins/pr-review/commands/check-security.md b/ko/07-plugins/pr-review/commands/check-security.md new file mode 100644 index 00000000..2931f0a7 --- /dev/null +++ b/ko/07-plugins/pr-review/commands/check-security.md @@ -0,0 +1,14 @@ +--- +name: Security Check +description: ๋ณด์•ˆ ์ค‘์‹ฌ ์ฝ”๋“œ ๋ฆฌ๋ทฐ ์‹คํ–‰ +--- + +# ๋ณด์•ˆ ์ ๊ฒ€ + +์ฝ”๋“œ ๋ณ€๊ฒฝ ์‚ฌํ•ญ์— ๋Œ€ํ•ด ์ง‘์ค‘์ ์ธ ๋ณด์•ˆ ๋ถ„์„์„ ์ˆ˜ํ–‰ํ•ฉ๋‹ˆ๋‹ค. + +1. ์ธ์ฆ(Authentication) ๋ฐ ์ธ๊ฐ€(Authorization) ๊ฒ€์ฆ +2. ๋ฐ์ดํ„ฐ ๋…ธ์ถœ ์œ„ํ—˜ ๋ถ„์„ +3. ์ธ์ ์…˜ ์ทจ์•ฝ์  ๋ถ„์„ +4. ์•”ํ˜ธํ™” ๊ด€๋ จ ์ทจ์•ฝ์  ๋ถ„์„ +5. ๋กœ๊ทธ ๋‚ด ๋ฏผ๊ฐ ์ •๋ณด ๋…ธ์ถœ ์—ฌ๋ถ€ ํ™•์ธ diff --git a/ko/07-plugins/pr-review/commands/check-tests.md b/ko/07-plugins/pr-review/commands/check-tests.md new file mode 100644 index 00000000..e7836b56 --- /dev/null +++ b/ko/07-plugins/pr-review/commands/check-tests.md @@ -0,0 +1,14 @@ +--- +name: Test Coverage Check +description: ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€ ๋ฐ ํ’ˆ์งˆ ๊ฒ€์ฆ +--- + +# ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€ ์ ๊ฒ€ + +ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€์™€ ํ’ˆ์งˆ์„ ๋ถ„์„ํ•ฉ๋‹ˆ๋‹ค. + +1. ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€ ๋น„์œจ ํ™•์ธ +2. ํ…Œ์ŠคํŠธ๋˜์ง€ ์•Š์€ ์ฝ”๋“œ ๊ฒฝ๋กœ ์‹๋ณ„ +3. ํ…Œ์ŠคํŠธ ํ’ˆ์งˆ ๊ฒ€ํ†  +4. ๋ˆ„๋ฝ๋œ ํ…Œ์ŠคํŠธ ์ผ€์ด์Šค ์ œ์•ˆ +5. ์—ฃ์ง€ ์ผ€์ด์Šค๊ฐ€ ํฌํ•จ๋˜์–ด ์žˆ๋Š”์ง€ ๊ฒ€์ฆ diff --git a/ko/07-plugins/pr-review/commands/review-pr.md b/ko/07-plugins/pr-review/commands/review-pr.md new file mode 100644 index 00000000..ab7afce7 --- /dev/null +++ b/ko/07-plugins/pr-review/commands/review-pr.md @@ -0,0 +1,14 @@ +--- +name: Review PR +description: ๋ณด์•ˆ ๋ฐ ํ…Œ์ŠคํŠธ ๊ฒ€์ฆ์„ ํฌํ•จํ•œ ์ข…ํ•ฉ์ ์ธ PR ๋ฆฌ๋ทฐ ์‹œ์ž‘ +--- + +# PR ๋ฆฌ๋ทฐ + +์ด ๋ช…๋ น์€ ๋‹ค์Œ ํ•ญ๋ชฉ์„ ํฌํ•จํ•œ ์ „์ฒด Pull Request ๋ฆฌ๋ทฐ๋ฅผ ์ˆ˜ํ–‰ํ•ฉ๋‹ˆ๋‹ค. + +1. ๋ณด์•ˆ ๋ถ„์„ +2. ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€ ๊ฒ€์ฆ +3. ๋ฌธ์„œ ์—…๋ฐ์ดํŠธ ํ™•์ธ +4. ์ฝ”๋“œ ํ’ˆ์งˆ ์ ๊ฒ€ +5. ์„ฑ๋Šฅ ์˜ํ–ฅ ํ‰๊ฐ€ diff --git a/ko/07-plugins/pr-review/hooks/pre-review.js b/ko/07-plugins/pr-review/hooks/pre-review.js new file mode 100644 index 00000000..21277093 --- /dev/null +++ b/ko/07-plugins/pr-review/hooks/pre-review.js @@ -0,0 +1,37 @@ +#!/usr/bin/env node + +/** + * Pre-review hook + * Runs before starting PR review to ensure prerequisites are met + */ + +async function preReview() { + console.log('Running pre-review checks...'); + + // Check if git repository + const { execSync } = require('child_process'); + try { + execSync('git rev-parse --git-dir', { stdio: 'pipe' }); + } catch (error) { + console.error('โŒ Not a git repository'); + process.exit(1); + } + + // Check for uncommitted changes + try { + const status = execSync('git status --porcelain', { encoding: 'utf-8' }); + if (status.trim()) { + console.warn('โš ๏ธ Warning: Uncommitted changes detected'); + } + } catch (error) { + console.error('โŒ Failed to check git status'); + process.exit(1); + } + + console.log('โœ… Pre-review checks passed'); +} + +preReview().catch(error => { + console.error('Pre-review hook failed:', error); + process.exit(1); +}); diff --git a/ko/07-plugins/pr-review/mcp/github-config.json b/ko/07-plugins/pr-review/mcp/github-config.json new file mode 100644 index 00000000..0f621316 --- /dev/null +++ b/ko/07-plugins/pr-review/mcp/github-config.json @@ -0,0 +1,11 @@ +{ + "mcpServers": { + "github": { + "command": "npx", + "args": ["@modelcontextprotocol/server-github"], + "env": { + "GITHUB_TOKEN": "${GITHUB_TOKEN}" + } + } + } +} diff --git a/ko/08-checkpoints/README.md b/ko/08-checkpoints/README.md new file mode 100644 index 00000000..7c263d05 --- /dev/null +++ b/ko/08-checkpoints/README.md @@ -0,0 +1,343 @@ + + + Claude How To + + +# ์ฒดํฌํฌ์ธํŠธ ๋ฐ ๋˜๊ฐ๊ธฐ + +์ฒดํฌํฌ์ธํŠธ๋ฅผ ์‚ฌ์šฉํ•˜๋ฉด Claude Code ์„ธ์…˜์—์„œ ๋Œ€ํ™” ์ƒํƒœ๋ฅผ ์ €์žฅํ•˜๊ณ  ์ด์ „ ์‹œ์ ์œผ๋กœ ๋˜๋Œ๋ฆด ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์ด๋Š” ๋‹ค์–‘ํ•œ ์ ‘๊ทผ ๋ฐฉ์‹์„ ์‹คํ—˜ํ•˜๊ฑฐ๋‚˜, ์‹ค์ˆ˜๋ฅผ ๋ณต๊ตฌํ•˜๊ฑฐ๋‚˜, ์—ฌ๋Ÿฌ ํ•ด๊ฒฐ ๋ฐฉ๋ฒ•์„ ๋น„๊ตํ•˜๋Š” ๋ฐ ๋งค์šฐ ์œ ์šฉํ•ฉ๋‹ˆ๋‹ค. + +## ๊ฐœ์š” + +์ฒดํฌํฌ์ธํŠธ๋Š” ๋Œ€ํ™” ์ƒํƒœ๋ฅผ ์ €์žฅํ•˜๊ณ  ์ด์ „ ์‹œ์ ์œผ๋กœ ๋˜๋Œ๋ฆด ์ˆ˜ ์žˆ๊ฒŒ ํ•ด์ฃผ๋Š” ๊ธฐ๋Šฅ์ž…๋‹ˆ๋‹ค. ์ด๋ฅผ ํ†ตํ•ด ์•ˆ์ „ํ•˜๊ฒŒ ๋‹ค์–‘ํ•œ ์ ‘๊ทผ ๋ฐฉ์‹์„ ์‹คํ—˜ํ•˜๊ณ  ํƒ์ƒ‰ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์ฒดํฌํฌ์ธํŠธ์—๋Š” ๋‹ค์Œ์ด ํฌํ•จ๋ฉ๋‹ˆ๋‹ค: + +- ๋ชจ๋“  ๋ฉ”์‹œ์ง€ ๊ธฐ๋ก +- ํŒŒ์ผ ์ˆ˜์ • ๋‚ด์—ญ +- ๋„๊ตฌ ์‚ฌ์šฉ ๊ธฐ๋ก +- ์„ธ์…˜ ์ปจํ…์ŠคํŠธ + +์ฒดํฌํฌ์ธํŠธ๋Š” ๋‹ค์–‘ํ•œ ์ ‘๊ทผ ๋ฐฉ์‹์„ ํƒ์ƒ‰ํ•˜๊ฑฐ๋‚˜, ์‹ค์ˆ˜๋ฅผ ๋ณต๊ตฌํ•˜๊ฑฐ๋‚˜, ๋Œ€์•ˆ๋“ค์„ ๋น„๊ตํ•  ๋•Œ ๋งค์šฐ ์œ ์šฉํ•ฉ๋‹ˆ๋‹ค. + +## ํ•ต์‹ฌ ๊ฐœ๋… + +| ๊ฐœ๋… | ์„ค๋ช… | +|------|------| +| **์ฒดํฌํฌ์ธํŠธ** | ๋ฉ”์‹œ์ง€, ํŒŒ์ผ, ์ปจํ…์ŠคํŠธ๋ฅผ ํฌํ•จํ•œ ๋Œ€ํ™” ์ƒํƒœ์˜ ์Šค๋ƒ…์ƒท | +| **๋˜๊ฐ๊ธฐ(Rewind)** | ์ฒดํฌํฌ์ธํŠธ ์‹œ์ ์œผ๋กœ ๋Œ์•„๊ฐ€ ์ดํ›„ ๋ณ€๊ฒฝ ์‚ฌํ•ญ์„ ํ๊ธฐ | +| **๋ธŒ๋žœ์น˜ ํฌ์ธํŠธ** | ์—ฌ๋Ÿฌ ์ ‘๊ทผ ๋ฐฉ์‹์„ ํƒ์ƒ‰ํ•˜๊ธฐ ์œ„ํ•œ ๊ธฐ์ค€ ์ฒดํฌํฌ์ธํŠธ | + +## ์ฒดํฌํฌ์ธํŠธ ์ ‘๊ทผ ๋ฐฉ๋ฒ• + +์ฒดํฌํฌ์ธํŠธ๋Š” ๋‘ ๊ฐ€์ง€ ๋ฐฉ๋ฒ•์œผ๋กœ ์ ‘๊ทผํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค: + +### ํ‚ค๋ณด๋“œ ๋‹จ์ถ•ํ‚ค ์‚ฌ์šฉ +`Esc` ํ‚ค๋ฅผ ๋‘ ๋ฒˆ ๋ˆ„๋ฅด๋ฉด(`Esc` + `Esc`) ์ฒดํฌํฌ์ธํŠธ ์ธํ„ฐํŽ˜์ด์Šค๊ฐ€ ์—ด๋ฆฌ๋ฉฐ ์ €์žฅ๋œ ์ฒดํฌํฌ์ธํŠธ๋ฅผ ํƒ์ƒ‰ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +### ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด ์‚ฌ์šฉ +๋น ๋ฅธ ์ ‘๊ทผ์„ ์œ„ํ•ด `/rewind` ๋ช…๋ น์–ด(๋ณ„์นญ: `/checkpoint`)๋ฅผ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค: + +```bash +# ๋˜๊ฐ๊ธฐ ์ธํ„ฐํŽ˜์ด์Šค ์—ด๊ธฐ +/rewind + +# ๋ณ„์นญ ์‚ฌ์šฉ +/checkpoint +``` + +## ๋˜๊ฐ๊ธฐ ์˜ต์…˜ + +๋˜๊ฐ๊ธฐ๋ฅผ ์ˆ˜ํ–‰ํ•˜๋ฉด ๋‹ค์Œ 5๊ฐ€์ง€ ์˜ต์…˜์ด ์ œ๊ณต๋ฉ๋‹ˆ๋‹ค: + +1. **์ฝ”๋“œ์™€ ๋Œ€ํ™” ๋ณต์›** -- ํŒŒ์ผ๊ณผ ๋ฉ”์‹œ์ง€๋ฅผ ํ•ด๋‹น ์ฒดํฌํฌ์ธํŠธ ์ƒํƒœ๋กœ ๋ชจ๋‘ ๋ณต์› +2. **๋Œ€ํ™”๋งŒ ๋ณต์›** -- ๋ฉ”์‹œ์ง€๋งŒ ๋˜๋Œ๋ฆฌ๊ณ  ํŒŒ์ผ์€ ํ˜„์žฌ ์ƒํƒœ ์œ ์ง€ +3. **์ฝ”๋“œ๋งŒ ๋ณต์›** -- ํŒŒ์ผ๋งŒ ๋˜๋Œ๋ฆฌ๊ณ  ๋Œ€ํ™” ๊ธฐ๋ก์€ ์œ ์ง€ +4. **์—ฌ๊ธฐ์„œ๋ถ€ํ„ฐ ์š”์•ฝ** -- ์„ ํƒ ์‹œ์  ์ดํ›„์˜ ๋Œ€ํ™”๋ฅผ AI๊ฐ€ ์ƒ์„ฑํ•œ ์š”์•ฝ์œผ๋กœ ์••์ถ•ํ•˜์—ฌ ์ปจํ…์ŠคํŠธ ๊ณต๊ฐ„์„ ํ™•๋ณด. ์ด์ „ ๋ฉ”์‹œ์ง€๋Š” ์œ ์ง€๋˜๋ฉฐ ๋””์Šคํฌ ํŒŒ์ผ์€ ๋ณ€๊ฒฝ๋˜์ง€ ์•Š์Œ. ์›๋ณธ ๋ฉ”์‹œ์ง€๋Š” ์„ธ์…˜์— ๋ณด์กด๋จ. ํ•„์š” ์‹œ ํŠน์ • ์ฃผ์ œ ์ค‘์‹ฌ์œผ๋กœ ์š”์•ฝ ๊ฐ€๋Šฅ +5. **์ทจ์†Œ** -- ์ž‘์—…์„ ์ทจ์†Œํ•˜๊ณ  ํ˜„์žฌ ์ƒํƒœ๋กœ ๋ณต๊ท€ + +> **์ฐธ๊ณ **: ๋Œ€ํ™” ๋ณต์› ๋˜๋Š” ์š”์•ฝ ํ›„์—๋Š” ์„ ํƒํ•œ ๋ฉ”์‹œ์ง€์˜ ์›๋ณธ ํ”„๋กฌํ”„ํŠธ๊ฐ€ ์ž…๋ ฅ์ฐฝ์— ๋ณต์›๋˜์–ด ๋‹ค์‹œ ์ „์†กํ•˜๊ฑฐ๋‚˜ ์ˆ˜์ •ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +> **`/clear`๋Š” ๋” ์ด์ƒ ๊ฐ•ํ•œ ๊ฒฝ๊ณ„๊ฐ€ ์•„๋‹˜ (v2.1.191+)**: `/rewind`๋ฅผ ์‚ฌ์šฉํ•˜๋ฉด `/clear` ์ด์ „ ์‹œ์ ์œผ๋กœ๋„ ๋˜๋Œ์•„๊ฐˆ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์ด์ œ clear ์ดํ›„์—๋„ ์ด์ „ ์ƒํƒœ๋กœ ๋ณต๊ท€๊ฐ€ ๊ฐ€๋Šฅํ•ฉ๋‹ˆ๋‹ค. + +## ์ž๋™ ์ฒดํฌํฌ์ธํŠธ + +Claude Code๋Š” ์ž๋™์œผ๋กœ ์ฒดํฌํฌ์ธํŠธ๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค: + +- **๋ชจ๋“  ์‚ฌ์šฉ์ž ์ž…๋ ฅ๋งˆ๋‹ค** ์ฒดํฌํฌ์ธํŠธ ์ƒ์„ฑ +- **์˜๊ตฌ ์ €์žฅ**: ์„ธ์…˜ ๊ฐ„ ์œ ์ง€๋จ +- **์ž๋™ ์ •๋ฆฌ**: 30์ผ ํ›„ ์ž๋™ ์‚ญ์ œ + +๋”ฐ๋ผ์„œ ๋ช‡ ๋ถ„ ์ „๋ถ€ํ„ฐ ๋ฉฐ์น  ์ „๊นŒ์ง€ ๋ชจ๋“  ์‹œ์ ์œผ๋กœ ๋˜๋Œ์•„๊ฐˆ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +## ์‚ฌ์šฉ ์‚ฌ๋ก€ + +| ์‹œ๋‚˜๋ฆฌ์˜ค | ์›Œํฌํ”Œ๋กœ์šฐ | +|----------|------------| +| **๋‹ค์–‘ํ•œ ์ ‘๊ทผ ๋ฐฉ์‹ ํƒ์ƒ‰** | ์ €์žฅ โ†’ A ์‹œ๋„ โ†’ ์ €์žฅ โ†’ ๋˜๊ฐ๊ธฐ โ†’ B ์‹œ๋„ โ†’ ๋น„๊ต | +| **์•ˆ์ „ํ•œ ๋ฆฌํŒฉํ† ๋ง** | ์ €์žฅ โ†’ ๋ฆฌํŒฉํ† ๋ง โ†’ ํ…Œ์ŠคํŠธ โ†’ ์‹คํŒจ ์‹œ ๋˜๊ฐ๊ธฐ | +| **A/B ํ…Œ์ŠคํŠธ** | ์ €์žฅ โ†’ A ์„ค๊ณ„ โ†’ ์ €์žฅ โ†’ ๋˜๊ฐ๊ธฐ โ†’ B ์„ค๊ณ„ โ†’ ๋น„๊ต | +| **์‹ค์ˆ˜ ๋ณต๊ตฌ** | ๋ฌธ์ œ ๋ฐœ๊ฒฌ โ†’ ๋งˆ์ง€๋ง‰ ์ •์ƒ ์ƒํƒœ๋กœ ๋˜๊ฐ๊ธฐ | + +## ์ฒดํฌํฌ์ธํŠธ ์‚ฌ์šฉ ๋ฐฉ๋ฒ• + +### ํ™•์ธ ๋ฐ ๋˜๊ฐ๊ธฐ + +`Esc`๋ฅผ ๋‘ ๋ฒˆ ๋ˆ„๋ฅด๊ฑฐ๋‚˜ `/rewind`๋ฅผ ์ž…๋ ฅํ•˜๋ฉด ์ฒดํฌํฌ์ธํŠธ ๋ธŒ๋ผ์šฐ์ €๊ฐ€ ์—ด๋ฆฝ๋‹ˆ๋‹ค. ์‹œ๊ฐ„์ˆœ์œผ๋กœ ๋ชจ๋“  ์ฒดํฌํฌ์ธํŠธ๊ฐ€ ํ‘œ์‹œ๋˜๋ฉฐ ์›ํ•˜๋Š” ์‹œ์ ์„ ์„ ํƒํ•ด ๋˜๋Œ๋ฆด ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +### ์ฒดํฌํฌ์ธํŠธ ์ƒ์„ธ ์ •๋ณด + +๊ฐ ์ฒดํฌํฌ์ธํŠธ์—๋Š” ๋‹ค์Œ ์ •๋ณด๊ฐ€ ํฌํ•จ๋ฉ๋‹ˆ๋‹ค: +- ์ƒ์„ฑ ์‹œ๊ฐ„ +- ์ˆ˜์ •๋œ ํŒŒ์ผ ๋ชฉ๋ก +- ๋Œ€ํ™” ๋ฉ”์‹œ์ง€ ์ˆ˜ +- ์‚ฌ์šฉ๋œ ๋„๊ตฌ ๋ชฉ๋ก + +## ์‹ค์ „ ์˜ˆ์‹œ + +### ์˜ˆ์‹œ 1: ๋‹ค์–‘ํ•œ ์ ‘๊ทผ ๋ฐฉ์‹ ํƒ์ƒ‰ + +``` +User: API์— ์บ์‹ฑ ๋ ˆ์ด์–ด๋ฅผ ์ถ”๊ฐ€ํ•ด์ค˜ + +Claude: Redis ์บ์‹ฑ์„ API์— ์ถ”๊ฐ€ํ•˜๊ฒ ์Šต๋‹ˆ๋‹ค... +[A ์‹œ์  ์ฒดํฌํฌ์ธํŠธ ์ƒ์„ฑ ํ›„ ๋ณ€๊ฒฝ ์ˆ˜ํ–‰] + +User: ์•„๋‹ˆ, ์ธ๋ฉ”๋ชจ๋ฆฌ ์บ์‹ฑ์œผ๋กœ ํ•ด๋ณด์ž + +Claude: ๋‹ค๋ฅธ ์ ‘๊ทผ ๋ฐฉ์‹์„ ์œ„ํ•ด ๋˜๊ฐ๊ธฐํ•ฉ๋‹ˆ๋‹ค... +[Esc+Esc๋กœ A ์ฒดํฌํฌ์ธํŠธ๋กœ ๋˜๊ฐ๊ธฐ] +[์ธ๋ฉ”๋ชจ๋ฆฌ ์บ์‹ฑ ์ ์šฉ] + +User: ์ด์ œ ๋‘ ๋ฐฉ์‹ ๋น„๊ตํ•  ์ˆ˜ ์žˆ๊ฒ ๋‹ค +``` + +### ์˜ˆ์‹œ 2: ์‹ค์ˆ˜ ๋ณต๊ตฌ + +``` +User: ์ธ์ฆ ๋ชจ๋“ˆ์„ JWT๋กœ ๋ฆฌํŒฉํ† ๋งํ•ด์ค˜ + +Claude: ์ธ์ฆ ๋ชจ๋“ˆ์„ ๋ฆฌํŒฉํ† ๋งํ•ฉ๋‹ˆ๋‹ค... +[๋Œ€๊ทœ๋ชจ ๋ณ€๊ฒฝ ์ˆ˜ํ–‰] + +User: ์ž ๊น, OAuth๊ฐ€ ๊นจ์กŒ์–ด. ๋˜๋Œ๋ฆฌ์ž + +Claude: ๋ฆฌํŒฉํ† ๋ง ์ด์ „ ์ƒํƒœ๋กœ ๋˜๊ฐ๊ฒ ์Šต๋‹ˆ๋‹ค... +[๋ฆฌํŒฉํ† ๋ง ์ด์ „ ์ฒดํฌํฌ์ธํŠธ๋กœ ๋ณต๊ท€] + +User: ์ด๋ฒˆ์—” ๋” ์•ˆ์ „ํ•˜๊ฒŒ ํ•ด๋ณด์ž +``` + +### ์˜ˆ์‹œ 3: ์•ˆ์ „ํ•œ ์‹คํ—˜ + +``` +User: ํ•จ์ˆ˜ํ˜• ์Šคํƒ€์ผ๋กœ ๋‹ค์‹œ ์ž‘์„ฑํ•ด๋ณด์ž +[์‹คํ—˜ ์‹œ์ž‘ ์ „ ์ฒดํฌํฌ์ธํŠธ ์ƒ์„ฑ] + +Claude: ํ•จ์ˆ˜ํ˜• ์Šคํƒ€์ผ๋กœ ๋ณ€๊ฒฝ ์ค‘... + +User: ํ…Œ์ŠคํŠธ ์‹คํŒจํ–ˆ์–ด. ๋˜๋Œ๋ฆฌ์ž +[์ฒดํฌํฌ์ธํŠธ๋กœ ๋ณต๊ท€] + +Claude: ์ด์ „ ์ƒํƒœ๋กœ ๋ณต์›ํ–ˆ์Šต๋‹ˆ๋‹ค. ๋‹ค๋ฅธ ์ ‘๊ทผ์„ ์‹œ๋„ํ•ด๋ณด๊ฒ ์Šต๋‹ˆ๋‹ค. +``` + +### ์˜ˆ์‹œ 4: ๋ธŒ๋žœ์น˜ ๋น„๊ต + +``` +User: ๋‘ ๊ฐ€์ง€ DB ์„ค๊ณ„๋ฅผ ๋น„๊ตํ•˜๊ณ  ์‹ถ์–ด +[์‹œ์ž‘ ์ฒดํฌํฌ์ธํŠธ] + +Claude: ์ฒซ ๋ฒˆ์งธ ์„ค๊ณ„ ๊ตฌํ˜„... +[์Šคํ‚ค๋งˆ A ๊ตฌํ˜„] + +User: ๋‹ค์‹œ ๋Œ์•„๊ฐ€์„œ ๋‘ ๋ฒˆ์งธ ๋ฐฉ์‹๋„ ํ•ด๋ณด์ž +[์‹œ์ž‘ ์ฒดํฌํฌ์ธํŠธ๋กœ ๋˜๊ฐ๊ธฐ] + +Claude: ์Šคํ‚ค๋งˆ B ๊ตฌํ˜„... +[์Šคํ‚ค๋งˆ B ๊ตฌํ˜„] + +User: ์ด์ œ ๋‘ ๊ฐ€์ง€ ๋น„๊ต ๊ฐ€๋Šฅ +``` + +## ์ฒดํฌํฌ์ธํŠธ ๋ณด๊ด€ ์ •์ฑ… + +Claude Code๋Š” ์ฒดํฌํฌ์ธํŠธ๋ฅผ ์ž๋™ ๊ด€๋ฆฌํ•ฉ๋‹ˆ๋‹ค: + +- ๋ชจ๋“  ์‚ฌ์šฉ์ž ์ž…๋ ฅ๋งˆ๋‹ค ์ž๋™ ์ƒ์„ฑ +- ์ตœ๋Œ€ 30์ผ๊ฐ„ ๋ณด๊ด€ +- ์˜ค๋ž˜๋œ ์ฒดํฌํฌ์ธํŠธ๋Š” ์ž๋™ ์‚ญ์ œ + +## ์›Œํฌํ”Œ๋กœ ํŒจํ„ด + +### ํƒ์ƒ‰์„ ์œ„ํ•œ ๋ธŒ๋žœ์นญ ์ „๋žต + +์—ฌ๋Ÿฌ ์ ‘๊ทผ ๋ฐฉ์‹์„ ๋น„๊ตํ•  ๋•Œ: + +``` +1. ์ดˆ๊ธฐ ์ƒํƒœ โ†’ ์ฒดํฌํฌ์ธํŠธ A +2. ๋ฐฉ๋ฒ• 1 ์‹œ๋„ โ†’ ์ฒดํฌํฌ์ธํŠธ B +3. A๋กœ ๋˜๊ฐ๊ธฐ +4. ๋ฐฉ๋ฒ• 2 ์‹œ๋„ โ†’ ์ฒดํฌํฌ์ธํŠธ C +5. B์™€ C ๋น„๊ต +6. ์ตœ์ข… ์„ ํƒ ํ›„ ์ง„ํ–‰ +``` + +### ์•ˆ์ „ํ•œ ๋ฆฌํŒฉํ† ๋ง ํŒจํ„ด + +ํฐ ๋ณ€๊ฒฝ์„ ํ•  ๋•Œ: + +``` +1. ํ˜„์žฌ ์ƒํƒœ โ†’ ์ž๋™ ์ฒดํฌํฌ์ธํŠธ +2. ๋ฆฌํŒฉํ† ๋ง ์‹œ์ž‘ +3. ํ…Œ์ŠคํŠธ ์‹คํ–‰ +4. ์„ฑ๊ณต โ†’ ๊ณ„์† ์ง„ํ–‰ +5. ์‹คํŒจ โ†’ ๋˜๊ฐ๊ธฐ ํ›„ ๋‹ค๋ฅธ ์ ‘๊ทผ ์‹œ๋„ +``` + +## ๋ชจ๋ฒ” ์‚ฌ์šฉ๋ฒ• + +์ฒดํฌํฌ์ธํŠธ๋Š” ์ž๋™ ์ƒ์„ฑ๋˜๋ฏ€๋กœ ๋ณ„๋„ ์ €์žฅ ์—†์ด ์ž‘์—…ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ํ•˜์ง€๋งŒ ๋‹ค์Œ ์›์น™์„ ๊ถŒ์žฅํ•ฉ๋‹ˆ๋‹ค: + +### ํšจ๊ณผ์ ์ธ ์‚ฌ์šฉ๋ฒ• + +โœ… **๊ถŒ์žฅ** +- ๋˜๊ฐ๊ธฐ ์ „ ์ฒดํฌํฌ์ธํŠธ ๋ชฉ๋ก ํ™•์ธ +- ๋‹ค๋ฅธ ๋ฐฉํ–ฅ์„ ์‹คํ—˜ํ•  ๋•Œ rewind ํ™œ์šฉ +- ์—ฌ๋Ÿฌ ์ ‘๊ทผ ๋ฐฉ์‹ ๋น„๊ต์— ํ™œ์šฉ +- ๊ฐ ์˜ต์…˜์˜ ์˜๋ฏธ ์ •ํ™•ํžˆ ์ดํ•ด + +โŒ **๋น„๊ถŒ์žฅ** +- ์ฒดํฌํฌ์ธํŠธ๋ฅผ ์ฝ”๋“œ ์ €์žฅ์†Œ์ฒ˜๋Ÿผ ์˜์กด +- ์™ธ๋ถ€ ํŒŒ์ผ ๋ณ€๊ฒฝ ์ถ”์  ์šฉ๋„๋กœ ์‚ฌ์šฉ +- Git ์ปค๋ฐ‹ ๋Œ€์ฒด ์ˆ˜๋‹จ์œผ๋กœ ์‚ฌ์šฉ + +## ๊ตฌ์„ฑ(Configuration) + +์ฒดํฌํฌ์ธํŠธ๋Š” Claude Code์˜ ๊ธฐ๋ณธ ๋‚ด์žฅ ๋™์ž‘์ด๋ฉฐ, ๋ณ„๋„์˜ ์„ค์ • ์—†์ด ์ž๋™์œผ๋กœ ํ™œ์„ฑํ™”๋ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ์‚ฌ์šฉ์ž ์ž…๋ ฅ๋งˆ๋‹ค ์ž๋™์œผ๋กœ ์ฒดํฌํฌ์ธํŠธ๊ฐ€ ์ƒ์„ฑ๋ฉ๋‹ˆ๋‹ค. + +์ฒดํฌํฌ์ธํŠธ์™€ ๊ด€๋ จ๋œ ์œ ์ผํ•œ ์„ค์ •์€ `cleanupPeriodDays`์ด๋ฉฐ, ์ด๋Š” ์„ธ์…˜ ๋ฐ ์ฒดํฌํฌ์ธํŠธ๊ฐ€ ์œ ์ง€๋˜๋Š” ๊ธฐ๊ฐ„์„ ์ œ์–ดํ•ฉ๋‹ˆ๋‹ค: + +```json +{ + "cleanupPeriodDays": 30 +} +``` + +- `cleanupPeriodDays`: ์„ธ์…˜ ๊ธฐ๋ก ๋ฐ ์ฒดํฌํฌ์ธํŠธ๋ฅผ ๋ณด๊ด€ํ•˜๋Š” ๊ธฐ๊ฐ„ (๊ธฐ๋ณธ๊ฐ’: `30`์ผ) + +> **v2.1.117 ์—…๋ฐ์ดํŠธ**: `cleanupPeriodDays`๋Š” ์ด์ œ ์ฒดํฌํฌ์ธํŠธ๋ฟ๋งŒ ์•„๋‹ˆ๋ผ ๋‹ค์Œ 4๊ฐ€์ง€ ๋””์Šคํฌ ์บ์‹œ ์ „์ฒด๋ฅผ ๊ด€๋ฆฌํ•ฉ๋‹ˆ๋‹ค: +> +> - ์„ธ์…˜ ์ฒดํฌํฌ์ธํŠธ +> - `~/.claude/tasks/` โ€” ์˜๊ตฌ ์ž‘์—… ๋ฆฌ์ŠคํŠธ +> - `~/.claude/shell-snapshots/` โ€” ์…ธ ํ™˜๊ฒฝ ์Šค๋ƒ…์ƒท +> - `~/.claude/backups/` โ€” ์„ค์ • ๋ฐ CLAUDE.md ๋ฐฑ์—… ๋กค๋ง ์ €์žฅ์†Œ +> +> ํ•˜๋‚˜์˜ ์„ค์ •๊ฐ’์œผ๋กœ ์œ„ 4๊ฐœ ๋””๋ ‰ํ† ๋ฆฌ๊ฐ€ ๋™์ผํ•œ ๋ณด๊ด€ ๊ธฐ๊ฐ„ ๊ธฐ์ค€์œผ๋กœ ์ •๋ฆฌ๋ฉ๋‹ˆ๋‹ค. + +## ์ œํ•œ์‚ฌํ•ญ(Limitations) + +์ฒดํฌํฌ์ธํŠธ์—๋Š” ๋‹ค์Œ๊ณผ ๊ฐ™์€ ์ œํ•œ์ด ์žˆ์Šต๋‹ˆ๋‹ค: + +- **bash ๋ช…๋ น ๋ณ€๊ฒฝ์€ ์ถ”์ ๋˜์ง€ ์•Š์Œ** - `rm`, `mv`, `cp` ๊ฐ™์€ ํŒŒ์ผ ์‹œ์Šคํ…œ ์ž‘์—…์€ ์ฒดํฌํฌ์ธํŠธ์— ํฌํ•จ๋˜์ง€ ์•Š์Œ +- **์™ธ๋ถ€ ๋ณ€๊ฒฝ์€ ์ถ”์ ๋˜์ง€ ์•Š์Œ** - Claude Code ์™ธ๋ถ€(์—๋””ํ„ฐ, ํ„ฐ๋ฏธ๋„ ๋“ฑ)์—์„œ ๋ฐœ์ƒํ•œ ๋ณ€๊ฒฝ์€ ๊ธฐ๋ก๋˜์ง€ ์•Š์Œ +- **๋ฒ„์ „ ๊ด€๋ฆฌ ์‹œ์Šคํ…œ ๋Œ€์ฒด ๋ถˆ๊ฐ€** - ์˜๊ตฌ์ ์ด๊ณ  ๊ฐ์‚ฌ ๊ฐ€๋Šฅํ•œ ๋ณ€๊ฒฝ ์ด๋ ฅ์€ Git์„ ์‚ฌ์šฉํ•ด์•ผ ํ•จ + +## ๋ฌธ์ œ ํ•ด๊ฒฐ(Troubleshooting) + +### ์ฒดํฌํฌ์ธํŠธ๊ฐ€ ๋ณด์ด์ง€ ์•Š์Œ + +**๋ฌธ์ œ**: ์˜ˆ์ƒํ•œ ์ฒดํฌํฌ์ธํŠธ๊ฐ€ ์—†์Œ + +**ํ•ด๊ฒฐ ๋ฐฉ๋ฒ•**: +- ์ฒดํฌํฌ์ธํŠธ๊ฐ€ ์ •๋ฆฌ๋˜์—ˆ๋Š”์ง€ ํ™•์ธ +- ๋””์Šคํฌ ๊ณต๊ฐ„ ํ™•์ธ +- `cleanupPeriodDays` ๊ฐ’์ด ์ถฉ๋ถ„ํžˆ ํฐ์ง€ ํ™•์ธ (๊ธฐ๋ณธ 30์ผ) + +### ๋˜๊ฐ๊ธฐ ์‹คํŒจ + +**๋ฌธ์ œ**: ์ฒดํฌํฌ์ธํŠธ๋กœ ๋˜๋Œ์•„๊ฐˆ ์ˆ˜ ์—†์Œ + +**ํ•ด๊ฒฐ ๋ฐฉ๋ฒ•**: +- ์ปค๋ฐ‹๋˜์ง€ ์•Š์€ ๋ณ€๊ฒฝ ์‚ฌํ•ญ ์ถฉ๋Œ ์—ฌ๋ถ€ ํ™•์ธ +- ์ฒดํฌํฌ์ธํŠธ ์†์ƒ ์—ฌ๋ถ€ ํ™•์ธ +- ๋‹ค๋ฅธ ์ฒดํฌํฌ์ธํŠธ๋กœ ๋˜๊ฐ๊ธฐ ์‹œ๋„ + +## Git๊ณผ์˜ ํ†ตํ•ฉ + +์ฒดํฌํฌ์ธํŠธ๋Š” Git์„ ๋Œ€์ฒดํ•˜์ง€ ์•Š๊ณ  ๋ณด์™„ํ•˜๋Š” ๊ธฐ๋Šฅ์ž…๋‹ˆ๋‹ค: + +| ๊ธฐ๋Šฅ | Git | ์ฒดํฌํฌ์ธํŠธ | +|------|-----|------------| +| ๋ฒ”์œ„ | ํŒŒ์ผ ์‹œ์Šคํ…œ | ๋Œ€ํ™” + ํŒŒ์ผ | +| ์ง€์†์„ฑ | ์˜๊ตฌ์  | ์„ธ์…˜ ๊ธฐ๋ฐ˜ | +| ์„ธ๋ถ„ํ™” | ์ปค๋ฐ‹ ๋‹จ์œ„ | ๋ชจ๋“  ์‹œ์  | +| ์†๋„ | ์ƒ๋Œ€์ ์œผ๋กœ ๋Š๋ฆผ | ์ฆ‰์‹œ | +| ๊ณต์œ  | ๊ฐ€๋Šฅ | ์ œํ•œ์  | + +๋‘˜์„ ํ•จ๊ป˜ ์‚ฌ์šฉํ•˜๋Š” ๊ฒƒ์ด ๊ถŒ์žฅ๋ฉ๋‹ˆ๋‹ค: +1. ๋น ๋ฅธ ์‹คํ—˜์—๋Š” ์ฒดํฌํฌ์ธํŠธ ์‚ฌ์šฉ +2. ํ™•์ •๋œ ๋ณ€๊ฒฝ์€ Git ์ปค๋ฐ‹ ์‚ฌ์šฉ +3. Git ์ž‘์—… ์ „ ์ฒดํฌํฌ์ธํŠธ ์ƒ์„ฑ +4. ์„ฑ๊ณตํ•œ ์ƒํƒœ๋ฅผ Git์— ์ €์žฅ + +## ๋น ๋ฅธ ์‹œ์ž‘ ๊ฐ€์ด๋“œ(Quick Start Guide) + +### ๊ธฐ๋ณธ ์›Œํฌํ”Œ๋กœ์šฐ + +1. **์ผ๋ฐ˜์ ์œผ๋กœ ์ž‘์—…** - Claude Code๊ฐ€ ์ž๋™์œผ๋กœ ์ฒดํฌํฌ์ธํŠธ ์ƒ์„ฑ +2. **๋˜๋Œ๋ฆฌ๊ณ  ์‹ถ์„ ๋•Œ** - `Esc` ๋‘ ๋ฒˆ ๋˜๋Š” `/rewind` ์‚ฌ์šฉ +3. **์ฒดํฌํฌ์ธํŠธ ์„ ํƒ** - ๋ชฉ๋ก์—์„œ ์›ํ•˜๋Š” ์‹œ์  ์„ ํƒ +4. **๋ณต์› ๋ฐฉ์‹ ์„ ํƒ** - ์ฝ”๋“œ์™€ ๋Œ€ํ™” ๋ณต์›, ๋Œ€ํ™”๋งŒ ๋ณต์›, ์ฝ”๋“œ๋งŒ ๋ณต์›, ์—ฌ๊ธฐ์„œ๋ถ€ํ„ฐ ์š”์•ฝ, ์ทจ์†Œ ์ค‘ ์„ ํƒ +5. **์ž‘์—… ๊ณ„์†** - ํ•ด๋‹น ์‹œ์ ์—์„œ ๋‹ค์‹œ ์ž‘์—… ์ง„ํ–‰ + +### ํ‚ค๋ณด๋“œ ๋‹จ์ถ•ํ‚ค + +- **`Esc` + `Esc`** - ์ฒดํฌํฌ์ธํŠธ ๋ธŒ๋ผ์šฐ์ € ์—ด๊ธฐ +- **`/rewind`** - ์ฒดํฌํฌ์ธํŠธ ์ ‘๊ทผ ๋ช…๋ น์–ด +- **`/checkpoint`** - `/rewind`์˜ ๋ณ„์นญ + +## ๋˜๊ฐ๊ธฐ๋ฅผ ์–ธ์ œ ํ•ด์•ผ ํ•˜๋Š”๊ฐ€: ์ปจํ…์ŠคํŠธ ๋ชจ๋‹ˆํ„ฐ๋ง + +์ฒดํฌํฌ์ธํŠธ๋Š” ๋˜๋Œ๋ฆด ์ˆ˜ ์žˆ๊ฒŒ ํ•ด์ฃผ์ง€๋งŒ, *์–ธ์ œ ๋˜๋Œ๋ ค์•ผ ํ•˜๋Š”์ง€*๋„ ์ค‘์š”ํ•ฉ๋‹ˆ๋‹ค. ๋Œ€ํ™”๊ฐ€ ๊ธธ์–ด์งˆ์ˆ˜๋ก Claude์˜ ์ปจํ…์ŠคํŠธ ์œˆ๋„์šฐ๊ฐ€ ์ฐจ๊ฒŒ ๋˜๊ณ , ๋ชจ๋ธ ์„ฑ๋Šฅ์ด ์ ์ง„์ ์œผ๋กœ ์ €ํ•˜๋  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์ด๋•Œ ์‚ฌ์šฉ์ž๋Š” ์ธ์ง€ํ•˜์ง€ ๋ชปํ•œ ์ƒํƒœ์—์„œ ํ’ˆ์งˆ์ด ๋‚ฎ์•„์ง„ ๊ฒฐ๊ณผ๋ฅผ ๊ธฐ๋ฐ˜์œผ๋กœ ์ฝ”๋“œ๋ฅผ ์ƒ์„ฑํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +**[cc-context-stats](https://github.com/luongnv89/cc-context-stats)**๋Š” ์ด๋ฅผ ํ•ด๊ฒฐํ•˜๊ธฐ ์œ„ํ•ด Claude Code ์ƒํƒœ๋ฐ”์— ์‹ค์‹œ๊ฐ„ **์ปจํ…์ŠคํŠธ ๊ตฌ๊ฐ„ ํ‘œ์‹œ**๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. ์ปจํ…์ŠคํŠธ๋ฅผ ์„ธ ๊ตฌ๊ฐ„์œผ๋กœ ๋‚˜๋ˆ„์–ด ๋ณด์—ฌ์ค๋‹ˆ๋‹ค: + +- **Plan (์ดˆ๋ก)**: ์•ˆ์ „ํ•œ ๊ณ„ํš ๋ฐ ๊ฐœ๋ฐœ ๋‹จ๊ณ„ +- **Code (๋…ธ๋ž‘)**: ์ƒˆ๋กœ์šด ๊ณ„ํš ์‹œ์ž‘์€ ํ”ผํ•ด์•ผ ํ•˜๋Š” ๋‹จ๊ณ„ +- **Dump (์ฃผํ™ฉ)**: ๋งˆ๋ฌด๋ฆฌํ•˜๊ณ  ๋˜๊ฐ๊ธฐ๊ฐ€ ํ•„์š”ํ•œ ๋‹จ๊ณ„ + +์ด ๊ตฌ๊ฐ„์ด ๋ณ€๊ฒฝ๋˜๋ฉด ์ฒดํฌํฌ์ธํŠธ๋ฅผ ๋งŒ๋“ค๊ณ  ์ƒˆ๋กœ ์‹œ์ž‘ํ•˜๋Š” ๊ฒƒ์ด ๊ถŒ์žฅ๋ฉ๋‹ˆ๋‹ค. + +## ๊ด€๋ จ ๊ฐœ๋…(Related Concepts) + +- **[๊ณ ๊ธ‰ ๊ธฐ๋Šฅ](../09-advanced-features/)** - ํ”Œ๋ž˜๋‹ ๋ชจ๋“œ ๋ฐ ๊ธฐํƒ€ ๊ณ ๊ธ‰ ๊ธฐ๋Šฅ +- **[๋ฉ”๋ชจ๋ฆฌ ๊ด€๋ฆฌ](../02-memory/)** - ๋Œ€ํ™” ๊ธฐ๋ก ๋ฐ ์ปจํ…์ŠคํŠธ ๊ด€๋ฆฌ +- **[์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด](../01-slash-commands/)** - ์‚ฌ์šฉ์ž ๋ช…๋ น ๋‹จ์ถ• ๊ธฐ๋Šฅ +- **[ํ›…(Hooks)](../06-hooks/)** - ์ด๋ฒคํŠธ ๊ธฐ๋ฐ˜ ์ž๋™ํ™” +- **[ํ”Œ๋Ÿฌ๊ทธ์ธ](../07-plugins/)** - ํ™•์žฅ ๊ธฐ๋Šฅ ํŒจํ‚ค์ง€ + +## ์ถ”๊ฐ€ ์ž๋ฃŒ(Additional Resources) + +- [๊ณต์‹ ์ฒดํฌํฌ์ธํŠธ ๋ฌธ์„œ](https://code.claude.com/docs/en/checkpointing) +- [๊ณ ๊ธ‰ ๊ธฐ๋Šฅ ๊ฐ€์ด๋“œ](../09-advanced-features/) - Extended thinking ๋“ฑ ๊ธฐ๋Šฅ + +## ์š”์•ฝ(Summary) + +์ฒดํฌํฌ์ธํŠธ๋Š” Claude Code์˜ ์ž๋™ ๊ธฐ๋Šฅ์œผ๋กœ, ์ž‘์—…์„ ์žƒ์ง€ ์•Š๊ณ  ๋‹ค์–‘ํ•œ ์ ‘๊ทผ ๋ฐฉ์‹์„ ์•ˆ์ „ํ•˜๊ฒŒ ์‹คํ—˜ํ•  ์ˆ˜ ์žˆ๊ฒŒ ํ•ด์ค๋‹ˆ๋‹ค. ๋ชจ๋“  ์‚ฌ์šฉ์ž ์ž…๋ ฅ๋งˆ๋‹ค ์ž๋™์œผ๋กœ ์ฒดํฌํฌ์ธํŠธ๊ฐ€ ์ƒ์„ฑ๋˜๋ฏ€๋กœ ์–ธ์ œ๋“ ์ง€ ์ด์ „ ์‹œ์ ์œผ๋กœ ๋˜๋Œ๋ฆด ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +ํ•ต์‹ฌ ์žฅ์ : +- ์—ฌ๋Ÿฌ ์ ‘๊ทผ ๋ฐฉ์‹์„ ์ž์œ ๋กญ๊ฒŒ ์‹คํ—˜ ๊ฐ€๋Šฅ +- ์‹ค์ˆ˜ ๋ฐœ์ƒ ์‹œ ๋น ๋ฅธ ๋ณต๊ตฌ +- ๋‹ค์–‘ํ•œ ํ•ด๊ฒฐ์ฑ… ๋น„๊ต ๊ฐ€๋Šฅ +- Git๊ณผ ์•ˆ์ „ํ•˜๊ฒŒ ํ•จ๊ป˜ ์‚ฌ์šฉ ๊ฐ€๋Šฅ + +์ค‘์š”: ์ฒดํฌํฌ์ธํŠธ๋Š” Git์„ ๋Œ€์ฒดํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋น ๋ฅธ ์‹คํ—˜์—๋Š” ์ฒดํฌํฌ์ธํŠธ๋ฅผ, ํ™•์ •๋œ ๋ณ€๊ฒฝ์—๋Š” Git์„ ์‚ฌ์šฉํ•˜์„ธ์š”. + +--- + +**Last Updated**: June 28, 2026 +**Claude Code Version**: 2.1.195 +**Sources**: +- https://code.claude.com/docs/en/checkpointing +- https://code.claude.com/docs/en/settings +- https://github.com/anthropics/claude-code/releases/tag/v2.1.117 +**Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5 diff --git a/ko/08-checkpoints/checkpoint-examples.md b/ko/08-checkpoints/checkpoint-examples.md new file mode 100644 index 00000000..ebc095c6 --- /dev/null +++ b/ko/08-checkpoints/checkpoint-examples.md @@ -0,0 +1,336 @@ +# ์ฒดํฌํฌ์ธํŠธ ์˜ˆ์ œ(Checkpoints and Rewind Examples) + +Claude Code์—์„œ ์ฒดํฌํฌ์ธํŠธ๋ฅผ ํšจ๊ณผ์ ์œผ๋กœ ์‚ฌ์šฉํ•˜๋Š” ์‹ค์ œ ์˜ˆ์ œ์ž…๋‹ˆ๋‹ค. + +์ฐธ๊ณ : ์ฒดํฌํฌ์ธํŠธ๋Š” ๋ชจ๋“  ์‚ฌ์šฉ์ž ์ž…๋ ฅ๋งˆ๋‹ค ์ž๋™์œผ๋กœ ์ƒ์„ฑ๋ฉ๋‹ˆ๋‹ค. ๋”ฐ๋ผ์„œ ์ˆ˜๋™ ์ €์žฅ์ด ํ•„์š”ํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋˜๋Œ๋ฆฌ๋ ค๋ฉด `Esc`๋ฅผ ๋‘ ๋ฒˆ ๋ˆ„๋ฅด๊ฑฐ๋‚˜(`Esc+Esc`) `/rewind`๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ์ฒดํฌํฌ์ธํŠธ ๋ธŒ๋ผ์šฐ์ €๋ฅผ ์—ด ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +## ์˜ˆ์ œ 1: ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ + +### ์‹œ๋‚˜๋ฆฌ์˜ค +MySQL์—์„œ PostgreSQL๋กœ ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ํ•ด์•ผ ํ•˜์ง€๋งŒ, ์ง์ ‘ ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ ๋ฐฉ์‹๊ณผ ์ ์ง„์ ์ธ dual-write ๋ฐฉ์‹ ๋‘ ๊ฐ€์ง€๋ฅผ ๋ชจ๋‘ ์‹คํ—˜ํ•ด๋ณด๊ณ  ์‹ถ๋‹ค. + +### ์›Œํฌํ”Œ๋กœ์šฐ + +``` +User: MySQL์—์„œ PostgreSQL๋กœ ์ง์ ‘ ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜์„ ๊ตฌํ˜„ํ•ด์ค˜ + [์ฒดํฌํฌ์ธํŠธ A ์ž๋™ ์ƒ์„ฑ] + +Claude: ์ง์ ‘ ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜์„ ๊ตฌํ˜„ํ•˜๊ฒ ์Šต๋‹ˆ๋‹ค... +[DB ๋“œ๋ผ์ด๋ฒ„ ๋ณ€๊ฒฝ, ์ฟผ๋ฆฌ ์ˆ˜์ •, ์Šคํ‚ค๋งˆ ๋ณ€๊ฒฝ] + +User: ํ…Œ์ŠคํŠธ ์‹คํ–‰ + [์ฒดํฌํฌ์ธํŠธ B ์ž๋™ ์ƒ์„ฑ] + +Claude: ํ…Œ์ŠคํŠธ ์‹คํ–‰ ์ค‘... +โŒ 15๊ฐœ ํ…Œ์ŠคํŠธ ์‹คํŒจ - ์ปค๋„ฅ์…˜ ํ’€ ๋ฌธ์ œ ๋ฐœ์ƒ + +User: ์ด ๋ฐฉ์‹์€ ๋ฌธ์ œ๊ฐ€ ์žˆ์–ด. dual-write ๋ฐฉ์‹์œผ๋กœ ๋‹ค์‹œ ํ•ด๋ณด์ž. +[Esc+Esc๋กœ ์ฒดํฌํฌ์ธํŠธ A ์„ ํƒ ํ›„ "์ฝ”๋“œ์™€ ๋Œ€ํ™” ๋ณต์›"] + +User: ์ด์ œ ๋‘ ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค์— ๋™์‹œ์— ์“ฐ๋Š” dual-write ํŒจํ„ด์„ ๊ตฌํ˜„ํ•ด์ค˜ + +Claude: dual-write ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜์„ ๊ตฌํ˜„ํ•˜๊ฒ ์Šต๋‹ˆ๋‹ค... +[dual-write ๋ ˆ์ด์–ด ๋ฐ ์ ์ง„์  ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ ์ „๋žต ๊ตฌํ˜„] + +User: ํ…Œ์ŠคํŠธ ์‹คํ–‰ + +Claude: ํ…Œ์ŠคํŠธ ์‹คํ–‰ ์ค‘... +โœ… ๋ชจ๋“  ํ…Œ์ŠคํŠธ ํ†ต๊ณผ + +User: dual-write ๋ฐฉ์‹์ด ๋” ์•ˆ์ „ํ•˜๋„ค. ์ด๊ฑธ ์ปค๋ฐ‹ํ•˜์ž +``` + +## ์˜ˆ์ œ 2: ์„ฑ๋Šฅ ์ตœ์ ํ™” + +### ์‹œ๋‚˜๋ฆฌ์˜ค +์—ฌ๋Ÿฌ ๊ฐ€์ง€ ์„ฑ๋Šฅ ์ตœ์ ํ™” ์ „๋žต์„ ๋น„๊ตํ•ด์•ผ ํ•˜๋Š” ์ƒํ™ฉ + +### ์›Œํฌํ”Œ๋กœ์šฐ + +``` +User: API ์‘๋‹ต ์†๋„๋ฅผ ์ตœ์ ํ™”ํ•ด์ค˜. ํ˜„์žฌ: 450ms + [์ฒดํฌํฌ์ธํŠธ "Baseline" ์ž๋™ ์ƒ์„ฑ] + +Claude: DB ์ฟผ๋ฆฌ ์บ์‹ฑ์„ ์ถ”๊ฐ€ํ•˜๊ฒ ์Šต๋‹ˆ๋‹ค... +[Redis ์บ์‹ฑ ๊ตฌํ˜„] + +User: ์„ฑ๋Šฅ ํ…Œ์ŠคํŠธ ์‹คํ–‰ + +Claude: ๊ฒฐ๊ณผ: ํ‰๊ท  280ms (38% ๊ฐœ์„ ) + +User: ๋‹ค๋ฅธ ๋ฐฉ๋ฒ•๋„ ์‹œ๋„ํ•ด๋ณด์ž +[Esc+Esc๋กœ Baseline ๋ณต์›] + +User: DB ์ฟผ๋ฆฌ ์ตœ์ ํ™” ๋ฐฉ์‹์œผ๋กœ ํ•ด๋ณด์ž + +Claude: DB ์ฟผ๋ฆฌ๋ฅผ ์ตœ์ ํ™”ํ•˜๊ฒ ์Šต๋‹ˆ๋‹ค... +[์ธ๋ฑ์Šค ์ถ”๊ฐ€, N+1 ๋ฌธ์ œ ํ•ด๊ฒฐ] + +User: ์„ฑ๋Šฅ ํ…Œ์ŠคํŠธ ์‹คํ–‰ + +Claude: ๊ฒฐ๊ณผ: ํ‰๊ท  180ms (60% ๊ฐœ์„ ) + +User: ์„ธ ๋ฒˆ์งธ ๋ฐฉ๋ฒ•๋„ ํ•ด๋ณด์ž +[Esc+Esc๋กœ Baseline ๋ณต์›] + +User: ์‘๋‹ต ์••์ถ• + CDN ์ ์šฉํ•ด๋ณด์ž + +Claude: gzip ์ ์šฉ ๋ฐ CDN ์„ค์ •... +[์••์ถ• ๋ฐ CDN ๊ตฌ์„ฑ] + +User: ์„ฑ๋Šฅ ํ…Œ์ŠคํŠธ ์‹คํ–‰ + +Claude: ๊ฒฐ๊ณผ: ํ‰๊ท  320ms (29% ๊ฐœ์„ ) + +User: ์ฟผ๋ฆฌ ์ตœ์ ํ™”๊ฐ€ ๊ฐ€์žฅ ์ข‹๋„ค. ์—ฌ๊ธฐ์— ์บ์‹ฑ์„ ๊ฒฐํ•ฉํ•ด๋ณด์ž +[์ฟผ๋ฆฌ ์ตœ์ ํ™” ์ฒดํฌํฌ์ธํŠธ๋กœ ๋ณต์›] + +User: Redis ์บ์‹ฑ์„ ์ถ”๊ฐ€ํ•ด๋ณด์ž + +Claude: Redis ์บ์‹ฑ ์ถ”๊ฐ€... +``` + +## ์˜ˆ์ œ 3: UI/UX ๋ฐ˜๋ณต ๊ฐœ์„  + +### ์‹œ๋‚˜๋ฆฌ์˜ค +๋Œ€์‹œ๋ณด๋“œ ๋ ˆ์ด์•„์›ƒ์„ ์—ฌ๋Ÿฌ ๋ฐฉ์‹์œผ๋กœ ์‹คํ—˜ + +### ์›Œํฌํ”Œ๋กœ์šฐ + +``` +User: ์‚ฌ์ด๋“œ๋ฐ” ๋ ˆ์ด์•„์›ƒ์œผ๋กœ ๋Œ€์‹œ๋ณด๋“œ๋ฅผ ๋‹ค์‹œ ์„ค๊ณ„ํ•ด์ค˜ + [์ฒดํฌํฌ์ธํŠธ "Start" ์ž๋™ ์ƒ์„ฑ] + +Claude: ์‚ฌ์ด๋“œ๋ฐ” ๋ ˆ์ด์•„์›ƒ ๊ตฌํ˜„ + +User: ์Šคํฌ๋ฆฐ์ƒท ๋ณด์—ฌ์ค˜ + +Claude: [์Šคํฌ๋ฆฐ์ƒท] + +User: ๋„ˆ๋ฌด ๋‹ต๋‹ตํ•ด. ์ƒ๋‹จ ๋„ค๋น„๊ฒŒ์ด์…˜์œผ๋กœ ๋ฐ”๊ฟ”๋ณด์ž +[Start ์ฒดํฌํฌ์ธํŠธ๋กœ ๋ณต์›] + +User: ์ƒ๋‹จ ๋„ค๋น„๊ฒŒ์ด์…˜์œผ๋กœ ๊ตฌํ˜„ํ•ด์ค˜ + +Claude: ์ƒ๋‹จ ๋„ค๋น„๊ฒŒ์ด์…˜ ๊ตฌํ˜„ + +User: ์Šคํฌ๋ฆฐ์ƒท ๋ณด์—ฌ์ค˜ + +Claude: [์Šคํฌ๋ฆฐ์ƒท] + +User: ๊ดœ์ฐฎ๊ธด ํ•œ๋ฐ ์นด๋“œ ๊ทธ๋ฆฌ๋“œ ๋ฐฉ์‹๋„ ํ•ด๋ณด์ž +[Start๋กœ ๋ณต์›] + +User: ์นด๋“œ ๊ธฐ๋ฐ˜ ๊ทธ๋ฆฌ๋“œ๋กœ ๊ตฌํ˜„ํ•ด์ค˜ + +Claude: ์นด๋“œ ๊ทธ๋ฆฌ๋“œ ๊ตฌํ˜„ + +User: ์ด๊ฑด ์ข‹๋‹ค! ๊ทธ๋Ÿฐ๋ฐ ์ƒ๋‹จ ๋„ค๋น„๊ฒŒ์ด์…˜๋„ ๊ฐ™์ด ๋„ฃ์–ด๋ณผ ์ˆ˜ ์žˆ๋‚˜? +[์นด๋“œ ๊ทธ๋ฆฌ๋“œ ์ดํ›„ ์ฒดํฌํฌ์ธํŠธ๋กœ ๋ณต์›] + +User: ์นด๋“œ ๊ทธ๋ฆฌ๋“œ์— ์ƒ๋‹จ ๋„ค๋น„๊ฒŒ์ด์…˜์„ ์ถ”๊ฐ€ํ•ด์ค˜ + +Claude: ์ƒ๋‹จ ๋„ค๋น„๊ฒŒ์ด์…˜ + ์นด๋“œ ๊ทธ๋ฆฌ๋“œ ๊ฒฐํ•ฉ +``` + +## ์˜ˆ์ œ 4: ๋””๋ฒ„๊น… ์„ธ์…˜ + +### ์‹œ๋‚˜๋ฆฌ์˜ค +๋ณต์žกํ•œ ๋ฉ”๋ชจ๋ฆฌ ๋ˆ„์ˆ˜ ๋ฒ„๊ทธ ํ•ด๊ฒฐ + +### ์›Œํฌํ”Œ๋กœ์šฐ + +``` +User: ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜์— ๋ฉ”๋ชจ๋ฆฌ ๋ˆ„์ˆ˜๊ฐ€ ์žˆ์–ด + [์ฒดํฌํฌ์ธํŠธ "๋””๋ฒ„๊น… ์ „" ์ž๋™ ์ƒ์„ฑ] + +Claude: ์›์ธ ๋ถ„์„ ์ค‘... +[์ฝ”๋“œ ๋ถ„์„] + +User: ์ด๋ฒคํŠธ ๋ฆฌ์Šค๋„ˆ ๋ฌธ์ œ์ธ ๊ฒƒ ๊ฐ™์•„. ๊ทธ๊ฑธ ๊ณ ์ณ๋ณด์ž + +Claude: ์ด๋ฒคํŠธ ๋ฆฌ์Šค๋„ˆ ์ •๋ฆฌ ์ˆ˜์ • + +User: ๋ฉ”๋ชจ๋ฆฌ ํ”„๋กœํŒŒ์ผ๋Ÿฌ ์‹คํ–‰ + +Claude: ์—ฌ์ „ํžˆ ๋ˆ„์ˆ˜ ๋ฐœ์ƒ - ์ด๋ฒคํŠธ ๋ฆฌ์Šค๋„ˆ๊ฐ€ ์›์ธ์ด ์•„๋‹˜ + +User: ๋‹ค๋ฅธ ๊ฐ€์„ค๋กœ ๋Œ์•„๊ฐ€๋ณด์ž +[๋””๋ฒ„๊น… ์ „ ์ฒดํฌํฌ์ธํŠธ๋กœ ๋ณต์›] + +User: DB ์ปค๋„ฅ์…˜ ๋ฌธ์ œ์ผ ์ˆ˜๋„ ์žˆ์–ด + +Claude: ์ปค๋„ฅ์…˜ ํ’€ ์ˆ˜์ • + +User: ๋ฉ”๋ชจ๋ฆฌ ํ”„๋กœํŒŒ์ผ๋Ÿฌ ์‹คํ–‰ + +Claude: ์—ฌ์ „ํžˆ ๋ˆ„์ˆ˜ - ์ปค๋„ฅ์…˜ ๋ฌธ์ œ ์•„๋‹˜ + +User: ๋‹ค๋ฅธ ๋ฐฉํ–ฅ์œผ๋กœ ๊ฐ€๋ณด์ž +[๋””๋ฒ„๊น… ์ „์œผ๋กœ ๋ณต์›] + +User: ์ˆœํ™˜ ์ฐธ์กฐ๋ฅผ ํ™•์ธํ•ด๋ณด์ž + +Claude: ์บ์‹œ ๋‚ด๋ถ€ ์ˆœํ™˜ ์ฐธ์กฐ ๋ฐœ๊ฒฌ ๋ฐ ์ˆ˜์ • + +User: ๋ฉ”๋ชจ๋ฆฌ ํ”„๋กœํŒŒ์ผ๋Ÿฌ ์‹คํ–‰ + +Claude: โœ… ๋ฉ”๋ชจ๋ฆฌ ๋ˆ„์ˆ˜ ํ•ด๊ฒฐ! ์บ์‹œ ์ˆœํ™˜ ์ฐธ์กฐ๊ฐ€ ์›์ธ์ด์—ˆ์Œ + +User: ์ข‹๋‹ค. ์ด๊ฑฐ ์ปค๋ฐ‹ํ•˜์ž +``` + +## ์˜ˆ์ œ 5: API ์„ค๊ณ„ ์ง„ํ™” + +### ์‹œ๋‚˜๋ฆฌ์˜ค +REST API ์„ค๊ณ„๋ฅผ ์—ฌ๋Ÿฌ ๋ฐฉ์‹์œผ๋กœ ๋ฐœ์ „์‹œํ‚ค๋Š” ๊ณผ์ • + +### ์›Œํฌํ”Œ๋กœ์šฐ + +``` +User: ๋ธ”๋กœ๊ทธ ํ”Œ๋žซํผ์šฉ REST API๋ฅผ ๋งŒ๋“ค์–ด์ค˜ + [API ์„ค๊ณ„ ์ „ ์ฒดํฌํฌ์ธํŠธ ์ƒ์„ฑ] + +Claude: ๊ธฐ๋ณธ CRUD API ์ƒ์„ฑ + +User: ํŽ˜์ด์ง€๋„ค์ด์…˜์ด๋ž‘ ํ•„ํ„ฐ๋ง๋„ ์ถ”๊ฐ€ํ•ด์ค˜ + +Claude: ํŽ˜์ด์ง€๋„ค์ด์…˜ ๋ฐ ํ•„ํ„ฐ๋ง ์ถ”๊ฐ€ + +User: ๋ฆฌ์†Œ์Šค ๊ด€๊ณ„๋„ ๊ฐœ์„ ํ•ด์•ผ ํ•ด + +Claude: HATEOAS ๋งํฌ ๊ตฌ์กฐ ์ ์šฉ + +User: ์ž ๊น, REST ๋Œ€์‹  GraphQL๋กœ ํ•ด๋ณด์ž +[API ์„ค๊ณ„ ์ „์œผ๋กœ ๋ณต์›] + +User: GraphQL API๋กœ ๋‹ค์‹œ ๋งŒ๋“ค์–ด์ค˜ + +Claude: GraphQL API ๊ตฌํ˜„ + +User: REST๊ฐ€ ๋” ๋‚˜์€ ๊ฒƒ ๊ฐ™์•„ +[HATEOAS ์ดํ›„ ์ฒดํฌํฌ์ธํŠธ๋กœ ๋ณต์›] + +User: REST API๋กœ ์ตœ์ข… ํ™•์ •ํ•˜์ž +``` + +## ์˜ˆ์ œ 6: ์„ค์ • ๊ด€๋ฆฌ(Configuration Management) + +### ์‹œ๋‚˜๋ฆฌ์˜ค +์—ฌ๋Ÿฌ ๊ฐ€์ง€ ์„ค์ • ๋ฐฉ์‹(config approach)์„ ์‹คํ—˜ํ•˜๋Š” ์ƒํ™ฉ + +### ์›Œํฌํ”Œ๋กœ์šฐ + +``` +User: ์„ค์ •์„ ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋กœ ์˜ฎ๊ฒจ์ค˜ + [์ฒดํฌํฌ์ธํŠธ "Original config" ์ž๋™ ์ƒ์„ฑ] + +Claude: ํ™˜๊ฒฝ ๋ณ€์ˆ˜ ๊ธฐ๋ฐ˜ ์„ค์ •์„ ์ ์šฉํ•˜๊ฒ ์Šต๋‹ˆ๋‹ค... +[ํ™˜๊ฒฝ ๋ณ€์ˆ˜ ๊ตฌ์„ฑ ์ ์šฉ] + +User: ๊ฐœ๋ฐœ ํ™˜๊ฒฝ์—์„œ ํ…Œ์ŠคํŠธ + +Claude: ๋กœ์ปฌ์—์„œ๋Š” ์ •์ƒ ๋™์ž‘ํ•˜์ง€๋งŒ, ํ”„๋กœ๋•์…˜ ๋ฐฐํฌ์—์„œ ๋ฌธ์ œ ๋ฐœ์ƒ + +User: ๋‹ค๋ฅธ ๋ฐฉ์‹์œผ๋กœ ํ•ด๋ณด์ž +[Esc+Esc๋กœ Original config ์ฒดํฌํฌ์ธํŠธ ์„ ํƒ ํ›„ "์ฝ”๋“œ์™€ ๋Œ€ํ™” ๋ณต์›"] + +User: ์„ค์ • ํŒŒ์ผ ๊ธฐ๋ฐ˜ ๋ฐฉ์‹ + ๊ฒ€์ฆ ๋กœ์ง์œผ๋กœ ๋ฐ”๊ฟ”๋ณด์ž + +Claude: YAML ์„ค์ • + JSON schema ๊ฒ€์ฆ ์ ์šฉ + +User: ๊ฐœ๋ฐœ ํ™˜๊ฒฝ ํ…Œ์ŠคํŠธ + +Claude: โœ… ์ •์ƒ ๋™์ž‘, ๊ฒ€์ฆ ์—๋Ÿฌ๋„ ์ž˜ ์ฒ˜๋ฆฌ๋จ + +User: ๋ฏผ๊ฐํ•œ ๊ฐ’์€ env var๋„ ์ง€์›ํ•  ์ˆ˜ ์žˆ์–ด? + +Claude: secrets๋Š” env var override ๋ฐฉ์‹ ์ถ”๊ฐ€ + +User: ๋ฐฐํฌ ํ…Œ์ŠคํŠธ + +Claude: โœ… ๋ชจ๋“  ํ™˜๊ฒฝ์—์„œ ์ •์ƒ ๋™์ž‘ + +User: ์ด ๋ฐฉ์‹์ด ํ”„๋กœ๋•์…˜์— ์ ํ•ฉํ•˜๋„ค +``` + +## ์˜ˆ์ œ 7: ํ…Œ์ŠคํŠธ ์ „๋žต(Test Strategy) + +### ์‹œ๋‚˜๋ฆฌ์˜ค +ํฌ๊ด„์ ์ธ ํ…Œ์ŠคํŠธ ๊ตฌ์กฐ๋ฅผ ๊ตฌ์ถ•ํ•˜๋Š” ๊ณผ์ • + +### ์›Œํฌํ”Œ๋กœ์šฐ + +``` +User: auth ๋ชจ๋“ˆ์— ์œ ๋‹› ํ…Œ์ŠคํŠธ ์ถ”๊ฐ€ํ•ด์ค˜ + [์ฒดํฌํฌ์ธํŠธ ์ž๋™ ์ƒ์„ฑ] + +Claude: Jest ๊ธฐ๋ฐ˜ ์œ ๋‹› ํ…Œ์ŠคํŠธ ์ถ”๊ฐ€ + +User: ํ…Œ์ŠคํŠธ ์‹คํ–‰ + +Claude: 45๊ฐœ ํ…Œ์ŠคํŠธ ํ†ต๊ณผ, ์ปค๋ฒ„๋ฆฌ์ง€ 78% + +User: ํ†ตํ•ฉ ํ…Œ์ŠคํŠธ๋„ ์ถ”๊ฐ€ํ•ด์ค˜ + +Claude: ํ†ตํ•ฉ ํ…Œ์ŠคํŠธ ์ถ”๊ฐ€ + +User: ํ…Œ์ŠคํŠธ ์‹คํ–‰ + +Claude: 89๊ฐœ ํ†ต๊ณผ, ์ปค๋ฒ„๋ฆฌ์ง€ 92%, ํ•˜์ง€๋งŒ ์‹คํ–‰ ์†๋„ 3๋ถ„ (๋Š๋ฆผ) + +User: ๋„ˆ๋ฌด ๋Š๋ ค. ์ตœ์ ํ™”ํ•˜์ž + +Claude: ํ…Œ์ŠคํŠธ ํ™˜๊ฒฝ ์ตœ์ ํ™”, ๋ณ‘๋ ฌ ์‹คํ–‰ ์ ์šฉ + +User: ํ…Œ์ŠคํŠธ ์‹คํ–‰ + +Claude: 89๊ฐœ ํ†ต๊ณผ, ์ปค๋ฒ„๋ฆฌ์ง€ 92%, 35์ดˆ๋กœ ๊ฐœ์„ ๋จ โœ… + +User: ์ข‹๋‹ค. ์ด์ œ E2E ํ…Œ์ŠคํŠธ๋„ ์ถ”๊ฐ€ํ•˜์ž + +Claude: Playwright ๊ธฐ๋ฐ˜ E2E ํ…Œ์ŠคํŠธ ์ถ”๊ฐ€ + +User: ์ „์ฒด ํ…Œ์ŠคํŠธ ์‹คํ–‰ + +Claude: 112๊ฐœ ํ†ต๊ณผ, ์ปค๋ฒ„๋ฆฌ์ง€ 94%, 2๋ถ„ ์†Œ์š” + +User: ๊ท ํ˜• ์ž˜ ๋งž์•˜๋„ค +``` + +## ์˜ˆ์ œ 8: Summarize from Checkpoint ์‚ฌ์šฉ + +### ์‹œ๋‚˜๋ฆฌ์˜ค +๊ธด ๋””๋ฒ„๊น… ์„ธ์…˜ ์ดํ›„ ์ปจํ…์ŠคํŠธ๋ฅผ ์••์ถ•ํ•˜๋ฉด์„œ ํ•ต์‹ฌ๋งŒ ์œ ์ง€ + +### ์›Œํฌํ”Œ๋กœ์šฐ + +``` +User: [20๊ฐœ ์ด์ƒ์˜ ๋ฉ”์‹œ์ง€๋กœ ๋””๋ฒ„๊น… ์ง„ํ–‰ ํ›„] + +[Esc+Esc๋กœ ์ดˆ๊ธฐ ์ฒดํฌํฌ์ธํŠธ ์„ ํƒ ํ›„ "์—ฌ๊ธฐ์„œ๋ถ€ํ„ฐ ์š”์•ฝ" ์„ ํƒ] +[์„ ํƒ์ ์œผ๋กœ ์ง€์‹œ์‚ฌํ•ญ: "๋ฌด์—‡์„ ์‹œ๋„ํ–ˆ๊ณ  ๋ฌด์—‡์ด ํ•ด๊ฒฐ๋๋Š”์ง€ ์ค‘์‹ฌ์œผ๋กœ ์š”์•ฝ"] + +Claude: [ํ•ด๋‹น ์‹œ์  ์ดํ›„ ๋Œ€ํ™” ๋‚ด์šฉ์„ ์š”์•ฝ ์ƒ์„ฑ] +[์›๋ณธ ๋ฉ”์‹œ์ง€๋Š” transcript์— ๋ณด์กด๋จ] +[์š”์•ฝ์œผ๋กœ ๋Œ€ํ™”๊ฐ€ ์••์ถ•๋˜์–ด ์ปจํ…์ŠคํŠธ ์‚ฌ์šฉ๋Ÿ‰ ๊ฐ์†Œ] + +User: ์ด์ œ ์„ฑ๊ณตํ•œ ์ ‘๊ทผ ๋ฐฉ์‹์œผ๋กœ ๊ณ„์† ์ง„ํ–‰ํ•˜์ž +``` + +## ํ•ต์‹ฌ ์ •๋ฆฌ(Key Takeaways) + +1. **์ฒดํฌํฌ์ธํŠธ๋Š” ์ž๋™ ์ƒ์„ฑ๋จ**: ๋ชจ๋“  ์ž…๋ ฅ๋งˆ๋‹ค ์ž๋™ ์ €์žฅ โ†’ ์ˆ˜๋™ ์ €์žฅ ๋ถˆํ•„์š” +2. **์ ‘๊ทผ ๋ฐฉ๋ฒ•์€ 2๊ฐ€์ง€**: Esc+Esc ๋˜๋Š” /rewind +3. **๋ณต์› ๋ฐฉ์‹ ์„ ํƒ ์ค‘์š”**: ์ฝ”๋“œ / ๋Œ€ํ™” / ๋‘˜ ๋‹ค / ์š”์•ฝ ์ค‘ ์„ ํƒ +4. **์‹คํ—˜์„ ๋‘๋ ค์›Œํ•˜์ง€ ๋ง ๊ฒƒ**: ์ฒดํฌํฌ์ธํŠธ ๋•๋ถ„์— ์•ˆ์ „ํ•˜๊ฒŒ ๋ณ€๊ฒฝ ๊ฐ€๋Šฅ +5. **Git๊ณผ ํ•จ๊ป˜ ์‚ฌ์šฉ**: ์ฒดํฌํฌ์ธํŠธ๋Š” ์‹คํ—˜์šฉ, Git์€ ํ™•์ •์šฉ +6. **๊ธด ์„ธ์…˜์€ ์š”์•ฝ ํ™œ์šฉ**: "์—ฌ๊ธฐ์„œ๋ถ€ํ„ฐ ์š”์•ฝ"์œผ๋กœ ์ปจํ…์ŠคํŠธ ๊ด€๋ฆฌ + +--- +**Last Updated**: June 2, 2026 +**Claude Code Version**: 2.1.160 +**Sources**: +- https://code.claude.com/docs/en/checkpointing +- https://code.claude.com/docs/en/changelog +**Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5 diff --git a/ko/09-advanced-features/README.md b/ko/09-advanced-features/README.md new file mode 100644 index 00000000..c2552002 --- /dev/null +++ b/ko/09-advanced-features/README.md @@ -0,0 +1,2389 @@ + + + Claude How To + + +# ๊ณ ๊ธ‰ ๊ธฐ๋Šฅ + +๊ธฐํš ๋ชจ๋“œ, ํ™•์žฅ๋œ ์‚ฌ๊ณ , ์ž๋™ ๋ชจ๋“œ, ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž‘์—…, ๊ถŒํ•œ ๋ชจ๋“œ, ์ธ์‡„ ๋ชจ๋“œ (๋น„๋Œ€ํ™”ํ˜•), ์„ธ์…˜ ๊ด€๋ฆฌ, ๋Œ€ํ™”ํ˜• ๊ธฐ๋Šฅ, ์ฑ„๋„, ์Œ์„ฑ ๋ฐ›์•„์“ฐ๊ธฐ, ์›๊ฒฉ ์ œ์–ด, ์›น ์„ธ์…˜, ๋ฐ์Šคํฌํ†ฑ ์•ฑ, ์ž‘์—… ๋ชฉ๋ก, ํ”„๋กฌํ”„ํŠธ ์ œ์•ˆ, Git ์›ŒํฌํŠธ๋ฆฌ, ์ƒŒ๋“œ๋ฐ•์‹ฑ, ๊ด€๋ฆฌํ˜• ์„ค์ •, ๊ตฌ์„ฑ ๋“ฑ Claude Code์˜ ๊ณ ๊ธ‰ ๊ธฐ๋Šฅ์— ๋Œ€ํ•œ ์ข…ํ•ฉ ๊ฐ€์ด๋“œ์ž…๋‹ˆ๋‹ค. + +## ๋ชฉ์ฐจ + +1. [๊ฐœ์š”](#๊ฐœ์š”) +2. [๊ธฐํš ๋ชจ๋“œ](#๊ธฐํš-๋ชจ๋“œ) +3. [์šธํŠธ๋ผํ”Œ๋žœ (ํด๋ผ์šฐ๋“œ ๊ธฐํš ์ดˆ์•ˆ ์ž‘์„ฑ)](#์šธํŠธ๋ผํ”Œ๋žœ-ํด๋ผ์šฐ๋“œ-๊ธฐํš-์ดˆ์•ˆ-์ž‘์„ฑ) +4. [ํ™•์žฅ๋œ ์‚ฌ๊ณ ](#ํ™•์žฅ๋œ-์‚ฌ๊ณ ) +5. [์ž๋™ ๋ชจ๋“œ](#์ž๋™-๋ชจ๋“œ) +6. [๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž‘์—…](#๋ฐฑ๊ทธ๋ผ์šด๋“œ-์ž‘์—…) +7. [๋ชจ๋‹ˆํ„ฐ ๋„๊ตฌ (์ด๋ฒคํŠธ ๊ธฐ๋ฐ˜ ์ŠคํŠธ๋ฆผ)](#๋ชจ๋‹ˆํ„ฐ-๋„๊ตฌ-์ด๋ฒคํŠธ-๊ธฐ๋ฐ˜-์ŠคํŠธ๋ฆผ) +8. [๋™์  ์›Œํฌํ”Œ๋กœ์šฐ](#๋™์ -์›Œํฌํ”Œ๋กœ์šฐ) +9. [์˜ˆ์•ฝ๋œ ์ž‘์—…](#์˜ˆ์•ฝ๋œ-์ž‘์—…) +10. [๊ถŒํ•œ ๋ชจ๋“œ](#๊ถŒํ•œ-๋ชจ๋“œ) +11. [ํ—ค๋“œ๋ฆฌ์Šค ๋ชจ๋“œ](#ํ—ค๋“œ๋ฆฌ์Šค-๋ชจ๋“œ) +12. [์„ธ์…˜ ๊ด€๋ฆฌ](#์„ธ์…˜-๊ด€๋ฆฌ) +13. [๋Œ€ํ™”ํ˜• ๊ธฐ๋Šฅ](#๋Œ€ํ™”ํ˜•-๊ธฐ๋Šฅ) +14. [TUI ๋ชจ๋“œ (์ „์ฒด ํ™”๋ฉด)](#tui-๋ชจ๋“œ-์ „์ฒด-ํ™”๋ฉด) +15. [์Œ์„ฑ ๋ฐ›์•„์“ฐ๊ธฐ](#์Œ์„ฑ-๋ฐ›์•„์“ฐ๊ธฐ) +16. [์ฑ„๋„](#์ฑ„๋„) +17. [Chrome ํ†ตํ•ฉ](#chrome-ํ†ตํ•ฉ) +18. [์›๊ฒฉ ์ œ์–ด](#์›๊ฒฉ-์ œ์–ด) +19. [์›น ์„ธ์…˜](#์›น-์„ธ์…˜) +20. [๋ฐ์Šคํฌํ†ฑ ์•ฑ](#๋ฐ์Šคํฌํ†ฑ-์•ฑ) +21. [์ž‘์—… ๋ชฉ๋ก](#์ž‘์—…-๋ชฉ๋ก) +22. [ํ”„๋กฌํ”„ํŠธ ์ œ์•ˆ](#ํ”„๋กฌํ”„ํŠธ-์ œ์•ˆ) +23. [Git ์›ŒํฌํŠธ๋ฆฌ](#git-์›ŒํฌํŠธ๋ฆฌ) +24. [์ƒŒ๋“œ๋ฐ•์‹ฑ](#์ƒŒ๋“œ๋ฐ•์‹ฑ) +25. [๊ด€๋ฆฌํ˜• ์„ค์ • (์—”ํ„ฐํ”„๋ผ์ด์ฆˆ)](#๊ด€๋ฆฌํ˜•-์„ค์ •-์—”ํ„ฐํ”„๋ผ์ด์ฆˆ) +26. [๊ตฌ์„ฑ ๋ฐ ์„ค์ •](#๊ตฌ์„ฑ-๋ฐ-์„ค์ •) +27. [์—์ด์ „ํŠธ ํŒ€](#์—์ด์ „ํŠธ-ํŒ€) +28. [๋ชจ๋ฒ” ์‚ฌ๋ก€](#๋ชจ๋ฒ”-์‚ฌ๋ก€) +29. [์ถ”๊ฐ€ ์ž๋ฃŒ](#์ถ”๊ฐ€-์ž๋ฃŒ) + +--- + +## ๊ฐœ์š” + +Claude Code์˜ ๊ณ ๊ธ‰ ๊ธฐ๋Šฅ์€ ๊ธฐํš, ์ถ”๋ก , ์ž๋™ํ™” ๋ฐ ์ œ์–ด ๋ฉ”์ปค๋‹ˆ์ฆ˜์„ ํ†ตํ•ด ํ•ต์‹ฌ ๊ธฐ๋Šฅ์„ ํ™•์žฅํ•ฉ๋‹ˆ๋‹ค. ์ด๋Ÿฌํ•œ ๊ธฐ๋Šฅ์€ ๋ณต์žกํ•œ ๊ฐœ๋ฐœ ์ž‘์—…, ์ฝ”๋“œ ๊ฒ€ํ† , ์ž๋™ํ™” ๋ฐ ๋‹ค์ค‘ ์„ธ์…˜ ๊ด€๋ฆฌ๋ฅผ ์œ„ํ•œ ์ •๊ตํ•œ ์›Œํฌํ”Œ๋กœ์šฐ๋ฅผ ๊ฐ€๋Šฅํ•˜๊ฒŒ ํ•ฉ๋‹ˆ๋‹ค. + +**์ฃผ์š” ๊ณ ๊ธ‰ ๊ธฐ๋Šฅ์€ ๋‹ค์Œ๊ณผ ๊ฐ™์Šต๋‹ˆ๋‹ค:** +- **๊ธฐํš ๋ชจ๋“œ**: ์ฝ”๋”ฉ ์ „์— ์ƒ์„ธํ•œ ๊ตฌํ˜„ ๊ณ„ํš ์ƒ์„ฑ +- **ํ™•์žฅ๋œ ์‚ฌ๊ณ **: ๋ณต์žกํ•œ ๋ฌธ์ œ์— ๋Œ€ํ•œ ์‹ฌ์ธต์ ์ธ ์ถ”๋ก  +- **์ž๋™ ๋ชจ๋“œ**: ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์•ˆ์ „ ๋ถ„๋ฅ˜๊ธฐ๊ฐ€ ๊ฐ ์ž‘์—… ์‹คํ–‰ ์ „์— ๊ฒ€ํ†  (์—ฐ๊ตฌ ๋ฏธ๋ฆฌ๋ณด๊ธฐ) +- **๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž‘์—…**: ๋Œ€ํ™”๋ฅผ ์ฐจ๋‹จํ•˜์ง€ ์•Š๊ณ  ๊ธด ์ž‘์—… ์‹คํ–‰ +- **๊ถŒํ•œ ๋ชจ๋“œ**: Claude๊ฐ€ ์ˆ˜ํ–‰ํ•  ์ˆ˜ ์žˆ๋Š” ์ž‘์—… ์ œ์–ด (`default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions`) +- **์ธ์‡„ ๋ชจ๋“œ**: ์ž๋™ํ™” ๋ฐ CI/CD๋ฅผ ์œ„ํ•ด Claude Code๋ฅผ ๋น„๋Œ€ํ™”ํ˜•์œผ๋กœ ์‹คํ–‰ (`claude -p`) +- **์„ธ์…˜ ๊ด€๋ฆฌ**: ์—ฌ๋Ÿฌ ์ž‘์—… ์„ธ์…˜ ๊ด€๋ฆฌ +- **๋Œ€ํ™”ํ˜• ๊ธฐ๋Šฅ**: ํ‚ค๋ณด๋“œ ๋‹จ์ถ•ํ‚ค, ์—ฌ๋Ÿฌ ์ค„ ์ž…๋ ฅ, ๋ช…๋ น ๊ธฐ๋ก +- **์Œ์„ฑ ๋ฐ›์•„์“ฐ๊ธฐ**: 20๊ฐœ ์–ธ์–ด STT๋ฅผ ์ง€์›ํ•˜๋Š” ํ‘ธ์‹œํˆฌํ†ก ์Œ์„ฑ ์ž…๋ ฅ +- **์ฑ„๋„**: MCP ์„œ๋ฒ„๊ฐ€ ์‹คํ–‰ ์ค‘์ธ ์„ธ์…˜์œผ๋กœ ๋ฉ”์‹œ์ง€๋ฅผ ํ‘ธ์‹œ (์—ฐ๊ตฌ ๋ฏธ๋ฆฌ๋ณด๊ธฐ) +- **์›๊ฒฉ ์ œ์–ด**: Claude.ai ๋˜๋Š” Claude ์•ฑ์—์„œ Claude Code ์ œ์–ด +- **์›น ์„ธ์…˜**: claude.ai/code์—์„œ ๋ธŒ๋ผ์šฐ์ € ๋‚ด Claude Code ์‹คํ–‰ +- **๋ฐ์Šคํฌํ†ฑ ์•ฑ**: ์‹œ๊ฐ์  ์ฐจ์ด ๊ฒ€ํ†  ๋ฐ ์—ฌ๋Ÿฌ ์„ธ์…˜์„ ์œ„ํ•œ ๋…๋ฆฝํ˜• ์•ฑ +- **์ž‘์—… ๋ชฉ๋ก**: ์ปจํ…์ŠคํŠธ ์••์ถ• ์ „๋ฐ˜์— ๊ฑธ์นœ ์˜๊ตฌ์ ์ธ ์ž‘์—… ์ถ”์  +- **ํ”„๋กฌํ”„ํŠธ ์ œ์•ˆ**: ์ปจํ…์ŠคํŠธ ๊ธฐ๋ฐ˜์˜ ์Šค๋งˆํŠธ ๋ช…๋ น ์ œ์•ˆ +- **Git ์›ŒํฌํŠธ๋ฆฌ**: ๋ณ‘๋ ฌ ์ž‘์—…์„ ์œ„ํ•œ ๊ฒฉ๋ฆฌ๋œ ์›ŒํฌํŠธ๋ฆฌ ๋ธŒ๋žœ์น˜ +- **์ƒŒ๋“œ๋ฐ•์‹ฑ**: OS ์ˆ˜์ค€์˜ ํŒŒ์ผ ์‹œ์Šคํ…œ ๋ฐ ๋„คํŠธ์›Œํฌ ๊ฒฉ๋ฆฌ +- **๊ด€๋ฆฌํ˜• ์„ค์ •**: plist, ๋ ˆ์ง€์ŠคํŠธ๋ฆฌ ๋˜๋Š” ๊ด€๋ฆฌํ˜• ํŒŒ์ผ์„ ํ†ตํ•œ ์—”ํ„ฐํ”„๋ผ์ด์ฆˆ ๋ฐฐํฌ +- **๊ตฌ์„ฑ**: JSON ๊ตฌ์„ฑ ํŒŒ์ผ๋กœ ๋™์ž‘ ์‚ฌ์šฉ์ž ์ •์˜ + +--- + +## ๊ธฐํš ๋ชจ๋“œ + +๊ธฐํš ๋ชจ๋“œ๋ฅผ ์‚ฌ์šฉํ•˜๋ฉด Claude๊ฐ€ ๊ตฌํ˜„ ์ „์— ๋ณต์žกํ•œ ์ž‘์—…์„ ์‹ ์ค‘ํ•˜๊ฒŒ ๊ณ ๋ คํ•˜์—ฌ ๊ฒ€ํ† ํ•˜๊ณ  ์Šน์ธํ•  ์ˆ˜ ์žˆ๋Š” ์ƒ์„ธํ•œ ๊ณ„ํš์„ ๋งŒ๋“ค ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +### ๊ธฐํš ๋ชจ๋“œ๋ž€ ๋ฌด์—‡์ž…๋‹ˆ๊นŒ? + +๊ธฐํš ๋ชจ๋“œ๋Š” ๋‘ ๋‹จ๊ณ„๋กœ ๊ตฌ์„ฑ๋œ ์ ‘๊ทผ ๋ฐฉ์‹์ž…๋‹ˆ๋‹ค: +1. **๊ธฐํš ๋‹จ๊ณ„**: Claude๊ฐ€ ์ž‘์—…์„ ๋ถ„์„ํ•˜๊ณ  ์ƒ์„ธํ•œ ๊ตฌํ˜„ ๊ณ„ํš์„ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. +2. **๊ตฌํ˜„ ๋‹จ๊ณ„**: ์Šน์ธ ํ›„ Claude๊ฐ€ ๊ณ„ํš์„ ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค. + +### ๊ธฐํš ๋ชจ๋“œ ์‚ฌ์šฉ ์‹œ์  + +โœ… ๊ธฐํš ๋ชจ๋“œ๋ฅผ ์‚ฌ์šฉํ•˜๋Š” ๊ฒฝ์šฐ: +- ๋ณต์žกํ•œ ๋‹ค์ค‘ ํŒŒ์ผ ๋ฆฌํŒฉํ† ๋ง +- ์ƒˆ๋กœ์šด ๊ธฐ๋Šฅ ๊ตฌํ˜„ +- ์•„ํ‚คํ…์ฒ˜ ๋ณ€๊ฒฝ +- ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ +- ์ฃผ์š” API ์žฌ์„ค๊ณ„ + +โŒ ๊ธฐํš ๋ชจ๋“œ๋ฅผ ์‚ฌ์šฉํ•˜์ง€ ์•Š๋Š” ๊ฒฝ์šฐ: +- ๊ฐ„๋‹จํ•œ ๋ฒ„๊ทธ ์ˆ˜์ • +- ํ˜•์‹ ๋ณ€๊ฒฝ +- ๋‹จ์ผ ํŒŒ์ผ ํŽธ์ง‘ +- ๋น ๋ฅธ ์ฟผ๋ฆฌ + +### ๊ธฐํš ๋ชจ๋“œ ํ™œ์„ฑํ™” + +**์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด**: +```bash +/plan Implement user authentication system +``` + +**CLI ํ”Œ๋ž˜๊ทธ**: +```bash +claude --permission-mode plan +``` + +**๊ธฐ๋ณธ๊ฐ’์œผ๋กœ ์„ค์ •**: +```json +{ + "permissions": { + "defaultMode": "plan" + } +} +``` + +**ํ‚ค๋ณด๋“œ ๋‹จ์ถ•ํ‚ค**: +- `Shift + Tab` - ๊ถŒํ•œ ๋ชจ๋“œ ์ „ํ™˜ (plan ํฌํ•จ) +- `Alt + M` - ๊ถŒํ•œ ๋ชจ๋“œ ์ „ํ™˜ (Windows/Linux) + +### ๊ธฐํš ๋ชจ๋“œ์˜ ์ด์  + +- **๊ตฌ์กฐํ™”๋œ ๊ตฌํ˜„ ์ ‘๊ทผ ๋ฐฉ์‹**: ๊ตฌํ˜„ ๋‹จ๊ณ„์˜ ์ƒ์„ธํ•œ ์„ธ๋ถ„ํ™” +- **๊ฒ€ํ†  ๋ฐ ์Šน์ธ**: ์‹คํ–‰ ์ „์— ๊ณ„ํš์„ ์Šน์ธํ•˜๊ฑฐ๋‚˜ ์กฐ์ • +- **์œ„ํ—˜ ์‹๋ณ„**: ๊ตฌํ˜„ ์ „์— ์ž ์žฌ์  ๋ฌธ์ œ ์‹๋ณ„ +- **๋ช…ํ™•ํ•œ ๋‹จ๊ณ„**: ์ฒด๊ณ„์ ์ธ ๊ตฌํ˜„ ๋‹จ๊ณ„ ๋ฐ ๋งˆ์ผ์Šคํ†ค + +### ์˜ˆ์‹œ: ๊ธฐ๋Šฅ ๊ตฌํ˜„ + +``` +User: /plan Add a real-time notification system + +Claude: ์‹ค์‹œ๊ฐ„ ์•Œ๋ฆผ ์‹œ์Šคํ…œ ๊ตฌํ˜„์„ ์œ„ํ•œ ๊ณ„ํš์„ ์ƒ์„ฑํ•˜๊ฒ ์Šต๋‹ˆ๋‹ค. + +## Implementation Plan + +### Phase 1: Infrastructure Setup +1. Install WebSocket libraries (socket.io) +2. Set up WebSocket server +3. Configure connection management + +### Phase 2: Backend Implementation +4. Create notification service +5. Implement notification queue +6. Add database schema for notifications +7. Create API endpoints + +### Phase 3: Frontend Integration +8. Set up WebSocket client +9. Create notification UI components +10. Implement notification state management +11. Add notification permissions + +### Phase 4: Testing & Deployment +12. Write unit tests +13. Write integration tests +14. Update documentation +15. Deploy to staging + +Estimated time: 3-4 hours +Files to modify: 12 +New files to create: 8 + +Ready to proceed? (yes/no/modify plan) + +User: yes + +Claude: [๊ณ„ํš์— ๋”ฐ๋ผ ๊ตฌํ˜„์„ ์‹œ์ž‘ํ•ฉ๋‹ˆ๋‹ค] +``` + +### ๊ณ„ํš ์ˆ˜์ • + +``` +User: Modify the plan - skip the queue for now, we'll add it later + +Claude: ์—…๋ฐ์ดํŠธ๋œ ๊ณ„ํš: +[ํ๊ฐ€ ์ œ๊ฑฐ๋œ ์ˆ˜์ •๋œ ๊ณ„ํš์„ ๋ณด์—ฌ์ค๋‹ˆ๋‹ค] + +User: Looks good, proceed + +Claude: [์ˆ˜์ •๋œ ๊ณ„ํš์„ ๊ตฌํ˜„ํ•ฉ๋‹ˆ๋‹ค] +``` + +### ๊ธฐํš ๋ชจ๋“œ ๊ตฌ์„ฑ + +๊ธฐํš ๋ชจ๋“œ๋Š” CLI ํ”Œ๋ž˜๊ทธ ๋˜๋Š” ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด๋ฅผ ํ†ตํ•ด ํ™œ์„ฑํ™”๋ฉ๋‹ˆ๋‹ค: + +```bash +# Activate plan mode via CLI +claude --permission-mode plan + +# Or use the /plan slash command inside the REPL +/plan Implement user authentication system +``` + +**๊ธฐํš์šฉ ๋ชจ๋ธ ๋ณ„์นญ**: Opus๋ฅผ ๊ธฐํš์—, Sonnet์„ ์‹คํ–‰์— ์‚ฌ์šฉํ•˜๋ ค๋ฉด `opusplan`์„ ๋ชจ๋ธ ๋ณ„์นญ์œผ๋กœ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค: + +```bash +claude --model opusplan "design and implement the new API" +``` + +**์™ธ๋ถ€์—์„œ ๊ณ„ํš ํŽธ์ง‘**: `Ctrl+G`๋ฅผ ๋ˆŒ๋Ÿฌ ์™ธ๋ถ€ ํŽธ์ง‘๊ธฐ์—์„œ ํ˜„์žฌ ๊ณ„ํš์„ ์—ด๊ณ  ์ƒ์„ธํ•˜๊ฒŒ ์ˆ˜์ •ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +> **v2.1.112 ์—…๋ฐ์ดํŠธ**: ์ด์ œ ๊ณ„ํš ํŒŒ์ผ์€ ๋ฌด์ž‘์œ„ ๋‹จ์–ด ๋Œ€์‹  ์ƒ์„ฑ๋œ ํ”„๋กฌํ”„ํŠธ์˜ ์ด๋ฆ„์„ ๋”ฐ์„œ ๋ช…๋ช…๋˜๋ฏ€๋กœ, ๋” ์‰ฝ๊ฒŒ ์ฐพ์•„๋ณด๊ณ  ์žฌ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +> **v2.1.136 ์—…๋ฐ์ดํŠธ โ€” ๊ธฐํš ๋ชจ๋“œ ์“ฐ๊ธฐ ๋ธ”๋ก์€ ๋ฌด์กฐ๊ฑด์ ์ž…๋‹ˆ๋‹ค**: ๊ธฐํš ๋ชจ๋“œ๋Š” ์ด์ œ `permissions.allow`์— ์ผ์น˜ํ•˜๋Š” `Edit(...)` ๊ทœ์น™์ด ์žˆ๋Š” ๊ฒฝ์šฐ๋ฅผ ํฌํ•จํ•˜์—ฌ ๋ชจ๋“  ํŒŒ์ผ ์“ฐ๊ธฐ๋ฅผ ์ฐจ๋‹จํ•ฉ๋‹ˆ๋‹ค. ์ด์ „์—๋Š” ๊ด€๋Œ€ํ•œ `Edit(...)` ๊ทœ์น™์ด ๊ธฐํš ๋ชจ๋“œ์—์„œ ์“ฐ๊ธฐ๋ฅผ ํ—ˆ์šฉํ•  ์ˆ˜ ์žˆ์—ˆ์ง€๋งŒ, ํ•ด๋‹น ์šฐํšŒ ๊ฒฝ๋กœ๋Š” ํ์‡„๋˜์—ˆ์Šต๋‹ˆ๋‹ค. ์›Œํฌํ”Œ๋กœ์šฐ๊ฐ€ ์ด์ „ ๋™์ž‘์— ์˜์กดํ•˜๋Š” ๊ฒฝ์šฐ, ํŽธ์ง‘ํ•˜๊ธฐ ์ „์— ๊ธฐํš ๋ชจ๋“œ๋ฅผ ์ข…๋ฃŒํ•˜์‹ญ์‹œ์˜ค (`Shift+Tab`). + +--- + +## ์šธํŠธ๋ผํ”Œ๋žœ (ํด๋ผ์šฐ๋“œ ๊ธฐํš ์ดˆ์•ˆ ์ž‘์„ฑ) + +> **v2.1.101์— ์ƒˆ๋กœ ์ถ”๊ฐ€**: ์šธํŠธ๋ผํ”Œ๋žœ์€ ์ด์ œ ์ฒ˜์Œ ํ˜ธ์ถœํ•  ๋•Œ ์›น ํด๋ผ์šฐ๋“œ ํ™˜๊ฒฝ์— Claude Code๋ฅผ ์ž๋™์œผ๋กœ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. ์ˆ˜๋™ ์„ค์ •์ด ํ•„์š” ์—†๊ณ , ์ดˆ์•ˆ ์ž‘์„ฑ์„ ์‹œ์ž‘ํ•˜๊ธฐ ์ „์— ์ปจํ…Œ์ด๋„ˆ๊ฐ€ ์ค€๋น„๋  ๋•Œ๊นŒ์ง€ ๊ธฐ๋‹ค๋ฆด ํ•„์š”๊ฐ€ ์—†์Šต๋‹ˆ๋‹ค. + +> **์ฐธ๊ณ **: ์šธํŠธ๋ผํ”Œ๋žœ์€ ์—ฐ๊ตฌ ๋ฏธ๋ฆฌ๋ณด๊ธฐ ๊ธฐ๋Šฅ์ด๋ฉฐ Claude Code v2.1.91 ์ด์ƒ์ด ํ•„์š”ํ•ฉ๋‹ˆ๋‹ค. + +`/ultraplan`์€ ๋กœ์ปฌ CLI์˜ ๊ธฐํš ์ž‘์—…์„ ๊ธฐํš ๋ชจ๋“œ๋กœ ์‹คํ–‰๋˜๋Š” ์›น ์„ธ์…˜์˜ Claude Code๋กœ ๋„˜๊น๋‹ˆ๋‹ค. Claude๋Š” ํด๋ผ์šฐ๋“œ์—์„œ ๊ณ„ํš ์ดˆ์•ˆ์„ ์ž‘์„ฑํ•˜๋Š” ๋™์•ˆ ํ„ฐ๋ฏธ๋„์€ ๋‹ค๋ฅธ ์ž‘์—…์„ ์œ„ํ•ด ์ž์œ ๋กญ๊ฒŒ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ๊ทธ๋Ÿฐ ๋‹ค์Œ ๋ธŒ๋ผ์šฐ์ €์—์„œ ์ดˆ์•ˆ์„ ๊ฒ€ํ† ํ•˜๊ณ  ๋™์ผํ•œ ํด๋ผ์šฐ๋“œ ์„ธ์…˜์—์„œ ์‹คํ–‰ํ•˜๊ฑฐ๋‚˜ ํ„ฐ๋ฏธ๋„๋กœ ๋‹ค์‹œ ์ „์†กํ• ์ง€ ์„ ํƒํ•ฉ๋‹ˆ๋‹ค. + +### ์šธํŠธ๋ผํ”Œ๋žœ ์‚ฌ์šฉ ์‹œ์  + +- ํ„ฐ๋ฏธ๋„๋ณด๋‹ค ๋” ํ’๋ถ€ํ•œ ๊ฒ€ํ†  ํ™”๋ฉด (์ธ๋ผ์ธ ์ฃผ์„, ์ด๋ชจ์ง€ ๋ฐ˜์‘, ๊ฐœ์š” ์‚ฌ์ด๋“œ๋ฐ”, ์˜๊ตฌ ๊ธฐ๋ก)์„ ์›ํ•  ๋•Œ. +- ๋กœ์ปฌ์—์„œ ์ฝ”๋”ฉ์„ ๊ณ„์†ํ•˜๋Š” ๋™์•ˆ ํ•ธ์ฆˆํ”„๋ฆฌ ์ดˆ์•ˆ ์ž‘์„ฑ์„ ์›ํ•  ๋•Œ โ€” ํด๋ผ์šฐ๋“œ ์„ธ์…˜์€ ์ €์žฅ์†Œ๋ฅผ ์กฐ์‚ฌํ•˜๊ณ  CLI๋ฅผ ์ฐจ๋‹จํ•˜์ง€ ์•Š๊ณ  ๊ณ„ํš์„ ์ž‘์„ฑํ•ฉ๋‹ˆ๋‹ค. +- ์‹คํ–‰ ์ „์— ์ดํ•ด ๊ด€๊ณ„์ž ๊ฒ€ํ† ๊ฐ€ ํ•„์š”ํ•œ ๊ณ„ํš โ€” ๊ณต์œ  ๊ฐ€๋Šฅํ•œ ์›น URL์ด ํ„ฐ๋ฏธ๋„ ์Šคํฌ๋กค๋ฐฑ์„ ๋ถ™์—ฌ๋„ฃ๋Š” ๊ฒƒ๋ณด๋‹ค ๋‚ซ์Šต๋‹ˆ๋‹ค. + +### ์š”๊ตฌ ์‚ฌํ•ญ + +- Claude Code on the web ๊ณ„์ •. +- GitHub ์ €์žฅ์†Œ (ํด๋ผ์šฐ๋“œ ์„ธ์…˜์€ ์‹ค์ œ ์ฝ”๋“œ์— ๋Œ€ํ•ด ์ดˆ์•ˆ์„ ์ž‘์„ฑํ•˜๊ธฐ ์œ„ํ•ด ์ €์žฅ์†Œ๋ฅผ ๋ณต์ œํ•ฉ๋‹ˆ๋‹ค). +- Amazon Bedrock, Google Cloud Vertex AI ๋˜๋Š” Microsoft Foundry์—์„œ๋Š” **์‚ฌ์šฉํ•  ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค**. + +### ์„ธ ๊ฐ€์ง€ ์‹คํ–‰ ๋ฐฉ๋ฒ• + +- **๋ช…๋ น์–ด**: `/ultraplan ` โ€” ๋ช…์‹œ์  ํ˜ธ์ถœ. +- **ํ‚ค์›Œ๋“œ**: ์ผ๋ฐ˜ ํ”„๋กฌํ”„ํŠธ์— `ultraplan` ๋‹จ์–ด๋ฅผ ํฌํ•จํ•˜๋ฉด Claude๊ฐ€ ์š”์ฒญ์„ ํด๋ผ์šฐ๋“œ๋กœ ๋ผ์šฐํŒ…ํ•ฉ๋‹ˆ๋‹ค. +- **๋กœ์ปฌ ๊ณ„ํš์—์„œ**: Claude๊ฐ€ ๋กœ์ปฌ์—์„œ ๊ณ„ํš์„ ์™„๋ฃŒํ•œ ํ›„ ์Šน์ธ ๋Œ€ํ™” ์ƒ์ž์—์„œ "์•„๋‹ˆ์š”, Claude Code on the web์—์„œ Ultraplan์œผ๋กœ ์ •๊ตํ™”"๋ฅผ ์„ ํƒํ•˜์—ฌ ๋” ์‹ฌ์ธต์ ์ธ ์กฐ์‚ฌ๋ฅผ ์œ„ํ•ด ์ดˆ์•ˆ์„ ๋„˜๊น๋‹ˆ๋‹ค. + +### ์‚ฌ์šฉ ์˜ˆ์‹œ + +```bash +/ultraplan migrate the auth service from sessions to JWTs +``` + +Claude๋Š” ์Šน์ธํ•˜๊ณ  ํด๋ผ์šฐ๋“œ ํ™˜๊ฒฝ์„ ์‹œ์ž‘ํ•œ ๋‹ค์Œ (v2.1.101+์—์„œ ์ฒ˜์Œ ์‹คํ–‰ ์‹œ ์ž๋™ ์ƒ์„ฑ), ๋ธŒ๋ผ์šฐ์ €์—์„œ ์—ด ์ˆ˜ ์žˆ๋Š” ์„ธ์…˜ ๋งํฌ๋ฅผ ๋ฐ˜ํ™˜ํ•ฉ๋‹ˆ๋‹ค. + +### ์ƒํƒœ ํ‘œ์‹œ๊ธฐ + +| ์ƒํƒœ | ์˜๋ฏธ | +|---|---| +| `โ—‡ ultraplan` | Claude๊ฐ€ ์ฝ”๋“œ๋ฒ ์ด์Šค๋ฅผ ์กฐ์‚ฌํ•˜๊ณ  ๊ณ„ํš ์ดˆ์•ˆ์„ ์ž‘์„ฑ ์ค‘์ž…๋‹ˆ๋‹ค | +| `โ—‡ ultraplan needs your input` | Claude๊ฐ€ ๋ช…ํ™•ํ•œ ์งˆ๋ฌธ์„ ๊ฐ€์ง€๊ณ  ์žˆ์Šต๋‹ˆ๋‹ค. ์„ธ์…˜ ๋งํฌ๋ฅผ ์—ด์–ด ์‘๋‹ตํ•˜์‹ญ์‹œ์˜ค | +| `โ—† ultraplan ready` | ๋ธŒ๋ผ์šฐ์ €์—์„œ ๊ณ„ํš์„ ๊ฒ€ํ† ํ•  ์ค€๋น„๊ฐ€ ๋˜์—ˆ์Šต๋‹ˆ๋‹ค | + +### ์‹คํ–‰ ์˜ต์…˜ + +๊ณ„ํš์ด ์ค€๋น„๋˜๋ฉด ๋‘ ๊ฐ€์ง€ ์‹คํ–‰ ๊ฒฝ๋กœ๊ฐ€ ์žˆ์Šต๋‹ˆ๋‹ค. ๋ธŒ๋ผ์šฐ์ €์—์„œ ๊ณ„ํš์„ ์Šน์ธํ•˜์—ฌ ๋™์ผํ•œ ํด๋ผ์šฐ๋“œ ์„ธ์…˜์—์„œ ์‹คํ–‰ํ•˜๋ฉด Claude๊ฐ€ ์›๊ฒฉ์œผ๋กœ ๋ณ€๊ฒฝ ์‚ฌํ•ญ์„ ๊ตฌํ˜„ํ•˜๊ณ  ์›น UI์—์„œ Pull Request๋ฅผ ์—ฝ๋‹ˆ๋‹ค. ๋˜๋Š” "๊ณ„ํš ์Šน์ธ ๋ฐ ํ„ฐ๋ฏธ๋„๋กœ ํ…”๋ ˆํฌํŠธ"๋ฅผ ์„ ํƒํ•˜์—ฌ ๋กœ์ปฌ์—์„œ ๊ตฌํ˜„ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ํ„ฐ๋ฏธ๋„ ํ…”๋ ˆํฌํŠธ ๋Œ€ํ™” ์ƒ์ž๋Š” ์„ธ ๊ฐ€์ง€ ์„ ํƒ์ง€๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค: + +- **์—ฌ๊ธฐ์„œ ๊ตฌํ˜„** โ€” ํ˜„์žฌ ํ„ฐ๋ฏธ๋„ ์„ธ์…˜์—์„œ ์Šน์ธ๋œ ๊ณ„ํš์„ ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค. +- **์ƒˆ ์„ธ์…˜ ์‹œ์ž‘** โ€” ๋™์ผํ•œ ์ž‘์—… ๋””๋ ‰ํ† ๋ฆฌ์—์„œ ์ƒˆ ์„ธ์…˜์„ ์—ด๊ณ  ๊ฑฐ๊ธฐ์„œ ๊ตฌํ˜„ํ•ฉ๋‹ˆ๋‹ค. +- **์ทจ์†Œ** โ€” ๊ณ„ํš์„ ํŒŒ์ผ๋กœ ์ €์žฅํ•˜์—ฌ ๋‚˜์ค‘์— ๋‹ค์‹œ ์‹œ์ž‘ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +> **๊ฒฝ๊ณ **: ์šธํŠธ๋ผํ”Œ๋žœ์ด ์‹œ์ž‘๋˜๋ฉด ์›๊ฒฉ ์ œ์–ด๊ฐ€ ์—ฐ๊ฒฐ ํ•ด์ œ๋ฉ๋‹ˆ๋‹ค. ๋‘ ๊ธฐ๋Šฅ ๋ชจ๋‘ claude.ai/code ์ธํ„ฐํŽ˜์ด์Šค๋ฅผ ๊ณต์œ ํ•˜๋ฏ€๋กœ ํ•œ ๋ฒˆ์— ํ•˜๋‚˜๋งŒ ํ™œ์„ฑํ™”๋  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +--- + +## ํ™•์žฅ๋œ ์‚ฌ๊ณ  + +ํ™•์žฅ๋œ ์‚ฌ๊ณ ๋Š” Claude๊ฐ€ ์†”๋ฃจ์…˜์„ ์ œ๊ณตํ•˜๊ธฐ ์ „์— ๋ณต์žกํ•œ ๋ฌธ์ œ์— ๋Œ€ํ•ด ๋” ๋งŽ์€ ์‹œ๊ฐ„์„ ์ถ”๋ก ํ•˜๋„๋ก ํ—ˆ์šฉํ•ฉ๋‹ˆ๋‹ค. + +### ํ™•์žฅ๋œ ์‚ฌ๊ณ ๋ž€ ๋ฌด์—‡์ž…๋‹ˆ๊นŒ? + +ํ™•์žฅ๋œ ์‚ฌ๊ณ ๋Š” Claude๊ฐ€ ๋‹ค์Œ์„ ์ˆ˜ํ–‰ํ•˜๋Š” ์‹ ์ค‘ํ•œ ๋‹จ๊ณ„๋ณ„ ์ถ”๋ก  ํ”„๋กœ์„ธ์Šค์ž…๋‹ˆ๋‹ค: +- ๋ณต์žกํ•œ ๋ฌธ์ œ๋ฅผ ๋ถ„ํ•ดํ•ฉ๋‹ˆ๋‹ค +- ์—ฌ๋Ÿฌ ์ ‘๊ทผ ๋ฐฉ์‹์„ ๊ณ ๋ คํ•ฉ๋‹ˆ๋‹ค +- ์žฅ๋‹จ์ ์„ ํ‰๊ฐ€ํ•ฉ๋‹ˆ๋‹ค +- ์—ฃ์ง€ ์ผ€์ด์Šค๋ฅผ ํ†ตํ•ด ์ถ”๋ก ํ•ฉ๋‹ˆ๋‹ค + +### ํ™•์žฅ๋œ ์‚ฌ๊ณ  ํ™œ์„ฑํ™” + +**ํ‚ค๋ณด๋“œ ๋‹จ์ถ•ํ‚ค**: +- `Option + T` (macOS) / `Alt + T` (Windows/Linux) - ํ™•์žฅ๋œ ์‚ฌ๊ณ  ์ „ํ™˜ + +**์ž๋™ ํ™œ์„ฑํ™”**: +- ๋ชจ๋“  ๋ชจ๋ธ (Opus 4.8, Opus 4.7, Sonnet 4.6, Haiku 4.5)์— ๊ธฐ๋ณธ์ ์œผ๋กœ ํ™œ์„ฑํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- Opus 4.8: ๋…ธ๋ ฅ ์ˆ˜์ค€์ด ์žˆ๋Š” ์ ์‘ํ˜• ์ถ”๋ก : `low` (โ—‹), `medium` (โ—), `high` (โ—), `xhigh`, `max`. ๊ธฐ๋ณธ๊ฐ’์€ Opus 4.8 (v2.1.154), Opus 4.6, Sonnet 4.6์—์„œ๋Š” `high`์ด๊ณ , Opus 4.7์—์„œ๋Š” `xhigh`์ž…๋‹ˆ๋‹ค. `xhigh`๋Š” Opus 4.8 ๋ฐ Opus 4.7์—์„œ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค (Opus 4.6 / Sonnet 4.6์—์„œ๋Š” `high`๋กœ ๋Œ€์ฒด๋ฉ๋‹ˆ๋‹ค). `max`๋Š” Opus 4.8/4.7/4.6 ๋ฐ Sonnet 4.6์—์„œ ์ž‘๋™ํ•ฉ๋‹ˆ๋‹ค (์„ธ์…˜ ์ „์šฉ). Haiku 4.5์—๋Š” ๋…ธ๋ ฅ ์ˆ˜์ค€์ด ์—†์Šต๋‹ˆ๋‹ค. Opus 4.8 ๋ฐ Opus 4.7์€ 1M ํ† ํฐ์˜ ๊ธฐ๋ณธ ์ปจํ…์ŠคํŠธ ์ฐฝ์„ ๊ฐ€์ง‘๋‹ˆ๋‹ค (1M ์ปจํ…์ŠคํŠธ ์ˆ˜์ •์€ v2.1.117์— ์ ์šฉ๋จ โ€” ์ด์ „์—๋Š” `/context`๊ฐ€ Opus 4.7์„ 200K ์ฐฝ์— ๋Œ€ํ•ด ์ž˜๋ชป ๊ณ„์‚ฐํ•˜์—ฌ ์กฐ๊ธฐ ์ž๋™ ์••์ถ•์„ ํŠธ๋ฆฌ๊ฑฐํ–ˆ์Šต๋‹ˆ๋‹ค). v2.1.129๋ถ€ํ„ฐ `/context`๋Š” UI ๋‚ด์—์„œ๋งŒ ์‹œ๊ฐํ™”๋ฅผ ํ‘œ์‹œํ•ฉ๋‹ˆ๋‹ค. ASCII ์‹œ๊ฐํ™”๋Š” ๋” ์ด์ƒ ๋Œ€ํ™” ์ปจํ…์ŠคํŠธ๋กœ ์œ ์ถœ๋˜์ง€ ์•Š์œผ๋ฏ€๋กœ (ํ˜ธ์ถœ๋‹น ์•ฝ 1.6k ํ† ํฐ ์ ˆ์•ฝ), `/context`๋Š” ์ž์œ ๋กญ๊ฒŒ ํ˜ธ์ถœํ•ด๋„ ์•ˆ์ „ํ•ฉ๋‹ˆ๋‹ค. +- Opus 4.6 / Sonnet 4.6์˜ Pro/Max ๊ตฌ๋…์ž: v2.1.117์—์„œ ๊ธฐ๋ณธ ๋…ธ๋ ฅ ์ˆ˜์ค€์ด `medium`์—์„œ `high`๋กœ ์ƒํ–ฅ ์กฐ์ •๋˜์—ˆ์Šต๋‹ˆ๋‹ค. +- ๋‹ค๋ฅธ ๋ชจ๋ธ: ์ตœ๋Œ€ 31,999 ํ† ํฐ์˜ ๊ณ ์ • ์˜ˆ์‚ฐ + +**๊ตฌ์„ฑ ๋ฐฉ๋ฒ•**: +- ์ „ํ™˜: `Alt+T` / `Option+T`, ๋˜๋Š” `/config`๋ฅผ ํ†ตํ•ด +- ์ถ”๋ก  ๋ณด๊ธฐ: `Ctrl+O` (์ž์„ธํ•œ ๋ชจ๋“œ) +- ๋…ธ๋ ฅ ์„ค์ •: `/effort` ๋ช…๋ น์–ด ๋˜๋Š” `--effort` ํ”Œ๋ž˜๊ทธ + +**์‚ฌ์šฉ์ž ์ง€์ • ์˜ˆ์‚ฐ**: +```bash +export MAX_THINKING_TOKENS=1024 +``` + +**๋…ธ๋ ฅ ์ˆ˜์ค€** (Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 4.6์—์„œ ์ง€์› โ€” Haiku 4.5 ์ œ์™ธ): +```bash +export CLAUDE_CODE_EFFORT_LEVEL=high # low (โ—‹), medium (โ—), high (โ—), xhigh (Opus 4.8/4.7), or max โ€” default is high on Opus 4.8 +``` + +**CLI ํ”Œ๋ž˜๊ทธ**: +```bash +claude --effort high "complex architectural review" +``` + +**์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด**: +``` +/effort high +``` + +> **์ฐธ๊ณ :** ํ”„๋กฌํ”„ํŠธ์˜ "ultrathink" ํ‚ค์›Œ๋“œ๋Š” ์‹ฌ์ธต ์ถ”๋ก  ๋ชจ๋“œ๋ฅผ ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค. ๋…ธ๋ ฅ ์ˆ˜์ค€ `low`, `medium`, `high`, `max`๋Š” Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 4.6์—์„œ ์ง€์›๋ฉ๋‹ˆ๋‹ค (Haiku 4.5๋Š” ์ง€์›ํ•˜์ง€ ์•Š์Œ). `xhigh`๋Š” Opus 4.8 ๋ฐ Opus 4.7์—์„œ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ๊ธฐ๋ณธ ๋…ธ๋ ฅ ์ˆ˜์ค€์€ Opus 4.8 (๋ฐ Opus 4.6 / Sonnet 4.6)์—์„œ `high`์ด๊ณ  Opus 4.7์—์„œ `xhigh`์ž…๋‹ˆ๋‹ค. `/effort` ๋ฉ”๋‰ด๋Š” `ultracode`๋„ ์ œ๊ณตํ•˜๋Š”๋ฐ, ์ด๋Š” ๋ชจ๋ธ ๋…ธ๋ ฅ ์ˆ˜์ค€์ด **์•„๋‹ˆ๋ฉฐ** `xhigh`๋ฅผ ๋ณด๋‚ด๊ณ  Claude๊ฐ€ ๋™์  ์›Œํฌํ”Œ๋กœ์šฐ๋ฅผ ์กฐ์œจํ•˜๋„๋ก ํ•ฉ๋‹ˆ๋‹ค (์„ธ์…˜ ์ „์šฉ). + +### ํ™•์žฅ๋œ ์‚ฌ๊ณ ์˜ ์ด์  + +- **์‹ฌ์ธต ์ถ”๋ก **: ๋ณต์žกํ•œ ๋ฌธ์ œ์— ๋Œ€ํ•ด ๋” ๋งŽ์€ ์‹œ๊ฐ„์„ ํ• ์• ํ•˜์—ฌ ์ƒ๊ฐ +- **๋” ๋‚˜์€ ์•„ํ‚คํ…์ฒ˜ ๊ฒฐ์ •**: ํฌ๊ด„์ ์ธ ํ‰๊ฐ€๋ฅผ ํ†ตํ•ด ์ •๋ณด์— ์ž…๊ฐํ•œ ์„ ํƒ +- **์—ฃ์ง€ ์ผ€์ด์Šค ๊ณ ๋ ค**: ์ž ์žฌ์  ๋ฌธ์ œ ๋ฐ ์‹œ๋‚˜๋ฆฌ์˜ค์— ๋Œ€ํ•œ ์‹ฌ์ธต์  ์‚ฌ๊ณ  +- **์ฒ ์ €ํ•œ ๋ถ„์„**: ๋ณต์žกํ•œ ๋ฌธ์ œ ํ•ด๊ฒฐ์„ ์œ„ํ•œ ๊ตฌ์กฐํ™”๋œ ์ ‘๊ทผ ๋ฐฉ์‹ + +### ์˜ˆ์‹œ: ์•„ํ‚คํ…์ฒ˜ ๊ฒฐ์ • + +``` +User: ultrathink Should we use microservices or a monolith for our e-commerce platform? + +Claude: ์ด ์•„ํ‚คํ…์ฒ˜ ๊ฒฐ์ •์„ ์‹ ์ค‘ํ•˜๊ฒŒ ๊ณ ๋ คํ•ด ๋ณด๊ฒ ์Šต๋‹ˆ๋‹ค... + + +## Context Analysis +- Team size: 5 developers +- Expected traffic: 10k daily users initially +- Need to scale to 100k+ users +- Limited DevOps resources +- 6-month timeline to MVP + +## Approach 1: Microservices +Pros: ++ Independent scaling ++ Technology flexibility ++ Team independence ++ Fault isolation + +Cons: +- Operational complexity +- Network overhead +- Distributed tracing needed +- Requires DevOps expertise +- Slower initial development + +## Approach 2: Monolith +Pros: ++ Simpler deployment ++ Faster initial development ++ Easier debugging ++ Lower operational overhead ++ Single codebase + +Cons: +- Scaling challenges later +- All-or-nothing deployments +- Technology lock-in +- Potential for tight coupling + +## Decision Factors +1. Team size (5 devs) โ†’ Favors monolith +2. DevOps resources (limited) โ†’ Favors monolith +3. Timeline (6 months) โ†’ Favors monolith +4. Future scale (100k users) โ†’ Achievable with monolith + caching +5. Complexity budget โ†’ Limited + +## Recommendation +Start with a **modular monolith**: +- Single deployment unit +- Clear module boundaries +- Clean interfaces between modules +- Prepare for future extraction to microservices if needed + +This gives you: +โœ“ Fast initial development +โœ“ Low operational complexity +โœ“ Option to extract services later +โœ“ Clear architecture + +Migration path: When you reach 50k+ users or specific modules need independent scaling, extract those modules into microservices. + + +**Recommendation**: ๊น”๋”ํ•œ ๋ชจ๋“ˆ ๊ฒฝ๊ณ„๋ฅผ ๊ฐ€์ง„ ๋ชจ๋“ˆํ˜• ๋ชจ๋†€๋ฆฌ์Šค๋ฅผ ๊ตฌํ˜„ํ•˜์‹ญ์‹œ์˜ค. + +์ด ์ ‘๊ทผ ๋ฐฉ์‹์€ ํ˜„์žฌ ์ œ์•ฝ ์‚ฌํ•ญ(ํŒ€ ๊ทœ๋ชจ, ๊ธฐํ•œ, DevOps ๋ฆฌ์†Œ์Šค)๊ณผ ํ–ฅํ›„ ํ™•์žฅ์„ฑ ์š”๊ตฌ ์‚ฌํ•ญ์˜ ๊ท ํ˜•์„ ๋งž์ถฅ๋‹ˆ๋‹ค. ๋ช…ํ™•ํ•œ ๋น„์ฆˆ๋‹ˆ์Šค ํ•„์š”์„ฑ์ด ์žˆ์„ ๋•Œ ํŠน์ • ๋ชจ๋“ˆ์„ ๋‚˜์ค‘์— ๋งˆ์ดํฌ๋กœ ์„œ๋น„์Šค๋กœ ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. +``` + +### ํ™•์žฅ๋œ ์‚ฌ๊ณ  ๊ตฌ์„ฑ + +ํ™•์žฅ๋œ ์‚ฌ๊ณ ๋Š” ํ™˜๊ฒฝ ๋ณ€์ˆ˜, ํ‚ค๋ณด๋“œ ๋‹จ์ถ•ํ‚ค ๋ฐ CLI ํ”Œ๋ž˜๊ทธ๋ฅผ ํ†ตํ•ด ์ œ์–ด๋ฉ๋‹ˆ๋‹ค: + +```bash +# Set thinking token budget +export MAX_THINKING_TOKENS=16000 + +# Set effort level (Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 4.6): low (โ—‹), medium (โ—), high (โ—), xhigh (Opus 4.8/4.7), or max โ€” default is high on Opus 4.8 +export CLAUDE_CODE_EFFORT_LEVEL=high +``` + +์„ธ์…˜ ์ค‘์— `Alt+T` / `Option+T`๋กœ ์ „ํ™˜ํ•˜๊ฑฐ๋‚˜ `/effort`๋กœ ๋…ธ๋ ฅ ์ˆ˜์ค€์„ ์„ค์ •ํ•˜๊ฑฐ๋‚˜ `/config`๋ฅผ ํ†ตํ•ด ๊ตฌ์„ฑํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +> **๊ฐ„์†Œํ™”๋œ ์‹œ์Šคํ…œ ํ”„๋กฌํ”„ํŠธ (v2.1.154):** ๊ฐ„์†Œํ™”๋œ ์‹œ์Šคํ…œ ํ”„๋กฌํ”„ํŠธ๋Š” ์ด์ œ Haiku, Sonnet, Opus 4.7 ๋ฐ ์ด์ „ ๋ฒ„์ „์„ ์ œ์™ธํ•œ ๋ชจ๋“  ๋ชจ๋ธ์˜ **๊ธฐ๋ณธ๊ฐ’**์œผ๋กœ, Opus 4.8์˜ ๊ธฐ๋ณธ ํ† ํฐ ์˜ค๋ฒ„ํ—ค๋“œ๋ฅผ ์ค„์ž…๋‹ˆ๋‹ค. + +--- + +## ์ž๋™ ๋ชจ๋“œ + +์ž๋™ ๋ชจ๋“œ๋Š” ๋ฐฐ๊ฒฝ ์•ˆ์ „ ๋ถ„๋ฅ˜๊ธฐ๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ๊ฐ ์ž‘์—…์„ ์‹คํ–‰ํ•˜๊ธฐ ์ „์— ๊ฒ€ํ† ํ•˜๋Š” ์—ฐ๊ตฌ ๋ฏธ๋ฆฌ๋ณด๊ธฐ ๊ถŒํ•œ ๋ชจ๋“œ์ž…๋‹ˆ๋‹ค (2026๋…„ 3์›”). Claude๊ฐ€ ์ž์œจ์ ์œผ๋กœ ์ž‘์—…ํ•˜๋ฉด์„œ ์œ„ํ—˜ํ•œ ์ž‘์—…์„ ์ฐจ๋‹จํ•  ์ˆ˜ ์žˆ๋„๋ก ํ•ฉ๋‹ˆ๋‹ค. + +### ์š”๊ตฌ ์‚ฌํ•ญ + +- **ํ”Œ๋žœ**: Team, Enterprise ๋˜๋Š” API (Pro ๋˜๋Š” Max ํ”Œ๋žœ์—์„œ๋Š” ์‚ฌ์šฉํ•  ์ˆ˜ ์—†์Œ) +- **๋ชจ๋ธ**: Claude Sonnet 4.6 ๋˜๋Š” Opus 4.8 +- **์ œ๊ณต์ž**: Anthropic API๋งŒ ํ•ด๋‹น (Bedrock, Vertex ๋˜๋Š” Foundry์—์„œ๋Š” ์ง€์›๋˜์ง€ ์•Š์Œ) +- **๋ถ„๋ฅ˜๊ธฐ**: Claude Sonnet 4.6์—์„œ ์‹คํ–‰ (์ถ”๊ฐ€ ํ† ํฐ ๋น„์šฉ ๋ฐœ์ƒ) + +### ์ž๋™ ๋ชจ๋“œ ํ™œ์„ฑํ™” + +```bash +# Unlock auto mode with CLI flag (no longer required for Max subscribers on Opus 4.7 โ€” access it directly) +claude --enable-auto-mode + +# Then cycle to it with Shift+Tab in the REPL +``` + +> **v2.1.112 ์—…๋ฐ์ดํŠธ**: ์ž๋™ ๋ชจ๋“œ๋Š” ๋” ์ด์ƒ `--enable-auto-mode` ํ”Œ๋ž˜๊ทธ๋ฅผ ํ•„์š”๋กœ ํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. Max ๊ตฌ๋…์ž๋Š” Opus 4.7์—์„œ ์ง์ ‘ ์•ก์„ธ์Šคํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +> **v2.1.158 ์—…๋ฐ์ดํŠธ**: ์ž๋™ ๋ชจ๋“œ๋Š” ์ด์ œ Opus 4.7/4.8์šฉ Bedrock, Vertex, Foundry์—์„œ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค โ€” `CLAUDE_CODE_ENABLE_AUTO_MODE=1`์„ ์„ค์ •ํ•˜์—ฌ **์˜ตํŠธ์ธ**ํ•˜์‹ญ์‹œ์˜ค. + +๋˜๋Š” ๊ธฐ๋ณธ ๊ถŒํ•œ ๋ชจ๋“œ๋กœ ์„ค์ •: + +```bash +claude --permission-mode auto +``` + +๊ตฌ์„ฑ์œผ๋กœ ์„ค์ •: +```json +{ + "permissions": { + "defaultMode": "auto" + } +} +``` + +### ๋ถ„๋ฅ˜๊ธฐ ์ž‘๋™ ๋ฐฉ์‹ + +๋ฐฐ๊ฒฝ ๋ถ„๋ฅ˜๊ธฐ๋Š” ๋‹ค์Œ ๊ฒฐ์ • ์ˆœ์„œ๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ๊ฐ ์ž‘์—…์„ ํ‰๊ฐ€ํ•ฉ๋‹ˆ๋‹ค: + +1. **ํ—ˆ์šฉ/๊ฑฐ๋ถ€ ๊ทœ์น™** -- ๋ช…์‹œ์ ์ธ ๊ถŒํ•œ ๊ทœ์น™์ด ๋จผ์ € ํ™•์ธ๋ฉ๋‹ˆ๋‹ค. +2. **์ฝ๊ธฐ ์ „์šฉ/ํŽธ์ง‘ ์ž๋™ ์Šน์ธ** -- ํŒŒ์ผ ์ฝ๊ธฐ ๋ฐ ํŽธ์ง‘์€ ์ž๋™์œผ๋กœ ํ†ต๊ณผ๋ฉ๋‹ˆ๋‹ค. +3. **๋ถ„๋ฅ˜๊ธฐ** -- ๋ฐฐ๊ฒฝ ๋ถ„๋ฅ˜๊ธฐ๊ฐ€ ์ž‘์—…์„ ๊ฒ€ํ† ํ•ฉ๋‹ˆ๋‹ค. +4. **๋Œ€์ฒด** -- 3ํšŒ ์—ฐ์† ๋˜๋Š” ์ด 20ํšŒ ์ฐจ๋‹จ ํ›„ ํ”„๋กฌํ”„ํŠธ๋กœ ๋Œ€์ฒด๋ฉ๋‹ˆ๋‹ค. + +### ๊ธฐ๋ณธ ์ฐจ๋‹จ ์ž‘์—… + +์ž๋™ ๋ชจ๋“œ๋Š” ๊ธฐ๋ณธ์ ์œผ๋กœ ๋‹ค์Œ์„ ์ฐจ๋‹จํ•ฉ๋‹ˆ๋‹ค: + +| ์ฐจ๋‹จ๋œ ์ž‘์—… | ์˜ˆ์‹œ | +|----------------|---------| +| ํŒŒ์ดํ”„-ํˆฌ-์‰˜ ์„ค์น˜ | `curl \| bash` | +| ๋ฏผ๊ฐํ•œ ๋ฐ์ดํ„ฐ ์™ธ๋ถ€ ์ „์†ก | API ํ‚ค, ๋„คํŠธ์›Œํฌ๋ฅผ ํ†ตํ•œ ์ž๊ฒฉ ์ฆ๋ช… | +| ํ”„๋กœ๋•์…˜ ๋ฐฐํฌ | ํ”„๋กœ๋•์…˜์„ ๋Œ€์ƒ์œผ๋กœ ํ•˜๋Š” ๋ฐฐํฌ ๋ช…๋ น | +| ๋Œ€๋Ÿ‰ ์‚ญ์ œ | ๋Œ€๊ทœ๋ชจ ๋””๋ ‰ํ† ๋ฆฌ์— ๋Œ€ํ•œ `rm -rf` | +| IAM ๋ณ€๊ฒฝ | ๊ถŒํ•œ ๋ฐ ์—ญํ•  ์ˆ˜์ • | +| main์œผ๋กœ ๊ฐ•์ œ ํ‘ธ์‹œ | `git push --force origin main` | + +### ๊ธฐ๋ณธ ํ—ˆ์šฉ ์ž‘์—… + +| ํ—ˆ์šฉ๋œ ์ž‘์—… | ์˜ˆ์‹œ | +|----------------|---------| +| ๋กœ์ปฌ ํŒŒ์ผ ์ž‘์—… | ํ”„๋กœ์ ํŠธ ํŒŒ์ผ ์ฝ๊ธฐ, ์“ฐ๊ธฐ, ํŽธ์ง‘ | +| ์„ ์–ธ๋œ ์ข…์†์„ฑ ์„ค์น˜ | ๋งค๋‹ˆํŽ˜์ŠคํŠธ์—์„œ `npm install`, `pip install` | +| ์ฝ๊ธฐ ์ „์šฉ HTTP | ๋ฌธ์„œ ๊ฐ€์ ธ์˜ค๊ธฐ๋ฅผ ์œ„ํ•œ `curl` | +| ํ˜„์žฌ ๋ธŒ๋žœ์น˜๋กœ ํ‘ธ์‹œ | `git push origin feature-branch` | + +### ์ž๋™ ๋ชจ๋“œ ๊ตฌ์„ฑ + +**๊ธฐ๋ณธ ๊ทœ์น™์„ JSON์œผ๋กœ ์ถœ๋ ฅ**: +```bash +claude auto-mode defaults +``` + +์—”ํ„ฐํ”„๋ผ์ด์ฆˆ ๋ฐฐํฌ๋ฅผ ์œ„ํ•ด `autoMode.environment` ๊ด€๋ฆฌํ˜• ์„ค์ •์„ ํ†ตํ•ด **์‹ ๋ขฐํ•  ์ˆ˜ ์žˆ๋Š” ์ธํ”„๋ผ**๋ฅผ ๊ตฌ์„ฑํ•ฉ๋‹ˆ๋‹ค. ์ด๋ฅผ ํ†ตํ•ด ๊ด€๋ฆฌ์ž๋Š” ์‹ ๋ขฐํ•  ์ˆ˜ ์žˆ๋Š” CI/CD ํ™˜๊ฒฝ, ๋ฐฐํฌ ๋Œ€์ƒ ๋ฐ ์ธํ”„๋ผ ํŒจํ„ด์„ ์ •์˜ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +#### `"$defaults"`๋กœ ๊ธฐ๋ณธ๊ฐ’ ํ™•์žฅ (v2.1.118) + +v2.1.118๋ถ€ํ„ฐ `autoMode.allow`, `autoMode.soft_deny`, `autoMode.environment`๋Š” `"$defaults"` ํ† ํฐ์„ ํ—ˆ์šฉํ•˜์—ฌ ๊ธฐ๋ณธ ์ œ๊ณต ๋ชฉ๋ก์„ **๊ต์ฒดํ•˜๋Š” ๋Œ€์‹ ** ์‚ฌ์šฉ์ž ๊ทœ์น™์„ **์ถ”๊ฐ€**ํ•ฉ๋‹ˆ๋‹ค. v2.1.118 ์ด์ „์—๋Š” ์‚ฌ์šฉ์ž ์ •์˜ ๋ฐฐ์—ด์ด ๊ธฐ๋ณธ ์ œ๊ณต ๋ชฉ๋ก์„ ์ž๋™์œผ๋กœ ๋ฎ์–ด์ผ์Šต๋‹ˆ๋‹ค. + +#### `autoMode.hard_deny`๋ฅผ ์‚ฌ์šฉํ•œ ๋ฌด์กฐ๊ฑด์ ์ธ ์ฐจ๋‹จ (v2.1.136) + +`autoMode.hard_deny` (v2.1.136+)๋Š” **์ถ”๋ก ๋œ ์‚ฌ์šฉ์ž ์˜๋„์™€ ๊ด€๊ณ„์—†์ด** ํŠน์ • ์œ ํ˜•์˜ ์ž‘์—…์„ ์ฐจ๋‹จํ•˜๋Š” ๋ถ„๋ฅ˜๊ธฐ ๊ทœ์น™ ๋ฐฐ์—ด์ž…๋‹ˆ๋‹ค. ์ž๋™ ๋ชจ๋“œ์—์„œ ์ ˆ๋Œ€๋กœ ์‹คํ–‰๋˜์–ด์„œ๋Š” ์•ˆ ๋˜๋Š” ์ž‘์—…์— ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค. ์˜ˆ๋ฅผ ๋“ค์–ด, ๋ฃจํŠธ ๊ฒฝ๋กœ์˜ `rm -rf` ๋˜๋Š” ๋ณดํ˜ธ๋œ ๋ธŒ๋žœ์น˜์˜ `git push --force`๊ฐ€ ์žˆ์Šต๋‹ˆ๋‹ค. `soft_deny`์™€ ๋‹ฌ๋ฆฌ hard-deny ๊ทœ์น™์€ ๋ถ„๋ฅ˜๊ธฐ์— ์˜ํ•ด ํ˜‘์ƒ๋  ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค. + +```json +{ + "autoMode": { + "hard_deny": ["Bash(rm -rf /:*)", "Bash(git push --force*)"] + } +} +``` + +**์ด์ „ (๊ธฐ๋ณธ ์ œ๊ณต ํ•ญ๋ชฉ ๋Œ€์ฒด โ€” v2.1.118 ์ด์ „ ๋™์ž‘):** + +```json +{ + "autoMode": { + "allow": ["Bash(gh pr list:*)"] + } +} +``` + +**์ดํ›„ (๊ธฐ๋ณธ ์ œ๊ณต ํ•ญ๋ชฉ ํ™•์žฅ โ€” v2.1.118+):** + +```json +{ + "autoMode": { + "allow": ["$defaults", "Bash(gh pr list:*)"], + "soft_deny": ["$defaults", "Bash(kubectl delete:*)"], + "environment": ["$defaults", "trusted-ci.internal"] + } +} +``` + +`"$defaults"`๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ๊ธฐ๋ณธ ๊ทœ์น™์„ ์œ ์ง€ํ•˜๋ฉด์„œ ์กฐ์ง ๋˜๋Š” ํ”„๋กœ์ ํŠธ๋ณ„ ์ถ”๊ฐ€ ๊ธฐ๋Šฅ์„ ๊ณ„์ธตํ™”ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +#### `autoMode.classifyAllShell`์„ ์‚ฌ์šฉํ•˜์—ฌ ๋ชจ๋“  ์‰˜ ๋ช…๋ น ๋ถ„๋ฅ˜ (v2.1.193) + +`autoMode.classifyAllShell` (๋ถ€์šธ, v2.1.193+)์€ **๋ชจ๋“ ** Bash/PowerShell ๋ช…๋ น์„ ์ž๋™ ๋ชจ๋“œ ๋ถ„๋ฅ˜๊ธฐ๋ฅผ ํ†ตํ•ด ๋ผ์šฐํŒ…ํ•ฉ๋‹ˆ๋‹ค. ๋ถ„๋ฅ˜๊ธฐ๊ฐ€ ์„ธ์…˜์˜ ๋ชจ๋“  ์‰˜ ๋ช…๋ น์„ ๊ฒ€์‚ฌํ•˜๋„๋ก ํ•˜๋ ค๋ฉด ์ด ๊ธฐ๋Šฅ์„ ํ™œ์„ฑํ™”ํ•˜์‹ญ์‹œ์˜ค. + +```json +{ + "autoMode": { + "classifyAllShell": true + } +} +``` + +๊ฐ™์€ ๋ฆด๋ฆฌ์Šค์—์„œ ์ž๋™ ๋ชจ๋“œ๊ฐ€ ์ž‘์—…์„ ์ฐจ๋‹จํ•  ๋•Œ **๊ฑฐ๋ถ€ ์‚ฌ์œ **๊ฐ€ ํ‘œ์‹œ๋ฉ๋‹ˆ๋‹ค โ€” ํŠธ๋žœ์Šคํฌ๋ฆฝํŠธ, ๊ฑฐ๋ถ€ ํ† ์ŠคํŠธ, `/permissions` ์•„๋ž˜์˜ ์ตœ๊ทผ ๊ฑฐ๋ถ€ ๋ชฉ๋ก์—์„œ ๋ณผ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค (v2.1.193+). + +#### ๋‚ด์žฅ๋œ ์˜๋„ ๊ธฐ๋ฐ˜ ๋ณดํ˜ธ (v2.1.183) + +์‚ฌ์šฉ์ž๊ฐ€ ๊ตฌ์„ฑํ•˜๋Š” `hard_deny`์™€ ๋ณ„๋„๋กœ, ์ž๋™ ๋ชจ๋“œ๋Š” ๋‹ค์Œ๊ณผ ๊ฐ™์€ ํŒŒ๊ดด์ ์ธ ๋ช…๋ น์„ ์ด ์„ธ์…˜์—์„œ ๋ช…์‹œ์ ์œผ๋กœ ์š”์ฒญํ•˜์ง€ ์•Š๋Š” ํ•œ ๊ธฐ๋ณธ์ ์œผ๋กœ ์ฐจ๋‹จํ•ฉ๋‹ˆ๋‹ค: + +- `git reset --hard`, `git checkout -- .`, `git clean -fd`, `git stash drop` +- `git commit --amend` (์ปค๋ฐ‹์ด ์ด ์„ธ์…˜์—์„œ ์—์ด์ „ํŠธ์— ์˜ํ•ด ๋งŒ๋“ค์–ด์ง€์ง€ ์•Š์€ ๊ฒฝ์šฐ) +- `terraform destroy`, `pulumi destroy`, `cdk destroy` (ํŠน์ • ์Šคํƒ์„ ์š”์ฒญํ•˜์ง€ ์•Š๋Š” ํ•œ) + +์ด๋Š” ์ถ”๋ก ๋œ ์˜๋„์— ๊ธฐ๋ฐ˜ํ•œ ๋‚ด์žฅ๋œ ๊ธฐ๋ณธ ๋ณดํ˜ธ ๊ธฐ๋Šฅ์ž…๋‹ˆ๋‹ค. ์ด๋Ÿฌํ•œ ํ•ญ๋ชฉ์„ `hard_deny`์— ์ง์ ‘ ์ถ”๊ฐ€ํ•  ํ•„์š”๊ฐ€ ์—†์Šต๋‹ˆ๋‹ค. + +### ๋Œ€์ฒด ๋™์ž‘ + +๋ถ„๋ฅ˜๊ธฐ๊ฐ€ ๋ถˆํ™•์‹คํ•  ๋•Œ ์ž๋™ ๋ชจ๋“œ๋Š” ์‚ฌ์šฉ์ž์—๊ฒŒ ํ”„๋กฌํ”„ํŠธ๋ฅผ ํ‘œ์‹œํ•˜๋Š” ๊ฒƒ์œผ๋กœ ๋Œ€์ฒด๋ฉ๋‹ˆ๋‹ค: +- **3ํšŒ ์—ฐ์†** ๋ถ„๋ฅ˜๊ธฐ ์ฐจ๋‹จ ํ›„ +- ์„ธ์…˜์—์„œ **์ด 20ํšŒ** ๋ถ„๋ฅ˜๊ธฐ ์ฐจ๋‹จ ํ›„ + +์ด๋Š” ๋ถ„๋ฅ˜๊ธฐ๊ฐ€ ์ž‘์—…์„ ์ž์‹  ์žˆ๊ฒŒ ์Šน์ธํ•  ์ˆ˜ ์—†์„ ๋•Œ ์‚ฌ์šฉ์ž๊ฐ€ ํ•ญ์ƒ ์ œ์–ด๊ถŒ์„ ์œ ์ง€ํ•˜๋„๋ก ๋ณด์žฅํ•ฉ๋‹ˆ๋‹ค. + +### ์ž๋™ ๋ชจ๋“œ์™€ ๋™๋“ฑํ•œ ๊ถŒํ•œ ์‹œ๋“œ (ํŒ€ ํ”Œ๋žœ ๋ถˆํ•„์š”) + +ํŒ€ ํ”Œ๋žœ์ด ์—†๊ฑฐ๋‚˜ ๋ฐฐ๊ฒฝ ๋ถ„๋ฅ˜๊ธฐ ์—†์ด ๋” ๊ฐ„๋‹จํ•œ ์ ‘๊ทผ ๋ฐฉ์‹์„ ์›ํ•œ๋‹ค๋ฉด, `~/.claude/settings.json`์— ๋ณด์ˆ˜์ ์ธ ์•ˆ์ „ ๊ถŒํ•œ ๊ทœ์น™์˜ ๊ธฐ์ค€์„ ์„ ์‹œ๋“œํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์Šคํฌ๋ฆฝํŠธ๋Š” ์ฝ๊ธฐ ์ „์šฉ ๋ฐ ๋กœ์ปฌ ๊ฒ€์‚ฌ ๊ทœ์น™์œผ๋กœ ์‹œ์ž‘ํ•œ ๋‹ค์Œ, ํŽธ์ง‘, ํ…Œ์ŠคํŠธ, ๋กœ์ปฌ Git ์“ฐ๊ธฐ, ํŒจํ‚ค์ง€ ์„ค์น˜ ๋ฐ GitHub ์“ฐ๊ธฐ ์ž‘์—…์€ ์›ํ•  ๋•Œ๋งŒ ์˜ตํŠธ์ธํ•  ์ˆ˜ ์žˆ๋„๋ก ํ•ฉ๋‹ˆ๋‹ค. + +**ํŒŒ์ผ:** `09-advanced-features/setup-auto-mode-permissions.py` + +```bash +# Preview what would be added (no changes written) +python3 09-advanced-features/setup-auto-mode-permissions.py --dry-run + +# Apply the conservative baseline +python3 09-advanced-features/setup-auto-mode-permissions.py + +# Add more capability only when you need it +python3 09-advanced-features/setup-auto-mode-permissions.py --include-edits --include-tests +python3 09-advanced-features/setup-auto-mode-permissions.py --include-git-write --include-packages +``` + +์Šคํฌ๋ฆฝํŠธ๋Š” ๋‹ค์Œ ๋ฒ”์ฃผ์— ๊ฑธ์ณ ๊ทœ์น™์„ ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค: + +| ๋ฒ”์ฃผ | ์˜ˆ์‹œ | +|----------|---------| +| ํ•ต์‹ฌ ์ฝ๊ธฐ ์ „์šฉ ๋„๊ตฌ | `Read(*)`, `Glob(*)`, `Grep(*)`, `Agent(*)`, `WebSearch(*)`, `WebFetch(*)` | +| ๋กœ์ปฌ ๊ฒ€์‚ฌ | `Bash(git status:*)`, `Bash(git log:*)`, `Bash(git diff:*)`, `Bash(cat:*)` | +| ์„ ํƒ์  ํŽธ์ง‘ | `Edit(*)`, `Write(*)`, `NotebookEdit(*)` | +| ์„ ํƒ์  ํ…Œ์ŠคํŠธ/๋นŒ๋“œ | `Bash(pytest:*)`, `Bash(python3 -m pytest:*)`, `Bash(cargo test:*)` | +| ์„ ํƒ์  Git ์“ฐ๊ธฐ | `Bash(git add:*)`, `Bash(git commit:*)`, `Bash(git stash:*)` | +| Git (๋กœ์ปฌ ์“ฐ๊ธฐ) | `Bash(git add:*)`, `Bash(git commit:*)`, `Bash(git checkout:*)` | +| ํŒจํ‚ค์ง€ ๊ด€๋ฆฌ์ž | `Bash(npm install:*)`, `Bash(pip install:*)`, `Bash(cargo build:*)` | +| ๋นŒ๋“œ ๋ฐ ํ…Œ์ŠคํŠธ | `Bash(make:*)`, `Bash(pytest:*)`, `Bash(go test:*)` | +| ์ผ๋ฐ˜ ์‰˜ | `Bash(ls:*)`, `Bash(cat:*)`, `Bash(find:*)`, `Bash(cp:*)`, `Bash(mv:*)` | +| GitHub CLI | `Bash(gh pr view:*)`, `Bash(gh pr create:*)`, `Bash(gh issue list:*)` | + +์œ„ํ—˜ํ•œ ์ž‘์—… (`rm -rf`, `sudo`, ๊ฐ•์ œ ํ‘ธ์‹œ, `DROP TABLE`, `terraform destroy` ๋“ฑ)์€ ์˜๋„์ ์œผ๋กœ ์ œ์™ธ๋ฉ๋‹ˆ๋‹ค. ์Šคํฌ๋ฆฝํŠธ๋Š” ๋ฉฑ๋“ฑ์„ฑ์ด ์žˆ์œผ๋ฏ€๋กœ ๋‘ ๋ฒˆ ์‹คํ–‰ํ•ด๋„ ๊ทœ์น™์ด ์ค‘๋ณต๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. + +--- + +## ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž‘์—… + +๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž‘์—…์€ ์žฅ๊ธฐ ์‹คํ–‰ ์ž‘์—…์„ ๋Œ€ํ™”๋ฅผ ์ฐจ๋‹จํ•˜์ง€ ์•Š๊ณ  ์‹คํ–‰ํ•  ์ˆ˜ ์žˆ๋„๋ก ํ•ฉ๋‹ˆ๋‹ค. + +### ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž‘์—…์ด๋ž€ ๋ฌด์—‡์ž…๋‹ˆ๊นŒ? + +๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž‘์—…์€ ๊ณ„์† ์ž‘์—…ํ•˜๋Š” ๋™์•ˆ ๋น„๋™๊ธฐ์ ์œผ๋กœ ์‹คํ–‰๋ฉ๋‹ˆ๋‹ค: +- ๊ธด ํ…Œ์ŠคํŠธ ์Šค์œ„ํŠธ +- ๋นŒ๋“œ ํ”„๋กœ์„ธ์Šค +- ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ +- ๋ฐฐํฌ ์Šคํฌ๋ฆฝํŠธ +- ๋ถ„์„ ๋„๊ตฌ + +**๊ธฐ๋ณธ ์‚ฌ์šฉ๋ฒ•:** +```bash +User: Run tests in background + +Claude: Started task bg-1234 + +/task list # Show all tasks +/task status bg-1234 # Check progress +/task show bg-1234 # View output +/task cancel bg-1234 # Cancel task +``` + +### ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž‘์—… ์‹œ์ž‘ + +``` +User: Run the full test suite in the background + +Claude: ๋ฐฑ๊ทธ๋ผ์šด๋“œ์—์„œ ํ…Œ์ŠคํŠธ๋ฅผ ์‹œ์ž‘ํ•ฉ๋‹ˆ๋‹ค (task-id: bg-1234) +ํ…Œ์ŠคํŠธ๊ฐ€ ์‹คํ–‰๋˜๋Š” ๋™์•ˆ ์ž‘์—…์„ ๊ณ„์†ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +[๋Œ€ํ™”๋ฅผ ๊ณ„์†ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค] + +User: Meanwhile, let's refactor the auth module + +Claude: [ํ…Œ์ŠคํŠธ๊ฐ€ ๋ฐฑ๊ทธ๋ผ์šด๋“œ์—์„œ ์‹คํ–‰๋˜๋Š” ๋™์•ˆ ์ธ์ฆ ๋ชจ๋“ˆ์„ ๋ฆฌํŒฉํ† ๋งํ•ฉ๋‹ˆ๋‹ค] + +[๋‚˜์ค‘์—, ํ…Œ์ŠคํŠธ๊ฐ€ ์™„๋ฃŒ๋˜๋ฉด] + +Claude: ๐Ÿ“ข ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž‘์—… bg-1234 ์™„๋ฃŒ: +โœ… 245 tests passed +โŒ 3 tests failed +๊ฒฐ๊ณผ ๋ณด๊ธฐ: /task show bg-1234 +``` + +### ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž‘์—… ๊ด€๋ฆฌ + +**ํ™œ์„ฑ ์ž‘์—… ๋ชฉ๋ก**: +``` +User: /task list + +Active background tasks: +1. [bg-1234] Running tests (50% complete, 2min remaining) +2. [bg-1235] Building Docker image (25% complete, 8min remaining) +3. [bg-1236] Deploying to staging (90% complete, 30sec remaining) +``` + +**์ž‘์—… ์ƒํƒœ ํ™•์ธ**: +``` +User: /task status bg-1234 + +Task bg-1234: Running tests +Status: In progress +Progress: 120/245 tests (49%) +Started: 2025-11-08 10:30:15 +Estimated completion: 2025-11-08 10:34:22 +``` + +**์ž‘์—… ์ถœ๋ ฅ ๋ณด๊ธฐ**: +``` +User: /task show bg-1234 + +[ํ…Œ์ŠคํŠธ ์‹คํ–‰์˜ ์‹ค์‹œ๊ฐ„ ์ถœ๋ ฅ์„ ๋ณด์—ฌ์ค๋‹ˆ๋‹ค] +``` + +**์ž‘์—… ์ทจ์†Œ**: +``` +User: /task cancel bg-1234 + +Cancelled background task bg-1234 +``` + +### ์˜ˆ์‹œ: ๋ณ‘๋ ฌ ๊ฐœ๋ฐœ + +``` +User: Run the build in the background + +Claude: ๋นŒ๋“œ๋ฅผ ์‹œ์ž‘ํ•ฉ๋‹ˆ๋‹ค... (task-id: bg-5001) + +User: Also run the linter in background + +Claude: ๋ฆฐํ„ฐ๋ฅผ ์‹œ์ž‘ํ•ฉ๋‹ˆ๋‹ค... (task-id: bg-5002) + +User: While those run, let's implement the new API endpoint + +Claude: [๋นŒ๋“œ ๋ฐ ๋ฆฐํ„ฐ๊ฐ€ ์‹คํ–‰๋˜๋Š” ๋™์•ˆ API ์—”๋“œํฌ์ธํŠธ๋ฅผ ๊ตฌํ˜„ํ•ฉ๋‹ˆ๋‹ค] + +[10๋ถ„ ํ›„] + +Claude: ๐Ÿ“ข ๋นŒ๋“œ ์„ฑ๊ณต์ ์œผ๋กœ ์™„๋ฃŒ๋จ (bg-5001) +๐Ÿ“ข ๋ฆฐํ„ฐ์—์„œ 12๊ฐœ์˜ ๋ฌธ์ œ ๋ฐœ๊ฒฌ๋จ (bg-5002) + +User: Show me the linter issues + +Claude: [bg-5002์˜ ๋ฆฐํ„ฐ ์ถœ๋ ฅ์„ ๋ณด์—ฌ์ค๋‹ˆ๋‹ค] +``` + +### ๊ตฌ์„ฑ + +```json +{ + "backgroundTasks": { + "enabled": true, + "maxConcurrentTasks": 5, + "notifyOnCompletion": true, + "autoCleanup": true, + "logOutput": true + } +} +``` + +--- + +## ๋ชจ๋‹ˆํ„ฐ ๋„๊ตฌ (์ด๋ฒคํŠธ ๊ธฐ๋ฐ˜ ์ŠคํŠธ๋ฆผ) + +> **v2.1.98์— ์ƒˆ๋กœ ์ถ”๊ฐ€**: ๋ชจ๋‹ˆํ„ฐ ๋„๊ตฌ๋ฅผ ์‚ฌ์šฉํ•˜๋ฉด Claude๊ฐ€ ๋ฐฑ๊ทธ๋ผ์šด๋“œ ๋ช…๋ น์˜ stdout์„ ๊ด€์ฐฐํ•˜๊ณ  ์ผ์น˜ํ•˜๋Š” ์ด๋ฒคํŠธ๊ฐ€ ๋‚˜ํƒ€๋‚˜๋Š” ์ฆ‰์‹œ ๋ฐ˜์‘ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์ด๋Š” ํด๋ง ๋ฃจํ”„์™€ `sleep`์„ ๊ธด ํ”„๋กœ์„ธ์Šค ๋Œ€๊ธฐ ๋Œ€์‹  ๋Œ€์ฒดํ•ฉ๋‹ˆ๋‹ค. + +๋ชจ๋‹ˆํ„ฐ๋Š” stdout์— ์“ฐ๋Š” ๋ชจ๋“  ์‰˜ ๋ช…๋ น์— ์—ฐ๊ฒฐ๋ฉ๋‹ˆ๋‹ค. ๋ช…๋ น์—์„œ ๋‚˜์˜ค๋Š” ๊ฐ stdout ์ค„์€ ์„ธ์…˜์„ ๊นจ์šฐ๋Š” ์•Œ๋ฆผ์ด ๋ฉ๋‹ˆ๋‹ค. Claude๊ฐ€ ๋ช…๋ น์„ ์ง€์ •ํ•˜๋ฉด, ํ•˜๋„ค์Šค๊ฐ€ ์ถœ๋ ฅ์„ ์ŠคํŠธ๋ฆฌ๋ฐํ•˜๊ณ  ์ด๋ฒคํŠธ๊ฐ€ ๋ฐœ์ƒํ•˜๋ฉด ์ „๋‹ฌํ•ฉ๋‹ˆ๋‹ค. ๊ธฐ๋ณธ ํ”„๋กœ์„ธ์Šค ์‹คํ–‰์— ๋Œ€ํ•ด์„œ๋Š” ๊ด€๋ จ [๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž‘์—…](#๋ฐฑ๊ทธ๋ผ์šด๋“œ-์ž‘์—…) ์„น์…˜์„ ์ฐธ์กฐํ•˜์‹ญ์‹œ์˜ค. + +### ์™œ ์ค‘์š”ํ•œ๊ฐ€์š”? + +`/loop` ๋˜๋Š” `sleep`์„ ์‚ฌ์šฉํ•˜๋Š” ํด๋ง์€ ๋ณ€๊ฒฝ ์‚ฌํ•ญ์ด ์žˆ๋Š”์ง€ ์—ฌ๋ถ€์™€ ๊ด€๊ณ„์—†์ด ๋งค ์ฃผ๊ธฐ๋งˆ๋‹ค ์ „์ฒด API ์™•๋ณต์„ ์†Œ๋ชจํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋‹ˆํ„ฐ๋Š” ์ด๋ฒคํŠธ๊ฐ€ ๋ฐœ์ƒํ•  ๋•Œ๊นŒ์ง€ ์กฐ์šฉํžˆ ์žˆ๋‹ค๊ฐ€ ๋ช…๋ น์ด ์กฐ์šฉํ•  ๋•Œ๋Š” **ํ† ํฐ์„ ์ „ํ˜€ ์†Œ๋น„ํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค**. ์ด๋ฒคํŠธ๊ฐ€ ๋ฐœ์ƒํ•˜๋ฉด Claude๋Š” ์ฆ‰์‹œ ๋ฐ˜์‘ํ•˜๋ฉฐ, ๋‹ค์Œ ํด๋ง ์ฃผ๊ธฐ๊นŒ์ง€ ๊ธฐ๋‹ค๋ฆฌ์ง€ ์•Š๊ณ  ์ง€์—ฐ ์—†์ด ๋ฌธ์ œ๋ฅผ ํ•ด๊ฒฐํ•ฉ๋‹ˆ๋‹ค. ๋ช‡ ๋ถ„ ์ด์ƒ ์‹คํ–‰๋˜๋Š” ๋ชจ๋“  ์ž‘์—…์— ๋Œ€ํ•ด ์ด๋Š” ํด๋ง ๋ฃจํ”„๋ณด๋‹ค ์ €๋ ดํ•˜๊ณ  ๋น ๋ฆ…๋‹ˆ๋‹ค. + +### ๋‘ ๊ฐ€์ง€ ์ผ๋ฐ˜์ ์ธ ํŒจํ„ด + +**์ŠคํŠธ๋ฆผ ํ•„ํ„ฐ**๋Š” ์žฅ๊ธฐ ์‹คํ–‰ ์†Œ์Šค์—์„œ ์ง€์†์ ์ธ ์ถœ๋ ฅ์„ ๊ด€์ฐฐํ•ฉ๋‹ˆ๋‹ค. ๋ช…๋ น์€ ์˜์›ํžˆ ์‹คํ–‰๋˜๋ฉฐ, ์ผ์น˜ํ•˜๋Š” ๋ชจ๋“  ์ค„์ด ์ด๋ฒคํŠธ๊ฐ€ ๋ฉ๋‹ˆ๋‹ค. + +```bash +tail -f /var/log/app.log | grep --line-buffered "ERROR" +``` + +**ํด-์•ค-์ด๋ฐ‹ ํ•„ํ„ฐ**๋Š” ์ฃผ๊ธฐ์ ์œผ๋กœ ์†Œ์Šค๋ฅผ ํ™•์ธํ•˜๊ณ  ๋ณ€๊ฒฝ ์‚ฌํ•ญ์ด ์žˆ์„ ๋•Œ๋งŒ ์ด๋ฒคํŠธ๋ฅผ ๋ฐœ์ƒ์‹œํ‚ต๋‹ˆ๋‹ค. API, ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ๋˜๋Š” ๊ธฐ๋ณธ ์ŠคํŠธ๋ฆผ์ด ์—†๋Š” ๋ชจ๋“  ๊ฒƒ์— ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค. + +```bash +last=$(date -u +%Y-%m-%dT%H:%M:%SZ) +while true; do + gh api "repos/owner/repo/issues/123/comments?since=$last" || true + last=$(date -u +%Y-%m-%dT%H:%M:%SZ) + sleep 30 +done +``` + +### ๊ตฌ์ฒด์ ์ธ ์˜ˆ์‹œ + +"๋‚ด ๊ฐœ๋ฐœ ์„œ๋ฒ„๋ฅผ ์‹œ์ž‘ํ•˜๊ณ  ์˜ค๋ฅ˜๋ฅผ ๋ชจ๋‹ˆํ„ฐ๋งํ•ด ์ค˜." Claude๋Š” ์„œ๋ฒ„๋ฅผ ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž‘์—…์œผ๋กœ ์‹œ์ž‘ํ•˜๊ณ , ๋ชจ๋‹ˆํ„ฐ ํ•„ํ„ฐ (`tail -F server.log | grep --line-buffered -E "ERROR|FATAL"`)๋ฅผ ์—ฐ๊ฒฐํ•˜๋ฉฐ, ์„ธ์…˜์€ ์กฐ์šฉํ•ด์ง‘๋‹ˆ๋‹ค. ๋กœ๊ทธ์— ์˜ค๋ฅ˜ ์ค„์ด ๋‚˜ํƒ€๋‚˜๋Š” ์ˆœ๊ฐ„, Claude๋Š” ๊นจ์–ด๋‚˜ ์˜ค๋ฅ˜๋ฅผ ์ฝ๊ณ  ๋ฐ˜์‘ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์„œ๋ฒ„๋ฅผ ์žฌ์‹œ์ž‘ํ•˜๊ฑฐ๋‚˜ ๋ฒ„๊ทธ๋ฅผ ์ˆ˜์ •ํ•˜๊ฑฐ๋‚˜ ์‚ฌ์šฉ์ž์—๊ฒŒ ์•Œ๋ฆด ์ˆ˜ ์žˆ์œผ๋ฉฐ, ์‚ฌ์šฉ์ž๊ฐ€ ์ง์ ‘ ํ™•์ธํ•  ํ•„์š”๊ฐ€ ์—†์Šต๋‹ˆ๋‹ค. + +> **๊ฒฝ๊ณ **: `grep`์œผ๋กœ ํŒŒ์ดํ•‘ํ•  ๋•Œ **ํ•ญ์ƒ** `grep --line-buffered`๋ฅผ ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค. ์ด๋ฅผ ์‚ฌ์šฉํ•˜์ง€ ์•Š์œผ๋ฉด grep์ด stdout์„ 4KB ์ฒญํฌ๋กœ ๋ฒ„ํผ๋งํ•˜์—ฌ ํŠธ๋ž˜ํ”ฝ์ด ์ ์€ ์ŠคํŠธ๋ฆผ์—์„œ ์ด๋ฒคํŠธ๊ฐ€ ๋ช‡ ๋ถ„ ์ง€์—ฐ๋  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์ด๋Š” ์‹ค์ œ๋กœ ๋ชจ๋‹ˆํ„ฐ๊ฐ€ ์ค‘๋‹จ๋˜๋Š” ๊ฐ€์žฅ ํ”ํ•œ ๋ฐฉ๋ฒ•์ž…๋‹ˆ๋‹ค. ํ•„ํ„ฐ๊ฐ€ ์ž‘๋™ํ•ด์•ผ ํ•  ๋•Œ ์นจ๋ฌตํ•˜๋Š” ๊ฒƒ์ฒ˜๋Ÿผ ๋ณด์ด๋ฉด ๋จผ์ € `--line-buffered` ํ”Œ๋ž˜๊ทธ๋ฅผ ํ™•์ธํ•˜์‹ญ์‹œ์˜ค. + +--- + +## ๋™์  ์›Œํฌํ”Œ๋กœ์šฐ + +> **v2.1.154์— ์ƒˆ๋กœ ์ถ”๊ฐ€** + +๋™์  ์›Œํฌํ”Œ๋กœ์šฐ๋ฅผ ์‚ฌ์šฉํ•˜๋ฉด Claude๊ฐ€ ์ˆ˜์‹ญ์—์„œ ์ˆ˜๋ฐฑ ๊ฐœ์˜ ๋ฐฑ๊ทธ๋ผ์šด๋“œ [์„œ๋ธŒ์—์ด์ „ํŠธ](../04-subagents/README.md)๋ฅผ **๊ฒฐ์ •์ ์œผ๋กœ** ์กฐ์œจํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์ฆ‰, ํŒฌ์•„์›ƒ, ํŒŒ์ดํ”„๋ผ์ธ ๋ฐ ๋ณ‘๋ ฌ ๋‹จ๊ณ„๊ฐ€ ๋ชจ๋ธ์˜ ์ฆ‰ํฅ ์—ฐ์ฃผ์— ๋งก๊ฒจ์ง€๋Š” ๋Œ€์‹  ์Šคํฌ๋ฆฝํŠธ์— ์ธ์ฝ”๋”ฉ๋ฉ๋‹ˆ๋‹ค. ๋‹จ์ผ ์—์ด์ „ํŠธ๊ฐ€ ํ•˜๋‚˜์˜ ์ปจํ…์ŠคํŠธ ์ฐฝ์„ ์œ ์ง€ํ•˜๋Š” ๋ฐ˜๋ฉด, ์›Œํฌํ”Œ๋กœ์šฐ๋Š” ๋งŽ์€ ์—์ด์ „ํŠธ์— ๊ฑธ์ณ ์ž‘์—…์„ ๋ถ„ํ•ดํ•˜๊ณ  ๊ทธ ๊ฒฐ๊ณผ๋ฅผ ์žฌ๊ฒฐํ•ฉํ•ฉ๋‹ˆ๋‹ค. + +### ์‚ฌ์šฉ ์‹œ์  + +- **ํฌ๊ด„์ ์ธ ๋ฒ”์œ„** โ€” ๋งŽ์€ ํŒŒ์ผ/์ฐจ์›์— ๊ฑธ์ณ ๋ณ‘๋ ฌ๋กœ ๊ฐ์‚ฌ ๋˜๋Š” ๊ฒ€ํ† . +- **์‹ ๋ขฐ์„ฑ** โ€” ๋…๋ฆฝ์ ์ธ ๊ด€์ ์„ ์ƒ์„ฑํ•œ ๋‹ค์Œ, ์ปค๋ฐ‹ํ•˜๊ธฐ ์ „์— ๋ฐœ๊ฒฌ ์‚ฌํ•ญ์„ ์ ๋Œ€์ ์œผ๋กœ ๊ฒ€์ฆ. +- **๋‹จ์ผ ์ปจํ…์ŠคํŠธ๋ฅผ ๋„˜์–ด์„œ๋Š” ํ™•์žฅ** โ€” ๋Œ€๊ทœ๋ชจ ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜, ๊ด‘๋ฒ”์œ„ํ•œ ์กฐ์‚ฌ ๋˜๋Š” ๋‹จ์ผ ์ปจํ…์ŠคํŠธ๋กœ๋Š” ๋‹ด์„ ์ˆ˜ ์—†๋Š” ์—ฐ๊ตฌ. + +์ด๋ฏธ ์ดํ•ดํ•˜๊ณ  ์žˆ๋Š” ์ผํšŒ์„ฑ ์ž‘์—…์˜ ๊ฒฝ์šฐ, ๋‹จ์ผ ์—์ด์ „ํŠธ (๋˜๋Š” ์ง์ ‘ ํŽธ์ง‘)๊ฐ€ ์—ฌ์ „ํžˆ ์˜ฌ๋ฐ”๋ฅธ ๋„๊ตฌ์ž…๋‹ˆ๋‹ค. ์›Œํฌํ”Œ๋กœ์šฐ๋Š” ์ž‘์—…์ด ๋ถ„์‚ฐ๋  ๋•Œ ํšจ๊ณผ๋ฅผ ๋ฐœํœ˜ํ•ฉ๋‹ˆ๋‹ค. + +### ์‹คํ–‰ ๋ฐ ๋ณด๊ธฐ + +- **์‹คํ–‰**: Claude์—๊ฒŒ ์ž‘์—…์„ ์œ„ํ•œ ์›Œํฌํ”Œ๋กœ์šฐ๋ฅผ ์ƒ์„ฑํ•˜๋„๋ก ์š”์ฒญํ•ฉ๋‹ˆ๋‹ค (์˜ˆ: "`src/`์˜ ๋ชจ๋“  ํŒŒ์ผ์„ ๊ฒ€ํ† ํ•˜๋Š” ์›Œํฌํ”Œ๋กœ์šฐ๋ฅผ ์‹คํ–‰ํ•ด ์ค˜"). Claude๋Š” ์˜ค์ผ€์ŠคํŠธ๋ ˆ์ด์…˜ ์Šคํฌ๋ฆฝํŠธ๋ฅผ ์ž‘์„ฑํ•˜๊ณ  ๋ฐฑ๊ทธ๋ผ์šด๋“œ์—์„œ ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค. +- **๋ณด๊ธฐ**: `/workflows` ๋ช…๋ น์€ ๋ผ์ด๋ธŒ ์ง„ํ–‰ ์ƒํ™ฉ๊ณผ ํ•จ๊ป˜ ์‹คํ–‰ ์ค‘์ด๊ฑฐ๋‚˜ ์™„๋ฃŒ๋œ ์›Œํฌํ”Œ๋กœ์šฐ ์‹คํ–‰์„ ํ‘œ์‹œํ•ฉ๋‹ˆ๋‹ค. +- **`ultracode`**: `/effort` ๋ฉ”๋‰ด์—์„œ `ultracode`๋ฅผ ์„ ํƒํ•˜๋ฉด ์„ธ์…˜์— ๋Œ€ํ•ด ์ด ๊ธฐ๋Šฅ์ด ์ผœ์ง‘๋‹ˆ๋‹ค. ์ด๋Š” ๋ชจ๋ธ์— `xhigh`๋ฅผ ๋ณด๋‚ด๊ณ  Claude๊ฐ€ ๊ธฐ๋ณธ์ ์œผ๋กœ ๋™์  ์›Œํฌํ”Œ๋กœ์šฐ๋ฅผ ์กฐ์œจํ•˜๋„๋ก ํ•ฉ๋‹ˆ๋‹ค. ์ด ๊ธฐ๋Šฅ์€ ์„ธ์…˜ ์ „์šฉ์ด๋ฉฐ ์„ค์ • ํŒŒ์ผ์—์„œ๋Š” ํ—ˆ์šฉ๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. (v2.1.160๋ถ€ํ„ฐ ํŠธ๋ฆฌ๊ฑฐ ํ‚ค์›Œ๋“œ๋Š” `ultracode`์ด๋ฉฐ, "workflow" ๋‹จ์–ด๋งŒ์œผ๋กœ๋Š” ๋” ์ด์ƒ ์‹คํ–‰๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค.) + +์›Œํฌํ”Œ๋กœ์šฐ๋Š” ์„œ๋ธŒ์—์ด์ „ํŠธ ๋ชจ๋ธ์„ ๊ธฐ๋ฐ˜์œผ๋กœ ๊ตฌ์ถ•๋ฉ๋‹ˆ๋‹ค. ๊ฐœ๋ณ„ ์—์ด์ „ํŠธ๊ฐ€ ์ •์˜๋˜๊ณ  ๋ฒ”์œ„๊ฐ€ ์ง€์ •๋˜๋Š” ๋ฐฉ๋ฒ•์€ [์„œ๋ธŒ์—์ด์ „ํŠธ](../04-subagents/README.md)๋ฅผ ์ฐธ์กฐํ•˜์‹ญ์‹œ์˜ค. + +--- + +## ์˜ˆ์•ฝ๋œ ์ž‘์—… + +์˜ˆ์•ฝ๋œ ์ž‘์—…์„ ์‚ฌ์šฉํ•˜๋ฉด ๋ฐ˜๋ณต์ ์ธ ์ผ์ • ๋˜๋Š” ์ผํšŒ์„ฑ ์•Œ๋ฆผ์œผ๋กœ ํ”„๋กฌํ”„ํŠธ๋ฅผ ์ž๋™์œผ๋กœ ์‹คํ–‰ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์ž‘์—…์€ ์„ธ์…˜ ๋ฒ”์œ„์ด๋ฉฐ, Claude Code๊ฐ€ ํ™œ์„ฑ ์ƒํƒœ์ผ ๋•Œ ์‹คํ–‰๋˜๊ณ  ์„ธ์…˜์ด ์ข…๋ฃŒ๋˜๋ฉด ์ง€์›Œ์ง‘๋‹ˆ๋‹ค. v2.1.72+๋ถ€ํ„ฐ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +> **claude.com์—์„œ "Routines"๋กœ ๋งˆ์ผ€ํŒ…๋จ (2026-05-14)**: Anthropic์˜ ์ œํ’ˆ ๋ธ”๋กœ๊ทธ๋Š” ์ด ๊ธฐ๋Šฅ์„ **Routines**๋กœ ์†Œ๊ฐœํ•ฉ๋‹ˆ๋‹ค. CLI ๋ช…๋ น์€ `/schedule`๋กœ ์œ ์ง€๋˜๋ฉฐ, ์ด ๊ฐ€์ด๋“œ๋Š” ์—ฐ์†์„ฑ์„ ์œ„ํ•ด ์›๋ž˜์˜ "์˜ˆ์•ฝ๋œ ์ž‘์—…" ๋ช…์นญ์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. claude.com ๋ฌธ์„œ๋‚˜ ๋ฐ์Šคํฌํ†ฑ ์•ฑ์—์„œ "Routines"๋ฅผ ๋ณธ๋‹ค๋ฉด, ๋™์ผํ•œ ๊ธฐ๋Šฅ์„ ์˜๋ฏธํ•ฉ๋‹ˆ๋‹ค. + +### `/loop` ๋ช…๋ น์–ด + +```bash +# Explicit interval +/loop 5m check if the deployment finished + +# Natural language +/loop check build status every 30 minutes +``` + +์ •ํ™•ํ•œ ์Šค์ผ€์ค„๋ง์„ ์œ„ํ•ด ํ‘œ์ค€ 5ํ•„๋“œ ํฌ๋ก  ํ‘œํ˜„์‹๋„ ์ง€์›๋ฉ๋‹ˆ๋‹ค. + +### ์ผํšŒ์„ฑ ์•Œ๋ฆผ + +ํŠน์ • ์‹œ๊ฐ„์— ํ•œ ๋ฒˆ ๋ฐœ์ƒํ•˜๋Š” ์•Œ๋ฆผ์„ ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค: + +``` +remind me at 3pm to push the release branch +in 45 minutes, run the integration tests +``` + +### ์˜ˆ์•ฝ๋œ ์ž‘์—… ๊ด€๋ฆฌ + +| ๋„๊ตฌ | ์„ค๋ช… | +|------|-------------| +| `CronCreate` | ์ƒˆ ์˜ˆ์•ฝ ์ž‘์—… ์ƒ์„ฑ | +| `CronList` | ๋ชจ๋“  ํ™œ์„ฑ ์˜ˆ์•ฝ ์ž‘์—… ๋‚˜์—ด. v2.1.136๋ถ€ํ„ฐ ์ถœ๋ ฅ์—๋Š” ํ•œ์ •์ž ๋ฐ ์˜ˆ์•ฝ๋œ ํ”„๋กฌํ”„ํŠธ ๋ณธ๋ฌธ๋„ ํฌํ•จ๋˜์–ด ๊ฐ ํฌ๋ก ์ด ์‹คํ–‰๋  ๋‚ด์šฉ์„ ์—ด์ง€ ์•Š๊ณ ๋„ ๊ฐ์‚ฌํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. | +| `CronDelete` | ์˜ˆ์•ฝ ์ž‘์—… ์ œ๊ฑฐ | + +**์ œํ•œ ๋ฐ ๋™์ž‘**: +- ์„ธ์…˜๋‹น ์ตœ๋Œ€ **50๊ฐœ์˜ ์˜ˆ์•ฝ๋œ ์ž‘์—…** +- ์„ธ์…˜ ๋ฒ”์œ„ โ€” ์„ธ์…˜์ด ์ข…๋ฃŒ๋˜๋ฉด ์ง€์›Œ์ง‘๋‹ˆ๋‹ค +- ๋ฐ˜๋ณต ์ž‘์—…์€ **3์ผ** ํ›„ ์ž๋™ ๋งŒ๋ฃŒ๋ฉ๋‹ˆ๋‹ค +- Claude Code๊ฐ€ ์‹คํ–‰ ์ค‘์ผ ๋•Œ๋งŒ ์ž‘์—…์ด ๋ฐœ์ƒํ•ฉ๋‹ˆ๋‹ค โ€” ๋†“์นœ ์ž‘์—…์— ๋Œ€ํ•œ ๋”ฐ๋ผ์žก๊ธฐ๋Š” ์—†์Šต๋‹ˆ๋‹ค + +### ๋™์ž‘ ์„ธ๋ถ€ ์ •๋ณด + +| ์ธก๋ฉด | ์„ธ๋ถ€ ์‚ฌํ•ญ | +|--------|--------| +| **๋ฐ˜๋ณต ์ง€ํ„ฐ** | ๊ฐ„๊ฒฉ์˜ ์ตœ๋Œ€ 10% (์ตœ๋Œ€ 15๋ถ„) | +| **์ผํšŒ์„ฑ ์ง€ํ„ฐ** | :00/:30 ๊ฒฝ๊ณ„์—์„œ ์ตœ๋Œ€ 90์ดˆ | +| **๋†“์นœ ๋ฐœ๋™** | ๋”ฐ๋ผ์žก๊ธฐ ์—†์Œ โ€” Claude Code๊ฐ€ ์‹คํ–‰ ์ค‘์ด ์•„๋‹ˆ๋ฉด ๊ฑด๋„ˆ๋œ€ | +| **์˜์†์„ฑ** | ์žฌ์‹œ์ž‘ ์‹œ ์˜์†๋˜์ง€ ์•Š์Œ | + +### ํด๋ผ์šฐ๋“œ ์˜ˆ์•ฝ ์ž‘์—… + +`/schedule`์„ ์‚ฌ์šฉํ•˜์—ฌ Anthropic ์ธํ”„๋ผ์—์„œ ์‹คํ–‰๋˜๋Š” ํด๋ผ์šฐ๋“œ ์˜ˆ์•ฝ ์ž‘์—…์„ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค: + +``` +/schedule daily at 9am run the test suite and report failures +``` + +ํด๋ผ์šฐ๋“œ ์˜ˆ์•ฝ ์ž‘์—…์€ ์žฌ์‹œ์ž‘ ์‹œ ์˜์†๋˜๋ฉฐ Claude Code๊ฐ€ ๋กœ์ปฌ์—์„œ ์‹คํ–‰ ์ค‘์ผ ํ•„์š”๊ฐ€ ์—†์Šต๋‹ˆ๋‹ค. + +### ์˜ˆ์•ฝ๋œ ์ž‘์—… ๋น„ํ™œ์„ฑํ™” + +```bash +export CLAUDE_CODE_DISABLE_CRON=1 +``` + +> **`/schedule` API ํ‚ค ํ‹ฐ์–ด์— ์˜ํ•ด ์ž๋™ ๋น„ํ™œ์„ฑํ™”๋จ (v2.1.139)**: `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, ๋˜๋Š” `apiKeyHelper` ์ค‘ ํ•˜๋‚˜๋ผ๋„ ์„ค์ •๋˜์–ด ์žˆ์œผ๋ฉด ํด๋ผ์šฐ๋“œ `/schedule`์€ ์ž๋™์œผ๋กœ ๋น„ํ™œ์„ฑํ™”๋ฉ๋‹ˆ๋‹ค. claude.ai๋กœ ๋กœ๊ทธ์ธ๋˜์–ด ์žˆ๋Š” ๊ฒฝ์šฐ์—๋„ ๋งˆ์ฐฌ๊ฐ€์ง€์ž…๋‹ˆ๋‹ค. ๋™์ผํ•œ ์กฐ๊ฑด์œผ๋กœ [์›๊ฒฉ ์ œ์–ด ๋น„ํ™œ์„ฑํ™”](#์›๊ฒฉ-์ œ์–ด-๋น„ํ™œ์„ฑํ™”-disableremotecontrol-v21128), claude.ai MCP ์ปค๋„ฅํ„ฐ, ์•Œ๋ฆผ ์„ค์ •์ด ๋น„ํ™œ์„ฑํ™”๋ฉ๋‹ˆ๋‹ค. `/schedule`์„ ์‚ฌ์šฉํ•˜๋ ค๋ฉด API ํ‚ค๋ฅผ ํ•ด์ œํ•˜๊ฑฐ๋‚˜ Pro/Max OAuth ํ‹ฐ์–ด์—์„œ ์‹คํ–‰ํ•˜์‹ญ์‹œ์˜ค. ๋กœ์ปฌ `CronCreate`์—๋Š” ์˜ํ–ฅ์„ ๋ฏธ์น˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. + +### ์˜ˆ์‹œ: ๋ฐฐํฌ ๋ชจ๋‹ˆํ„ฐ๋ง + +``` +/loop 5m check the deployment status of the staging environment. + If the deploy succeeded, notify me and stop looping. + If it failed, show the error logs. +``` + +> **ํŒ**: ์˜ˆ์•ฝ๋œ ์ž‘์—…์€ ์„ธ์…˜ ๋ฒ”์œ„์ž…๋‹ˆ๋‹ค. ์žฌ์‹œ์ž‘ ํ›„์—๋„ ์œ ์ง€๋˜๋Š” ์˜๊ตฌ์ ์ธ ์ž๋™ํ™”๋ฅผ ์œ„ํ•ด์„œ๋Š” CI/CD ํŒŒ์ดํ”„๋ผ์ธ, GitHub Actions ๋˜๋Š” ๋ฐ์Šคํฌํ†ฑ ์•ฑ ์˜ˆ์•ฝ ์ž‘์—…์„ ๋Œ€์‹  ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค. + +--- + +## ๊ถŒํ•œ ๋ชจ๋“œ + +๊ถŒํ•œ ๋ชจ๋“œ๋Š” Claude๊ฐ€ ๋ช…์‹œ์ ์ธ ์Šน์ธ ์—†์ด ์ˆ˜ํ–‰ํ•  ์ˆ˜ ์žˆ๋Š” ์ž‘์—…์„ ์ œ์–ดํ•ฉ๋‹ˆ๋‹ค. + +### ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ๊ถŒํ•œ ๋ชจ๋“œ + +| ๋ชจ๋“œ | ๋™์ž‘ | +|---|---| +| `default` | ํŒŒ์ผ๋งŒ ์ฝ์Œ; ๋‹ค๋ฅธ ๋ชจ๋“  ์ž‘์—…์— ๋Œ€ํ•ด ํ”„๋กฌํ”„ํŠธ๋ฅผ ํ‘œ์‹œ | +| `acceptEdits` | ํŒŒ์ผ ์ฝ๊ธฐ ๋ฐ ํŽธ์ง‘; ๋ช…๋ น์— ๋Œ€ํ•ด ํ”„๋กฌํ”„ํŠธ๋ฅผ ํ‘œ์‹œ | +| `plan` | ํŒŒ์ผ๋งŒ ์ฝ์Œ (์—ฐ๊ตฌ ๋ชจ๋“œ, ํŽธ์ง‘ ๋ถˆ๊ฐ€) | +| `auto` | ๋ฐฐ๊ฒฝ ์•ˆ์ „ ๋ถ„๋ฅ˜๊ธฐ ๊ฒ€์‚ฌ๋ฅผ ํ†ตํ•œ ๋ชจ๋“  ์ž‘์—… (์—ฐ๊ตฌ ๋ฏธ๋ฆฌ๋ณด๊ธฐ) | +| `bypassPermissions` | ๋ชจ๋“  ์ž‘์—…, ๊ถŒํ•œ ๊ฒ€์‚ฌ ์—†์Œ (์œ„ํ—˜) | +| `dontAsk` | ๋ฏธ๋ฆฌ ์Šน์ธ๋œ ๋„๊ตฌ๋งŒ ์‹คํ–‰; ๋‹ค๋ฅธ ๋ชจ๋“  ๊ฒƒ์€ ๊ฑฐ๋ถ€ | + +CLI์—์„œ `Shift+Tab`์œผ๋กœ ๋ชจ๋“œ๋ฅผ ์ˆœํ™˜ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. `--permission-mode` ํ”Œ๋ž˜๊ทธ ๋˜๋Š” `permissions.defaultMode` ์„ค์ •์„ ์‚ฌ์šฉํ•˜์—ฌ ๊ธฐ๋ณธ๊ฐ’์„ ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค. + +v2.1.160 ํ˜„์žฌ, `acceptEdits` ๋ชจ๋“œ์—์„œ๋„ ์‰˜ ์‹œ์ž‘ ํŒŒ์ผ (`.zshenv`, `.zlogin`, `.bash_login`, `~/.config/git/`) ๋ฐ ์ฝ”๋“œ ์‹คํ–‰ ๋นŒ๋“œ ๊ตฌ์„ฑ (`.npmrc`, `.yarnrc*`, `bunfig.toml`, `.bazelrc`, `.pre-commit-config.yaml`, `.devcontainer/`, โ€ฆ)์„ ์ž‘์„ฑํ•˜๊ธฐ ์ „์— ํ”„๋กฌํ”„ํŠธ๋ฅผ ํ‘œ์‹œํ•ฉ๋‹ˆ๋‹ค. ์ด๋Š” ์˜๋„์น˜ ์•Š์€ ๋ช…๋ น ์‹คํ–‰์„ ๋ฐฉ์ง€ํ•˜๊ธฐ ์œ„ํ•จ์ž…๋‹ˆ๋‹ค. + +> **`--dangerously-skip-permissions` ํ™•์žฅ ๊ฒฝ๋กœ ๋ฒ”์œ„ (v2.1.121, v2.1.126)**: `--dangerously-skip-permissions` CLI ํ”Œ๋ž˜๊ทธ (๋ฐ ๋™๋“ฑํ•œ `bypassPermissions` ๋ชจ๋“œ)๋Š” ์ด์ œ ํ›จ์”ฌ ๋” ๊ด‘๋ฒ”์œ„ํ•œ ํ—ˆ์šฉ ๋ชฉ๋ก (`.claude/skills/`, `.claude/agents/`, `.claude/commands/`, `.claude/`, `.git/`, `.vscode/`, ์‰˜ ๊ตฌ์„ฑ ํŒŒ์ผ)์— ๋Œ€ํ•œ ์“ฐ๊ธฐ ํ”„๋กฌํ”„ํŠธ๋ฅผ ์šฐํšŒํ•ฉ๋‹ˆ๋‹ค. ์žฌ์•™์ ์ธ ์‚ญ์ œ ๋ช…๋ น (`rm -rf /` ๋“ฑ)์€ ๋ชจ๋“œ์™€ ๊ด€๊ณ„์—†์ด ์—ฌ์ „ํžˆ ํ”„๋กฌํ”„ํŠธ๋ฅผ ํ‘œ์‹œํ•ฉ๋‹ˆ๋‹ค. ์ด ํ”Œ๋ž˜๊ทธ๋Š” ์ด์ „๋ณด๋‹ค ๋” ๋‚ ์นด๋กœ์šด ๋„๊ตฌ๋กœ ์ทจ๊ธ‰ํ•˜์‹ญ์‹œ์˜ค. ์ผํšŒ์šฉ ์ƒŒ๋“œ๋ฐ•์Šค์—์„œ๋งŒ ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค. + +> **Windows ์‰˜ ๊ฐ์ง€ (v2.1.120, v2.1.126)**: Git for Windows / Git Bash๋Š” ๋” ์ด์ƒ ํ•„์ˆ˜๊ฐ€ ์•„๋‹™๋‹ˆ๋‹ค. Git Bash๊ฐ€ ์—†์œผ๋ฉด Claude Code๋Š” PowerShell์„ ์‰˜ ๋„๊ตฌ๋กœ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. v2.1.126๋ถ€ํ„ฐ PowerShell ๋„๊ตฌ๊ฐ€ ํ™œ์„ฑํ™”๋˜๋ฉด PowerShell์ด *๊ธฐ๋ณธ* ์‰˜์ด๋ฉฐ, Microsoft Store, PATH๊ฐ€ ์—†๋Š” MSI, ๋˜๋Š” `.NET ์ „์—ญ ๋„๊ตฌ`๋ฅผ ํ†ตํ•ด ์„ค์น˜๋œ PowerShell 7๋„ ๊ฐ์ง€ํ•ฉ๋‹ˆ๋‹ค. + +> **PowerShell ๋„๊ตฌ๊ฐ€ Windows์šฉ Bedrock/Vertex/Foundry์—์„œ ๊ธฐ๋ณธ์ ์œผ๋กœ ํ™œ์„ฑํ™”๋จ (v2.1.143)**: v2.1.143๋ถ€ํ„ฐ PowerShell ๋„๊ตฌ๋Š” Bedrock, Vertex, Foundry ์‚ฌ์šฉ์ž๋ฅผ ์œ„ํ•ด **Windows์—์„œ ๊ธฐ๋ณธ์ ์œผ๋กœ ํ™œ์„ฑํ™”๋ฉ๋‹ˆ๋‹ค**. Claude Code๋Š” `-ExecutionPolicy Bypass`๋กœ PowerShell์„ ํ˜ธ์ถœํ•˜๋ฏ€๋กœ ์‹œ์Šคํ…œ ์ •์ฑ…์ด `Restricted`์ธ ๊ฒฝ์šฐ์—๋„ ์Šคํฌ๋ฆฝํŠธ๊ฐ€ ์‹คํ–‰๋ฉ๋‹ˆ๋‹ค. Claude Code๊ฐ€ ์‹œ์Šคํ…œ ์‹คํ–‰ ์ •์ฑ…์„ ๋”ฐ๋ฅด๋„๋ก ํ•˜๋ ค๋ฉด `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1`์„ ์„ค์ •ํ•˜์‹ญ์‹œ์˜ค. PowerShell ๋„๊ตฌ๋ฅผ ์™„์ „ํžˆ ๋น„ํ™œ์„ฑํ™”ํ•˜๋ ค๋ฉด `CLAUDE_CODE_USE_POWERSHELL_TOOL=0`์„ ์„ค์ •ํ•˜์‹ญ์‹œ์˜ค. + +### ํ™œ์„ฑํ™” ๋ฐฉ๋ฒ• + +**ํ‚ค๋ณด๋“œ ๋‹จ์ถ•ํ‚ค**: +```bash +Shift + Tab # 6๊ฐ€์ง€ ๋ชจ๋“œ ๋ชจ๋‘ ์ˆœํ™˜ +``` + +**์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด**: +```bash +/plan # ๊ธฐํš ๋ชจ๋“œ ์ง„์ž… +``` + +**CLI ํ”Œ๋ž˜๊ทธ**: +```bash +claude --permission-mode plan +claude --permission-mode auto +``` + +**์„ค์ •**: +```json +{ + "permissions": { + "defaultMode": "auto" + } +} +``` + +### ๊ถŒํ•œ ๋ชจ๋“œ ์˜ˆ์‹œ + +#### ๊ธฐ๋ณธ ๋ชจ๋“œ +Claude๋Š” ์ค‘์š”ํ•œ ์ž‘์—…์— ๋Œ€ํ•ด ํ™•์ธ์„ ์š”์ฒญํ•ฉ๋‹ˆ๋‹ค: + +``` +User: Fix the bug in auth.ts + +Claude: src/auth.ts ํŒŒ์ผ์„ ์ˆ˜์ •ํ•˜์—ฌ ๋ฒ„๊ทธ๋ฅผ ์ˆ˜์ •ํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. +๋ณ€๊ฒฝ ์‚ฌํ•ญ์€ ๋น„๋ฐ€๋ฒˆํ˜ธ ์œ ํšจ์„ฑ ๊ฒ€์‚ฌ ๋กœ์ง์„ ์—…๋ฐ์ดํŠธํ•  ๊ฒƒ์ž…๋‹ˆ๋‹ค. + +์ด ๋ณ€๊ฒฝ ์‚ฌํ•ญ์„ ์Šน์ธํ•˜์‹œ๊ฒ ์Šต๋‹ˆ๊นŒ? (yes/no/show) +``` + +#### ๊ธฐํš ๋ชจ๋“œ +์‹คํ–‰ ์ „์— ๊ตฌํ˜„ ๊ณ„ํš์„ ๊ฒ€ํ† ํ•ฉ๋‹ˆ๋‹ค: + +``` +User: /plan Implement user authentication system + +Claude: ์ธ์ฆ ์‹œ์Šคํ…œ ๊ตฌํ˜„์„ ์œ„ํ•œ ๊ณ„ํš์„ ์ƒ์„ฑํ•˜๊ฒ ์Šต๋‹ˆ๋‹ค. + +## Implementation Plan +[๋‹จ๊ณ„ ๋ฐ ์ ˆ์ฐจ๊ฐ€ ํฌํ•จ๋œ ์ƒ์„ธ ๊ณ„ํš] + +๊ณ„์† ์ง„ํ–‰ํ•˜์‹œ๊ฒ ์Šต๋‹ˆ๊นŒ? (yes/no/modify) +``` + +#### ํŽธ์ง‘ ์Šน์ธ ๋ชจ๋“œ +ํŒŒ์ผ ์ˆ˜์ • ์‚ฌํ•ญ์„ ์ž๋™์œผ๋กœ ์Šน์ธํ•ฉ๋‹ˆ๋‹ค: + +``` +User: acceptEdits +User: Fix the bug in auth.ts + +Claude: [๋ฌป์ง€ ์•Š๊ณ  ๋ณ€๊ฒฝ ์‚ฌํ•ญ์„ ์ ์šฉํ•ฉ๋‹ˆ๋‹ค] +``` + +### ์‚ฌ์šฉ ์‚ฌ๋ก€ + +**์ฝ”๋“œ ๊ฒ€ํ† **: +``` +User: claude --permission-mode plan +User: Review this PR and suggest improvements + +Claude: [์ฝ”๋“œ๋ฅผ ์ฝ๊ณ  ํ”ผ๋“œ๋ฐฑ์„ ์ œ๊ณตํ•˜์ง€๋งŒ ์ˆ˜์ •ํ•  ์ˆ˜๋Š” ์—†์Šต๋‹ˆ๋‹ค] +``` + +**ํŽ˜์–ด ํ”„๋กœ๊ทธ๋ž˜๋ฐ**: +``` +User: claude --permission-mode default +User: Let's implement the feature together + +Claude: [๊ฐ ๋ณ€๊ฒฝ ์‚ฌํ•ญ ์ „์— ์Šน์ธ์„ ์š”์ฒญํ•ฉ๋‹ˆ๋‹ค] +``` + +**์ž๋™ํ™”๋œ ์ž‘์—…**: +``` +User: claude --permission-mode acceptEdits +User: Fix all linting issues in the codebase + +Claude: [ํŒŒ์ผ ํŽธ์ง‘์„ ๋ฌป์ง€ ์•Š๊ณ  ์ž๋™ ์Šน์ธํ•ฉ๋‹ˆ๋‹ค] +``` + +--- + +## ํ—ค๋“œ๋ฆฌ์Šค ๋ชจ๋“œ + +์ธ์‡„ ๋ชจ๋“œ (`claude -p`)๋Š” Claude Code๋ฅผ ๋Œ€ํ™”ํ˜• ์ž…๋ ฅ ์—†์ด ์‹คํ–‰ํ•  ์ˆ˜ ์žˆ๋„๋ก ํ•˜์—ฌ ์ž๋™ํ™” ๋ฐ CI/CD์— ์™„๋ฒฝํ•ฉ๋‹ˆ๋‹ค. ์ด๋Š” ์ด์ „์˜ `--headless` ํ”Œ๋ž˜๊ทธ๋ฅผ ๋Œ€์ฒดํ•˜๋Š” ๋น„๋Œ€ํ™”ํ˜• ๋ชจ๋“œ์ž…๋‹ˆ๋‹ค. + +### ์ธ์‡„ ๋ชจ๋“œ์—์„œ ์‹คํ–‰ (๋น„๋Œ€ํ™”ํ˜•) + +์ธ์‡„ ๋ชจ๋“œ๋Š” ๋‹ค์Œ์„ ๊ฐ€๋Šฅํ•˜๊ฒŒ ํ•ฉ๋‹ˆ๋‹ค: +- ์ž๋™ํ™”๋œ ์Šคํฌ๋ฆฝํŠธ ์‹คํ–‰ +- CI/CD ํ†ตํ•ฉ +- ๋ฐฐ์น˜ ์ฒ˜๋ฆฌ +- ์˜ˆ์•ฝ๋œ ์ž‘์—… + +### ์ธ์‡„ ๋ชจ๋“œ์—์„œ ์‹คํ–‰ (๋น„๋Œ€ํ™”ํ˜•) + +```bash +# ํŠน์ • ์ž‘์—… ์‹คํ–‰ +claude -p "Run all tests" + +# ํŒŒ์ดํ”„๋œ ๋‚ด์šฉ ์ฒ˜๋ฆฌ +cat error.log | claude -p "Analyze these errors" + +# CI/CD ํ†ตํ•ฉ (GitHub Actions) +- name: AI Code Review + run: claude -p "Review PR" +``` + +### ์ถ”๊ฐ€ ์ธ์‡„ ๋ชจ๋“œ ์‚ฌ์šฉ ์˜ˆ์‹œ + +```bash +# ์ถœ๋ ฅ ์บก์ฒ˜๋ฅผ ํ†ตํ•ด ํŠน์ • ์ž‘์—… ์‹คํ–‰ +claude -p "Run all tests and generate coverage report" + +# ๊ตฌ์กฐํ™”๋œ ์ถœ๋ ฅ์œผ๋กœ +claude -p --output-format json "Analyze code quality" + +# stdin์—์„œ ์ž…๋ ฅ๋ฐ›๊ธฐ +echo "Analyze code quality" | claude -p "explain this" +``` + +### ์˜ˆ์‹œ: CI/CD ํ†ตํ•ฉ + +**GitHub Actions**: +```yaml +# .github/workflows/code-review.yml +name: AI Code Review + +on: [pull_request] + +jobs: + review: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Install Claude Code + run: npm install -g @anthropic-ai/claude-code + + - name: Run Claude Code Review + env: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + run: | + claude -p --output-format json \ + --max-turns 3 \ + "Review this PR for: + - Code quality issues + - Security vulnerabilities + - Performance concerns + - Test coverage + Output results as JSON" > review.json + + - name: Post Review Comment + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const review = JSON.parse(fs.readFileSync('review.json', 'utf8')); + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: JSON.stringify(review, null, 2) + }); +``` + +### ์ธ์‡„ ๋ชจ๋“œ ๊ตฌ์„ฑ + +์ธ์‡„ ๋ชจ๋“œ (`claude -p`)๋Š” ์ž๋™ํ™”๋ฅผ ์œ„ํ•œ ์—ฌ๋Ÿฌ ํ”Œ๋ž˜๊ทธ๋ฅผ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค: + +```bash +# ์ž์œจ์  ํ„ด ์ œํ•œ +claude -p --max-turns 5 "refactor this module" + +# ๊ตฌ์กฐํ™”๋œ JSON ์ถœ๋ ฅ +claude -p --output-format json "analyze this codebase" + +# ์Šคํ‚ค๋งˆ ์œ ํšจ์„ฑ ๊ฒ€์‚ฌ ํฌํ•จ +claude -p --json-schema '{"type":"object","properties":{"issues":{"type":"array"}}}' \ + "find bugs in this code" + +# ์„ธ์…˜ ์˜์†์„ฑ ๋น„ํ™œ์„ฑํ™” +claude -p --no-session-persistence "one-off analysis" +``` + +### ์•ˆ์ „ ๋ชจ๋“œ (๋ฌธ์ œ ํ•ด๊ฒฐ) + +`--safe-mode` (๋ฐ `CLAUDE_CODE_SAFE_MODE` ํ™˜๊ฒฝ ๋ณ€์ˆ˜, ์˜ˆ: `CLAUDE_CODE_SAFE_MODE=1`)๋Š” **๋ชจ๋“  ์‚ฌ์šฉ์ž ์ •์˜๋ฅผ ๋น„ํ™œ์„ฑํ™”**ํ•œ ์ƒํƒœ๋กœ Claude Code๋ฅผ ์‹œ์ž‘ํ•ฉ๋‹ˆ๋‹ค. CLAUDE.md, ํ”Œ๋Ÿฌ๊ทธ์ธ, ์Šคํ‚ฌ, ํ›… ๋ฐ MCP ์„œ๋ฒ„๊ฐ€ ๋ชจ๋‘ ๊บผ์ง‘๋‹ˆ๋‹ค. + +```bash +# ๋ชจ๋“  ์‚ฌ์šฉ์ž ์ •์˜๋ฅผ ๋น„ํ™œ์„ฑํ™”ํ•œ ์ƒํƒœ๋กœ ์‹คํ–‰ +claude --safe-mode + +# ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋ฅผ ํ†ตํ•œ ๋™๋“ฑํ•œ ๋ฐฉ๋ฒ• +CLAUDE_CODE_SAFE_MODE=1 claude +``` + +์ด๊ฒƒ์€ ๋ฌธ์ œ ํ•ด๊ฒฐ ๋„๊ตฌ์ž…๋‹ˆ๋‹ค. ์‚ฌ์šฉ์ž ์ •์˜ ๊ตฌ์„ฑ์ด ๋ฌธ์ œ๋ฅผ ์ผ์œผํ‚ค๋Š” ๊ฒฝ์šฐ, ์•ˆ์ „ ๋ชจ๋“œ๋กœ ์‹œ์ž‘ํ•˜์—ฌ ๋ฌธ์ œ๊ฐ€ ์‚ฌ์šฉ์ž ์„ค์ •์— ์žˆ๋Š”์ง€ Claude Code ์ž์ฒด์— ์žˆ๋Š”์ง€ ๊ฒฉ๋ฆฌํ•˜์—ฌ ํ™•์ธํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +--- + +## ์„ธ์…˜ ๊ด€๋ฆฌ + +์—ฌ๋Ÿฌ Claude Code ์„ธ์…˜์„ ํšจ๊ณผ์ ์œผ๋กœ ๊ด€๋ฆฌํ•ฉ๋‹ˆ๋‹ค. + +### ์„ธ์…˜ ๊ด€๋ฆฌ ๋ช…๋ น์–ด + +| ๋ช…๋ น์–ด | ์„ค๋ช… | +|---------|-------------| +| `/resume` | ID ๋˜๋Š” ์ด๋ฆ„์œผ๋กœ ๋Œ€ํ™” ๋‹ค์‹œ ์‹œ์ž‘ | +| `/rename` | ํ˜„์žฌ ์„ธ์…˜ ์ด๋ฆ„ ์ง€์ • | +| `/fork` | ํ˜„์žฌ ์„ธ์…˜์„ ์ƒˆ ๋ธŒ๋žœ์น˜๋กœ ํฌํฌ | +| `claude -c` | ๊ฐ€์žฅ ์ตœ๊ทผ ๋Œ€ํ™” ๊ณ„์† | +| `claude -r "session"` | ์ด๋ฆ„ ๋˜๋Š” ID๋กœ ์„ธ์…˜ ๋‹ค์‹œ ์‹œ์ž‘ | + +### ์„ธ์…˜ ๋‹ค์‹œ ์‹œ์ž‘ + +**๊ฐ€์žฅ ์ตœ๊ทผ ๋Œ€ํ™” ๊ณ„์†**: +```bash +claude -c +``` + +**์ด๋ฆ„ ์ง€์ •๋œ ์„ธ์…˜ ๋‹ค์‹œ ์‹œ์ž‘**: +```bash +claude -r "auth-refactor" "finish this PR" +``` + +**ํ˜„์žฌ ์„ธ์…˜ ์ด๋ฆ„ ๋ณ€๊ฒฝ** (REPL ๋‚ด๋ถ€): +``` +/rename auth-refactor +``` + +### ์„ธ์…˜ ํฌํฌ + +์›๋ณธ์„ ์žƒ์ง€ ์•Š๊ณ  ๋‹ค๋ฅธ ์ ‘๊ทผ ๋ฐฉ์‹์„ ์‹œ๋„ํ•˜๊ธฐ ์œ„ํ•ด ์„ธ์…˜์„ ํฌํฌํ•ฉ๋‹ˆ๋‹ค: + +``` +/fork +``` + +๋˜๋Š” CLI์—์„œ: +```bash +claude --resume auth-refactor --fork-session "try OAuth instead" +``` + +### ์„ธ์…˜ ์˜์†์„ฑ + +์„ธ์…˜์€ ์ž๋™์œผ๋กœ ์ €์žฅ๋˜๋ฉฐ ๋‹ค์‹œ ์‹œ์ž‘ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค: + +```bash +# ๊ฐ€์žฅ ์ตœ๊ทผ ๋Œ€ํ™” ๊ณ„์† +claude -c + +# ์ด๋ฆ„ ๋˜๋Š” ID๋กœ ํŠน์ • ์„ธ์…˜ ๋‹ค์‹œ ์‹œ์ž‘ +claude -r "auth-refactor" + +# ์‹คํ—˜์„ ์œ„ํ•ด ์„ธ์…˜ ๋‹ค์‹œ ์‹œ์ž‘ ๋ฐ ํฌํฌ +claude --resume auth-refactor --fork-session "alternative approach" +``` + +### ์„ธ์…˜ ์š”์•ฝ (v2.1.108) + +์˜ค๋žซ๋™์•ˆ ๋–จ์–ด์ ธ ์žˆ๋˜ ์„ธ์…˜์œผ๋กœ ๋Œ์•„์˜ค๋ฉด Claude๊ฐ€ ์ˆ˜ํ–‰๋œ ์ž‘์—…์— ๋Œ€ํ•œ ๊ฐ„๋žตํ•œ ์š”์•ฝ์„ ํ‘œ์‹œํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์ด ๊ธฐ๋Šฅ์€ ์›๊ฒฉ ๋ถ„์„์ด ๋น„ํ™œ์„ฑํ™”๋œ ์‚ฌ์šฉ์ž (Bedrock, Vertex, Foundry ์‚ฌ์šฉ์ž)์—๊ฒŒ ๊ธฐ๋ณธ์ ์œผ๋กœ ํ™œ์„ฑํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. + +> **OTEL ์›๊ฒฉ ์ธก์ • โ€” ํ”ผ๋“œ๋ฐฑ ์„ค๋ฌธ์กฐ์‚ฌ ์žฌํ™œ์„ฑํ™” (v2.1.136+)**: OpenTelemetry ๋ฐ์ดํ„ฐ๋ฅผ ์บก์ฒ˜ํ•˜๋Š” ์กฐ์ง์€ `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL=1`์„ ์„ค์ •ํ•˜์—ฌ Anthropic์˜ ์„ธ์…˜ ํ’ˆ์งˆ ์„ค๋ฌธ์กฐ์‚ฌ๋ฅผ ๋‹ค์‹œ ํ™œ์„ฑํ™”ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์„ค๋ฌธ์กฐ์‚ฌ๋Š” ์ด์ „์— ์›๊ฒฉ ์ธก์ • ํŒŒ์ดํ”„๋ผ์ธ์—์„œ ๋ฆฌ๋””๋ ‰์…˜๋˜์—ˆ๊ธฐ ๋•Œ๋ฌธ์— OTEL ๋ฐฐํฌ์—์„œ๋Š” ๊ธฐ๋ณธ์ ์œผ๋กœ ๊บผ์ ธ ์žˆ์Šต๋‹ˆ๋‹ค. + +> **OTEL ์›๊ฒฉ ์ธก์ • โ€” `assistant_response` ๋กœ๊ทธ ์ด๋ฒคํŠธ (v2.1.193+)**: Claude Code๋Š” ๋ชจ๋ธ์˜ ์‘๋‹ต ํ…์ŠคํŠธ๋ฅผ ๋‹ด์€ `claude_code.assistant_response` OpenTelemetry ๋กœ๊ทธ ์ด๋ฒคํŠธ๋ฅผ ๋ฐฉ์ถœํ•˜์—ฌ OTEL ํŒŒ์ดํ”„๋ผ์ธ์ด ๊ธฐ์กด ๋„๊ตฌ/์ด๋ฒคํŠธ ์›๊ฒฉ ์ธก์ •๊ณผ ํ•จ๊ป˜ Claude๊ฐ€ ๋งํ•œ ๋‚ด์šฉ์„ ์บก์ฒ˜ํ•  ์ˆ˜ ์žˆ๋„๋ก ํ•ฉ๋‹ˆ๋‹ค. + +**์š”์•ฝ ๋™์ž‘ ์ œ์–ด:** + +```bash +/recap # ์ˆ˜๋™์œผ๋กœ ์š”์•ฝ ํŠธ๋ฆฌ๊ฑฐ +/config # ์ž๋™ ์š”์•ฝ ์ผœ๊ธฐ/๋„๊ธฐ ์ „ํ™˜ +``` + +๋˜๋Š” ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋ฅผ ํ†ตํ•ด: +```bash +CLAUDE_CODE_ENABLE_AWAY_SUMMARY=0 claude # ์š”์•ฝ ๋น„ํ™œ์„ฑํ™” +CLAUDE_CODE_ENABLE_AWAY_SUMMARY=1 claude # ์š”์•ฝ ๊ฐ•์ œ ํ™œ์„ฑํ™” +``` + +--- + +## ๋Œ€ํ™”ํ˜• ๊ธฐ๋Šฅ + +### ํ‚ค๋ณด๋“œ ๋‹จ์ถ•ํ‚ค + +Claude Code๋Š” ํšจ์œจ์„ฑ์„ ์œ„ํ•œ ํ‚ค๋ณด๋“œ ๋‹จ์ถ•ํ‚ค๋ฅผ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค. ๋‹ค์Œ์€ ๊ณต์‹ ๋ฌธ์„œ์˜ ์ „์ฒด ์ฐธ์กฐ์ž…๋‹ˆ๋‹ค: + +| ๋‹จ์ถ•ํ‚ค | ์„ค๋ช… | +|----------|-------------| +| `Ctrl+C` | ํ˜„์žฌ ์ž…๋ ฅ/์ƒ์„ฑ ์ทจ์†Œ | +| `Ctrl+D` | Claude Code ์ข…๋ฃŒ | +| `Ctrl+G` | ์™ธ๋ถ€ ํŽธ์ง‘๊ธฐ์—์„œ ๊ณ„ํš ํŽธ์ง‘ | +| `Ctrl+L` | ํ„ฐ๋ฏธ๋„ ํ™”๋ฉด ์ง€์šฐ๊ธฐ | +| `Ctrl+O` | ์ž์„ธํ•œ ์ถœ๋ ฅ ์ „ํ™˜ (์ถ”๋ก  ๋ณด๊ธฐ) | +| `Ctrl+R` | ๊ธฐ๋ก ์—ญ๋ฐฉํ–ฅ ๊ฒ€์ƒ‰. **๋ชจ๋“  ํ”„๋กœ์ ํŠธ์˜ ๋ชจ๋“  ํ”„๋กฌํ”„ํŠธ**๋ฅผ ๊ธฐ๋ณธ์œผ๋กœ ๊ฒ€์ƒ‰ํ•ฉ๋‹ˆ๋‹ค (v2.1.129+); ์„ ํƒ๊ธฐ ๋‚ด์—์„œ `Ctrl+S`๋ฅผ ๋ˆ„๋ฅด๋ฉด ํ˜„์žฌ ํ”„๋กœ์ ํŠธ๋กœ ๋ฒ”์œ„๋ฅผ ์ขํž™๋‹ˆ๋‹ค. ์ด์ „ ๋ฒ„์ „์€ ํ”„๋กœ์ ํŠธ ์ „์šฉ์ด ๊ธฐ๋ณธ๊ฐ’์ด์—ˆ์Šต๋‹ˆ๋‹ค. | +| `Ctrl+T` | ์ž‘์—… ๋ชฉ๋ก ๋ณด๊ธฐ ์ „ํ™˜ | +| `Ctrl+B` | ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž‘์—… | +| `Esc+Esc` | ์ฝ”๋“œ/๋Œ€ํ™” ๋˜๊ฐ๊ธฐ | +| `Shift+Tab` / `Alt+M` | ๊ถŒํ•œ ๋ชจ๋“œ ์ „ํ™˜ | +| `Option+P` / `Alt+P` | ๋ชจ๋ธ ์ „ํ™˜ | +| `Option+T` / `Alt+T` | ํ™•์žฅ๋œ ์‚ฌ๊ณ  ์ „ํ™˜ | + +**๋ผ์ธ ํŽธ์ง‘ (ํ‘œ์ค€ readline ๋‹จ์ถ•ํ‚ค):** + +| ๋‹จ์ถ•ํ‚ค | ๋™์ž‘ | +|----------|--------| +| `Ctrl + A` | ์ค„ ์‹œ์ž‘์œผ๋กœ ์ด๋™ | +| `Ctrl + E` | ์ค„ ๋์œผ๋กœ ์ด๋™ | +| `Ctrl + K` | ์ค„ ๋๊นŒ์ง€ ์ž˜๋ผ๋‚ด๊ธฐ | +| `Ctrl + U` | ์ค„ ์‹œ์ž‘๊นŒ์ง€ ์ž˜๋ผ๋‚ด๊ธฐ | +| `Ctrl + W` | ๋‹จ์–ด ๋’ค๋กœ ์‚ญ์ œ | +| `Ctrl + Y` | ๋ถ™์—ฌ๋„ฃ๊ธฐ (yank) | +| `Tab` | ์ž๋™ ์™„์„ฑ | +| `โ†‘ / โ†“` | ๋ช…๋ น ๊ธฐ๋ก | + +### ํ‚ค ๋ฐ”์ธ๋”ฉ ์‚ฌ์šฉ์ž ์ง€์ • + +`/keybindings`๋ฅผ ์‹คํ–‰ํ•˜์—ฌ ์‚ฌ์šฉ์ž ์ง€์ • ํ‚ค๋ณด๋“œ ๋‹จ์ถ•ํ‚ค๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. ์ด ๋ช…๋ น์€ `~/.claude/keybindings.json`์„ ์—ด์–ด ํŽธ์ง‘ํ•  ์ˆ˜ ์žˆ๋„๋ก ํ•ฉ๋‹ˆ๋‹ค (v2.1.18+). + +**๊ตฌ์„ฑ ํ˜•์‹**: + +```json +{ + "$schema": "https://www.schemastore.org/claude-code-keybindings.json", + "bindings": [ + { + "context": "Chat", + "bindings": { + "ctrl+e": "chat:externalEditor", + "ctrl+u": null, + "ctrl+k ctrl+s": "chat:stash" + } + }, + { + "context": "Confirmation", + "bindings": { + "ctrl+a": "confirmation:yes" + } + } + ] +} +``` + +๊ธฐ๋ณธ ๋‹จ์ถ•ํ‚ค๋ฅผ ํ•ด์ œํ•˜๋ ค๋ฉด ๋ฐ”์ธ๋”ฉ์„ `null`๋กœ ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค. + +### ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ์ปจํ…์ŠคํŠธ + +ํ‚ค ๋ฐ”์ธ๋”ฉ์€ ํŠน์ • UI ์ปจํ…์ŠคํŠธ์— ๋”ฐ๋ผ ๋ฒ”์œ„๊ฐ€ ์ง€์ •๋ฉ๋‹ˆ๋‹ค: + +| ์ปจํ…์ŠคํŠธ | ์ฃผ์š” ๋™์ž‘ | +|---------|-------------| +| **Chat** | `submit`, `cancel`, `cycleMode`, `modelPicker`, `thinkingToggle`, `undo`, `externalEditor`, `stash`, `imagePaste` | +| **Confirmation** | `yes`, `no`, `previous`, `next`, `nextField`, `cycleMode`, `toggleExplanation` | +| **Global** | `interrupt`, `exit`, `toggleTodos`, `toggleTranscript` | +| **Autocomplete** | `accept`, `dismiss`, `next`, `previous` | +| **HistorySearch** | `search`, `previous`, `next` | +| **Settings** | ์ปจํ…์ŠคํŠธ๋ณ„ ์„ค์ • ํƒ์ƒ‰ | +| **Tabs** | ํƒญ ์ „ํ™˜ ๋ฐ ๊ด€๋ฆฌ | +| **Help** | ๋„์›€๋ง ํŒจ๋„ ํƒ์ƒ‰ | + +`Transcript`, `Task`, `ThemePicker`, `Attachments`, `Footer`, `MessageSelector`, `DiffDialog`, `ModelPicker`, `Select`๋ฅผ ํฌํ•จํ•˜์—ฌ ์ด 18๊ฐœ์˜ ์ปจํ…์ŠคํŠธ๊ฐ€ ์žˆ์Šต๋‹ˆ๋‹ค. + +### ์ฝ”๋“œ ์ง€์› + +ํ‚ค ๋ฐ”์ธ๋”ฉ์€ ์ฝ”๋“œ ์‹œํ€€์Šค (๋‹ค์ค‘ ํ‚ค ์กฐํ•ฉ)๋ฅผ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค: + +``` +"ctrl+k ctrl+s" โ†’ ๋‘ ํ‚ค ์‹œํ€€์Šค: ctrl+k๋ฅผ ๋ˆ„๋ฅธ ๋‹ค์Œ ctrl+s๋ฅผ ๋ˆ„๋ฆ…๋‹ˆ๋‹ค +"ctrl+shift+p" โ†’ ๋™์‹œ์— ์—ฌ๋Ÿฌ ๋ณด์กฐ ํ‚ค๋ฅผ ๋ˆ„๋ฆ„ +``` + +**ํ‚ค ์ž…๋ ฅ ๊ตฌ๋ฌธ**: +- **์ˆ˜์ •์ž**: `ctrl`, `alt` (๋˜๋Š” `opt`), `shift`, `meta` (๋˜๋Š” `cmd`) +- **๋Œ€๋ฌธ์ž๋Š” Shift๋ฅผ ์˜๋ฏธ**: `K`๋Š” `shift+k`์™€ ๋™์ผ +- **ํŠน์ˆ˜ ํ‚ค**: `escape`, `enter`, `return`, `tab`, `space`, `backspace`, `delete`, ํ™”์‚ดํ‘œ ํ‚ค + +### ์˜ˆ์•ฝ ๋ฐ ์ถฉ๋Œ ํ‚ค + +| ํ‚ค | ์ƒํƒœ | ์ฐธ๊ณ  ์‚ฌํ•ญ | +|-----|--------|-------| +| `Ctrl+C` | ์˜ˆ์•ฝ๋จ | ์žฌ์„ค์ • ๋ถˆ๊ฐ€ (์ธํ„ฐ๋ŸฝํŠธ) | +| `Ctrl+D` | ์˜ˆ์•ฝ๋จ | ์žฌ์„ค์ • ๋ถˆ๊ฐ€ (์ข…๋ฃŒ) | +| `Ctrl+B` | ํ„ฐ๋ฏธ๋„ ์ถฉ๋Œ | tmux ์ ‘๋‘์‚ฌ ํ‚ค | +| `Ctrl+A` | ํ„ฐ๋ฏธ๋„ ์ถฉ๋Œ | GNU Screen ์ ‘๋‘์‚ฌ ํ‚ค | +| `Ctrl+Z` | ํ„ฐ๋ฏธ๋„ ์ถฉ๋Œ | ํ”„๋กœ์„ธ์Šค ์ผ์‹œ ์ค‘๋‹จ | + +> **ํŒ**: ๋‹จ์ถ•ํ‚ค๊ฐ€ ์ž‘๋™ํ•˜์ง€ ์•Š์œผ๋ฉด ํ„ฐ๋ฏธ๋„ ์—๋ฎฌ๋ ˆ์ดํ„ฐ ๋˜๋Š” ๋ฉ€ํ‹ฐํ”Œ๋ ‰์„œ์™€์˜ ์ถฉ๋Œ์„ ํ™•์ธํ•˜์‹ญ์‹œ์˜ค. + +### ํƒญ ์™„์„ฑ + +Claude Code๋Š” ์ง€๋Šฅ์ ์ธ ํƒญ ์™„์„ฑ์„ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค: + +``` +User: /rew +โ†’ /rewind + +User: /plu +โ†’ /plugin + +User: /plugin +โ†’ /plugin install +โ†’ /plugin enable +โ†’ /plugin disable +``` + +### ๋ช…๋ น ๊ธฐ๋ก + +์ด์ „ ๋ช…๋ น์— ์•ก์„ธ์Šคํ•ฉ๋‹ˆ๋‹ค: + +``` +User: <โ†‘> # ์ด์ „ ๋ช…๋ น +User: <โ†“> # ๋‹ค์Œ ๋ช…๋ น +User: Ctrl+R # ๊ธฐ๋ก ๊ฒ€์ƒ‰ + +(reverse-i-search)`test': run all tests +``` + +### ์—ฌ๋Ÿฌ ์ค„ ์ž…๋ ฅ + +๋ณต์žกํ•œ ์ฟผ๋ฆฌ์—๋Š” ์—ฌ๋Ÿฌ ์ค„ ๋ชจ๋“œ๋ฅผ ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค: + +```bash +User: \ +> ์—ฌ๋Ÿฌ ์ค„์— ๊ฑธ์นœ +> ๋ณต์žกํ•œ ํ”„๋กฌํ”„ํŠธ +> ์ž…๋‹ˆ๋‹ค. +> \end +``` + +**์˜ˆ์‹œ:** + +``` +User: \ +> ๋‹ค์Œ ์š”๊ตฌ ์‚ฌํ•ญ์„ ๊ฐ€์ง„ ์‚ฌ์šฉ์ž ์ธ์ฆ ์‹œ์Šคํ…œ์„ ๊ตฌํ˜„ํ•˜์‹ญ์‹œ์˜ค: +> - JWT ํ† ํฐ +> - ์ด๋ฉ”์ผ ์ธ์ฆ +> - ๋น„๋ฐ€๋ฒˆํ˜ธ ์žฌ์„ค์ • +> - 2๋‹จ๊ณ„ ์ธ์ฆ ์ง€์› +> \end + +Claude: [์—ฌ๋Ÿฌ ์ค„ ์š”์ฒญ์„ ์ฒ˜๋ฆฌํ•ฉ๋‹ˆ๋‹ค] +``` + +### ์ธ๋ผ์ธ ํŽธ์ง‘ + +์ „์†กํ•˜๊ธฐ ์ „์— ๋ช…๋ น์„ ํŽธ์ง‘ํ•ฉ๋‹ˆ๋‹ค: + +``` +User: Deploy to prodcutionuction + +[์ „์†กํ•˜๊ธฐ ์ „์— ํ˜„์žฌ ์œ„์น˜์—์„œ ํŽธ์ง‘] +``` + +### Vim ๋ชจ๋“œ + +ํ…์ŠคํŠธ ํŽธ์ง‘์„ ์œ„ํ•œ Vi/Vim ํ‚ค ๋ฐ”์ธ๋”ฉ์„ ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค: + +**ํ™œ์„ฑํ™”**: +- `/config` (ํ† ๊ธ€ "Editor / Vim mode") ๋˜๋Š” `~/.claude/settings.json`์—์„œ `editorMode: "vim"`์œผ๋กœ ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค. ๋…๋ฆฝํ˜• `/vim` ์Šฌ๋ž˜์‹œ ๋ช…๋ น์€ ์ œ๊ฑฐ๋˜์—ˆ์Šต๋‹ˆ๋‹ค ( [issue #43370](https://github.com/anthropics/claude-code/issues/43370) ์ฐธ์กฐ); ์ด์ œ vim ๋ชจ๋“œ๋Š” ๊ตฌ์„ฑ ๊ธฐ๋ฐ˜์ž…๋‹ˆ๋‹ค. +- `Esc`๋กœ NORMAL, `i/a/o`๋กœ INSERT, `v`๋กœ VISUAL, `V`๋กœ VISUAL-LINE ๋ชจ๋“œ ์ „ํ™˜ (v2.1.118+) + +**ํƒ์ƒ‰ ํ‚ค**: +- `h` / `l` - ์™ผ์ชฝ/์˜ค๋ฅธ์ชฝ์œผ๋กœ ์ด๋™ +- `j` / `k` - ์•„๋ž˜/์œ„๋กœ ์ด๋™ +- `w` / `b` / `e` - ๋‹จ์–ด ๋‹จ์œ„ ์ด๋™ +- `0` / `$` - ์ค„ ์‹œ์ž‘/๋์œผ๋กœ ์ด๋™ +- `gg` / `G` - ํ…์ŠคํŠธ ์‹œ์ž‘/๋์œผ๋กœ ์ด๋™ + +**ํ…์ŠคํŠธ ๊ฐ์ฒด**: +- `iw` / `aw` - ๋‹จ์–ด ๋‚ด๋ถ€/์ฃผ๋ณ€ +- `i"` / `a"` - ์ธ์šฉ๋œ ๋ฌธ์ž์—ด ๋‚ด๋ถ€/์ฃผ๋ณ€ +- `i(` / `a(` - ๊ด„ํ˜ธ ๋‚ด๋ถ€/์ฃผ๋ณ€ + +**๋น„์ฃผ์–ผ ๋ชจ๋“œ (v2.1.118+)**: + +| ํ‚ค | ๋ชจ๋“œ | ๋™์ž‘ | +|-----|------|----------| +| `v` | Visual | ์‹œ๊ฐ์  ํ”ผ๋“œ๋ฐฑ์ด ์žˆ๋Š” ๋ฌธ์ž ๋‹จ์œ„ ์„ ํƒ; ๋ชจ์…˜ ํ‚ค๋กœ ํ™•์žฅ | +| `V` | Visual-line | ์ค„ ๋‹จ์œ„ ์„ ํƒ; ํ•ญ์ƒ ์ „์ฒด ์ค„ ์„ ํƒ | +| `y` | Yank | ํ˜„์žฌ ๋น„์ฃผ์–ผ ์„ ํƒ ๋ณต์‚ฌ | +| `d` / `x` | Delete | ํ˜„์žฌ ๋น„์ฃผ์–ผ ์„ ํƒ ์‚ญ์ œ | +| `c` | Change | ์„ ํƒ ์‚ญ์ œ ํ›„ INSERT ๋ชจ๋“œ ์ง„์ž… | +| `Esc` | Exit | NORMAL ๋ชจ๋“œ๋กœ ๋Œ์•„๊ฐ€๊ธฐ | + +๋น„์ฃผ์–ผ ์„ ํƒ์€ ์ž…๋ ฅ ํ•„๋“œ์— ๊ฐ•์กฐ ํ‘œ์‹œ๋˜์–ด ์—ฐ์‚ฐ์ž๋ฅผ ์ปค๋ฐ‹ํ•˜๊ธฐ ์ „์— ๋ฌด์—‡์ด yank๋˜๊ฑฐ๋‚˜, ์‚ญ์ œ๋˜๊ฑฐ๋‚˜, ๋ณ€๊ฒฝ๋  ๊ฒƒ์ธ์ง€ ์ •ํ™•ํžˆ ํ™•์ธํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +### Bash ๋ชจ๋“œ + +`!` ์ ‘๋‘์‚ฌ๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ์‰˜ ๋ช…๋ น์„ ์ง์ ‘ ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค: + +```bash +! npm test +! git status +! cat src/index.js +``` + +์ปจํ…์ŠคํŠธ ์ „ํ™˜ ์—†์ด ๋น ๋ฅธ ๋ช…๋ น ์‹คํ–‰์— ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค. + +**v2.1.193๋ถ€ํ„ฐ:** bash ๋ชจ๋“œ (`!`)๋Š” ์‹ค์‹œ๊ฐ„ ํŒŒ์ผ ๊ฒฝ๋กœ ์ž๋™ ์™„์„ฑ์„ ์ œ๊ณตํ•˜๋ฏ€๋กœ ํ”„๋กฌํ”„ํŠธ๋ฅผ ๋ฒ—์–ด๋‚˜์ง€ ์•Š๊ณ  ์‰˜ ๋ช…๋ น์„ ์ž…๋ ฅํ•˜๋Š” ๋™์•ˆ ๊ฒฝ๋กœ๊ฐ€ ์™„์„ฑ๋ฉ๋‹ˆ๋‹ค. + +**v2.1.186๋ถ€ํ„ฐ:** `!` ๋ช…๋ น์˜ ์ถœ๋ ฅ์€ ์ด์ œ Claude์—๊ฒŒ ์ž๋™์œผ๋กœ ์ „์†ก๋˜์–ด Claude๊ฐ€ ์‘๋‹ตํ•ฉ๋‹ˆ๋‹ค. ์ถœ๋ ฅ์ด ์‘๋‹ต ์—†์ด ์ปจํ…์ŠคํŠธ์—๋งŒ ์ถ”๊ฐ€๋˜๋Š” ์ด์ „ ๋™์ž‘์„ ์œ ์ง€ํ•˜๋ ค๋ฉด `settings.json`์—์„œ `"respondToBashCommands": false`๋ฅผ ์„ค์ •ํ•˜์‹ญ์‹œ์˜ค. + +--- + +## TUI ๋ชจ๋“œ (์ „์ฒด ํ™”๋ฉด) + +> **v2.1.110์— ์ƒˆ๋กœ ์ถ”๊ฐ€** + +TUI (ํ…์ŠคํŠธ ์‚ฌ์šฉ์ž ์ธํ„ฐํŽ˜์ด์Šค) ๋ชจ๋“œ๋Š” Claude Code๋ฅผ ๊นœ๋นก์ž„ ์—†๋Š” ์ถœ๋ ฅ์œผ๋กœ ์ „์ฒด ํ™”๋ฉด์œผ๋กœ ๋ Œ๋”๋งํ•˜์—ฌ tmux ๋˜๋Š” iTerm2 ๋ถ„ํ•  ์ฐฝ๊ณผ ๊ฐ™์€ ํ„ฐ๋ฏธ๋„ ๋ฉ€ํ‹ฐํ”Œ๋ ‰์„œ์— ์ด์ƒ์ ์ž…๋‹ˆ๋‹ค. + +### TUI ๋ชจ๋“œ ํ™œ์„ฑํ™” + +`/tui` ๋ช…๋ น์„ ์‚ฌ์šฉํ•˜๊ฑฐ๋‚˜ `--tui` ํ”Œ๋ž˜๊ทธ๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ TUI ๋ชจ๋“œ๋ฅผ ์ „ํ™˜ํ•ฉ๋‹ˆ๋‹ค: + +```bash +/tui # ์„ธ์…˜ ๋‚ด์—์„œ ์ „ํ™˜ +claude --tui # TUI ๋ชจ๋“œ๋กœ ์ง์ ‘ ์‹œ์ž‘ +``` + +### ๊ตฌ์„ฑ + +| ์„ค์ • | ์„ค๋ช… | ๊ธฐ๋ณธ๊ฐ’ | +|---------|-------------|---------| +| `autoScrollEnabled` | ์ตœ์‹  ๋ฉ”์‹œ์ง€๋กœ ์ž๋™ ์Šคํฌ๋กค | `true` | + +`/config` ๋˜๋Š” `settings.json`์„ ํ†ตํ•ด ์ž๋™ ์Šคํฌ๋กค์„ ๋น„ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค: + +```json +{ + "autoScrollEnabled": false +} +``` + +### ํฌ์ปค์Šค ๋ณด๊ธฐ + +`/focus` ๋ช…๋ น์€ ํฌ์ปค์Šค ๋ณด๊ธฐ๋ฅผ ์ „ํ™˜ํ•ฉ๋‹ˆ๋‹ค. ์ด๋Š” ๊ฐ€์žฅ ๊ด€๋ จ์„ฑ ๋†’์€ ์ถœ๋ ฅ๋งŒ ํ‘œ์‹œํ•˜๋Š” ์ง‘์ค‘ ๋ชจ๋“œ์ž…๋‹ˆ๋‹ค. `Ctrl+O`๋Š” ์ด์ œ ์ผ๋ฐ˜ ํŠธ๋žœ์Šคํฌ๋ฆฝํŠธ์™€ ์ž์„ธํ•œ ํŠธ๋žœ์Šคํฌ๋ฆฝํŠธ ๊ฐ„์—๋งŒ ์ „ํ™˜๋ฉ๋‹ˆ๋‹ค (ํฌ์ปค์Šค ๋ณด๊ธฐ๋Š” `/focus`์ž…๋‹ˆ๋‹ค). + +--- + +## ์Œ์„ฑ ๋ฐ›์•„์“ฐ๊ธฐ + +์Œ์„ฑ ๋ฐ›์•„์“ฐ๊ธฐ๋Š” Claude Code์— ํ‘ธ์‹œํˆฌํ†ก ์Œ์„ฑ ์ž…๋ ฅ์„ ์ œ๊ณตํ•˜์—ฌ ํ”„๋กฌํ”„ํŠธ๋ฅผ ์ž…๋ ฅํ•˜๋Š” ๋Œ€์‹  ๋งํ•  ์ˆ˜ ์žˆ๋„๋ก ํ•ฉ๋‹ˆ๋‹ค. + +### ์Œ์„ฑ ๋ฐ›์•„์“ฐ๊ธฐ ํ™œ์„ฑํ™” + +``` +/voice +``` + +### ๊ธฐ๋Šฅ + +| ๊ธฐ๋Šฅ | ์„ค๋ช… | +|---------|-------------| +| **ํ‘ธ์‹œํˆฌํ†ก** | ๋…น์Œํ•˜๋ ค๋ฉด ํ‚ค๋ฅผ ๋ˆ„๋ฅด๊ณ , ๋ณด๋‚ด๋ ค๋ฉด ๋†“์Šต๋‹ˆ๋‹ค | +| **20๊ฐœ ์–ธ์–ด** | ์Œ์„ฑ-ํ…์ŠคํŠธ ๋ณ€ํ™˜์€ 20๊ฐœ ์–ธ์–ด๋ฅผ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค | +| **์‚ฌ์šฉ์ž ์ง€์ • ํ‚ค ๋ฐ”์ธ๋”ฉ** | `/keybindings`๋ฅผ ํ†ตํ•ด ํ‘ธ์‹œํˆฌํ†ก ํ‚ค๋ฅผ ๊ตฌ์„ฑํ•ฉ๋‹ˆ๋‹ค | +| **๊ณ„์ • ์š”๊ตฌ ์‚ฌํ•ญ** | STT ์ฒ˜๋ฆฌ๋ฅผ ์œ„ํ•ด Claude.ai ๊ณ„์ •์ด ํ•„์š”ํ•ฉ๋‹ˆ๋‹ค | + +### ๊ตฌ์„ฑ + +ํ‚ค ๋ฐ”์ธ๋”ฉ ํŒŒ์ผ (`/keybindings`)์—์„œ ํ‘ธ์‹œํˆฌํ†ก ํ‚ค ๋ฐ”์ธ๋”ฉ์„ ์‚ฌ์šฉ์ž ์ง€์ •ํ•ฉ๋‹ˆ๋‹ค. ์Œ์„ฑ ๋ฐ›์•„์“ฐ๊ธฐ๋Š” ์Œ์„ฑ-ํ…์ŠคํŠธ ๋ณ€ํ™˜ ์ฒ˜๋ฆฌ๋ฅผ ์œ„ํ•ด Claude.ai ๊ณ„์ •์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + +--- + +## ์ฑ„๋„ + +์ฑ„๋„์€ ์™ธ๋ถ€ ์„œ๋น„์Šค์—์„œ MCP ์„œ๋ฒ„๋ฅผ ํ†ตํ•ด ์‹คํ–‰ ์ค‘์ธ Claude Code ์„ธ์…˜์œผ๋กœ ์ด๋ฒคํŠธ๋ฅผ ํ‘ธ์‹œํ•˜๋Š” ์—ฐ๊ตฌ ๋ฏธ๋ฆฌ๋ณด๊ธฐ ๊ธฐ๋Šฅ์ž…๋‹ˆ๋‹ค. ์†Œ์Šค์—๋Š” Telegram, Discord, iMessage ๋ฐ ์ž„์˜์˜ ์›นํ›…์ด ํฌํ•จ๋˜์–ด Claude๊ฐ€ ํด๋ง ์—†์ด ์‹ค์‹œ๊ฐ„ ์•Œ๋ฆผ์— ๋ฐ˜์‘ํ•  ์ˆ˜ ์žˆ๋„๋ก ํ•ฉ๋‹ˆ๋‹ค. + +> **์ธ์ฆ (v2.1.128+)**: `--channels`๋Š” ์ด์ œ Pro/Max OAuth **๋ฐ** API ํ‚ค (์ฝ˜์†”) ์ธ์ฆ ๋ชจ๋‘์—์„œ ์ž‘๋™ํ•ฉ๋‹ˆ๋‹ค. ์ด์ „ ๋ฆด๋ฆฌ์Šค์—์„œ๋Š” OAuth๊ฐ€ ํ•„์š”ํ–ˆ์Šต๋‹ˆ๋‹ค. + +### ์ฑ„๋„ ๊ตฌ๋… + +```bash +# ์‹œ์ž‘ ์‹œ ์ฑ„๋„ ํ”Œ๋Ÿฌ๊ทธ์ธ ๊ตฌ๋… +claude --channels discord,telegram + +# ์—ฌ๋Ÿฌ ์†Œ์Šค ๊ตฌ๋… +claude --channels discord,telegram,imessage,webhooks +``` + +### ์ง€์›๋˜๋Š” ํ†ตํ•ฉ + +| ํ†ตํ•ฉ | ์„ค๋ช… | +|-------------|-------------| +| **Discord** | ์„ธ์…˜์—์„œ Discord ๋ฉ”์‹œ์ง€ ์ˆ˜์‹  ๋ฐ ์‘๋‹ต | +| **Telegram** | ์„ธ์…˜์—์„œ Telegram ๋ฉ”์‹œ์ง€ ์ˆ˜์‹  ๋ฐ ์‘๋‹ต | +| **iMessage** | ์„ธ์…˜์—์„œ iMessage ์•Œ๋ฆผ ์ˆ˜์‹  | +| **Webhooks** | ์ž„์˜์˜ ์›นํ›… ์†Œ์Šค์—์„œ ์ด๋ฒคํŠธ ์ˆ˜์‹  | + +### ๊ตฌ์„ฑ + +์‹œ์ž‘ ์‹œ `--channels` ํ”Œ๋ž˜๊ทธ๋กœ ์ฑ„๋„์„ ๊ตฌ์„ฑํ•ฉ๋‹ˆ๋‹ค. ์—”ํ„ฐํ”„๋ผ์ด์ฆˆ ๋ฐฐํฌ์˜ ๊ฒฝ์šฐ, ๊ด€๋ฆฌํ˜• ์„ค์ •์„ ์‚ฌ์šฉํ•˜์—ฌ ํ—ˆ์šฉ๋˜๋Š” ์ฑ„๋„ ํ”Œ๋Ÿฌ๊ทธ์ธ์„ ์ œ์–ดํ•ฉ๋‹ˆ๋‹ค: + +```json +{ + "allowedChannelPlugins": ["discord", "telegram"] +} +``` + +`allowedChannelPlugins` ๊ด€๋ฆฌํ˜• ์„ค์ •์€ ์กฐ์ง ์ „์ฒด์—์„œ ํ—ˆ์šฉ๋˜๋Š” ์ฑ„๋„ ํ”Œ๋Ÿฌ๊ทธ์ธ์„ ์ œ์–ดํ•ฉ๋‹ˆ๋‹ค. + +### ์ž‘๋™ ๋ฐฉ์‹ + +1. MCP ์„œ๋ฒ„๋Š” ์™ธ๋ถ€ ์„œ๋น„์Šค์— ์—ฐ๊ฒฐํ•˜๋Š” ์ฑ„๋„ ํ”Œ๋Ÿฌ๊ทธ์ธ ์—ญํ• ์„ ํ•ฉ๋‹ˆ๋‹ค. +2. ๋“ค์–ด์˜ค๋Š” ๋ฉ”์‹œ์ง€ ๋ฐ ์ด๋ฒคํŠธ๋Š” ํ™œ์„ฑ Claude Code ์„ธ์…˜์œผ๋กœ ํ‘ธ์‹œ๋ฉ๋‹ˆ๋‹ค. +3. Claude๋Š” ์„ธ์…˜ ์ปจํ…์ŠคํŠธ ๋‚ด์—์„œ ๋ฉ”์‹œ์ง€๋ฅผ ์ฝ๊ณ  ์‘๋‹ตํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. +4. ์ฑ„๋„ ํ”Œ๋Ÿฌ๊ทธ์ธ์€ `allowedChannelPlugins` ๊ด€๋ฆฌํ˜• ์„ค์ •์„ ํ†ตํ•ด ์Šน์ธ๋˜์–ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. +5. ํด๋ง์ด ํ•„์š” ์—†์Šต๋‹ˆ๋‹ค โ€” ์ด๋ฒคํŠธ๋Š” ์‹ค์‹œ๊ฐ„์œผ๋กœ ํ‘ธ์‹œ๋ฉ๋‹ˆ๋‹ค. + +--- + +## Chrome ํ†ตํ•ฉ + +Chrome ํ†ตํ•ฉ์€ Claude Code๋ฅผ Chrome ๋˜๋Š” Microsoft Edge ๋ธŒ๋ผ์šฐ์ €์— ์—ฐ๊ฒฐํ•˜์—ฌ ์‹ค์‹œ๊ฐ„ ์›น ์ž๋™ํ™” ๋ฐ ๋””๋ฒ„๊น…์„ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค. ์ด๋Š” v2.0.73+ (Edge ์ง€์›์€ v1.0.36+์— ์ถ”๊ฐ€๋จ)๋ถ€ํ„ฐ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ๋Š” ๋ฒ ํƒ€ ๊ธฐ๋Šฅ์ž…๋‹ˆ๋‹ค. + +### Chrome ํ†ตํ•ฉ ํ™œ์„ฑํ™” + +**์‹œ์ž‘ ์‹œ**: + +```bash +claude --chrome # Chrome ์—ฐ๊ฒฐ ํ™œ์„ฑํ™” +claude --no-chrome # Chrome ์—ฐ๊ฒฐ ๋น„ํ™œ์„ฑํ™” +``` + +**์„ธ์…˜ ๋‚ด์—์„œ**: + +``` +/chrome +``` + +"๊ธฐ๋ณธ์ ์œผ๋กœ ํ™œ์„ฑํ™”"๋ฅผ ์„ ํƒํ•˜์—ฌ ๋ชจ๋“  ํ–ฅํ›„ ์„ธ์…˜์— ๋Œ€ํ•ด Chrome ํ†ตํ•ฉ์„ ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค. Claude Code๋Š” ๋ธŒ๋ผ์šฐ์ €์˜ ๋กœ๊ทธ์ธ ์ƒํƒœ๋ฅผ ๊ณต์œ ํ•˜๋ฏ€๋กœ ์ธ์ฆ๋œ ์›น ์•ฑ๊ณผ ์ƒํ˜ธ ์ž‘์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +### ๊ธฐ๋Šฅ + +| ๊ธฐ๋Šฅ | ์„ค๋ช… | +|------------|-------------| +| **์‹ค์‹œ๊ฐ„ ๋””๋ฒ„๊น…** | ์ฝ˜์†” ๋กœ๊ทธ ์ฝ๊ธฐ, DOM ์š”์†Œ ๊ฒ€์‚ฌ, JavaScript ์‹ค์‹œ๊ฐ„ ๋””๋ฒ„๊น… | +| **๋””์ž์ธ ๊ฒ€์ฆ** | ๋ Œ๋”๋ง๋œ ํŽ˜์ด์ง€๋ฅผ ๋””์ž์ธ ๋ชจํ˜•๊ณผ ๋น„๊ต | +| **์–‘์‹ ์œ ํšจ์„ฑ ๊ฒ€์‚ฌ** | ์–‘์‹ ์ œ์ถœ, ์ž…๋ ฅ ์œ ํšจ์„ฑ ๊ฒ€์‚ฌ ๋ฐ ์˜ค๋ฅ˜ ์ฒ˜๋ฆฌ ํ…Œ์ŠคํŠธ | +| **์›น ์•ฑ ํ…Œ์ŠคํŠธ** | ์ธ์ฆ๋œ ์•ฑ (Gmail, Google Docs, Notion ๋“ฑ)๊ณผ ์ƒํ˜ธ ์ž‘์šฉ | +| **๋ฐ์ดํ„ฐ ์ถ”์ถœ** | ์›น ํŽ˜์ด์ง€์—์„œ ์ฝ˜ํ…์ธ  ์Šคํฌ๋žฉ ๋ฐ ์ฒ˜๋ฆฌ | +| **์„ธ์…˜ ๋…นํ™”** | ๋ธŒ๋ผ์šฐ์ € ์ƒํ˜ธ ์ž‘์šฉ์„ GIF ํŒŒ์ผ๋กœ ๋…นํ™” | + +### ์‚ฌ์ดํŠธ๋ณ„ ๊ถŒํ•œ + +Chrome ํ™•์žฅ ํ”„๋กœ๊ทธ๋žจ์€ ์‚ฌ์ดํŠธ๋ณ„ ์•ก์„ธ์Šค๋ฅผ ๊ด€๋ฆฌํ•ฉ๋‹ˆ๋‹ค. ํ™•์žฅ ํ”„๋กœ๊ทธ๋žจ ํŒ์—…์„ ํ†ตํ•ด ํŠน์ • ์‚ฌ์ดํŠธ์— ๋Œ€ํ•œ ์•ก์„ธ์Šค๋ฅผ ์–ธ์ œ๋“ ์ง€ ๋ถ€์—ฌํ•˜๊ฑฐ๋‚˜ ์ทจ์†Œํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. Claude Code๋Š” ๋ช…์‹œ์ ์œผ๋กœ ํ—ˆ์šฉํ•œ ์‚ฌ์ดํŠธ์™€๋งŒ ์ƒํ˜ธ ์ž‘์šฉํ•ฉ๋‹ˆ๋‹ค. + +### ์ž‘๋™ ๋ฐฉ์‹ + +Claude Code๋Š” ๋ณด์ด๋Š” ์ฐฝ์—์„œ ๋ธŒ๋ผ์šฐ์ €๋ฅผ ์ œ์–ดํ•ฉ๋‹ˆ๋‹ค. ์‚ฌ์šฉ์ž๋Š” ์‹ค์‹œ๊ฐ„์œผ๋กœ ์ž‘์—…์ด ๋ฐœ์ƒํ•˜๋Š” ๊ฒƒ์„ ๋ณผ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ๋ธŒ๋ผ์šฐ์ €๊ฐ€ ๋กœ๊ทธ์ธ ํŽ˜์ด์ง€๋‚˜ CAPTCHA๋ฅผ ๋งŒ๋‚˜๋ฉด Claude๋Š” ์ผ์‹œ ์ค‘์ง€ํ•˜๊ณ  ์‚ฌ์šฉ์ž๊ฐ€ ์ˆ˜๋™์œผ๋กœ ์ฒ˜๋ฆฌํ•  ๋•Œ๊นŒ์ง€ ๊ธฐ๋‹ค๋ฆฐ ๋‹ค์Œ ๊ณ„์† ์ง„ํ–‰ํ•ฉ๋‹ˆ๋‹ค. + +### ์•Œ๋ ค์ง„ ์ œํ•œ ์‚ฌํ•ญ + +- **๋ธŒ๋ผ์šฐ์ € ์ง€์›**: Chrome ๋ฐ Edge๋งŒ ์ง€์› โ€” Brave, Arc ๋ฐ ๊ธฐํƒ€ Chromium ๋ธŒ๋ผ์šฐ์ €๋Š” ์ง€์›๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. +- **WSL**: Windows Sub์‹œ์Šคํ…œ for Linux์—์„œ๋Š” ์‚ฌ์šฉํ•  ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค. +- **ํƒ€์‚ฌ ์ œ๊ณต์ž**: Bedrock, Vertex ๋˜๋Š” Foundry API ์ œ๊ณต์ž์™€๋Š” ์ง€์›๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. +- **์„œ๋น„์Šค ์›Œ์ปค ์œ ํœด**: Chrome ํ™•์žฅ ํ”„๋กœ๊ทธ๋žจ ์„œ๋น„์Šค ์›Œ์ปค๋Š” ํ™•์žฅ๋œ ์„ธ์…˜ ๋™์•ˆ ์œ ํœด ์ƒํƒœ๊ฐ€ ๋  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +> **ํŒ**: Chrome ํ†ตํ•ฉ์€ ๋ฒ ํƒ€ ๊ธฐ๋Šฅ์ž…๋‹ˆ๋‹ค. ๋ธŒ๋ผ์šฐ์ € ์ง€์›์€ ํ–ฅํ›„ ๋ฆด๋ฆฌ์Šค์—์„œ ํ™•์žฅ๋  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +--- + +## ์›๊ฒฉ ์ œ์–ด + +์›๊ฒฉ ์ œ์–ด๋ฅผ ์‚ฌ์šฉํ•˜๋ฉด ํœด๋Œ€ํฐ, ํƒœ๋ธ”๋ฆฟ ๋˜๋Š” ๋ชจ๋“  ๋ธŒ๋ผ์šฐ์ €์—์„œ ๋กœ์ปฌ๋กœ ์‹คํ–‰ ์ค‘์ธ Claude Code ์„ธ์…˜์„ ๊ณ„์†ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ๋กœ์ปฌ ์„ธ์…˜์€ ์‚ฌ์šฉ์ž ์ปดํ“จํ„ฐ์—์„œ ๊ณ„์† ์‹คํ–‰๋˜๋ฉฐ, ์•„๋ฌด๊ฒƒ๋„ ํด๋ผ์šฐ๋“œ๋กœ ์ด๋™ํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. Pro, Max, Team ๋ฐ Enterprise ํ”Œ๋žœ์—์„œ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค (v2.1.51+). + +### ์›๊ฒฉ ์ œ์–ด ์‹œ์ž‘ + +**CLI์—์„œ**: + +```bash +# ๊ธฐ๋ณธ ์„ธ์…˜ ์ด๋ฆ„์œผ๋กœ ์‹œ์ž‘ +claude remote-control + +# ์‚ฌ์šฉ์ž ์ง€์ • ์ด๋ฆ„์œผ๋กœ ์‹œ์ž‘ +claude remote-control --name "Auth Refactor" +``` + +**์„ธ์…˜ ๋‚ด์—์„œ**: + +``` +/remote-control +/remote-control "Auth Refactor" +``` + +**์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ํ”Œ๋ž˜๊ทธ**: + +| ํ”Œ๋ž˜๊ทธ | ์„ค๋ช… | +|------|-------------| +| `--name "title"` | ์‰ฌ์šด ์‹๋ณ„์„ ์œ„ํ•œ ์‚ฌ์šฉ์ž ์ง€์ • ์„ธ์…˜ ์ œ๋ชฉ | +| `--verbose` | ์ƒ์„ธ ์—ฐ๊ฒฐ ๋กœ๊ทธ ํ‘œ์‹œ | +| `--sandbox` | ํŒŒ์ผ ์‹œ์Šคํ…œ ๋ฐ ๋„คํŠธ์›Œํฌ ๊ฒฉ๋ฆฌ ํ™œ์„ฑํ™” | +| `--no-sandbox` | ์ƒŒ๋“œ๋ฐ•์‹ฑ ๋น„ํ™œ์„ฑํ™” (๊ธฐ๋ณธ๊ฐ’) | + +### ์„ธ์…˜์— ์—ฐ๊ฒฐ + +๋‹ค๋ฅธ ๊ธฐ๊ธฐ์—์„œ ์—ฐ๊ฒฐํ•˜๋Š” ์„ธ ๊ฐ€์ง€ ๋ฐฉ๋ฒ•: + +1. **์„ธ์…˜ URL** โ€” ์„ธ์…˜์ด ์‹œ์ž‘๋  ๋•Œ ํ„ฐ๋ฏธ๋„์— ์ธ์‡„๋ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ๋ธŒ๋ผ์šฐ์ €์—์„œ ์—ฝ๋‹ˆ๋‹ค. +2. **QR ์ฝ”๋“œ** โ€” ์‹œ์ž‘ ํ›„ `spacebar`๋ฅผ ๋ˆŒ๋Ÿฌ ์Šค์บ” ๊ฐ€๋Šฅํ•œ QR ์ฝ”๋“œ๋ฅผ ํ‘œ์‹œํ•ฉ๋‹ˆ๋‹ค. +3. **์ด๋ฆ„์œผ๋กœ ์ฐพ๊ธฐ** โ€” claude.ai/code ๋˜๋Š” Claude ๋ชจ๋ฐ”์ผ ์•ฑ (iOS/Android)์—์„œ ์„ธ์…˜์„ ๊ฒ€์ƒ‰ํ•ฉ๋‹ˆ๋‹ค. + +### ๋ณด์•ˆ + +- ์ปดํ“จํ„ฐ์— **์ธ๋ฐ”์šด๋“œ ํฌํŠธ**๊ฐ€ ์—ด๋ฆฌ์ง€ ์•Š์Šต๋‹ˆ๋‹ค. +- **์•„์›ƒ๋ฐ”์šด๋“œ HTTPS๋งŒ** TLS๋ฅผ ํ†ตํ•ด ์ด๋ฃจ์–ด์ง‘๋‹ˆ๋‹ค. +- **๋ฒ”์œ„๊ฐ€ ์ง€์ •๋œ ์ž๊ฒฉ ์ฆ๋ช…** โ€” ์—ฌ๋Ÿฌ ๊ฐœ์˜ ๋‹จ๊ธฐ์ ์ด๊ณ  ์ข์€ ๋ฒ”์œ„์˜ ํ† ํฐ. +- **์„ธ์…˜ ๊ฒฉ๋ฆฌ** โ€” ๊ฐ ์›๊ฒฉ ์„ธ์…˜์€ ๋…๋ฆฝ์ ์ž…๋‹ˆ๋‹ค. + +### ์›๊ฒฉ ์ œ์–ด ๋Œ€ ์›น์˜ Claude Code + +| ์ธก๋ฉด | ์›๊ฒฉ ์ œ์–ด | ์›น์˜ Claude Code | +|--------|---------------|-------------------| +| **์‹คํ–‰** | ์‚ฌ์šฉ์ž ์ปดํ“จํ„ฐ์—์„œ ์‹คํ–‰ | Anthropic ํด๋ผ์šฐ๋“œ์—์„œ ์‹คํ–‰ | +| **๋กœ์ปฌ ๋„๊ตฌ** | ๋กœ์ปฌ MCP ์„œ๋ฒ„, ํŒŒ์ผ ๋ฐ CLI์— ๋Œ€ํ•œ ์ „์ฒด ์•ก์„ธ์Šค | ๋กœ์ปฌ ์ข…์†์„ฑ ์—†์Œ | +| **์‚ฌ์šฉ ์‚ฌ๋ก€** | ๋‹ค๋ฅธ ๊ธฐ๊ธฐ์—์„œ ๋กœ์ปฌ ์ž‘์—… ๊ณ„์† | ๋ชจ๋“  ๋ธŒ๋ผ์šฐ์ €์—์„œ ์ƒˆ๋กœ ์‹œ์ž‘ | + +### ์ œํ•œ ์‚ฌํ•ญ + +- Claude Code ์ธ์Šคํ„ด์Šค๋‹น ํ•˜๋‚˜์˜ ์›๊ฒฉ ์„ธ์…˜ +- ํ˜ธ์ŠคํŠธ ์ปดํ“จํ„ฐ์—์„œ ํ„ฐ๋ฏธ๋„์ด ์—ด๋ ค ์žˆ์–ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. +- ๋„คํŠธ์›Œํฌ์— ์—ฐ๊ฒฐํ•  ์ˆ˜ ์—†์œผ๋ฉด ์„ธ์…˜์ด ์•ฝ 10๋ถ„ ํ›„์— ์‹œ๊ฐ„ ์ดˆ๊ณผ๋ฉ๋‹ˆ๋‹ค. + +### ์‚ฌ์šฉ ์‚ฌ๋ก€ + +- ์ฑ…์ƒ์—์„œ ๋–จ์–ด์ ธ ์žˆ๋Š” ๋™์•ˆ ๋ชจ๋ฐ”์ผ ๊ธฐ๊ธฐ๋‚˜ ํƒœ๋ธ”๋ฆฟ์—์„œ Claude Code ์ œ์–ด +- ๋กœ์ปฌ ๋„๊ตฌ ์‹คํ–‰์„ ์œ ์ง€ํ•˜๋ฉด์„œ ํ’๋ถ€ํ•œ claude.ai UI ์‚ฌ์šฉ +- ์ „์ฒด ๋กœ์ปฌ ๊ฐœ๋ฐœ ํ™˜๊ฒฝ์œผ๋กœ ์ด๋™ ์ค‘ ๋น ๋ฅธ ์ฝ”๋“œ ๊ฒ€ํ†  + +### ํ‘ธ์‹œ ์•Œ๋ฆผ (v2.1.110) + +์›๊ฒฉ ์ œ์–ด๊ฐ€ ํ™œ์„ฑ ์ƒํƒœ์ด๊ณ  `/config`์—์„œ "Claude๊ฐ€ ๊ฒฐ์ •ํ•  ๋•Œ ํ‘ธ์‹œ"๊ฐ€ ํ™œ์„ฑํ™”๋˜์–ด ์žˆ์œผ๋ฉด Claude๋Š” ์‚ฌ์šฉ์ž ํœด๋Œ€ํฐ์œผ๋กœ ๋ชจ๋ฐ”์ผ ํ‘ธ์‹œ ์•Œ๋ฆผ์„ ๋ณด๋‚ผ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์˜ˆ๋ฅผ ๋“ค์–ด, ๊ธด ์ž‘์—…์ด ์™„๋ฃŒ๋˜๊ฑฐ๋‚˜ ์‚ฌ์šฉ์ž ์ž…๋ ฅ์ด ํ•„์š”ํ•  ๋•Œ์ž…๋‹ˆ๋‹ค. + +ํ™œ์„ฑํ™” ๋ฐฉ๋ฒ•: +1. ์›๊ฒฉ ์ œ์–ด ํ™œ์„ฑํ™”: `/remote-control` ๋˜๋Š” `claude --rc` +2. `/config`๋ฅผ ์—ด๊ณ  **Push when Claude decides**๋ฅผ ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค. + +ํ‘ธ์‹œ ์•Œ๋ฆผ์—๋Š” Claude ๊ตฌ๋… ๋ฐ Claude ๋ชจ๋ฐ”์ผ ์•ฑ์ด ํ•„์š”ํ•ฉ๋‹ˆ๋‹ค. + +### ์›๊ฒฉ ์ œ์–ด ๋น„ํ™œ์„ฑํ™” (`disableremotecontrol`, v2.1.128+) + +Team ๋˜๋Š” Enterprise ํ”Œ๋žœ์˜ ๊ด€๋ฆฌ์ž๋Š” `disableRemoteControl` ์„ค์ •์„ ์‚ฌ์šฉํ•˜์—ฌ ์›๊ฒฉ ์ œ์–ด๋ฅผ ์™„์ „ํžˆ ์ฐจ๋‹จํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. `true`๋กœ ์„ค์ •๋˜๋ฉด `claude remote-control`๊ณผ `/remote-control` ๋ชจ๋‘ ์‹œ์ž‘์„ ๊ฑฐ๋ถ€ํ•ฉ๋‹ˆ๋‹ค. + +```json +{ + "disableRemoteControl": true +} +``` + +์ด ์„ค์ •์€ **๊ด€๋ฆฌ/์ •์ฑ…** ๋ฒ”์œ„ (์˜ˆ: macOS์˜ `/Library/Application Support/ClaudeCode/managed-settings.json`)์—์„œ ์ ์šฉ๋˜๋ฏ€๋กœ ๊ฐœ๋ณ„ ์‚ฌ์šฉ์ž๊ฐ€ ์žฌ์ •์˜ํ•  ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค. ์กฐ์ง ์ „์ฒด์—์„œ ๋กœ์ปฌ ์ „์šฉ ์‹คํ–‰์„ ๊ฐ•์ œํ•ด์•ผ ํ•  ๋•Œ ์œ ์šฉํ•ฉ๋‹ˆ๋‹ค. + +> **API ํ‚ค ํ‹ฐ์–ด์— ์˜ํ•ด ์›๊ฒฉ ์ œ์–ด๊ฐ€ ์ž๋™ ๋น„ํ™œ์„ฑํ™”๋˜๋Š” ๊ฒฝ์šฐ (v2.1.139)**: `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `apiKeyHelper` ์ค‘ ํ•˜๋‚˜๋ผ๋„ ์„ค์ •๋˜์–ด ์žˆ์œผ๋ฉด ์›๊ฒฉ ์ œ์–ด๊ฐ€ **์ž๋™์œผ๋กœ ๋น„ํ™œ์„ฑํ™”๋ฉ๋‹ˆ๋‹ค**. claude.ai๋กœ ๋™์‹œ์— ๋กœ๊ทธ์ธ๋˜์–ด ์žˆ๋Š” ๊ฒฝ์šฐ์—๋„ ๋งˆ์ฐฌ๊ฐ€์ง€์ž…๋‹ˆ๋‹ค. +> +> ๋™์ผํ•œ ์กฐ๊ฑด์œผ๋กœ [`/schedule`](#์˜ˆ์•ฝ๋œ-์ž‘์—…), claude.ai MCP ์ปค๋„ฅํ„ฐ, ์•Œ๋ฆผ ์„ค์ •์ด ๋น„ํ™œ์„ฑํ™”๋ฉ๋‹ˆ๋‹ค. ์ด ๋„ค ๊ฐ€์ง€ claude.ai ์—ฐ๊ฒฐ ๊ธฐ๋Šฅ์€ OAuth ๋กœ๊ทธ์ธ์ด ํ™œ์„ฑ ์ž๊ฒฉ ์ฆ๋ช…์ผ ๋•Œ๋งŒ ์ž‘๋™ํ•ฉ๋‹ˆ๋‹ค. ์ด๋Ÿฌํ•œ ๊ธฐ๋Šฅ์„ ์‚ฌ์šฉํ•˜๋ ค๋ฉด API ํ‚ค๋ฅผ ํ•ด์ œํ•˜๊ฑฐ๋‚˜ Pro/Max OAuth ํ‹ฐ์–ด์—์„œ ์‹คํ–‰ํ•˜์‹ญ์‹œ์˜ค. + +--- + +## ์›น ์„ธ์…˜ + +์›น ์„ธ์…˜์„ ์‚ฌ์šฉํ•˜๋ฉด claude.ai/code์—์„œ ๋ธŒ๋ผ์šฐ์ € ๋‚ด์—์„œ ์ง์ ‘ Claude Code๋ฅผ ์‹คํ–‰ํ•˜๊ฑฐ๋‚˜ CLI์—์„œ ์›น ์„ธ์…˜์„ ์ƒ์„ฑํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +### ์›น ์„ธ์…˜ ์ƒ์„ฑ + +```bash +# CLI์—์„œ ์ƒˆ ์›น ์„ธ์…˜ ์ƒ์„ฑ +claude --remote "implement the new API endpoints" +``` + +์ด๋ ‡๊ฒŒ ํ•˜๋ฉด claude.ai์—์„œ Claude Code ์„ธ์…˜์ด ์‹œ์ž‘๋˜๋ฉฐ, ๋ชจ๋“  ๋ธŒ๋ผ์šฐ์ €์—์„œ ์•ก์„ธ์Šคํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +### ๋กœ์ปฌ์—์„œ ์›น ์„ธ์…˜ ๋‹ค์‹œ ์‹œ์ž‘ + +์›น์—์„œ ์„ธ์…˜์„ ์‹œ์ž‘ํ•˜๊ณ  ๋กœ์ปฌ์—์„œ ๊ณ„์†ํ•˜๋ ค๋ฉด: + +```bash +# ๋กœ์ปฌ ํ„ฐ๋ฏธ๋„์—์„œ ์›น ์„ธ์…˜ ๋‹ค์‹œ ์‹œ์ž‘ +claude --teleport +``` + +๋˜๋Š” ๋Œ€ํ™”ํ˜• REPL ๋‚ด์—์„œ: +``` +/teleport +``` + +### ์‚ฌ์šฉ ์‚ฌ๋ก€ + +- ํ•œ ์ปดํ“จํ„ฐ์—์„œ ์ž‘์—…์„ ์‹œ์ž‘ํ•˜๊ณ  ๋‹ค๋ฅธ ์ปดํ“จํ„ฐ์—์„œ ๊ณ„์† +- ํŒ€์›๊ณผ ์„ธ์…˜ URL ๊ณต์œ  +- ์‹œ๊ฐ์  ์ฐจ์ด ๊ฒ€ํ† ๋ฅผ ์œ„ํ•ด ์›น UI๋ฅผ ์‚ฌ์šฉํ•œ ๋‹ค์Œ ์‹คํ–‰์„ ์œ„ํ•ด ํ„ฐ๋ฏธ๋„๋กœ ์ „ํ™˜ + +--- + +## ๋ฐ์Šคํฌํ†ฑ ์•ฑ + +Claude Code ๋ฐ์Šคํฌํ†ฑ ์•ฑ์€ ์‹œ๊ฐ์  ์ฐจ์ด ๊ฒ€ํ† , ๋ณ‘๋ ฌ ์„ธ์…˜ ๋ฐ ํ†ตํ•ฉ ์ปค๋„ฅํ„ฐ๋ฅผ ๊ฐ–์ถ˜ ๋…๋ฆฝํ˜• ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜์„ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. macOS ๋ฐ Windows (Pro, Max, Team ๋ฐ Enterprise ํ”Œ๋žœ)์—์„œ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +### ์„ค์น˜ + +ํ”Œ๋žซํผ์— ๋งž๋Š” [claude.ai](https://claude.ai)์—์„œ ๋‹ค์šด๋กœ๋“œํ•˜์‹ญ์‹œ์˜ค: +- **macOS**: ์œ ๋‹ˆ๋ฒ„์„ค ๋นŒ๋“œ (Apple Silicon ๋ฐ Intel) +- **Windows**: x64 ๋ฐ ARM64 ์„ค์น˜ ํ”„๋กœ๊ทธ๋žจ ์‚ฌ์šฉ ๊ฐ€๋Šฅ + +์„ค์ • ์ง€์นจ์€ [๋ฐ์Šคํฌํ†ฑ ๋น ๋ฅธ ์‹œ์ž‘](https://code.claude.com/docs/en/desktop-quickstart)์„ ์ฐธ์กฐํ•˜์‹ญ์‹œ์˜ค. + +### CLI์—์„œ ํ•ธ๋“œ์˜คํ”„ + +ํ˜„์žฌ CLI ์„ธ์…˜์„ ๋ฐ์Šคํฌํ†ฑ ์•ฑ์œผ๋กœ ์ „์†กํ•ฉ๋‹ˆ๋‹ค: + +``` +/desktop +``` + +### ํ•ต์‹ฌ ๊ธฐ๋Šฅ + +| ๊ธฐ๋Šฅ | ์„ค๋ช… | +|---------|-------------| +| **์ฐจ์ด์  ๋ณด๊ธฐ** | ์ธ๋ผ์ธ ์ฃผ์„์ด ์žˆ๋Š” ํŒŒ์ผ๋ณ„ ์‹œ๊ฐ์  ๊ฒ€ํ† ; Claude๋Š” ์ฃผ์„์„ ์ฝ๊ณ  ์ˆ˜์ • | +| **์•ฑ ๋ฏธ๋ฆฌ๋ณด๊ธฐ** | ๋ผ์ด๋ธŒ ๊ฒ€์ฆ์„ ์œ„ํ•ด ์ž„๋ฒ ๋””๋“œ ๋ธŒ๋ผ์šฐ์ €์™€ ํ•จ๊ป˜ ๊ฐœ๋ฐœ ์„œ๋ฒ„ ์ž๋™ ์‹œ์ž‘ | +| **PR ๋ชจ๋‹ˆํ„ฐ๋ง** | CI ์˜ค๋ฅ˜ ์ž๋™ ์ˆ˜์ • ๋ฐ ๊ฒ€์‚ฌ๊ฐ€ ํ†ต๊ณผ๋˜๋ฉด ์ž๋™ ๋ณ‘ํ•ฉ๋˜๋Š” GitHub CLI ํ†ตํ•ฉ | +| **๋ณ‘๋ ฌ ์„ธ์…˜** | ์ž๋™ Git ์›ŒํฌํŠธ๋ฆฌ ๊ฒฉ๋ฆฌ๋ฅผ ํ†ตํ•ด ์‚ฌ์ด๋“œ๋ฐ”์— ์—ฌ๋Ÿฌ ์„ธ์…˜ ํ‘œ์‹œ | +| **์˜ˆ์•ฝ๋œ ์ž‘์—…** | ์•ฑ์ด ์—ด๋ ค ์žˆ๋Š” ๋™์•ˆ ์‹คํ–‰๋˜๋Š” ๋ฐ˜๋ณต ์ž‘์—… (์‹œ๊ฐ„๋ณ„, ์ผ๋ณ„, ์ฃผ์ค‘, ์ฃผ๋ณ„) | +| **ํ’๋ถ€ํ•œ ๋ Œ๋”๋ง** | ๊ตฌ๋ฌธ ๊ฐ•์กฐ ํ‘œ์‹œ๊ฐ€ ์žˆ๋Š” ์ฝ”๋“œ, ๋งˆํฌ๋‹ค์šด ๋ฐ ๋‹ค์ด์–ด๊ทธ๋žจ ๋ Œ๋”๋ง; GitHub-Flavored-Markdown ์ž‘์—… ๋ชฉ๋ก ํ™•์ธ๋ž€ (`- [ ]` / `- [x]`)์€ ํ™•์ธ๋ž€์œผ๋กœ ๋ Œ๋”๋ง๋ฉ๋‹ˆ๋‹ค (v2.1.149+) | + +### ์•ฑ ๋ฏธ๋ฆฌ๋ณด๊ธฐ ๊ตฌ์„ฑ + +`.claude/launch.json`์—์„œ ๊ฐœ๋ฐœ ์„œ๋ฒ„ ๋™์ž‘์„ ๊ตฌ์„ฑํ•ฉ๋‹ˆ๋‹ค: + +```json +{ + "command": "npm run dev", + "port": 3000, + "readyPattern": "ready on", + "persistCookies": true +} +``` + +### ์ปค๋„ฅํ„ฐ + +๋” ํ’๋ถ€ํ•œ ์ปจํ…์ŠคํŠธ๋ฅผ ์œ„ํ•ด ์™ธ๋ถ€ ์„œ๋น„์Šค๋ฅผ ์—ฐ๊ฒฐํ•ฉ๋‹ˆ๋‹ค: + +| ์ปค๋„ฅํ„ฐ | ๊ธฐ๋Šฅ | +|-----------|------------| +| **GitHub** | PR ๋ชจ๋‹ˆํ„ฐ๋ง, ์ด์Šˆ ์ถ”์ , ์ฝ”๋“œ ๊ฒ€ํ†  | +| **Slack** | ์•Œ๋ฆผ, ์ฑ„๋„ ์ปจํ…์ŠคํŠธ | +| **Linear** | ์ด์Šˆ ์ถ”์ , ์Šคํ”„๋ฆฐํŠธ ๊ด€๋ฆฌ | +| **Notion** | ๋ฌธ์„œํ™”, ์ง€์‹ ๊ธฐ๋ฐ˜ ์•ก์„ธ์Šค | +| **Asana** | ์ž‘์—… ๊ด€๋ฆฌ, ํ”„๋กœ์ ํŠธ ์ถ”์  | +| **Calendar** | ์ผ์ • ์ธ์‹, ํšŒ์˜ ์ปจํ…์ŠคํŠธ | + +> **์ฐธ๊ณ **: ์ปค๋„ฅํ„ฐ๋Š” ์›๊ฒฉ (ํด๋ผ์šฐ๋“œ) ์„ธ์…˜์—์„œ๋Š” ์‚ฌ์šฉํ•  ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค. + +### ์›๊ฒฉ ๋ฐ SSH ์„ธ์…˜ + +- **์›๊ฒฉ ์„ธ์…˜**: Anthropic ํด๋ผ์šฐ๋“œ ์ธํ”„๋ผ์—์„œ ์‹คํ–‰; ์•ฑ์ด ๋‹ซํ˜€๋„ ๊ณ„์† ์‹คํ–‰๋ฉ๋‹ˆ๋‹ค. claude.ai/code ๋˜๋Š” Claude ๋ชจ๋ฐ”์ผ ์•ฑ์—์„œ ์•ก์„ธ์Šคํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. +- **SSH ์„ธ์…˜**: SSH๋ฅผ ํ†ตํ•ด ์›๊ฒฉ ๋จธ์‹ ์— ์—ฐ๊ฒฐํ•˜์—ฌ ์›๊ฒฉ ํŒŒ์ผ ์‹œ์Šคํ…œ ๋ฐ ๋„๊ตฌ์— ์™„์ „ํžˆ ์•ก์„ธ์Šคํ•ฉ๋‹ˆ๋‹ค. Claude Code๋Š” ์›๊ฒฉ ๋จธ์‹ ์— ์„ค์น˜๋˜์–ด ์žˆ์–ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. + +### ๋ฐ์Šคํฌํ†ฑ์˜ ๊ถŒํ•œ ๋ชจ๋“œ + +๋ฐ์Šคํฌํ†ฑ ์•ฑ์€ CLI์™€ ๋™์ผํ•œ 4๊ฐ€์ง€ ๊ถŒํ•œ ๋ชจ๋“œ๋ฅผ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค: + +| ๋ชจ๋“œ | ๋™์ž‘ | +|------|----------| +| **๊ถŒํ•œ ์š”์ฒญ** (๊ธฐ๋ณธ๊ฐ’) | ๋ชจ๋“  ํŽธ์ง‘ ๋ฐ ๋ช…๋ น ๊ฒ€ํ†  ๋ฐ ์Šน์ธ | +| **์ž๋™ ํŽธ์ง‘ ์Šน์ธ** | ํŒŒ์ผ ํŽธ์ง‘์€ ์ž๋™ ์Šน์ธ; ๋ช…๋ น์€ ์ˆ˜๋™ ์Šน์ธ ํ•„์š” | +| **๊ณ„ํš ๋ชจ๋“œ** | ๋ณ€๊ฒฝ ์‚ฌํ•ญ์„ ์ ์šฉํ•˜๊ธฐ ์ „์— ์ ‘๊ทผ ๋ฐฉ์‹ ๊ฒ€ํ†  | +| **๊ถŒํ•œ ์šฐํšŒ** | ์ž๋™ ์‹คํ–‰ (์ƒŒ๋“œ๋ฐ•์Šค ์ „์šฉ, ๊ด€๋ฆฌ์ž ์ œ์–ด) | + +### ์—”ํ„ฐํ”„๋ผ์ด์ฆˆ ๊ธฐ๋Šฅ + +- **๊ด€๋ฆฌ์ž ์ฝ˜์†”**: ์กฐ์ง์˜ ์ฝ”๋“œ ํƒญ ์•ก์„ธ์Šค ๋ฐ ๊ถŒํ•œ ์„ค์ • ์ œ์–ด +- **MDM ๋ฐฐํฌ**: macOS์—์„œ๋Š” MDM, Windows์—์„œ๋Š” MSIX๋ฅผ ํ†ตํ•ด ๋ฐฐํฌ +- **SSO ํ†ตํ•ฉ**: ์กฐ์ง ๊ตฌ์„ฑ์›์— ๋Œ€ํ•œ ๋‹จ์ผ ๋กœ๊ทธ์ธ ํ•„์ˆ˜ํ™” +- **๊ด€๋ฆฌํ˜• ์„ค์ •**: ํŒ€ ๊ตฌ์„ฑ ๋ฐ ๋ชจ๋ธ ๊ฐ€์šฉ์„ฑ ์ค‘์•™ ๊ด€๋ฆฌ + +--- + +## ์ž‘์—… ๋ชฉ๋ก + +์ž‘์—… ๋ชฉ๋ก ๊ธฐ๋Šฅ์€ ์ปจํ…์ŠคํŠธ ์••์ถ• (๋Œ€ํ™” ๊ธฐ๋ก์ด ์ปจํ…์ŠคํŠธ ์ฐฝ์— ๋งž๊ฒŒ ์ž˜๋ฆด ๋•Œ) ํ›„์—๋„ ์œ ์ง€๋˜๋Š” ์˜๊ตฌ์ ์ธ ์ž‘์—… ์ถ”์  ๊ธฐ๋Šฅ์„ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. + +### ์ž‘์—… ๋ชฉ๋ก ์ „ํ™˜ + +์„ธ์…˜ ์ค‘์— `Ctrl+T`๋ฅผ ๋ˆŒ๋Ÿฌ ์ž‘์—… ๋ชฉ๋ก ๋ณด๊ธฐ๋ฅผ ์ผœ๊ฑฐ๋‚˜ ๋•๋‹ˆ๋‹ค. + +### ์˜๊ตฌ ์ž‘์—… + +์ž‘์—…์€ ์ปจํ…์ŠคํŠธ ์••์ถ• ํ›„์—๋„ ์œ ์ง€๋˜๋ฏ€๋กœ ๋Œ€ํ™” ์ปจํ…์ŠคํŠธ๊ฐ€ ์ž˜๋ฆด ๋•Œ ์žฅ๊ธฐ ์‹คํ–‰ ์ž‘์—… ํ•ญ๋ชฉ์ด ์†์‹ค๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ์ด๋Š” ๋ณต์žกํ•œ ๋‹ค๋‹จ๊ณ„ ๊ตฌํ˜„์— ํŠนํžˆ ์œ ์šฉํ•ฉ๋‹ˆ๋‹ค. + +### ๋ช…๋ช…๋œ ์ž‘์—… ๋””๋ ‰ํ† ๋ฆฌ + +`CLAUDE_CODE_TASK_LIST_ID` ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ์„ธ์…˜ ๊ฐ„์— ๊ณต์œ ๋˜๋Š” ๋ช…๋ช…๋œ ์ž‘์—… ๋””๋ ‰ํ† ๋ฆฌ๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค: + +```bash +export CLAUDE_CODE_TASK_LIST_ID=my-project-sprint-3 +``` + +์ด๋ฅผ ํ†ตํ•ด ์—ฌ๋Ÿฌ ์„ธ์…˜์ด ๋™์ผํ•œ ์ž‘์—… ๋ชฉ๋ก์„ ๊ณต์œ ํ•  ์ˆ˜ ์žˆ์œผ๋ฏ€๋กœ ํŒ€ ์›Œํฌํ”Œ๋กœ์šฐ ๋˜๋Š” ๋‹ค์ค‘ ์„ธ์…˜ ํ”„๋กœ์ ํŠธ์— ์œ ์šฉํ•ฉ๋‹ˆ๋‹ค. + +--- + +## ํ”„๋กฌํ”„ํŠธ ์ œ์•ˆ + +ํ”„๋กฌํ”„ํŠธ ์ œ์•ˆ์€ Git ๊ธฐ๋ก ๋ฐ ํ˜„์žฌ ๋Œ€ํ™” ์ปจํ…์ŠคํŠธ๋ฅผ ๊ธฐ๋ฐ˜์œผ๋กœ ํšŒ์ƒ‰์œผ๋กœ ํ‘œ์‹œ๋œ ์˜ˆ์‹œ ๋ช…๋ น์„ ํ‘œ์‹œํ•ฉ๋‹ˆ๋‹ค. + +### ์ž‘๋™ ๋ฐฉ์‹ + +- ์ž…๋ ฅ ํ”„๋กฌํ”„ํŠธ ์•„๋ž˜์— ํšŒ์ƒ‰ ํ…์ŠคํŠธ๋กœ ์ œ์•ˆ์ด ๋‚˜ํƒ€๋‚ฉ๋‹ˆ๋‹ค. +- `Tab`์„ ๋ˆŒ๋Ÿฌ ์ œ์•ˆ์„ ์ˆ˜๋ฝํ•ฉ๋‹ˆ๋‹ค. +- `Enter`๋ฅผ ๋ˆŒ๋Ÿฌ ์ˆ˜๋ฝํ•˜๊ณ  ์ฆ‰์‹œ ์ œ์ถœํ•ฉ๋‹ˆ๋‹ค. +- ์ œ์•ˆ์€ Git ๊ธฐ๋ก ๋ฐ ๋Œ€ํ™” ์ƒํƒœ์—์„œ ๊ฐ€์ ธ์˜จ ์ปจํ…์ŠคํŠธ ์ธ์‹์ž…๋‹ˆ๋‹ค. + +### ํ”„๋กฌํ”„ํŠธ ์ œ์•ˆ ๋น„ํ™œ์„ฑํ™” + +```bash +export CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false +``` + +--- + +## Git ์›ŒํฌํŠธ๋ฆฌ + +Git ์›ŒํฌํŠธ๋ฆฌ๋ฅผ ์‚ฌ์šฉํ•˜๋ฉด Claude Code๋ฅผ ๊ฒฉ๋ฆฌ๋œ ์›ŒํฌํŠธ๋ฆฌ์—์„œ ์‹œ์ž‘ํ•˜์—ฌ Stashํ•˜๊ฑฐ๋‚˜ ์ „ํ™˜ํ•  ํ•„์š” ์—†์ด ๋‹ค๋ฅธ ๋ธŒ๋žœ์น˜์—์„œ ๋ณ‘๋ ฌ ์ž‘์—…์„ ์ˆ˜ํ–‰ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +### ์›ŒํฌํŠธ๋ฆฌ์—์„œ ์‹œ์ž‘ + +```bash +# ๊ฒฉ๋ฆฌ๋œ ์›ŒํฌํŠธ๋ฆฌ์—์„œ Claude Code ์‹œ์ž‘ +claude --worktree +# ๋˜๋Š” +claude -w +``` + +### ์›ŒํฌํŠธ๋ฆฌ ์œ„์น˜ + +์›ŒํฌํŠธ๋ฆฌ๋Š” ๋‹ค์Œ ์œ„์น˜์— ์ƒ์„ฑ๋ฉ๋‹ˆ๋‹ค: +``` +/.claude/worktrees/ +``` + +### ๋ชจ๋…ธ๋ ˆํฌ๋ฅผ ์œ„ํ•œ ์ŠคํŒŒ์Šค ์ฒดํฌ์•„์›ƒ + +`worktree.sparsePaths` ์„ค์ •์„ ์‚ฌ์šฉํ•˜์—ฌ ๋ชจ๋…ธ๋ ˆํฌ์—์„œ ์ŠคํŒŒ์Šค ์ฒดํฌ์•„์›ƒ์„ ์ˆ˜ํ–‰ํ•˜์—ฌ ๋””์Šคํฌ ์‚ฌ์šฉ๋Ÿ‰๊ณผ ํด๋ก  ์‹œ๊ฐ„์„ ์ค„์ž…๋‹ˆ๋‹ค: + +```json +{ + "worktree": { + "sparsePaths": ["packages/my-package", "shared/"] + } +} +``` + +### ๊ธฐ๋ณธ ๋ธŒ๋žœ์น˜ ์ฐธ์กฐ (`worktree.baseRef`) + +**`worktree.baseRef`** (v2.1.133 ์ถ”๊ฐ€) โ€” `claude --worktree`๊ฐ€ `origin/`์—์„œ ๋ถ„๊ธฐํ• ์ง€ ์•„๋‹ˆ๋ฉด ๋กœ์ปฌ `HEAD`์—์„œ ๋ถ„๊ธฐํ• ์ง€๋ฅผ ์ œ์–ดํ•ฉ๋‹ˆ๋‹ค. + +- `"fresh"` (๊ธฐ๋ณธ๊ฐ’) โ€” `origin/`์—์„œ ๋ถ„๊ธฐํ•˜๋ฉฐ, ๋กœ์ปฌ ํ‘ธ์‹œ๋˜์ง€ ์•Š์€ ์ปค๋ฐ‹์„ ๋ฌด์‹œํ•ฉ๋‹ˆ๋‹ค. **์ด๋Š” v2.1.128์—์„œ ๋„์ž…๋œ ๋™์ž‘์„ ๋˜๋Œ๋ฆฝ๋‹ˆ๋‹ค.** ๋”ฐ๋ผ์„œ v2.1.128 ์ดํ›„ ๋กœ์ปฌ-HEAD ๋ถ„๊ธฐ์— ์˜์กดํ–ˆ๋˜ ์‚ฌ์šฉ์ž๋Š” ๋‹ค์‹œ ์˜ตํŠธ์ธํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. +- `"head"` โ€” ๋กœ์ปฌ `HEAD`์—์„œ ๋ถ„๊ธฐํ•˜๋ฉฐ, ํ‘ธ์‹œ๋˜์ง€ ์•Š์€ ์ปค๋ฐ‹์„ ๋ณด์กดํ•ฉ๋‹ˆ๋‹ค. + +`~/.claude/settings.json`์—์„œ ์„ค์ •: + +```json +{ "worktree": { "baseRef": "head" } } +``` + +### ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์„ธ์…˜ ๊ฒฉ๋ฆฌ (`worktree.bgIsolation`) + +**`worktree.bgIsolation`** (v2.1.143 ์ถ”๊ฐ€) โ€” ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์„ธ์…˜ (์˜ˆ: `/bg`, `claude --bg`, ๋˜๋Š” ์—์ด์ „ํŠธ ๋ณด๊ธฐ์—์„œ)์ด ์ž์ฒด ์›ŒํฌํŠธ๋ฆฌ๋ฅผ ๊ฐ€์งˆ์ง€ ์•„๋‹ˆ๋ฉด ํฌ๊ทธ๋ผ์šด๋“œ ์ž‘์—… ๋ณต์‚ฌ๋ณธ์„ ์ง์ ‘ ํŽธ์ง‘ํ• ์ง€๋ฅผ ์ œ์–ดํ•ฉ๋‹ˆ๋‹ค. + +- *(๊ธฐ๋ณธ๊ฐ’)* โ€” ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์„ธ์…˜์€ `--worktree`์™€ ๋™์ผํ•œ ๋ฐฉ์‹์œผ๋กœ `/.claude/worktrees/` ์•„๋ž˜์— ๊ฒฉ๋ฆฌ๋œ ์›ŒํฌํŠธ๋ฆฌ๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. +- `"none"` โ€” ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์„ธ์…˜์€ ํ˜„์žฌ ์ž‘์—… ๋ณต์‚ฌ๋ณธ์„ ์ง์ ‘ ํŽธ์ง‘ํ•ฉ๋‹ˆ๋‹ค. ์›ŒํฌํŠธ๋ฆฌ๊ฐ€ ๋น„์‹ค์šฉ์ ์ธ ๊ฒฝ์šฐ (์˜ˆ: ๋Œ€๊ทœ๋ชจ ๋„ค์ดํ‹ฐ๋ธŒ ๋นŒ๋“œ ์•„ํ‹ฐํŒฉํŠธ) ๋˜๋Š” ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์—์ด์ „ํŠธ๊ฐ€ ํฌ๊ทธ๋ผ์šด๋“œ ์„ธ์…˜๊ณผ ํŽธ์ง‘์„ ์กฐ์œจํ•ด์•ผ ํ•˜๋Š” ๊ฒฝ์šฐ์— ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค. + +```json +{ "worktree": { "bgIsolation": "none" } } +``` + +์žฅ๋‹จ์ : `"none"`์€ ์›ŒํฌํŠธ๋ฆฌ ๊ฒฉ๋ฆฌ์˜ ์•ˆ์ „๋ง์„ ์ œ๊ฑฐํ•ฉ๋‹ˆ๋‹ค. ๋ฐฑ๊ทธ๋ผ์šด๋“œ ๋ฐ ํฌ๊ทธ๋ผ์šด๋“œ ์„ธ์…˜์˜ ๋™์‹œ ํŽธ์ง‘์€ ๋ผ์ด๋ธŒ ์ž‘์—… ๋ณต์‚ฌ๋ณธ์—์„œ ๋ณ‘ํ•ฉ ์ถฉ๋Œ์„ ์ผ์œผํ‚ฌ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +### ์›ŒํฌํŠธ๋ฆฌ ๋„๊ตฌ ๋ฐ ํ›… + +| ํ•ญ๋ชฉ | ์„ค๋ช… | +|------|-------------| +| `EnterWorktree` | ์›ŒํฌํŠธ๋ฆฌ์— ์ง„์ž…ํ•˜๋Š” ๋„๊ตฌ; v2.1.157๋ถ€ํ„ฐ ์„ธ์…˜ ์ค‘์— Claude ๊ด€๋ฆฌ ์›ŒํฌํŠธ๋ฆฌ ๊ฐ„ ์ „ํ™˜ ๊ฐ€๋Šฅ | +| `ExitWorktree` | ํ˜„์žฌ ์›ŒํฌํŠธ๋ฆฌ๋ฅผ ์ข…๋ฃŒํ•˜๊ณ  ์ •๋ฆฌํ•˜๋Š” ๋„๊ตฌ | +| `WorktreeCreate` | ์›ŒํฌํŠธ๋ฆฌ๊ฐ€ ์ƒ์„ฑ๋  ๋•Œ ๋ฐœ์ƒํ•˜๋Š” ํ›… ์ด๋ฒคํŠธ | +| `WorktreeRemove` | ์›ŒํฌํŠธ๋ฆฌ๊ฐ€ ์ œ๊ฑฐ๋  ๋•Œ ๋ฐœ์ƒํ•˜๋Š” ํ›… ์ด๋ฒคํŠธ | + +v2.1.157๋ถ€ํ„ฐ Claude๊ฐ€ ๊ด€๋ฆฌํ•˜๋Š” ์›ŒํฌํŠธ๋ฆฌ๋Š” ์—์ด์ „ํŠธ๊ฐ€ ์ž‘์—…์„ ๋งˆ์นœ ํ›„ ์ž ๊ธˆ ํ•ด์ œ๋˜๋ฏ€๋กœ `git worktree remove`/`prune`์œผ๋กœ ์ •๋ฆฌํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +### ์ž๋™ ์ •๋ฆฌ + +์›ŒํฌํŠธ๋ฆฌ์—์„œ ๋ณ€๊ฒฝ ์‚ฌํ•ญ์ด ์—†์œผ๋ฉด ์„ธ์…˜์ด ์ข…๋ฃŒ๋  ๋•Œ ์ž๋™์œผ๋กœ ์ •๋ฆฌ๋ฉ๋‹ˆ๋‹ค. + +### ์‚ฌ์šฉ ์‚ฌ๋ก€ + +- ๋ฉ”์ธ ๋ธŒ๋žœ์น˜๋ฅผ ๊ฑด๋“œ๋ฆฌ์ง€ ์•Š๊ณ  ๊ธฐ๋Šฅ ๋ธŒ๋žœ์น˜์—์„œ ์ž‘์—… +- ์ž‘์—… ๋””๋ ‰ํ† ๋ฆฌ์— ์˜ํ–ฅ์„ ๋ฏธ์น˜์ง€ ์•Š๊ณ  ๊ฒฉ๋ฆฌ๋œ ํ™˜๊ฒฝ์—์„œ ํ…Œ์ŠคํŠธ ์‹คํ–‰ +- ์ผํšŒ์šฉ ํ™˜๊ฒฝ์—์„œ ์‹คํ—˜์ ์ธ ๋ณ€๊ฒฝ ์‹œ๋„ +- ๋” ๋น ๋ฅธ ์‹œ์ž‘์„ ์œ„ํ•ด ๋ชจ๋…ธ๋ ˆํฌ์—์„œ ํŠน์ • ํŒจํ‚ค์ง€ ์ŠคํŒŒ์Šค ์ฒดํฌ์•„์›ƒ + +--- + +## ์ƒŒ๋“œ๋ฐ•์‹ฑ + +์ƒŒ๋“œ๋ฐ•์‹ฑ์€ Claude Code์— ์˜ํ•ด ์‹คํ–‰๋˜๋Š” Bash ๋ช…๋ น์— OS ์ˆ˜์ค€์˜ ํŒŒ์ผ ์‹œ์Šคํ…œ ๋ฐ ๋„คํŠธ์›Œํฌ ๊ฒฉ๋ฆฌ๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. ์ด๋Š” ๊ถŒํ•œ ๊ทœ์น™์„ ๋ณด์™„ํ•˜๋ฉฐ ์ถ”๊ฐ€ ๋ณด์•ˆ ๊ณ„์ธต์„ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. + +### ์ƒŒ๋“œ๋ฐ•์‹ฑ ํ™œ์„ฑํ™” + +**์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด**: +``` +/sandbox +``` + +**CLI ํ”Œ๋ž˜๊ทธ**: +```bash +claude --sandbox # ์ƒŒ๋“œ๋ฐ•์‹ฑ ํ™œ์„ฑํ™” +claude --no-sandbox # ์ƒŒ๋“œ๋ฐ•์‹ฑ ๋น„ํ™œ์„ฑํ™” +``` + +### ๊ตฌ์„ฑ ์„ค์ • + +| ์„ค์ • | ์„ค๋ช… | +|---------|-------------| +| `sandbox.enabled` | ์ƒŒ๋“œ๋ฐ•์‹ฑ ํ™œ์„ฑํ™” ๋˜๋Š” ๋น„ํ™œ์„ฑํ™” | +| `sandbox.failIfUnavailable` | ์ƒŒ๋“œ๋ฐ•์‹ฑ์„ ํ™œ์„ฑํ™”ํ•  ์ˆ˜ ์—†๋Š” ๊ฒฝ์šฐ ์‹คํŒจ | +| `sandbox.filesystem.allowWrite` | ์“ฐ๊ธฐ ์•ก์„ธ์Šค ํ—ˆ์šฉ ๊ฒฝ๋กœ | +| `sandbox.filesystem.allowRead` | ์ฝ๊ธฐ ์•ก์„ธ์Šค ํ—ˆ์šฉ ๊ฒฝ๋กœ | +| `sandbox.filesystem.denyRead` | ์ฝ๊ธฐ ์•ก์„ธ์Šค ๊ฑฐ๋ถ€ ๊ฒฝ๋กœ | +| `sandbox.network.allowedDomains` | Bash๋กœ ์‹œ์ž‘๋œ ํ”„๋กœ์„ธ์Šค๊ฐ€ ๋„๋‹ฌํ•  ์ˆ˜ ์žˆ๋Š” ๋„๋ฉ”์ธ ( `*.` ์™€์ผ๋“œ์นด๋“œ ์ง€์›) | +| `sandbox.network.deniedDomains` | `allowedDomains` ์™€์ผ๋“œ์นด๋“œ๊ฐ€ ํ—ˆ์šฉํ•˜๋”๋ผ๋„ ์ฐจ๋‹จํ•  ๋„๋ฉ”์ธ (v2.1.113+) | +| `sandbox.enableWeakerNetworkIsolation` | macOS์—์„œ ์•ฝํ•œ ๋„คํŠธ์›Œํฌ ๊ฒฉ๋ฆฌ ํ™œ์„ฑํ™” | +| `sandbox.bwrapPath` | (v2.1.133+, Linux/WSL) `bubblewrap` ๋ฐ”์ด๋„ˆ๋ฆฌ ๊ฒฝ๋กœ. ๊ธฐ๋ณธ๊ฐ’: `$PATH` ์กฐํšŒ. | +| `sandbox.socatPath` | (v2.1.133+, Linux/WSL) `socat` ๋ฐ”์ด๋„ˆ๋ฆฌ ๊ฒฝ๋กœ. ๊ธฐ๋ณธ๊ฐ’: `$PATH` ์กฐํšŒ. | +| `sandbox.credentials` | (v2.1.187+) ์ƒŒ๋“œ๋ฐ•์Šค ๋ช…๋ น์ด ์ž๊ฒฉ ์ฆ๋ช… ํŒŒ์ผ ๋ฐ ๋น„๋ฐ€ ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋ฅผ ์ฝ๋Š” ๊ฒƒ์„ ์ฐจ๋‹จํ•ฉ๋‹ˆ๋‹ค. | +| `sandbox.allowAppleEvents` | (v2.1.181+, macOS) ์ƒŒ๋“œ๋ฐ•์Šค ๋ช…๋ น์ด Apple Event๋ฅผ ๋ณด๋‚ด๋„๋ก ์˜ตํŠธ์ธํ•ฉ๋‹ˆ๋‹ค. | + +**Linux/WSL ๋ฐ”์ด๋„ˆ๋ฆฌ ๊ฒฝ๋กœ** (v2.1.133+) โ€” ๋น„ํ‘œ์ค€ ์„ค์น˜ ์œ„์น˜์—์„œ Claude Code๋ฅผ ๊ฐ€๋ฆฌํ‚ต๋‹ˆ๋‹ค: + +```json +{ + "sandbox": { + "bwrapPath": "/opt/bubblewrap/bin/bwrap", + "socatPath": "/opt/socat/bin/socat" + } +} +``` + +๊ด‘๋ฒ”์œ„ํ•œ ์™€์ผ๋“œ์นด๋“œ๋ฅผ ์žฌ์ •์˜ํ•˜๋Š” `deniedDomains`์˜ ์˜ˆ์‹œ (v2.1.113+): + +```json +{ + "sandbox": { + "network": { + "allowedDomains": ["*.example.com"], + "deniedDomains": ["evil.example.com"] + } + } +} +``` + +์™€์ผ๋“œ์นด๋“œ๋Š” `example.com`์˜ ๋ชจ๋“  ๊ฒƒ์„ ํ—ˆ์šฉํ•˜์ง€๋งŒ, `deniedDomains`๋Š” ํŠน์ • ์ด๋ฆ„์˜ ํ˜ธ์ŠคํŠธ๋ฅผ ์—ฌ์ „ํžˆ ์ฐจ๋‹จํ•ฉ๋‹ˆ๋‹ค. + +### ์˜ˆ์‹œ ๊ตฌ์„ฑ + +```json +{ + "sandbox": { + "enabled": true, + "failIfUnavailable": true, + "filesystem": { + "allowWrite": ["/Users/me/project"], + "allowRead": ["/Users/me/project", "/usr/local/lib"], + "denyRead": ["/Users/me/.ssh", "/Users/me/.aws"] + }, + "enableWeakerNetworkIsolation": true + } +} +``` + +### ์ž‘๋™ ๋ฐฉ์‹ + +- Bash ๋ช…๋ น์€ ์ œํ•œ๋œ ํŒŒ์ผ ์‹œ์Šคํ…œ ์•ก์„ธ์Šค๋ฅผ ๊ฐ€์ง„ ์ƒŒ๋“œ๋ฐ•์Šค ํ™˜๊ฒฝ์—์„œ ์‹คํ–‰๋ฉ๋‹ˆ๋‹ค. +- ์˜๋„์น˜ ์•Š์€ ์™ธ๋ถ€ ์—ฐ๊ฒฐ์„ ๋ฐฉ์ง€ํ•˜๊ธฐ ์œ„ํ•ด ๋„คํŠธ์›Œํฌ ์•ก์„ธ์Šค๋ฅผ ๊ฒฉ๋ฆฌํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. +- ์‹ฌ์ธต ๋ฐฉ์–ด๋ฅผ ์œ„ํ•ด ๊ถŒํ•œ ๊ทœ์น™๊ณผ ํ•จ๊ป˜ ์ž‘๋™ํ•ฉ๋‹ˆ๋‹ค. +- macOS์—์„œ๋Š” ๋„คํŠธ์›Œํฌ ์ œํ•œ์„ ์œ„ํ•ด `sandbox.enableWeakerNetworkIsolation`์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค (macOS์—์„œ๋Š” ์ „์ฒด ๋„คํŠธ์›Œํฌ ๊ฒฉ๋ฆฌ๊ฐ€ ๋ถˆ๊ฐ€๋Šฅํ•ฉ๋‹ˆ๋‹ค). + +### ์‚ฌ์šฉ ์‚ฌ๋ก€ + +- ์‹ ๋ขฐํ•  ์ˆ˜ ์—†๊ฑฐ๋‚˜ ์ƒ์„ฑ๋œ ์ฝ”๋“œ๋ฅผ ์•ˆ์ „ํ•˜๊ฒŒ ์‹คํ–‰ +- ํ”„๋กœ์ ํŠธ ์™ธ๋ถ€ ํŒŒ์ผ์— ๋Œ€ํ•œ ์šฐ๋ฐœ์ ์ธ ์ˆ˜์ • ๋ฐฉ์ง€ +- ์ž๋™ํ™”๋œ ์ž‘์—… ์ค‘ ๋„คํŠธ์›Œํฌ ์•ก์„ธ์Šค ์ œํ•œ + +--- + +## ๊ด€๋ฆฌํ˜• ์„ค์ • (์—”ํ„ฐํ”„๋ผ์ด์ฆˆ) + +๊ด€๋ฆฌํ˜• ์„ค์ •์€ ์—”ํ„ฐํ”„๋ผ์ด์ฆˆ ๊ด€๋ฆฌ์ž๊ฐ€ ํ”Œ๋žซํผ ๊ณ ์œ ์˜ ๊ด€๋ฆฌ ๋„๊ตฌ๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ์กฐ์ง ์ „์ฒด์— Claude Code ๊ตฌ์„ฑ์„ ๋ฐฐํฌํ•  ์ˆ˜ ์žˆ๋„๋ก ํ•ฉ๋‹ˆ๋‹ค. + +### ๋ฐฐํฌ ๋ฐฉ๋ฒ• + +| ํ”Œ๋žซํผ | ๋ฐฉ๋ฒ• | ์ดํ›„ ๋ฒ„์ „ | +|----------|--------|-------| +| macOS | ๊ด€๋ฆฌํ˜• plist ํŒŒ์ผ (MDM) | v2.1.51+ | +| Windows | Windows ๋ ˆ์ง€์ŠคํŠธ๋ฆฌ | v2.1.51+ | +| ํฌ๋กœ์Šค ํ”Œ๋žซํผ | ๊ด€๋ฆฌํ˜• ๊ตฌ์„ฑ ํŒŒ์ผ | v2.1.51+ | +| ํฌ๋กœ์Šค ํ”Œ๋žซํผ | ๊ด€๋ฆฌํ˜• ๋“œ๋กญ์ธ (`managed-settings.d/` ๋””๋ ‰ํ† ๋ฆฌ) | v2.1.83+ | + +### ๊ด€๋ฆฌํ˜• ๋“œ๋กญ์ธ + +v2.1.83๋ถ€ํ„ฐ ๊ด€๋ฆฌ์ž๋Š” `managed-settings.d/` ๋””๋ ‰ํ† ๋ฆฌ์— ์—ฌ๋Ÿฌ ๊ด€๋ฆฌํ˜• ์„ค์ • ํŒŒ์ผ์„ ๋ฐฐํฌํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ํŒŒ์ผ์€ ์•ŒํŒŒ๋ฒณ์ˆœ์œผ๋กœ ๋ณ‘ํ•ฉ๋˜์–ด ํŒ€ ๊ฐ„์— ๋ชจ๋“ˆํ˜• ๊ตฌ์„ฑ์„ ๊ฐ€๋Šฅํ•˜๊ฒŒ ํ•ฉ๋‹ˆ๋‹ค: + +``` +~/.claude/managed-settings.d/ + 00-org-defaults.json + 10-team-policies.json + 20-project-overrides.json +``` + +### ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ๊ด€๋ฆฌํ˜• ์„ค์ • + +| ์„ค์ • | ์„ค๋ช… | +|---------|-------------| +| `disableBypassPermissionsMode` | ์‚ฌ์šฉ์ž๊ฐ€ ๊ถŒํ•œ ์šฐํšŒ ๋ชจ๋“œ๋ฅผ ํ™œ์„ฑํ™”ํ•˜์ง€ ๋ชปํ•˜๋„๋ก ๋ฐฉ์ง€ | +| `availableModels` | ์‚ฌ์šฉ์ž๊ฐ€ ์„ ํƒํ•  ์ˆ˜ ์žˆ๋Š” ๋ชจ๋ธ ์ œํ•œ | +| `enforceAvailableModels` | (v2.1.175) `true`์ธ ๊ฒฝ์šฐ, `availableModels` ํ—ˆ์šฉ ๋ชฉ๋ก์€ **๊ธฐ๋ณธ** ๋ชจ๋ธ๋„ ์ œํ•œํ•ฉ๋‹ˆ๋‹ค. ๊ตฌ์„ฑ๋œ ๊ธฐ๋ณธ๊ฐ’์ด ๋ชฉ๋ก์— ์—†์œผ๋ฉด Claude Code๋Š” ํ—ˆ์šฉ๋œ ์ฒซ ๋ฒˆ์งธ ๋ชจ๋ธ๋กœ ๋Œ€์ฒด๋ฉ๋‹ˆ๋‹ค. ์‚ฌ์šฉ์ž ๋ฐ ํ”„๋กœ์ ํŠธ ์„ค์ •์€ ๋” ์ด์ƒ ๊ด€๋ฆฌ๋˜๋Š” `availableModels` ๋ชฉ๋ก์„ ํ™•์žฅํ•  ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค. | +| `allowedChannelPlugins` | ํ—ˆ์šฉ๋˜๋Š” ์ฑ„๋„ ํ”Œ๋Ÿฌ๊ทธ์ธ ์ œ์–ด | +| `autoMode.environment` | ์ž๋™ ๋ชจ๋“œ์— ๋Œ€ํ•œ ์‹ ๋ขฐํ•  ์ˆ˜ ์žˆ๋Š” ์ธํ”„๋ผ ๊ตฌ์„ฑ | +| `wslInheritsWindowsSettings` | Windows/WSL ์ „์šฉ (v2.1.118+): `true`์ธ ๊ฒฝ์šฐ, WSL ๋‚ด์—์„œ ์‹คํ–‰๋˜๋Š” Claude Code๋Š” Windows ํ˜ธ์ŠคํŠธ์˜ ๊ด€๋ฆฌ๋˜๋Š” ์„ค์ •์„ ์ƒ์†ํ•˜๋ฏ€๋กœ ๋ ˆ์ง€์ŠคํŠธ๋ฆฌ/MDM์„ ํ†ตํ•ด ๋ฐฐํฌ๋œ ์—”ํ„ฐํ”„๋ผ์ด์ฆˆ ์ •์ฑ…์ด Windows ๋ฐ WSL ์‰˜ ์ „์ฒด์— ๊ท ์ผํ•˜๊ฒŒ ์ ์šฉ๋ฉ๋‹ˆ๋‹ค. | +| `parentSettingsBehavior` | (v2.1.133+, ๊ด€๋ฆฌ์ž ๊ณ„์ธต) SDK์˜ `managedSettings`๊ฐ€ ๋ถ€๋ชจ ํ”„๋กœ์„ธ์Šค ์„ค์ •๊ณผ ๋ณ‘ํ•ฉ๋˜๋Š” ๋ฐฉ์‹์„ ์ œ์–ดํ•ฉ๋‹ˆ๋‹ค. `"first-wins"`๋Š” ๊ธฐ์กด ์šฐ์„  ์ˆœ์œ„๋ฅผ ์œ ์ง€ํ•˜๊ณ  (์ถฉ๋Œ ์‹œ ๋จผ์ € ์„ค์ •๋œ ๊ฒƒ์ด ์Šน๋ฆฌ), `"merge"`๋Š” ๊ฐ’์„ ๊นŠ์ด ๋ณ‘ํ•ฉํ•ฉ๋‹ˆ๋‹ค. | +| ์‚ฌ์šฉ์ž ์ง€์ • ์ •์ฑ… | ์กฐ์ง๋ณ„ ๊ถŒํ•œ ๋ฐ ๋„๊ตฌ ์ •์ฑ… | + +### ์˜ˆ์‹œ: macOS Plist + +```xml + + + + + disableBypassPermissionsMode + + availableModels + + claude-sonnet-4-6 + claude-haiku-4-5 + + + +``` + +--- + +## ๊ตฌ์„ฑ ๋ฐ ์„ค์ • + +### ๊ตฌ์„ฑ ํŒŒ์ผ ์œ„์น˜ + +1. **์ „์—ญ ๊ตฌ์„ฑ**: `~/.claude/config.json` +2. **ํ”„๋กœ์ ํŠธ ๊ตฌ์„ฑ**: `./.claude/config.json` +3. **์‚ฌ์šฉ์ž ๊ตฌ์„ฑ**: `~/.config/claude-code/settings.json` + +### ์ „์ฒด ๊ตฌ์„ฑ ์˜ˆ์‹œ + +**ํ•ต์‹ฌ ๊ณ ๊ธ‰ ๊ธฐ๋Šฅ ๊ตฌ์„ฑ:** + +```json +{ + "permissions": { + "mode": "default" + }, + "hooks": { + "PreToolUse:Edit": "eslint --fix ${file_path}", + "PostToolUse:Write": "~/.claude/hooks/security-scan.sh" + }, + "mcp": { + "enabled": true, + "servers": { + "github": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github"] + } + } + } +} +``` + +**ํ™•์žฅ ๊ตฌ์„ฑ ์˜ˆ์‹œ:** + +```json +{ + "permissions": { + "mode": "default", + "allowedTools": ["Bash(git log:*)", "Read"], + "disallowedTools": ["Bash(rm -rf:*)"] + }, + + "hooks": { + "PreToolUse": [{ "matcher": "Edit", "hooks": ["eslint --fix ${file_path}"] }], + "PostToolUse": [{ "matcher": "Write", "hooks": ["~/.claude/hooks/security-scan.sh"] }], + "Stop": [{ "hooks": ["~/.claude/hooks/notify.sh"] }] + }, + + "mcp": { + "enabled": true, + "servers": { + "github": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github"], + "env": { + "GITHUB_TOKEN": "${GITHUB_TOKEN}" + } + } + } + } +} +``` + +### ๋Œ€์ฒด ๋ชจ๋ธ (`fallbackModel`) + +`fallbackModel` ์„ค์ •์„ ์‚ฌ์šฉํ•˜๋ฉด ๊ธฐ๋ณธ ๋ชจ๋ธ์ด ๊ณผ๋ถ€ํ•˜๋˜๊ฑฐ๋‚˜ ์‚ฌ์šฉํ•  ์ˆ˜ ์—†์„ ๋•Œ ์ˆœ์„œ๋Œ€๋กœ ์‹œ๋„๋˜๋Š” **์ตœ๋Œ€ 3๊ฐœ์˜** ๋Œ€์ฒด ๋ชจ๋ธ์„ ๊ตฌ์„ฑํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +```json +{ + "fallbackModel": ["claude-opus-4-8", "claude-sonnet-4-6", "claude-haiku-4-5"] +} +``` + +**v2.1.166๋ถ€ํ„ฐ** `--fallback-model` ํ”Œ๋ž˜๊ทธ๋Š” ๋Œ€ํ™”ํ˜• ์„ธ์…˜์—๋„ ์ ์šฉ๋ฉ๋‹ˆ๋‹ค (ํ—ค๋“œ๋ฆฌ์Šค๋ฟ๋งŒ ์•„๋‹ˆ๋ผ). ๋Œ€์ฒด ์‹œ Claude Code๋Š” ์˜ˆ๊ธฐ์น˜ ์•Š์€ ์žฌ์‹œ๋„ ๋ถˆ๊ฐ€๋Šฅํ•œ ์˜ค๋ฅ˜๋ฅผ ํ•œ ๋ฒˆ ์žฌ์‹œ๋„ํ•ฉ๋‹ˆ๋‹ค. ์ธ์ฆ, ์†๋„ ์ œํ•œ, ์š”์ฒญ ํฌ๊ธฐ ๋ฐ ์ „์†ก ์˜ค๋ฅ˜๋Š” ์ฆ‰์‹œ ์‹คํŒจํ•ฉ๋‹ˆ๋‹ค. + +### ํ™˜๊ฒฝ ๋ณ€์ˆ˜ + +ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋กœ ๊ตฌ์„ฑ์„ ์žฌ์ •์˜ํ•ฉ๋‹ˆ๋‹ค: + +```bash +# Model selection +export ANTHROPIC_MODEL=claude-opus-4-8 +export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-8 +export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6 +export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5 + +# API configuration +export ANTHROPIC_API_KEY=sk-ant-... + +# Thinking configuration +export MAX_THINKING_TOKENS=16000 +export CLAUDE_CODE_EFFORT_LEVEL=high # low, medium, high, xhigh (Opus 4.8/4.7), or max โ€” default is high on Opus 4.8 (supported on Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 4.6) + +# Feature toggles +export CLAUDE_CODE_DISABLE_AUTO_MEMORY=true +export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=true +export CLAUDE_CODE_DISABLE_CRON=1 +export CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=true +export CLAUDE_CODE_DISABLE_TERMINAL_TITLE=true +export CLAUDE_CODE_DISABLE_1M_CONTEXT=true +export CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=true +export CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false +export CLAUDE_CODE_ENABLE_TASKS=true +export CLAUDE_CODE_SIMPLE=true # Set by --bare flag + +# MCP configuration +export MAX_MCP_OUTPUT_TOKENS=50000 +export ENABLE_TOOL_SEARCH=true + +# Prompt caching +export ENABLE_PROMPT_CACHING_1H=1 # Use 1-hour prompt cache TTL (default is 5 min) + +# Task management +export CLAUDE_CODE_TASK_LIST_ID=my-project-tasks + +# Agent teams (experimental) +export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 + +# Subagent and plugin configuration +export CLAUDE_CODE_SUBAGENT_MODEL=sonnet +export CLAUDE_CODE_PLUGIN_SEED_DIR=./my-plugins +export CLAUDE_CODE_NEW_INIT=1 + +# Subprocess and streaming +export CLAUDE_CODE_SUBPROCESS_ENV_SCRUB="SECRET_KEY,DB_PASSWORD" +export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80 +export CLAUDE_STREAM_IDLE_TIMEOUT_MS=30000 +export ANTHROPIC_CUSTOM_MODEL_OPTION=my-custom-model +export SLASH_COMMAND_TOOL_CHAR_BUDGET=50000 + +# Output and package manager (v2.1.129+) +export CLAUDE_CODE_FORCE_SYNC_OUTPUT=1 # Force synchronous output for terminals where auto-detect misses (Emacs eat, etc.) +export CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 # Enable background upgrades for Homebrew/WinGet installs +export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 # Opt in to /v1/models gateway discovery when ANTHROPIC_BASE_URL is set + +# Windows PowerShell tool (v2.1.143+) โ€” default-on for Bedrock/Vertex/Foundry on Windows +export CLAUDE_CODE_USE_POWERSHELL_TOOL=0 # Disable the PowerShell tool entirely +export CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1 # Honor system ExecutionPolicy instead of `-ExecutionPolicy Bypass` + +# Workload identity federation (v2.1.141+) +export ANTHROPIC_WORKSPACE_ID=ws_abc123 # Scope the federated token to a specific workspace when the rule covers multiple + +# Stop hook safety cap (v2.1.143+) +export CLAUDE_CODE_STOP_HOOK_BLOCK_CAP=8 # Max consecutive Stop-hook blocks before the session ends with a warning. Set 0 to disable the cap. +``` + +> **v2.1.108**: `ENABLE_PROMPT_CACHING_1H=1` โ€” ๊ธฐ๋ณธ 5๋ถ„ TTL ๋Œ€์‹  1์‹œ๊ฐ„ ํ”„๋กฌํ”„ํŠธ ์บ์‹œ TTL์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. ๊ธธ๊ณ  ์•ˆ์ •์ ์ธ ์„ธ์…˜์—์„œ ์บ์‹œ ๋ˆ„๋ฝ์„ ์ค„์ž…๋‹ˆ๋‹ค. (v2.1.129๋Š” 1์‹œ๊ฐ„ TTL์ด ์ž๋™์œผ๋กœ 5๋ถ„์œผ๋กœ ๋‹ค์šด๊ทธ๋ ˆ์ด๋“œ๋˜๋˜ ํšŒ๊ท€ ๋ฒ„๊ทธ๋ฅผ ์ˆ˜์ •ํ•ฉ๋‹ˆ๋‹ค.) + +> **v2.1.129**: `CLAUDE_CODE_FORCE_SYNC_OUTPUT=1`์€ ์ž๋™ ๊ฐ์ง€๊ฐ€ ์‹คํŒจํ•˜๋Š” ํ„ฐ๋ฏธ๋„ (์˜ˆ: Emacs `eat`)์— ๋Œ€ํ•ด ๋™๊ธฐ์‹ ์ถœ๋ ฅ์„ ๊ฐ•์ œํ•ฉ๋‹ˆ๋‹ค. `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1`์€ Homebrew/WinGet ์„ค์น˜์— ๋Œ€ํ•œ ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์—…๊ทธ๋ ˆ์ด๋“œ๋ฅผ ํ™œ์„ฑํ™”ํ•˜๋ฉฐ, ๊ทธ๋ ‡์ง€ ์•Š์œผ๋ฉด ์ž๋™ ์—…๋ฐ์ดํŠธ๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. + +### ๊ตฌ์„ฑ ๊ด€๋ฆฌ ๋ช…๋ น์–ด + +``` +User: /config +[๋Œ€ํ™”ํ˜• ๊ตฌ์„ฑ ๋ฉ”๋‰ด ์—ด๊ธฐ] +``` + +`/config` ๋ช…๋ น์€ ๋‹ค์Œ๊ณผ ๊ฐ™์€ ์„ค์ •์„ ์ „ํ™˜ํ•˜๋Š” ๋Œ€ํ™”ํ˜• ๋ฉ”๋‰ด๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค: +- ํ™•์žฅ๋œ ์‚ฌ๊ณ  ์ผœ๊ธฐ/๋„๊ธฐ +- ์ž์„ธํ•œ ์ถœ๋ ฅ +- ๊ถŒํ•œ ๋ชจ๋“œ +- ๋ชจ๋ธ ์„ ํƒ + +๋Œ€ํ™”ํ˜• ๋ฉ”๋‰ด์—์„œ Enter ๋˜๋Š” Space๋ฅผ ๋ˆŒ๋Ÿฌ ์„ ํƒํ•œ ์„ค์ •์„ ๋ณ€๊ฒฝํ•˜๊ณ , Esc๋ฅผ ๋ˆŒ๋Ÿฌ ์ €์žฅํ•˜๊ณ  ๋‹ซ์Šต๋‹ˆ๋‹ค (v2.1.183+). + +๋ฉ”๋‰ด๋ฅผ ์—ด์ง€ ์•Š๊ณ ๋„ ํ”„๋กฌํ”„ํŠธ์—์„œ ์ง์ ‘ ์„ค์ •์„ ์ง€์ •ํ•  ์ˆ˜๋„ ์žˆ์Šต๋‹ˆ๋‹ค: + +```bash +/config thinking=false # ๋‹จ์ผ ์„ค์ • ์ธ๋ผ์ธ์œผ๋กœ ์ง€์ • (v2.1.181+) +/config --help # ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ์•ฝ์‹ ํ‚ค ๋ชฉ๋ก (v2.1.183+) +``` + +`key=value` ์•ฝ์‹์€ ๋Œ€ํ™”ํ˜• ์„ธ์…˜, `-p` ํ”Œ๋ž˜๊ทธ ์‚ฌ์šฉ ์‹œ, ๊ทธ๋ฆฌ๊ณ  ์›๊ฒฉ ์ œ์–ด์—์„œ ์ž‘๋™ํ•ฉ๋‹ˆ๋‹ค. + +### ํ”„๋กœ์ ํŠธ๋ณ„ ๊ตฌ์„ฑ + +ํ”„๋กœ์ ํŠธ์— `.claude/config.json`์„ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค: + +```json +{ + "hooks": { + "PreToolUse": [{ "matcher": "Bash", "hooks": ["npm test && npm run lint"] }] + }, + "permissions": { + "mode": "default" + }, + "mcp": { + "servers": { + "project-db": { + "command": "mcp-postgres", + "env": { + "DATABASE_URL": "${PROJECT_DB_URL}" + } + } + } + } +} +``` + +--- + +## ์—์ด์ „ํŠธ ํŒ€ + +์—์ด์ „ํŠธ ํŒ€์€ ์—ฌ๋Ÿฌ Claude Code ์ธ์Šคํ„ด์Šค๊ฐ€ ์ž‘์—…์— ํ˜‘๋ ฅํ•  ์ˆ˜ ์žˆ๋„๋ก ํ•˜๋Š” ์‹คํ—˜์ ์ธ ๊ธฐ๋Šฅ์ž…๋‹ˆ๋‹ค. ๊ธฐ๋ณธ์ ์œผ๋กœ ๋น„ํ™œ์„ฑํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. + +### ์—์ด์ „ํŠธ ํŒ€ ํ™œ์„ฑํ™” + +ํ™˜๊ฒฝ ๋ณ€์ˆ˜ ๋˜๋Š” ์„ค์ •์„ ํ†ตํ•ด ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค: + +```bash +# ํ™˜๊ฒฝ ๋ณ€์ˆ˜ +export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 +``` + +๋˜๋Š” ์„ค์ • JSON์— ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค: + +```json +{ + "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" +} +``` + +### ์—์ด์ „ํŠธ ํŒ€ ์ž‘๋™ ๋ฐฉ์‹ + +- **ํŒ€ ๋ฆฌ๋”**๋Š” ์ „์ฒด ์ž‘์—…์„ ์กฐ์œจํ•˜๊ณ  ํ•˜์œ„ ์ž‘์—…์„ ํŒ€์›์—๊ฒŒ ์œ„์ž„ํ•ฉ๋‹ˆ๋‹ค. +- **ํŒ€์›**์€ ๊ฐ์ž ์ž์‹ ์˜ ์ปจํ…์ŠคํŠธ ์ฐฝ์„ ๊ฐ€์ง€๊ณ  ๋…๋ฆฝ์ ์œผ๋กœ ์ž‘์—…ํ•ฉ๋‹ˆ๋‹ค. +- **๊ณต์œ  ์ž‘์—… ๋ชฉ๋ก**์€ ํŒ€์› ๊ฐ„์˜ ์ž์ฒด ์กฐ์œจ์„ ๊ฐ€๋Šฅํ•˜๊ฒŒ ํ•ฉ๋‹ˆ๋‹ค. +- ํŒ€์›์˜ ์—ญํ•  ๋ฐ ์ „๋ฌธํ™”๋ฅผ ์ •์˜ํ•˜๋ ค๋ฉด ์„œ๋ธŒ์—์ด์ „ํŠธ ์ •์˜ (`.claude/agents/` ๋˜๋Š” `--agents` ํ”Œ๋ž˜๊ทธ)๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + +### ํ‘œ์‹œ ๋ชจ๋“œ + +์—์ด์ „ํŠธ ํŒ€์€ `--teammate-mode` ํ”Œ๋ž˜๊ทธ๋กœ ๊ตฌ์„ฑ๋˜๋Š” ๋‘ ๊ฐ€์ง€ ํ‘œ์‹œ ๋ชจ๋“œ๋ฅผ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค: + +| ๋ชจ๋“œ | ์„ค๋ช… | +|------|-------------| +| `in-process` (๊ธฐ๋ณธ๊ฐ’) | ํŒ€์›์€ ๋™์ผํ•œ ํ„ฐ๋ฏธ๋„ ํ”„๋กœ์„ธ์Šค ๋‚ด์—์„œ ์‹คํ–‰๋ฉ๋‹ˆ๋‹ค | +| `tmux` | ๊ฐ ํŒ€์›์€ ์ „์šฉ ๋ถ„ํ•  ์ฐฝ์„ ๊ฐ€์ง‘๋‹ˆ๋‹ค (tmux ๋˜๋Š” iTerm2 ํ•„์š”) | +| `auto` | ์ตœ์ƒ์˜ ํ‘œ์‹œ ๋ชจ๋“œ๋ฅผ ์ž๋™์œผ๋กœ ์„ ํƒํ•ฉ๋‹ˆ๋‹ค | + +```bash +# ํŒ€์› ํ‘œ์‹œ๋ฅผ ์œ„ํ•ด tmux ๋ถ„ํ•  ์ฐฝ ์‚ฌ์šฉ +claude --teammate-mode tmux + +# ๋ช…์‹œ์ ์œผ๋กœ ์ธํ”„๋กœ์„ธ์Šค ๋ชจ๋“œ ์‚ฌ์šฉ +claude --teammate-mode in-process +``` + +### ์‚ฌ์šฉ ์‚ฌ๋ก€ + +- ๋‹ค๋ฅธ ํŒ€์›์ด ๋‹ค๋ฅธ ๋ชจ๋“ˆ์„ ์ฒ˜๋ฆฌํ•˜๋Š” ๋Œ€๊ทœ๋ชจ ๋ฆฌํŒฉํ† ๋ง ์ž‘์—… +- ๋ณ‘๋ ฌ ์ฝ”๋“œ ๊ฒ€ํ†  ๋ฐ ๊ตฌํ˜„ +- ์ฝ”๋“œ๋ฒ ์ด์Šค ์ „์ฒด์— ๊ฑธ์นœ ์กฐ์ •๋œ ๋‹ค์ค‘ ํŒŒ์ผ ๋ณ€๊ฒฝ + +> **์ฐธ๊ณ **: ์—์ด์ „ํŠธ ํŒ€์€ ์‹คํ—˜์ ์ธ ๊ธฐ๋Šฅ์ด๋ฉฐ ํ–ฅํ›„ ๋ฆด๋ฆฌ์Šค์—์„œ ๋ณ€๊ฒฝ๋  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์ „์ฒด ์ฐธ์กฐ๋Š” [code.claude.com/docs/en/agent-teams](https://code.claude.com/docs/en/agent-teams)๋ฅผ ์ฐธ์กฐํ•˜์‹ญ์‹œ์˜ค. + +--- + +## ๋ชจ๋ฒ” ์‚ฌ๋ก€ + +### ๊ธฐํš ๋ชจ๋“œ +- โœ… ๋ณต์žกํ•œ ๋‹ค๋‹จ๊ณ„ ์ž‘์—…์— ์‚ฌ์šฉ +- โœ… ์Šน์ธ ์ „์— ๊ณ„ํš ๊ฒ€ํ†  +- โœ… ํ•„์š”ํ•  ๋•Œ ๊ณ„ํš ์ˆ˜์ • +- โŒ ๊ฐ„๋‹จํ•œ ์ž‘์—…์—๋Š” ์‚ฌ์šฉํ•˜์ง€ ์•Š์Œ + +### ํ™•์žฅ๋œ ์‚ฌ๊ณ  +- โœ… ์•„ํ‚คํ…์ฒ˜ ๊ฒฐ์ •์— ์‚ฌ์šฉ +- โœ… ๋ณต์žกํ•œ ๋ฌธ์ œ ํ•ด๊ฒฐ์— ์‚ฌ์šฉ +- โœ… ์‚ฌ๊ณ  ๊ณผ์ • ๊ฒ€ํ†  +- โŒ ๊ฐ„๋‹จํ•œ ์ฟผ๋ฆฌ์—๋Š” ์‚ฌ์šฉํ•˜์ง€ ์•Š์Œ + +### ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž‘์—… +- โœ… ์žฅ๊ธฐ ์‹คํ–‰ ์ž‘์—…์— ์‚ฌ์šฉ +- โœ… ์ž‘์—… ์ง„ํ–‰ ์ƒํ™ฉ ๋ชจ๋‹ˆํ„ฐ๋ง +- โœ… ์ž‘์—… ์‹คํŒจ๋ฅผ ์šฐ์•„ํ•˜๊ฒŒ ์ฒ˜๋ฆฌ +- โŒ ๋„ˆ๋ฌด ๋งŽ์€ ๋™์‹œ ์ž‘์—…์„ ์‹œ์ž‘ํ•˜์ง€ ์•Š์Œ + +### ๊ถŒํ•œ +- โœ… ์ฝ”๋“œ ๊ฒ€ํ† ์—๋Š” `plan` ์‚ฌ์šฉ (์ฝ๊ธฐ ์ „์šฉ) +- โœ… ๋Œ€ํ™”ํ˜• ๊ฐœ๋ฐœ์—๋Š” `default` ์‚ฌ์šฉ +- โœ… ์ž๋™ํ™” ์›Œํฌํ”Œ๋กœ์šฐ์—๋Š” `acceptEdits` ์‚ฌ์šฉ +- โœ… ์•ˆ์ „ ๋ณดํ˜ธ ๊ธฐ๋Šฅ์ด ์žˆ๋Š” ์ž์œจ ์ž‘์—…์—๋Š” `auto` ์‚ฌ์šฉ +- โŒ ์ ˆ๋Œ€์ ์œผ๋กœ ํ•„์š”ํ•œ ๊ฒฝ์šฐ๊ฐ€ ์•„๋‹ˆ๋ฉด `bypassPermissions` ์‚ฌ์šฉํ•˜์ง€ ์•Š์Œ + +### ์„ธ์…˜ +- โœ… ๋‹ค๋ฅธ ์ž‘์—…์— ๋Œ€ํ•ด ๋ณ„๋„์˜ ์„ธ์…˜ ์‚ฌ์šฉ +- โœ… ์ค‘์š”ํ•œ ์„ธ์…˜ ์ƒํƒœ ์ €์žฅ +- โœ… ์˜ค๋ž˜๋œ ์„ธ์…˜ ์ •๋ฆฌ +- โŒ ๊ด€๋ จ ์—†๋Š” ์ž‘์—…์„ ํ•œ ์„ธ์…˜์— ์„ž์ง€ ์•Š์Œ + +--- + +## ์ถ”๊ฐ€ ์ž๋ฃŒ + +Claude Code ๋ฐ ๊ด€๋ จ ๊ธฐ๋Šฅ์— ๋Œ€ํ•œ ์ž์„ธํ•œ ์ •๋ณด๋Š” ๋‹ค์Œ์„ ์ฐธ์กฐํ•˜์‹ญ์‹œ์˜ค: + +- [๊ณต์‹ ๋Œ€ํ™”ํ˜• ๋ชจ๋“œ ๋ฌธ์„œ](https://code.claude.com/docs/en/interactive-mode) +- [๊ณต์‹ ํ—ค๋“œ๋ฆฌ์Šค ๋ชจ๋“œ ๋ฌธ์„œ](https://code.claude.com/docs/en/headless) +- [CLI ์ฐธ์กฐ](https://code.claude.com/docs/en/cli-reference) +- [์ฒดํฌํฌ์ธํŠธ ๊ฐ€์ด๋“œ](../08-checkpoints/) - ์„ธ์…˜ ๊ด€๋ฆฌ ๋ฐ ๋˜๊ฐ๊ธฐ +- [์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด](../01-slash-commands/) - ๋ช…๋ น์–ด ์ฐธ์กฐ +- [๋ฉ”๋ชจ๋ฆฌ ๊ฐ€์ด๋“œ](../02-memory/) - ์˜๊ตฌ ์ปจํ…์ŠคํŠธ +- [์Šคํ‚ฌ ๊ฐ€์ด๋“œ](../03-skills/) - ์ž์œจ ๊ธฐ๋Šฅ +- [์„œ๋ธŒ์—์ด์ „ํŠธ ๊ฐ€์ด๋“œ](../04-subagents/) - ์œ„์ž„๋œ ์ž‘์—… ์‹คํ–‰ +- [MCP ๊ฐ€์ด๋“œ](../05-mcp/) - ์™ธ๋ถ€ ๋ฐ์ดํ„ฐ ์•ก์„ธ์Šค +- [ํ›… ๊ฐ€์ด๋“œ](../06-hooks/) - ์ด๋ฒคํŠธ ๊ธฐ๋ฐ˜ ์ž๋™ํ™” +- [ํ”Œ๋Ÿฌ๊ทธ์ธ ๊ฐ€์ด๋“œ](../07-plugins/) - ๋ฒˆ๋“ค ํ™•์žฅ +- [๊ณต์‹ ์˜ˆ์•ฝ๋œ ์ž‘์—… ๋ฌธ์„œ](https://code.claude.com/docs/en/scheduled-tasks) +- [๊ณต์‹ Chrome ํ†ตํ•ฉ ๋ฌธ์„œ](https://code.claude.com/docs/en/chrome) +- [๊ณต์‹ ์›๊ฒฉ ์ œ์–ด ๋ฌธ์„œ](https://code.claude.com/docs/en/remote-control) +- [๊ณต์‹ ํ‚ค ๋ฐ”์ธ๋”ฉ ๋ฌธ์„œ](https://code.claude.com/docs/en/keybindings) +- [๊ณต์‹ ๋ฐ์Šคํฌํ†ฑ ์•ฑ ๋ฌธ์„œ](https://code.claude.com/docs/en/desktop) +- [๊ณต์‹ ์—์ด์ „ํŠธ ํŒ€ ๋ฌธ์„œ](https://code.claude.com/docs/en/agent-teams) + +--- + +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: 2026๋…„ 6์›” 28์ผ +**Claude Code ๋ฒ„์ „**: 2.1.195 +**์ถœ์ฒ˜**: +- https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md +- https://docs.anthropic.com/en/docs/claude-code/settings +- https://code.claude.com/docs/en/troubleshooting +- https://code.claude.com/docs/en/changelog#2-1-175 +- https://code.claude.com/docs/en/permission-modes +- https://code.claude.com/docs/en/interactive-mode +- https://code.claude.com/docs/en/settings +- https://code.claude.com/docs/en/cli-reference +- https://code.claude.com/docs/en/model-config +- https://www.anthropic.com/news/claude-opus-4-8 +- https://claude.com/blog/introducing-routines-in-claude-code +- https://github.com/anthropics/claude-code/releases/tag/v2.1.117 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.139 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.154 +- https://code.claude.com/docs/en/overview +- https://code.claude.com/docs/en/sub-agents +**ํ˜ธํ™˜ ๋ชจ๋ธ**: Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5 diff --git a/ko/09-advanced-features/config-examples.json b/ko/09-advanced-features/config-examples.json new file mode 100644 index 00000000..183a2c4b --- /dev/null +++ b/ko/09-advanced-features/config-examples.json @@ -0,0 +1,267 @@ +{ + "description": "Example Claude Code configurations for different use cases", + + "examples": { + "development": { + "name": "Development Environment", + "description": "Configuration for active development work", + "config": { + "general": { + "model": "claude-sonnet-4-6", + "temperature": 0.7 + }, + "planning": { + "autoEnter": true, + "complexityThreshold": 3, + "requireApproval": true + }, + "permissions": { + "mode": "unrestricted" + }, + "backgroundTasks": { + "enabled": true, + "maxConcurrentTasks": 3 + }, + "hooks": { + "PreToolUse:Write": "prettier --write ${file_path}", + "PostToolUse:Write": "eslint ${file_path}" + } + } + }, + + "code_review": { + "name": "Code Review Mode", + "description": "Configuration for reviewing code without modifications", + "config": { + "general": { + "model": "claude-sonnet-4-6", + "temperature": 0.3 + }, + "permissions": { + "mode": "plan" + }, + "extendedThinking": { + "enabled": true, + "showThinkingProcess": true + }, + "planning": { + "autoEnter": false + } + } + }, + + "learning": { + "name": "Learning Mode", + "description": "Configuration for learning and experimentation", + "config": { + "general": { + "model": "claude-sonnet-4-6", + "temperature": 0.5 + }, + "permissions": { + "mode": "confirm" + }, + "extendedThinking": { + "enabled": true, + "showThinkingProcess": true + }, + "planning": { + "autoEnter": true, + "requireApproval": true, + "showTimeEstimates": true + }, + "checkpoints": { + "autoCheckpoint": true + } + } + }, + + "production": { + "name": "Production Deployment", + "description": "Configuration for production operations with safety checks", + "config": { + "general": { + "model": "claude-opus-4-7", + "temperature": 0.1 + }, + "permissions": { + "mode": "confirm", + "requireConfirmationFor": ["Bash", "Git", "Write", "Edit"] + }, + "hooks": { + "PreToolUse": "~/.claude/hooks/pre-commit.sh" + }, + "checkpoints": { + "autoCheckpoint": true + }, + "planning": { + "autoEnter": true, + "requireApproval": true + } + } + }, + + "ci_cd": { + "name": "CI/CD Pipeline", + "description": "Configuration for automated CI/CD operations", + "config": { + "general": { + "model": "claude-sonnet-4-6", + "temperature": 0 + }, + "permissions": { + "mode": "unrestricted" + }, + "headless": { + "exitOnError": true, + "verbose": true, + "timeout": 3600 + }, + "logging": { + "level": "debug", + "file": "./ci-claude.log" + }, + "planning": { + "autoEnter": false, + "requireApproval": false + } + } + }, + + "security_audit": { + "name": "Security Audit", + "description": "Configuration for security-focused code analysis", + "config": { + "general": { + "model": "claude-opus-4-7", + "temperature": 0.2 + }, + "permissions": { + "mode": "plan" + }, + "extendedThinking": { + "enabled": true, + "showThinkingProcess": true, + "minThinkingTime": 10 + }, + "hooks": { + "PostToolUse:Read": "~/.claude/hooks/security-scan.sh ${file_path}" + } + } + }, + + "performance_optimization": { + "name": "Performance Optimization", + "description": "Configuration for performance analysis and optimization", + "config": { + "general": { + "model": "claude-sonnet-4-6", + "temperature": 0.4 + }, + "planning": { + "autoEnter": true, + "requireApproval": true + }, + "backgroundTasks": { + "enabled": true, + "maxConcurrentTasks": 5 + }, + "checkpoints": { + "autoCheckpoint": true + } + } + }, + + "pair_programming": { + "name": "Pair Programming", + "description": "Configuration for collaborative development", + "config": { + "general": { + "model": "claude-sonnet-4-6", + "temperature": 0.6 + }, + "permissions": { + "mode": "confirm" + }, + "planning": { + "autoEnter": true, + "requireApproval": true, + "showTimeEstimates": true + }, + "extendedThinking": { + "enabled": true, + "showThinkingProcess": true + }, + "ui": { + "compactMode": false, + "showProgress": true + } + } + }, + + "refactoring": { + "name": "Large Refactoring", + "description": "Configuration for major refactoring work", + "config": { + "general": { + "model": "claude-opus-4-7", + "temperature": 0.3 + }, + "planning": { + "autoEnter": true, + "requireApproval": true, + "showTimeEstimates": true + }, + "checkpoints": { + "autoCheckpoint": true + }, + "hooks": { + "PreToolUse:Edit": "~/.claude/hooks/backup-file.sh ${file_path}", + "PostToolUse:Edit": "npm test -- --findRelatedTests ${file_path}" + }, + "permissions": { + "mode": "confirm" + } + } + }, + + "autonomous": { + "name": "Autonomous Development", + "description": "Configuration for autonomous work with auto mode safety checks", + "config": { + "general": { + "model": "claude-sonnet-4-6", + "temperature": 0.5 + }, + "permissions": { + "mode": "auto" + }, + "sandbox": { + "enabled": true, + "failIfUnavailable": false + }, + "backgroundTasks": { + "enabled": true, + "maxConcurrentTasks": 3 + } + } + }, + + "documentation": { + "name": "Documentation Writing", + "description": "Configuration for writing documentation", + "config": { + "general": { + "model": "claude-sonnet-4-6", + "temperature": 0.7 + }, + "permissions": { + "mode": "unrestricted" + }, + "hooks": { + "PostToolUse:Write": "markdownlint ${file_path}" + } + } + } + } +} diff --git a/ko/09-advanced-features/planning-mode-examples.md b/ko/09-advanced-features/planning-mode-examples.md new file mode 100644 index 00000000..b196d070 --- /dev/null +++ b/ko/09-advanced-features/planning-mode-examples.md @@ -0,0 +1,538 @@ +# ํ”Œ๋ž˜๋‹ ๋ชจ๋“œ ์˜ˆ์ œ(Planning Mode Examples) + +Claude Code์—์„œ ํ”Œ๋ž˜๋‹ ๋ชจ๋“œ๋ฅผ ํšจ๊ณผ์ ์œผ๋กœ ์‚ฌ์šฉํ•˜๋Š” ์‹ค์ œ ์˜ˆ์ œ์ž…๋‹ˆ๋‹ค. + +## ์˜ˆ์ œ 1: REST API ๊ตฌ์ถ• + +### ํ”Œ๋ž˜๋‹ ๋ชจ๋“œ ์—†์ด + +``` +User: ๋ธ”๋กœ๊ทธ์šฉ REST API ๋งŒ๋“ค์–ด์ค˜ + +Claude: API๋ฅผ ์ƒ์„ฑํ•˜๊ฒ ์Šต๋‹ˆ๋‹ค... +[์ฆ‰์‹œ ์ฝ”๋”ฉ ์‹œ์ž‘, ์š”๊ตฌ์‚ฌํ•ญ ์ผ๋ถ€ ๋ˆ„๋ฝ ๊ฐ€๋Šฅ] +``` + +--- + +### ํ”Œ๋ž˜๋‹ ๋ชจ๋“œ ์‚ฌ์šฉ (/plan) + +``` +User: /plan ๋ธ”๋กœ๊ทธ์šฉ REST API ๋งŒ๋“ค์–ด์ค˜ + +Claude: ๋ธ”๋กœ๊ทธ API์— ๋Œ€ํ•œ ์ „์ฒด ๊ณ„ํš์„ ์ž‘์„ฑํ•˜๊ฒ ์Šต๋‹ˆ๋‹ค. + +## ๋ธ”๋กœ๊ทธ REST API ๊ตฌํ˜„ ๊ณ„ํš + +### 1๋‹จ๊ณ„: ํ”„๋กœ์ ํŠธ ์„ค์ • (15๋ถ„) +1. Node.js + Express ํ”„๋กœ์ ํŠธ ์ดˆ๊ธฐํ™” +2. TypeScript ์„ค์ • ๊ตฌ์„ฑ +3. ์˜์กด์„ฑ ์„ค์น˜ (express, pg, jwt, joi) +4. ํ™˜๊ฒฝ ๋ณ€์ˆ˜ ์„ค์ • +5. ํ”„๋กœ์ ํŠธ ๊ตฌ์กฐ ๊ตฌ์„ฑ + +### 2๋‹จ๊ณ„: ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ๊ณ„์ธต (30๋ถ„) +6. DB ์Šคํ‚ค๋งˆ ์„ค๊ณ„ + - users ํ…Œ์ด๋ธ” (id, email, password_hash, created_at) + - posts ํ…Œ์ด๋ธ” (id, user_id, title, content, published, created_at, updated_at) + - comments ํ…Œ์ด๋ธ” (id, post_id, user_id, content, created_at) +7. ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ ํŒŒ์ผ ์ƒ์„ฑ +8. DB ์—ฐ๊ฒฐ ํ’€ ๊ตฌ์„ฑ +9. ๋ชจ๋ธ ๊ตฌํ˜„ + +### 3๋‹จ๊ณ„: ์ธ์ฆ (45๋ถ„) +10. ํšŒ์›๊ฐ€์ž… API +11. ๋กœ๊ทธ์ธ API (JWT) +12. ์ธ์ฆ ๋ฏธ๋“ค์›จ์–ด +13. bcrypt ๋น„๋ฐ€๋ฒˆํ˜ธ ํ•ด์‹ฑ +14. ํ† ํฐ ๊ฐฑ์‹  ๋กœ์ง + +### 4๋‹จ๊ณ„: ๊ฒŒ์‹œ๊ธ€ API (40๋ถ„) +15. GET /api/posts (ํŽ˜์ด์ง€๋„ค์ด์…˜) +16. GET /api/posts/:id +17. POST /api/posts (์ธ์ฆ ํ•„์š”) +18. PUT /api/posts/:id (๊ถŒํ•œ ์ฒดํฌ) +19. DELETE /api/posts/:id +20. GET /api/users/:id/posts + +### 5๋‹จ๊ณ„: ๋Œ“๊ธ€ API (30๋ถ„) +21. ๋Œ“๊ธ€ ์กฐํšŒ +22. ๋Œ“๊ธ€ ์ƒ์„ฑ +23. ๋Œ“๊ธ€ ์‚ญ์ œ + +### 6๋‹จ๊ณ„: ๊ฒ€์ฆ ๋ฐ ์—๋Ÿฌ ์ฒ˜๋ฆฌ (30๋ถ„) +24. Joi ๊ฒ€์ฆ +25. ๊ธ€๋กœ๋ฒŒ ์—๋Ÿฌ ํ•ธ๋“ค๋Ÿฌ +26. ์ž…๋ ฅ sanitization +27. rate limiting + +### 7๋‹จ๊ณ„: ํ…Œ์ŠคํŠธ (60๋ถ„) +28. ๋‹จ์œ„ ํ…Œ์ŠคํŠธ +29. ํ†ตํ•ฉ ํ…Œ์ŠคํŠธ (auth) +30. ํ†ตํ•ฉ ํ…Œ์ŠคํŠธ (posts) +31. ํ†ตํ•ฉ ํ…Œ์ŠคํŠธ (comments) +32. ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€ 80%+ + +### 8๋‹จ๊ณ„: ๋ฌธ์„œ ๋ฐ ๋ฐฐํฌ (30๋ถ„) +33. Swagger ๋ฌธ์„œ ์ƒ์„ฑ +34. README ์ž‘์„ฑ +35. Docker ์„ค์ • +36. CI/CD ๊ตฌ์„ฑ + +**์˜ˆ์ƒ ์‹œ๊ฐ„**: 4.5์‹œ๊ฐ„ +**์ƒ์„ฑ ํŒŒ์ผ ์ˆ˜**: ์•ฝ 25๊ฐœ +**ํ•ต์‹ฌ ๊ธฐ์ˆ **: Express, PostgreSQL, JWT, TypeScript + +**API ์š”์•ฝ**: +- ์ธ์ฆ: 2๊ฐœ +- ๊ฒŒ์‹œ๊ธ€: 6๊ฐœ +- ๋Œ“๊ธ€: 3๊ฐœ +- ์ด 11๊ฐœ ์—”๋“œํฌ์ธํŠธ + +์ด๋Œ€๋กœ ์ง„ํ–‰ํ• ๊นŒ์š”? (yes/no/modify) + +User: yes + +Claude: Phase 1๋ถ€ํ„ฐ ์ˆœ์ฐจ์ ์œผ๋กœ ์ง„ํ–‰ํ•ฉ๋‹ˆ๋‹ค... +[๋‹จ๊ณ„๋ณ„๋กœ ๊ตฌํ˜„ ์ง„ํ–‰] +``` + +## ์˜ˆ์ œ 2: ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ + +``` +User: /plan MongoDB์—์„œ PostgreSQL๋กœ ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ + +Claude: ๋ณต์žกํ•œ ์ž‘์—…์ด๋ฏ€๋กœ ์ƒ์„ธ ๊ณ„ํš์„ ์ˆ˜๋ฆฝํ•˜๊ฒ ์Šต๋‹ˆ๋‹ค. + +## MongoDB โ†’ PostgreSQL ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ ๊ณ„ํš + +### 1๋‹จ๊ณ„: ๋ถ„์„ ๋ฐ ์ค€๋น„ (Day 1) +1. ๊ธฐ์กด MongoDB ์Šคํ‚ค๋งˆ ๋ถ„์„ +2. ๋ฐ์ดํ„ฐ ๊ด€๊ณ„ ๋ฐ ๊ตฌ์กฐ ํŒŒ์•… +3. ๋ฐ์ดํ„ฐ ๊ทœ๋ชจ ๋ฐ ์„ฑ์žฅ๋ฅ  ๋ถ„์„ +4. PostgreSQL ์Šคํ‚ค๋งˆ ์„ค๊ณ„ +5. ๋ฐ์ดํ„ฐ ํƒ€์ž… ๋งคํ•‘ ์ •์˜ +6. ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ ๋ฆฌ์Šคํฌ ๋ถ„์„ + +### 2๋‹จ๊ณ„: PostgreSQL ๊ตฌ์„ฑ (Day 1) +7. DB ์„ค์น˜ ๋ฐ ์„ค์ • +8. ํ…Œ์ด๋ธ”/์ธ๋ฑ์Šค/์ œ์•ฝ์กฐ๊ฑด ์ƒ์„ฑ +9. ์ปค๋„ฅ์…˜ ํ’€ ์„ค์ • +10. ๋ฐฑ์—… ์ „๋žต ๊ตฌ์„ฑ + +### 3๋‹จ๊ณ„: Dual-write ๊ตฌํ˜„ (Day 2~3) +11. DB ์ถ”์ƒํ™” ๊ณ„์ธต ์ƒ์„ฑ +12. MongoDB + PostgreSQL ๋™์‹œ ์“ฐ๊ธฐ +13. ๋ฐ์ดํ„ฐ ์ผ๊ด€์„ฑ ๊ฒ€์ฆ ๋กœ์ง +14. ์Šคํ…Œ์ด์ง• ํ™˜๊ฒฝ ํ…Œ์ŠคํŠธ +15. ๋ชจ๋‹ˆํ„ฐ๋ง ๊ตฌ์„ฑ + +### 4๋‹จ๊ณ„: ๋ฐ์ดํ„ฐ ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ (Day 4) +16. MongoDB export ์Šคํฌ๋ฆฝํŠธ +17. PostgreSQL import ์Šคํฌ๋ฆฝํŠธ +18. ๋ฐ์ดํ„ฐ ๋ณ€ํ™˜ ๋กœ์ง +19. ํ…Œ์ŠคํŠธ ๋ฐ์ดํ„ฐ ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ +20. ๋ฌด๊ฒฐ์„ฑ ๊ฒ€์ฆ + +### 5๋‹จ๊ณ„: ์ ์ง„์  ์ „ํ™˜ (Day 5~7) +21. ํ”„๋กœ๋•์…˜ dual-write ํ™œ์„ฑํ™” +22. ๋ฐฐ์น˜ ๋‹จ์œ„ ๋ฐ์ดํ„ฐ ์ด๋™ +23. ์‹ค์‹œ๊ฐ„ ์ผ๊ด€์„ฑ ์ฒดํฌ +24. ๋ชจ๋‹ˆํ„ฐ๋ง ๊ฐ•ํ™” +25. ๋ฌธ์ œ ๋ฐœ์ƒ ์‹œ ๋กค๋ฐฑ ๋Œ€์‘ + +### 6๋‹จ๊ณ„: PostgreSQL ์ „ํ™˜ (Day 8) +26. ์ฝ๊ธฐ ํŠธ๋ž˜ํ”ฝ PostgreSQL ์ „ํ™˜ +27. ์„ฑ๋Šฅ ๋ถ„์„ +28. ์ฟผ๋ฆฌ ์ตœ์ ํ™” +29. MongoDB ์œ ์ง€ (์•ˆ์ „์žฅ์น˜) + +### 7๋‹จ๊ณ„: MongoDB ์ข…๋ฃŒ (Day 9~10) +30. MongoDB write ์ค‘๋‹จ +31. 2์ฃผ๊ฐ„ ๋ฐฑ์—… ์œ ์ง€ +32. ์ฝ”๋“œ ์ œ๊ฑฐ +33. ๋ฐ์ดํ„ฐ ์•„์นด์ด๋น™ +34. ์ธํ”„๋ผ ์ œ๊ฑฐ + +**์˜ˆ์ƒ ๊ธฐ๊ฐ„**: 10์ผ +**์œ„ํ—˜๋„**: ๋†’์Œ +**๋กค๋ฐฑ ์ „๋žต**: MongoDB ์œ ์ง€ + dual-write ์œ ์ง€ + +**์ฃผ์š” ๋ฆฌ์Šคํฌ** +- ๋ฐ์ดํ„ฐ ๋ถˆ์ผ์น˜ +- ์„ฑ๋Šฅ ์ €ํ•˜ +- ๋‹ค์šดํƒ€์ž„ +- ๋ฐ์ดํ„ฐ ์†์‹ค + +**์™„ํ™” ์ „๋žต** +- Dual-write +- ๋‹จ๊ณ„์  ์ „ํ™˜ +- ์‹ค์‹œ๊ฐ„ ๋ชจ๋‹ˆํ„ฐ๋ง +- ๋น ๋ฅธ ๋กค๋ฐฑ + +์ด๋Œ€๋กœ ์ง„ํ–‰ํ• ๊นŒ์š”? (yes/no/modify) + +User: modify - ๊ฐ ๋‹จ๊ณ„๋ณ„ ๋กค๋ฐฑ ์ถ”๊ฐ€ + +Claude: ๊ฐ ๋‹จ๊ณ„๋ณ„ ๋กค๋ฐฑ ํฌํ•จํ•˜์—ฌ ๊ณ„ํš์„ ์—…๋ฐ์ดํŠธํ•˜๊ฒ ์Šต๋‹ˆ๋‹ค... +``` + +## ์˜ˆ์ œ 3: ํ”„๋ก ํŠธ์—”๋“œ ๋ฆฌํŒฉํ† ๋ง + +``` +User: /plan React ์•ฑ์„ class component์—์„œ hooks๋กœ ๋ฆฌํŒฉํ† ๋งํ•ด์ค˜ + +Claude: ์ฒด๊ณ„์ ์ธ ๋ฆฌํŒฉํ† ๋ง ๊ณ„ํš์„ ์ˆ˜๋ฆฝํ•˜๊ฒ ์Šต๋‹ˆ๋‹ค. + +## React Class โ†’ Hooks ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ ๊ณ„ํš + +### 1๋‹จ๊ณ„: ์ค€๋น„ ๋ฐ ๋ถ„์„ (2์‹œ๊ฐ„) +1. ๋ชจ๋“  class component ๊ฐ์‚ฌ (์ „์ฒด .jsx/.tsx ํŒŒ์ผ ํƒ์ƒ‰) +2. ๋ณต์žก๋„ ๊ธฐ์ค€ ๋ถ„๋ฅ˜: + - ๋‹จ์ˆœ (state๋งŒ ์‚ฌ์šฉ): ์•ฝ 15๊ฐœ ์ปดํฌ๋„ŒํŠธ + - ์ค‘๊ฐ„ (lifecycle ํฌํ•จ): ์•ฝ 23๊ฐœ ์ปดํฌ๋„ŒํŠธ + - ๋ณต์žก (์—ฌ๋Ÿฌ lifecycle + refs): ์•ฝ 8๊ฐœ ์ปดํฌ๋„ŒํŠธ +3. ์™ธ๋ถ€ ๋ผ์ด๋ธŒ๋Ÿฌ๋ฆฌ ์˜์กด์„ฑ ํ™•์ธ +4. ์ปดํฌ๋„ŒํŠธ ์˜์กด์„ฑ ๊ทธ๋ž˜ํ”„ ์ƒ์„ฑ +5. ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ ์ˆœ์„œ ๊ฒฐ์ • (leaf node ์šฐ์„ ) + +### 2๋‹จ๊ณ„: ํ™˜๊ฒฝ ์„ค์ • (1์‹œ๊ฐ„) +6. React v18+ ์—…๊ทธ๋ ˆ์ด๋“œ +7. ESLint hooks ๊ทœ์น™ ์ ์šฉ +8. ๋ณ€ํ™˜ ํ…œํ”Œ๋ฆฟ ์ƒ์„ฑ +9. ํ…Œ์ŠคํŠธ ํ™˜๊ฒฝ ๊ตฌ์„ฑ +10. ์‹œ์ž‘ ์ „ ์ฒดํฌํฌ์ธํŠธ ์ƒ์„ฑ + +### 3๋‹จ๊ณ„: ๋‹จ์ˆœ ์ปดํฌ๋„ŒํŠธ ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ (4์‹œ๊ฐ„) +11. ๋‹จ์ˆœ state ์ปดํฌ๋„ŒํŠธ ๋ณ€ํ™˜ (15๊ฐœ) +12. this.state โ†’ useState ๋ณ€๊ฒฝ +13. this.setState โ†’ setter ํ•จ์ˆ˜ ๋ณ€๊ฒฝ +14. ๊ฐ ์ปดํฌ๋„ŒํŠธ ํ…Œ์ŠคํŠธ +15. ํ…Œ์ŠคํŠธ ์ฝ”๋“œ ์—…๋ฐ์ดํŠธ + +### 4๋‹จ๊ณ„: ์ค‘๊ฐ„ ์ปดํฌ๋„ŒํŠธ ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ (8์‹œ๊ฐ„) +16. lifecycle ํฌํ•จ ์ปดํฌ๋„ŒํŠธ ๋ณ€ํ™˜ (23๊ฐœ) +17. componentDidMount โ†’ useEffect +18. componentDidUpdate โ†’ useEffect +19. componentWillUnmount โ†’ cleanup ํ•จ์ˆ˜ +20. ์ „์ฒด ํ…Œ์ŠคํŠธ ์ˆ˜ํ–‰ + +### 5๋‹จ๊ณ„: ๋ณต์žก ์ปดํฌ๋„ŒํŠธ ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ (12์‹œ๊ฐ„) +21. ๋ณต์žก ์ปดํฌ๋„ŒํŠธ ๋ณ€ํ™˜ (8๊ฐœ) +22. useRef ์ ์šฉ +23. ๊ณตํ†ต ๋กœ์ง custom hook์œผ๋กœ ๋ถ„๋ฆฌ +24. edge case ์ฒ˜๋ฆฌ +25. ์ง‘์ค‘ ํ…Œ์ŠคํŠธ + +### 6๋‹จ๊ณ„: ๊ณตํ†ต ๋กœ์ง ์ถ”์ถœ (6์‹œ๊ฐ„) +26. ์ค‘๋ณต ๋กœ์ง ๋ถ„์„ +27. custom hooks ์ƒ์„ฑ: + - useAuth + - useFetch + - useLocalStorage + - useDebounce +28. ์ปดํฌ๋„ŒํŠธ ๋ฆฌํŒฉํ† ๋ง +29. hook ๋‹จ์œ„ ํ…Œ์ŠคํŠธ + +### 7๋‹จ๊ณ„: ์„ฑ๋Šฅ ์ตœ์ ํ™” (4์‹œ๊ฐ„) +30. React.memo ์ ์šฉ +31. useCallback ์ตœ์ ํ™” +32. useMemo ์ ์šฉ +33. ์„ฑ๋Šฅ ํ”„๋กœํŒŒ์ผ๋ง ๋ฐ ๊ฐœ์„  + +### 8๋‹จ๊ณ„: ์ •๋ฆฌ ๋ฐ ๋ฌธ์„œํ™” (2์‹œ๊ฐ„) +34. ๋ถˆํ•„์š”ํ•œ class ์œ ํ‹ธ ์ œ๊ฑฐ +35. ๋ฌธ์„œ ์—…๋ฐ์ดํŠธ +36. ์ฝ”๋”ฉ ๊ฐ€์ด๋“œ ์ˆ˜์ • +37. ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ ๊ฐ€์ด๋“œ ์ž‘์„ฑ + +**์˜ˆ์ƒ ์‹œ๊ฐ„**: 5์ผ (39์‹œ๊ฐ„) +**์ˆ˜์ • ํŒŒ์ผ ์ˆ˜**: 46๊ฐœ ์ปดํฌ๋„ŒํŠธ +**๋ฆฌ์Šคํฌ ์ˆ˜์ค€**: ์ค‘๊ฐ„ + +**๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ ์ˆœ์„œ** +1. ์˜์กด์„ฑ ์—†๋Š” leaf ์ปดํฌ๋„ŒํŠธ +2. ์ค‘๊ฐ„ ๋ ˆ๋ฒจ ์ปดํฌ๋„ŒํŠธ +3. ์ƒ์œ„ container ์ปดํฌ๋„ŒํŠธ +4. App.jsx (๋งˆ์ง€๋ง‰) + +**ํ…Œ์ŠคํŠธ ์ „๋žต** +- ๊ฐ ์ปดํฌ๋„ŒํŠธ ๋‹จ์œ„ ํ…Œ์ŠคํŠธ +- ์‚ฌ์šฉ์ž ํ”Œ๋กœ์šฐ ํ†ตํ•ฉ ํ…Œ์ŠคํŠธ +- ์‹œ๊ฐ์  ํšŒ๊ท€ ํ…Œ์ŠคํŠธ +- ์„ฑ๋Šฅ ๋ฒค์น˜๋งˆํฌ + +**์„ฑ๊ณต ๊ธฐ์ค€** +- ๋ชจ๋“  ํ…Œ์ŠคํŠธ ํ†ต๊ณผ +- UI ๋ณ€๊ฒฝ ์—†์Œ +- ์„ฑ๋Šฅ ์œ ์ง€ ๋˜๋Š” ๊ฐœ์„  +- ๋ฒˆ๋“ค ํฌ๊ธฐ ์ฆ๊ฐ€ ์—†์Œ + +์ด๋Œ€๋กœ ์ง„ํ–‰ํ• ๊นŒ์š”? (yes/no/modify) +``` + + +## ์˜ˆ์ œ 4: ๋ณด์•ˆ ๊ตฌํ˜„(Security Implementation) + +``` +User: /plan ์›น ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜ ๋ณด์•ˆ์„ ์ „๋ฐ˜์ ์œผ๋กœ ๊ฐ•ํ™”ํ•ด์ค˜ + +Claude: ์ข…ํ•ฉ์ ์ธ ๋ณด์•ˆ ๊ฐ•ํ™” ๊ณ„ํš์„ ์ˆ˜๋ฆฝํ•˜๊ฒ ์Šต๋‹ˆ๋‹ค. + +## ์›น ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜ ๋ณด์•ˆ ๊ตฌํ˜„ ๊ณ„ํš + +### 1๋‹จ๊ณ„: ๋ณด์•ˆ ๊ฐ์‚ฌ (Day 1) +1. ์ž๋™ ๋ณด์•ˆ ์Šค์บ๋„ˆ ์‹คํ–‰ (npm audit, Snyk) +2. ์˜์กด์„ฑ ์ทจ์•ฝ์  ์ ๊ฒ€ +3. OWASP Top 10 ์ค€์ˆ˜ ์—ฌ๋ถ€ ํ™•์ธ +4. ์ธ์ฆ ํ๋ฆ„ ๊ฐ์‚ฌ +5. ๋ฐ์ดํ„ฐ ์ฒ˜๋ฆฌ ๋ฐฉ์‹ ๊ฒ€ํ†  +6. ๋ณด์•ˆ ์ทจ์•ฝ์  ๋ฌธ์„œํ™” + +### 2๋‹จ๊ณ„: ์ธ์ฆ ๊ฐ•ํ™” (Day 2~3) +7. ๊ฐ•๋ ฅํ•œ ๋น„๋ฐ€๋ฒˆํ˜ธ ์ •์ฑ… ์ ์šฉ +8. ๋น„๋ฐ€๋ฒˆํ˜ธ ๊ฐ•๋„ ์ฒดํฌ ์ถ”๊ฐ€ +9. ๋กœ๊ทธ์ธ rate limiting ์ ์šฉ +10. ๋กœ๊ทธ์ธ ์‹คํŒจ ์‹œ ๊ณ„์ • ์ž ๊ธˆ +11. 2FA (TOTP) ๊ตฌํ˜„ +12. ์„ธ์…˜ ๊ด€๋ฆฌ ๊ฐœ์„  +13. ์•ˆ์ „ํ•œ ๋น„๋ฐ€๋ฒˆํ˜ธ ์žฌ์„ค์ • ํ๋ฆ„ ๊ตฌํ˜„ + +### 3๋‹จ๊ณ„: ๊ถŒํ•œ ๊ด€๋ฆฌ (Day 3~4) +14. RBAC(Role-Based Access Control) ๊ตฌํ˜„ +15. ๋ชจ๋“  API์— ๊ถŒํ•œ ์ฒดํฌ ์ถ”๊ฐ€ +16. ์ตœ์†Œ ๊ถŒํ•œ ์›์น™ ์ ์šฉ +17. ๊ฐ์‚ฌ ๋กœ๊ทธ ์ถ”๊ฐ€ +18. ๋ฆฌ์†Œ์Šค ๋‹จ์œ„ ๊ถŒํ•œ ์ œ์–ด + +### 4๋‹จ๊ณ„: ๋ฐ์ดํ„ฐ ๋ณดํ˜ธ (Day 4~5) +19. ๋ฏผ๊ฐ ๋ฐ์ดํ„ฐ ์•”ํ˜ธํ™” +20. ๋ชจ๋“  ํ†ต์‹  TLS ์ ์šฉ +21. ์„ธ์…˜ ์ €์žฅ ๋ณด์•ˆ ๊ฐ•ํ™” +22. ๋กœ๊ทธ์—์„œ PII ๋งˆ์Šคํ‚น +23. ๋ฐ์ดํ„ฐ ๋ณด๊ด€ ์ •์ฑ… ์ ์šฉ +24. ํŒŒ์ผ ์—…๋กœ๋“œ ๋ณด์•ˆ ์ฒ˜๋ฆฌ + +### 5๋‹จ๊ณ„: ์ž…๋ ฅ ๊ฒ€์ฆ (Day 5~6) +25. ๋ชจ๋“  API ์ž…๋ ฅ ๊ฒ€์ฆ +26. XSS ๋ฐฉ์ง€ (CSP ์ ์šฉ) +27. SQL Injection ๋ฐฉ์ง€ (prepared statement) +28. CSRF ๋ณดํ˜ธ +29. ์š”์ฒญ ํฌ๊ธฐ ์ œํ•œ +30. ํŒŒ์ผ ํƒ€์ž… ๊ฒ€์ฆ + +### 6๋‹จ๊ณ„: ๋ณด์•ˆ ํ—ค๋” (Day 6) +31. ๋ณด์•ˆ ํ—ค๋” ์ถ”๊ฐ€: + - HSTS + - X-Content-Type-Options + - X-Frame-Options + - CSP +32. CORS ์„ค์ • ๊ฐ•ํ™” +33. ๋ถˆํ•„์š”ํ•œ HTTP method ์ œ๊ฑฐ +34. ์„œ๋ฒ„ ์ •๋ณด ์ˆจ๊น€ + +### 7๋‹จ๊ณ„: ๋ชจ๋‹ˆํ„ฐ๋ง (Day 7) +35. ๋ณด์•ˆ ์ด๋ฒคํŠธ ๋กœ๊ทธ +36. ์ด์ƒ ํƒ์ง€ ์‹œ์Šคํ…œ +37. ์นจ์ž… ํƒ์ง€ ์„ค์ • +38. ์‹ค์‹œ๊ฐ„ ์•Œ๋ฆผ +39. ๋ณด์•ˆ ๋Œ€์‹œ๋ณด๋“œ + +### 8๋‹จ๊ณ„: ํ…Œ์ŠคํŠธ (Day 8~9) +40. ์นจํˆฌ ํ…Œ์ŠคํŠธ +41. ๋ณด์•ˆ ์Šค์บ๋‹ +42. ์ „์ฒด ๊ธฐ๋Šฅ ํ…Œ์ŠคํŠธ +43. ๋ณด์•ˆ ๋ฌธ์„œ ์ž‘์„ฑ +44. ๋Œ€์‘ ๋งค๋‰ด์–ผ ์ž‘์„ฑ + +### 9๋‹จ๊ณ„: ์ปดํ”Œ๋ผ์ด์–ธ์Šค (Day 10) +45. GDPR ์ ๊ฒ€ +46. ๊ฐœ์ธ์ •๋ณด ์ •์ฑ… ์ž‘์„ฑ +47. ๋ฐ์ดํ„ฐ ์š”์ฒญ ์ฒ˜๋ฆฌ ๊ธฐ๋Šฅ +48. ์ฟ ํ‚ค ๋™์˜ ๊ตฌํ˜„ +49. ์ •์ฑ… ๋ฌธ์„œํ™” + +**์˜ˆ์ƒ ๊ธฐ๊ฐ„**: 10์ผ +**์œ„ํ—˜๋„**: ๋งค์šฐ ๋†’์Œ (Critical) +**์šฐ์„ ์ˆœ์œ„**: ์ตœ์ƒ + +**๋ณด์•ˆ ๊ฐœ์„  ํ•ญ๋ชฉ ์š”์•ฝ** +- ์ธ์ฆ: 7๊ฐœ ๊ฐœ์„  +- ๊ถŒํ•œ: 5๊ฐœ ๊ฐœ์„  +- ๋ฐ์ดํ„ฐ ๋ณดํ˜ธ: 6๊ฐœ +- ์ž…๋ ฅ ๊ฒ€์ฆ: 6๊ฐœ +- ์ธํ”„๋ผ: 9๊ฐœ +- ๋ชจ๋‹ˆํ„ฐ๋ง: 5๊ฐœ + +**์ค€์ˆ˜ ๊ธฐ์ค€** +- OWASP Top 10 +- GDPR + +**์„ฑ๊ณต ๊ธฐ์ค€** +- ์น˜๋ช…์  ์ทจ์•ฝ์  0๊ฐœ +- OWASP Top 10 ๋Œ€์‘ ์™„๋ฃŒ +- ๋ณด์•ˆ ์ ์ˆ˜ 90/100 ์ด์ƒ +- ๋ชจ๋“  ์นจํˆฌ ํ…Œ์ŠคํŠธ ํ†ต๊ณผ + +์ด๋Œ€๋กœ ์ง„ํ–‰ํ• ๊นŒ์š”? (yes/no/modify) +``` + +## ์˜ˆ์ œ 5: ์„ฑ๋Šฅ ์ตœ์ ํ™” + +``` +User: /plan ๋Š๋ฆฐ ์ด์ปค๋จธ์Šค ์›น์‚ฌ์ดํŠธ๋ฅผ ์ตœ์ ํ™”ํ•ด์ค˜ + +Claude: ์ข…ํ•ฉ์ ์ธ ์„ฑ๋Šฅ ์ตœ์ ํ™” ๊ณ„ํš์„ ์ˆ˜๋ฆฝํ•˜๊ฒ ์Šต๋‹ˆ๋‹ค. + +## ์ด์ปค๋จธ์Šค ์„ฑ๋Šฅ ์ตœ์ ํ™” ๊ณ„ํš + +### 1๋‹จ๊ณ„: ์„ฑ๋Šฅ ๊ฐ์‚ฌ (4์‹œ๊ฐ„) +1. Lighthouse ๊ฐ์‚ฌ ์‹คํ–‰ +2. Chrome DevTools ์„ฑ๋Šฅ ํ”„๋กœํŒŒ์ผ ๋ถ„์„ +3. Core Web Vitals ์ธก์ •: + - LCP (Largest Contentful Paint) + - FID (First Input Delay) + - CLS (Cumulative Layout Shift) +4. ์„ฑ๋Šฅ ๋ณ‘๋ชฉ ์ง€์  ์‹๋ณ„ +5. ๊ธฐ์ค€ ์„ฑ๋Šฅ ์ง€ํ‘œ ์„ค์ • + +**ํ˜„์žฌ ์ง€ํ‘œ** +- LCP: 4.2s (๋ชฉํ‘œ: <2.5s) +- FID: 280ms (๋ชฉํ‘œ: <100ms) +- CLS: 0.25 (๋ชฉํ‘œ: <0.1) +- Page Load: 8.3s (๋ชฉํ‘œ: <3s) + +### 2๋‹จ๊ณ„: ์ด๋ฏธ์ง€ ์ตœ์ ํ™” (6์‹œ๊ฐ„) +6. WebP ํฌ๋งท์œผ๋กœ ๋ณ€ํ™˜ +7. ๋ฐ˜์‘ํ˜• ์ด๋ฏธ์ง€ ์ ์šฉ +8. ์ด๋ฏธ์ง€ lazy loading ์ ์šฉ +9. ์ด๋ฏธ์ง€ ์šฉ๋Ÿ‰ ์ตœ์ ํ™” (์••์ถ•) +10. CDN ์ ์šฉ +11. ์ด๋ฏธ์ง€ placeholder ์ถ”๊ฐ€ + +**์˜ˆ์ƒ ํšจ๊ณผ**: ๋กœ๋”ฉ ์‹œ๊ฐ„ ์•ฝ -40% + +### 3๋‹จ๊ณ„: ์ฝ”๋“œ ๋ถ„ํ•  ๋ฐ ์ง€์—ฐ ๋กœ๋”ฉ (8์‹œ๊ฐ„) +12. ๋ผ์šฐํŠธ ๊ธฐ๋ฐ˜ ์ฝ”๋“œ ๋ถ„ํ•  ๊ตฌํ˜„ +13. ์ค‘์š”ํ•˜์ง€ ์•Š์€ ์ปดํฌ๋„ŒํŠธ์— ์ง€์—ฐ ๋กœ๋”ฉ ์ ์šฉ +14. ๋ฒค๋” ๋ฒˆ๋“ค ๋ถ„ํ•  +15. ์ฒญํฌ ํฌ๊ธฐ ์ตœ์ ํ™” +16. ๋™์  import ๊ตฌํ˜„ +17. ํ•ต์‹ฌ ๋ฆฌ์†Œ์Šค ์‚ฌ์ „ ๋กœ๋”ฉ ์ถ”๊ฐ€ + +**์˜ˆ์ƒ ํšจ๊ณผ**: ์ดˆ๊ธฐ ๋ฒˆ๋“ค ํฌ๊ธฐ -30% + +### 4๋‹จ๊ณ„: ์บ์‹ฑ ์ „๋žต (6์‹œ๊ฐ„) +18. ๋ธŒ๋ผ์šฐ์ € ์บ์‹ฑ(Cache-Control) ๊ตฌํ˜„ +19. ์˜คํ”„๋ผ์ธ ์ง€์›์„ ์œ„ํ•œ ์„œ๋น„์Šค ์›Œ์ปค ์ถ”๊ฐ€ +20. API ์‘๋‹ต ์บ์‹ฑ ๊ตฌํ˜„ +21. ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ์ฟผ๋ฆฌ๋ฅผ ์œ„ํ•œ Redis ์บ์‹œ ์ถ”๊ฐ€ +22. stale-while-revalidate ์ „๋žต ๊ตฌํ˜„ +23. CDN ์บ์‹ฑ ๊ตฌ์„ฑ + +**์˜ˆ์ƒ ํšจ๊ณผ**: API ์‘๋‹ต ์‹œ๊ฐ„ -50% + +### 5๋‹จ๊ณ„: ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ์ตœ์ ํ™” (8์‹œ๊ฐ„) +24. ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ์ธ๋ฑ์Šค ์ถ”๊ฐ€ +25. ๋Š๋ฆฐ ์ฟผ๋ฆฌ(100ms ์ดˆ๊ณผ) ์ตœ์ ํ™” +26. ์ฟผ๋ฆฌ ๊ฒฐ๊ณผ ์บ์‹ฑ ๊ตฌํ˜„ +27. ์ปค๋„ฅ์…˜ ํ’€๋ง ์ถ”๊ฐ€ +28. ํ•„์š”ํ•œ ๊ฒฝ์šฐ ๋น„์ •๊ทœํ™” ์ ์šฉ +29. ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ์ฝ๊ธฐ ์ „์šฉ ๋ณต์ œ๋ณธ(Read Replica) ๊ตฌํ˜„ + +**์˜ˆ์ƒ ํšจ๊ณผ**: ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ์ฟผ๋ฆฌ ์‹œ๊ฐ„ -60% + +### 6๋‹จ๊ณ„: ํ”„๋ก ํŠธ์—”๋“œ ์ตœ์ ํ™” (10์‹œ๊ฐ„) +30. JavaScript ์ตœ์†Œํ™” ๋ฐ ์••์ถ• +31. CSS ์ตœ์†Œํ™” ๋ฐ ์••์ถ• +32. ์‚ฌ์šฉํ•˜์ง€ ์•Š๋Š” CSS ์ œ๊ฑฐ(PurgeCSS) +33. Critical CSS ๊ตฌํ˜„ +34. ์ค‘์š”ํ•˜์ง€ ์•Š์€ JavaScript ์‹คํ–‰ ์ง€์—ฐ +35. DOM ํฌ๊ธฐ ์ถ•์†Œ +36. React ๋ Œ๋”๋ง ์ตœ์ ํ™”(memo, useMemo) +37. ๊ธด ๋ชฉ๋ก์— ๊ฐ€์ƒ ์Šคํฌ๋กค๋ง ๊ตฌํ˜„ + +**์˜ˆ์ƒ ํšจ๊ณผ**: JavaScript ์‹คํ–‰ ์‹œ๊ฐ„ -35% + +### 7๋‹จ๊ณ„: ๋„คํŠธ์›Œํฌ ์ตœ์ ํ™” (4์‹œ๊ฐ„) +38. HTTP/2 ํ™œ์„ฑํ™” +39. ๋ฆฌ์†Œ์Šค ํžŒํŠธ(preconnect, prefetch) ๊ตฌํ˜„ +40. HTTP ์š”์ฒญ ์ˆ˜ ๊ฐ์†Œ +41. Brotli ์••์ถ• ํ™œ์„ฑํ™” +42. ์„œ๋“œํŒŒํ‹ฐ ์Šคํฌ๋ฆฝํŠธ ์ตœ์ ํ™” + +**์˜ˆ์ƒ ํšจ๊ณผ**: ๋„คํŠธ์›Œํฌ ์ฒ˜๋ฆฌ ์‹œ๊ฐ„ -25% + +### 8๋‹จ๊ณ„: ๋ชจ๋‹ˆํ„ฐ๋ง ๋ฐ ํ…Œ์ŠคํŠธ (4์‹œ๊ฐ„) +43. ์„ฑ๋Šฅ ๋ชจ๋‹ˆํ„ฐ๋ง(Datadog/New Relic) ์„ค์ • +44. Real User Monitoring(RUM) ์ถ”๊ฐ€ +45. ์„ฑ๋Šฅ ์˜ˆ์‚ฐ(Performance Budget) ์ƒ์„ฑ +46. ์ž๋™ํ™”๋œ Lighthouse CI ์„ค์ • +47. ์‹ค์ œ ๊ธฐ๊ธฐ์—์„œ ํ…Œ์ŠคํŠธ + +**์˜ˆ์ƒ ์†Œ์š” ์‹œ๊ฐ„**: 50์‹œ๊ฐ„(2์ฃผ) + +**๋ชฉํ‘œ ์ง€ํ‘œ** (90๋ฐฑ๋ถ„์œ„ ๊ธฐ์ค€): +- LCP: <2.0s (๊ธฐ์กด 4.2s) โœ… +- FID: <50ms (๊ธฐ์กด 280ms) โœ… +- CLS: <0.05 (๊ธฐ์กด 0.25) โœ… +- Page Load: <2.5s (๊ธฐ์กด 8.3s) โœ… + +**์˜ˆ์ƒ ๋งค์ถœ ํšจ๊ณผ**: +- 100ms ๊ฐœ์„  ์‹œ ์ „ํ™˜์œจ 1% ์ฆ๊ฐ€ +- ๋ชฉํ‘œ: 5.8์ดˆ ๊ฐœ์„  = ์•ฝ 58% ์ „ํ™˜์œจ ์ฆ๊ฐ€ +- ์˜ˆ์ƒ ์ถ”๊ฐ€ ๋งค์ถœ: ์ƒ๋‹นํ•œ ์ˆ˜์ค€ + +**์šฐ์„ ์ˆœ์œ„**: +1. ์ด๋ฏธ์ง€ ์ตœ์ ํ™” (๋น ๋ฅธ ์„ฑ๊ณผ) +2. ์ฝ”๋“œ ๋ถ„ํ•  (๋†’์€ ํšจ๊ณผ) +3. ์บ์‹ฑ (๋†’์€ ํšจ๊ณผ) +4. ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ์ตœ์ ํ™” (ํ•ต์‹ฌ) +5. ํ”„๋ก ํŠธ์—”๋“œ ์ตœ์ ํ™” (๋งˆ๋ฌด๋ฆฌ) + +์ด ๊ณ„ํš์œผ๋กœ ์ง„ํ–‰ํ•˜์‹œ๊ฒ ์Šต๋‹ˆ๊นŒ? (yes/no/modify) +``` + +## ํ•ต์‹ฌ ์š”์•ฝ + +### ๊ณ„ํš ๋ชจ๋“œ์˜ ์žฅ์  + +1. **๋ช…ํ™•์„ฑ**: ์ž‘์—… ์‹œ์ž‘ ์ „์— ๋ช…ํ™•ํ•œ ๋กœ๋“œ๋งต์„ ์ˆ˜๋ฆฝ +2. **์˜ˆ์ธก ๊ฐ€๋Šฅ์„ฑ**: ์‹œ๊ฐ„๊ณผ ๋…ธ๋ ฅ์— ๋Œ€ํ•œ ์˜ˆ์ƒ ์ œ๊ณต +3. **์œ„ํ—˜ ํ‰๊ฐ€**: ์ž ์žฌ์ ์ธ ๋ฌธ์ œ๋ฅผ ์กฐ๊ธฐ์— ์‹๋ณ„ +4. **์šฐ์„ ์ˆœ์œ„ ์„ค์ •**: ์ž‘์—…์„ ๋…ผ๋ฆฌ์ ์ธ ์ˆœ์„œ๋กœ ๊ตฌ์„ฑ +5. **์Šน์ธ ์ ˆ์ฐจ**: ์‹คํ–‰ ์ „์— ๊ฒ€ํ†  ๋ฐ ์Šน์ธ ๊ฐ€๋Šฅ +6. **์ˆ˜์ • ์šฉ์ด์„ฑ**: ํ”ผ๋“œ๋ฐฑ์„ ๋ฐ˜์˜ํ•˜์—ฌ ๊ณ„ํš ์กฐ์ • ๊ฐ€๋Šฅ + +### ๊ณ„ํš ๋ชจ๋“œ๋ฅผ ์‚ฌ์šฉํ•ด์•ผ ํ•˜๋Š” ๊ฒฝ์šฐ + +โœ… **ํ•ญ์ƒ ์‚ฌ์šฉํ•˜๋Š” ๊ฒƒ์ด ์ข‹์€ ๊ฒฝ์šฐ**: +- ๋ฉฐ์น  ์ด์ƒ ์†Œ์š”๋˜๋Š” ํ”„๋กœ์ ํŠธ +- ํŒ€ ํ˜‘์—… +- ์ค‘์š”ํ•œ ์‹œ์Šคํ…œ ๋ณ€๊ฒฝ +- ์ƒˆ๋กœ์šด ๊ฐœ๋… ํ•™์Šต +- ๋ณต์žกํ•œ ๋ฆฌํŒฉํ„ฐ๋ง + +โŒ **์‚ฌ์šฉํ•˜์ง€ ์•Š์•„๋„ ๋˜๋Š” ๊ฒฝ์šฐ**: +- ๋ฒ„๊ทธ ์ˆ˜์ • +- ์ž‘์€ ๋ณ€๊ฒฝ ์‚ฌํ•ญ +- ๋‹จ์ˆœํ•œ ์งˆ์˜ +- ๊ฐ„๋‹จํ•œ ์‹คํ—˜ + +### ๋ชจ๋ฒ” ์‚ฌ๋ก€ + +1. ์Šน์ธํ•˜๊ธฐ ์ „์— **๊ณ„ํš์„ ๊ผผ๊ผผํžˆ ๊ฒ€ํ† **ํ•˜์„ธ์š”. +2. ๋ฌธ์ œ๊ฐ€ ๋ณด์ด๋ฉด **๊ณ„ํš์„ ์ˆ˜์ •**ํ•˜์„ธ์š”. +3. ๋ณต์žกํ•œ ์ž‘์—…์€ **์„ธ๋ถ€ ์ž‘์—…์œผ๋กœ ๋ถ„ํ•ด**ํ•˜์„ธ์š”. +4. **ํ˜„์‹ค์ ์ธ ์ผ์ •**์„ ์‚ฐ์ •ํ•˜์„ธ์š”. +5. **๋กค๋ฐฑ ์ „๋žต**์„ ํฌํ•จํ•˜์„ธ์š”. +6. **์„ฑ๊ณต ๊ธฐ์ค€**์„ ์ถ”๊ฐ€ํ•˜์„ธ์š”. +7. ๊ฐ ๋‹จ๊ณ„๋งˆ๋‹ค **ํ…Œ์ŠคํŠธ ๊ณ„ํš**์„ ํฌํ•จํ•˜์„ธ์š”. + +--- +**Last Updated**: June 2, 2026 +**Claude Code Version**: 2.1.160 +**Sources**: +- https://code.claude.com/docs/en/changelog +- https://code.claude.com/docs/en/best-practices +**Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5 diff --git a/ko/09-advanced-features/setup-auto-mode-permissions.py b/ko/09-advanced-features/setup-auto-mode-permissions.py new file mode 100644 index 00000000..a677314d --- /dev/null +++ b/ko/09-advanced-features/setup-auto-mode-permissions.py @@ -0,0 +1,265 @@ +#!/usr/bin/env python3 +""" +setup-auto-mode-permissions.py + +Seed ~/.claude/settings.json with a conservative baseline of safe permissions +for Claude Code. The default set is read-only and local-inspection oriented; +optional flags let you widen the allowlist for editing, test execution, git +write operations, package installs, and GitHub CLI writes. + +Usage: + python3 setup-auto-mode-permissions.py + python3 setup-auto-mode-permissions.py --dry-run + python3 setup-auto-mode-permissions.py --include-edits --include-tests +""" + +from __future__ import annotations + +import argparse +import json +import tempfile +from pathlib import Path +from typing import Iterable + +SETTINGS_PATH = Path.home() / ".claude" / "settings.json" + +# Core baseline: read-only inspection and low-risk local shell commands. +CORE_PERMISSIONS = [ + "Read(*)", + "Glob(*)", + "Grep(*)", + "Agent(*)", + "Skill(*)", + "WebSearch(*)", + "WebFetch(*)", + "Bash(ls:*)", + "Bash(pwd:*)", + "Bash(which:*)", + "Bash(echo:*)", + "Bash(cat:*)", + "Bash(head:*)", + "Bash(tail:*)", + "Bash(wc:*)", + "Bash(sort:*)", + "Bash(uniq:*)", + "Bash(find:*)", + "Bash(dirname:*)", + "Bash(basename:*)", + "Bash(realpath:*)", + "Bash(file:*)", + "Bash(stat:*)", + "Bash(diff:*)", + "Bash(md5sum:*)", + "Bash(sha256sum:*)", + "Bash(date:*)", + "Bash(env:*)", + "Bash(printenv:*)", + "Bash(git status:*)", + "Bash(git log:*)", + "Bash(git diff:*)", + "Bash(git branch:*)", + "Bash(git show:*)", + "Bash(git rev-parse:*)", + "Bash(git remote -v:*)", + "Bash(git remote get-url:*)", + "Bash(git stash list:*)", +] + +# Optional but still local: file edits and task bookkeeping. +EDITING_PERMISSIONS = [ + "Edit(*)", + "Write(*)", + "NotebookEdit(*)", + "TaskCreate(*)", + "TaskUpdate(*)", +] + +# Optional dev/test commands. These can still execute arbitrary project scripts, +# so keep them opt-in rather than part of the default baseline. +TEST_AND_BUILD_PERMISSIONS = [ + "Bash(npm test:*)", + "Bash(cargo test:*)", + "Bash(go test:*)", + "Bash(pytest:*)", + "Bash(python3 -m pytest:*)", + "Bash(make:*)", + "Bash(cmake:*)", +] + +# Optional local git write operations. History-rewriting commands stay out of +# the default baseline because they are easy to misuse. +GIT_WRITE_PERMISSIONS = [ + "Bash(git add:*)", + "Bash(git commit:*)", + "Bash(git checkout:*)", + "Bash(git switch:*)", + "Bash(git stash:*)", + "Bash(git tag:*)", +] + +# Optional dependency/package commands. These are intentionally excluded from +# the default baseline because they can execute project hooks or fetch code. +PACKAGE_MANAGER_PERMISSIONS = [ + "Bash(npm ci:*)", + "Bash(npm install:*)", + "Bash(pip install:*)", + "Bash(pip3 install:*)", +] + +# Optional GitHub CLI write access. +GITHUB_WRITE_PERMISSIONS = [ + "Bash(gh pr create:*)", +] + +# Optional extra GitHub CLI read access. +GITHUB_READ_PERMISSIONS = [ + "Bash(gh pr view:*)", + "Bash(gh pr list:*)", + "Bash(gh issue view:*)", + "Bash(gh issue list:*)", + "Bash(gh repo view:*)", +] + + +def parse_args() -> argparse.Namespace: + parser = argparse.ArgumentParser( + description="Seed Claude Code settings with a conservative permission baseline." + ) + parser.add_argument( + "--dry-run", + action="store_true", + help="Preview the rules that would be added without writing settings.json", + ) + parser.add_argument( + "--include-edits", + action="store_true", + help="Add file-editing permissions (Edit/Write/NotebookEdit/TaskCreate/TaskUpdate)", + ) + parser.add_argument( + "--include-tests", + action="store_true", + help="Add local build/test commands such as pytest, cargo test, and make", + ) + parser.add_argument( + "--include-git-write", + action="store_true", + help="Add local git mutation commands such as add, commit, checkout, and stash", + ) + parser.add_argument( + "--include-packages", + action="store_true", + help="Add package install commands such as npm ci, npm install, and pip install", + ) + parser.add_argument( + "--include-gh-write", + action="store_true", + help="Add GitHub CLI write permissions such as gh pr create", + ) + parser.add_argument( + "--include-gh-read", + action="store_true", + help="Add GitHub CLI read permissions such as gh pr view and gh repo view", + ) + return parser.parse_args() + + +def load_settings(path: Path) -> dict: + if not path.exists(): + return {} + + try: + with path.open() as f: + settings = json.load(f) + except json.JSONDecodeError as exc: + raise SystemExit(f"Invalid JSON in {path}: {exc}") from exc + + if not isinstance(settings, dict): + raise SystemExit(f"Expected {path} to contain a JSON object.") + + return settings + + +def build_permissions(args: argparse.Namespace) -> list[str]: + permissions = list(CORE_PERMISSIONS) + + if args.include_edits: + permissions.extend(EDITING_PERMISSIONS) + + if args.include_tests: + permissions.extend(TEST_AND_BUILD_PERMISSIONS) + + if args.include_git_write: + permissions.extend(GIT_WRITE_PERMISSIONS) + + if args.include_packages: + permissions.extend(PACKAGE_MANAGER_PERMISSIONS) + + if args.include_gh_write: + permissions.extend(GITHUB_WRITE_PERMISSIONS) + + if args.include_gh_read: + permissions.extend(GITHUB_READ_PERMISSIONS) + + return permissions + + +def append_unique(existing: list, new_items: Iterable[str]) -> list[str]: + seen = set(existing) + added: list[str] = [] + for item in new_items: + if item not in seen: + existing.append(item) + seen.add(item) + added.append(item) + return added + + +def atomic_write_json(path: Path, payload: dict) -> None: + path.parent.mkdir(parents=True, exist_ok=True) + with tempfile.NamedTemporaryFile( + "w", + encoding="utf-8", + dir=str(path.parent), + delete=False, + ) as tmp: + json.dump(payload, tmp, indent=2) + tmp.write("\n") + tmp_path = Path(tmp.name) + + tmp_path.replace(path) + + +def main() -> None: + args = parse_args() + permissions_to_add = build_permissions(args) + + settings = load_settings(SETTINGS_PATH) + permissions = settings.setdefault("permissions", {}) + + if not isinstance(permissions, dict): + raise SystemExit("Expected permissions to be a JSON object.") + + allow = permissions.setdefault("allow", []) + if not isinstance(allow, list): + raise SystemExit("Expected permissions.allow to be a JSON array.") + + added = append_unique(allow, permissions_to_add) + + if not added: + print("Nothing to add โ€” all selected rules already present.") + return + + print(f"{'Would add' if args.dry_run else 'Adding'} {len(added)} rule(s):") + for rule in added: + print(f" + {rule}") + + if args.dry_run: + print("\nDry run โ€” no changes written.") + return + + atomic_write_json(SETTINGS_PATH, settings) + print(f"\nDone. {len(added)} rule(s) added to {SETTINGS_PATH}") + + +if __name__ == "__main__": + main() diff --git a/ko/10-cli/README.md b/ko/10-cli/README.md new file mode 100644 index 00000000..95ab7f76 --- /dev/null +++ b/ko/10-cli/README.md @@ -0,0 +1,1000 @@ + + + Claude How To + + +# CLI ์ฐธ์กฐ + +## ๊ฐœ์š” + +Claude Code CLI(๋ช…๋ น์ค„ ์ธํ„ฐํŽ˜์ด์Šค)๋Š” Claude Code์™€ ์ƒํ˜ธ ์ž‘์šฉํ•˜๋Š” ์ฃผ์š” ๋ฐฉ๋ฒ•์ž…๋‹ˆ๋‹ค. ์ด CLI๋Š” ์ฟผ๋ฆฌ๋ฅผ ์‹คํ–‰ํ•˜๊ณ , ์„ธ์…˜์„ ๊ด€๋ฆฌํ•˜๋ฉฐ, ๋ชจ๋ธ์„ ๊ตฌ์„ฑํ•˜๊ณ , Claude๋ฅผ ๊ฐœ๋ฐœ ์›Œํฌํ”Œ๋กœ์— ํ†ตํ•ฉํ•˜๊ธฐ ์œ„ํ•œ ๊ฐ•๋ ฅํ•œ ์˜ต์…˜์„ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. + +## ์•„ํ‚คํ…์ฒ˜ + +```mermaid +graph TD + A["User Terminal"] -->|"claude [options] [query]"| B["Claude Code CLI"] + B -->|Interactive| C["REPL Mode"] + B -->|"--print"| D["Print Mode (SDK)"] + B -->|"--resume"| E["Session Resume"] + C -->|Conversation| F["Claude API"] + D -->|Single Query| F + E -->|Load Context| F + F -->|Response| G["Output"] + G -->|text/json/stream-json| H["Terminal/Pipe"] +``` + +## ๋Ÿฐํƒ€์ž„ ๋ฐ ํŒจํ‚ค์ง• + +**v2.1.113**๋ถ€ํ„ฐ Claude Code CLI๋Š” ์„ ํƒ์  npm ์ข…์†์„ฑ์„ ํ†ตํ•ด **ํ”Œ๋žซํผ๋ณ„ ๋„ค์ดํ‹ฐ๋ธŒ ๋ฐ”์ด๋„ˆ๋ฆฌ**(macOS, Linux, Windows)๋ฅผ ์‹œ์ž‘ํ•ฉ๋‹ˆ๋‹ค. ์ด ๋ฐ”์ด๋„ˆ๋ฆฌ๋Š” ์„ค์น˜ ์‹œ ์šด์˜์ฒด์ œ ๋ฐ ์•„ํ‚คํ…์ฒ˜์— ๋งž์ถฐ์ง€๋ฉฐ, ์ด์ „ ๋ฒˆ๋“ค JavaScript ๋Ÿฐํƒ€์ž„์€ ๋” ์ด์ƒ macOS ๋˜๋Š” Linux์˜ ๊ธฐ๋ณธ๊ฐ’์ด ์•„๋‹™๋‹ˆ๋‹ค. + +**์‚ฌ์šฉ์ž ๋Œ€์ƒ ์„ค์น˜๋Š” ๋ณ€๊ฒฝ๋˜์ง€ ์•Š์•˜์Šต๋‹ˆ๋‹ค**: `npm install -g @anthropic-ai/claude-code`๋Š” ์—ฌ์ „ํžˆ ์ž‘๋™ํ•˜๋ฉฐ ๊ถŒ์žฅ ๊ฒฝ๋กœ๋กœ ๋‚จ์•„ ์žˆ์Šต๋‹ˆ๋‹ค. ๋‚ด๋ถ€์ ์œผ๋กœ npm์€ ์‚ฌ์šฉ์ž์˜ ํ”Œ๋žซํผ์— ๋งž๋Š” ์˜ฌ๋ฐ”๋ฅธ ๋„ค์ดํ‹ฐ๋ธŒ ๋ฐ”์ด๋„ˆ๋ฆฌ๋ฅผ ๊ฐ€์ ธ์˜ต๋‹ˆ๋‹ค. + +**๋‹ค์šด๋กœ๋“œ ํ˜ธ์ŠคํŠธ** (v2.1.116+): ๋„ค์ดํ‹ฐ๋ธŒ ๋ฐ”์ด๋„ˆ๋ฆฌ ์•„ํ‹ฐํŒฉํŠธ๋Š” `https://downloads.claude.ai/claude-code-releases`์—์„œ ์ œ๊ณต๋ฉ๋‹ˆ๋‹ค. + +> **๊ธฐ์—… / ํ”„๋ก์‹œ ์‚ฌ์šฉ์ž**: ๋„คํŠธ์›Œํฌ์—์„œ ๋ช…์‹œ์ ์ธ ํ—ˆ์šฉ ๋ชฉ๋ก์ด ํ•„์š”ํ•œ ๊ฒฝ์šฐ, `downloads.claude.ai` (๋ฐ `https://downloads.claude.ai/claude-code-releases`)๋ฅผ ํ”„๋ก์‹œ egress ๊ทœ์น™์— ์ถ”๊ฐ€ํ•˜์‹ญ์‹œ์˜ค. ์ด์ „์— `storage.googleapis.com` ๋˜๋Š” npm ๋ ˆ์ง€์ŠคํŠธ๋ฆฌ๋งŒ ํ—ˆ์šฉ ๋ชฉ๋ก์— ์ถ”๊ฐ€ํ–ˆ๋˜ ํ™˜๊ฒฝ์€ ์—…๋ฐ์ดํŠธํ•ด์•ผ ํ•˜๋ฉฐ, ๊ทธ๋ ‡์ง€ ์•Š์œผ๋ฉด `claude update` ๋ฐ ์ดˆ๊ธฐ ์„ค์น˜๊ฐ€ ์‹คํŒจํ•ฉ๋‹ˆ๋‹ค. + +์ด์ „ JavaScript ๋ฒˆ๋“ค์€ Windows ๋ฐ ํ•ด๋‹น ๋ฒˆ๋“ค์— ๊ณ ์ •๋œ ํ™˜๊ฒฝ์„ ์œ„ํ•ด ์—ฌ์ „ํžˆ ์ƒ์„ฑ๋ฉ๋‹ˆ๋‹ค. ์ด๋Ÿฌํ•œ ์„ค์น˜๋Š” Glob ๋ฐ Grep์„ ์ผ๋“ฑ ๋„๊ตฌ๋กœ ๊ณ„์† ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค([๋„๊ตฌ ๋ฐ ๊ถŒํ•œ ๊ด€๋ฆฌ](#๋„๊ตฌ-๋ฐ-๊ถŒํ•œ-๊ด€๋ฆฌ) ์„น์…˜์˜ Glob/Grep ๊ฐ์ฃผ ์ฐธ์กฐ). + +## CLI ๋ช…๋ น + +| Command | Description | Example | +|---------|-------------|---------| +| `claude` | ๋Œ€ํ™”ํ˜• REPL์„ ์‹œ์ž‘ํ•ฉ๋‹ˆ๋‹ค | `claude` | +| `claude "query"` | ์ดˆ๊ธฐ ํ”„๋กฌํ”„ํŠธ๋กœ REPL์„ ์‹œ์ž‘ํ•ฉ๋‹ˆ๋‹ค | `claude "explain this project"` | +| `claude -p "query"` | ์ธ์‡„ ๋ชจ๋“œ - ์ฟผ๋ฆฌ ํ›„ ์ข…๋ฃŒํ•ฉ๋‹ˆ๋‹ค | `claude -p "explain this function"` | +| `cat file \| claude -p "query"` | ํŒŒ์ดํ”„๋œ ์ฝ˜ํ…์ธ ๋ฅผ ์ฒ˜๋ฆฌํ•ฉ๋‹ˆ๋‹ค | `cat logs.txt \| claude -p "explain"` | +| `claude -c` | ๊ฐ€์žฅ ์ตœ๊ทผ ๋Œ€ํ™”๋ฅผ ๊ณ„์†ํ•ฉ๋‹ˆ๋‹ค | `claude -c` | +| `claude -c -p "query"` | ์ธ์‡„ ๋ชจ๋“œ์—์„œ ๊ณ„์†ํ•ฉ๋‹ˆ๋‹ค | `claude -c -p "check for type errors"` | +| `claude -r "" "query"` | ID ๋˜๋Š” ์ด๋ฆ„์œผ๋กœ ์„ธ์…˜์„ ์žฌ๊ฐœํ•ฉ๋‹ˆ๋‹ค | `claude -r "auth-refactor" "finish this PR"` | +| `claude update` | ์ตœ์‹  ๋ฒ„์ „์œผ๋กœ ์—…๋ฐ์ดํŠธํ•ฉ๋‹ˆ๋‹ค | `claude update` | +| `/doctor` (slash command) | ์„ค์น˜, ๊ตฌ์„ฑ ๋ฐ ํ”Œ๋Ÿฌ๊ทธ์ธ ์ƒํƒœ๋ฅผ ์ง„๋‹จํ•ฉ๋‹ˆ๋‹ค. v2.1.116๋ถ€ํ„ฐ Claude๊ฐ€ ์‘๋‹ต ์ค‘์ผ ๋•Œ๋„ ์—ด ์ˆ˜ ์žˆ์œผ๋ฉฐ, ์ƒํƒœ ์•„์ด์ฝ˜์„ ์ธ๋ผ์ธ์œผ๋กœ ํ‘œ์‹œํ•˜๊ณ , ๊ฐ์ง€๋œ ๋ฌธ์ œ๋ฅผ ์ž๋™์œผ๋กœ ํ•ด๊ฒฐํ•˜๊ธฐ ์œ„ํ•ด `f` ํ‚ค ์ž…๋ ฅ์„ ๋ฐ›์Šต๋‹ˆ๋‹ค. v2.1.178์—์„œ๋Š” ๋ ˆ์ด์•„์›ƒ์ด ๋” ๋ช…ํ™•ํ•œ ์ƒํƒœ ์•„์ด์ฝ˜๊ณผ ๊ฐ•์กฐ๋œ ๋ช…๋ น์ด ์žˆ๋Š” ํ‰๋ฉด ํŠธ๋ฆฌ๋กœ ์ƒˆ๋กœ ๊ณ ์ณ์กŒ์Šต๋‹ˆ๋‹ค | REPL ๋‚ด์—์„œ `/doctor`๋ฅผ ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค | +| `claude mcp` | MCP ์„œ๋ฒ„๋ฅผ ๊ตฌ์„ฑํ•ฉ๋‹ˆ๋‹ค (์ธ์ฆ์„ ์œ„ํ•œ `login`/`logout` ํฌํ•จ, v2.1.186+). | [MCP ๋ฌธ์„œ](../05-mcp/)๋ฅผ ์ฐธ์กฐํ•˜์‹ญ์‹œ์˜ค | +| `claude mcp serve` | Claude Code๋ฅผ MCP ์„œ๋ฒ„๋กœ ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค | `claude mcp serve` | +| `claude agents` | **์—์ด์ „ํŠธ ๋ทฐ**๋ฅผ ์—ฝ๋‹ˆ๋‹ค (์—ฐ๊ตฌ ๋ฏธ๋ฆฌ๋ณด๊ธฐ, v2.1.139+) โ€” ๋ชจ๋“  Claude Code ์„ธ์…˜์„ ์ƒํƒœ์™€ ํ•จ๊ป˜ ๋‚˜์—ดํ•˜๋Š” ๋‹ค์ค‘ ์„ธ์…˜ ๊ด€๋ฆฌ์ž์ž…๋‹ˆ๋‹ค. ์•„๋ž˜ [์—์ด์ „ํŠธ ๋ทฐ](#์—์ด์ „ํŠธ-๋ทฐ-claude-agents-v21139)๋ฅผ ์ฐธ์กฐํ•˜์‹ญ์‹œ์˜ค. | `claude agents` | +| `claude auto-mode defaults` | ์ž๋™ ๋ชจ๋“œ ๊ธฐ๋ณธ ๊ทœ์น™์„ JSON์œผ๋กœ ์ถœ๋ ฅํ•ฉ๋‹ˆ๋‹ค | `claude auto-mode defaults` | +| `claude remote-control` | ์›๊ฒฉ ์ œ์–ด ์„œ๋ฒ„๋ฅผ ์‹œ์ž‘ํ•ฉ๋‹ˆ๋‹ค | `claude remote-control` | +| `claude plugin` | ํ”Œ๋Ÿฌ๊ทธ์ธ์„ ๊ด€๋ฆฌํ•ฉ๋‹ˆ๋‹ค (์„ค์น˜, ํ™œ์„ฑํ™”, ๋น„ํ™œ์„ฑํ™”) | `claude plugin install my-plugin` | +| `claude plugin init ` | `.claude/skills`์— ์ƒˆ ํ”Œ๋Ÿฌ๊ทธ์ธ์„ ์Šค์บํด๋”ฉํ•ฉ๋‹ˆ๋‹ค โ€” ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ์—†์ด ์ž๋™ ๋กœ๋“œ๋ฉ๋‹ˆ๋‹ค (v2.1.157+) | `claude plugin init my-plugin` | +| `claude plugin tag ` | ๋ฒ„์ „ ์œ ํšจ์„ฑ ๊ฒ€์‚ฌ๋กœ ํ”Œ๋Ÿฌ๊ทธ์ธ์˜ ๋ฆด๋ฆฌ์Šค git ํƒœ๊ทธ๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค (v2.1.118+) | `claude plugin tag v0.3.0` | +| `claude install [version]` | ํŠน์ • ๋„ค์ดํ‹ฐ๋ธŒ ๋ฐ”์ด๋„ˆ๋ฆฌ ๋ฒ„์ „์„ ์„ค์น˜ํ•ฉ๋‹ˆ๋‹ค. `stable`, `latest` ๋˜๋Š” ๋ช…์‹œ์ ์ธ ๋ฒ„์ „ ๋ฌธ์ž์—ด์„ ๋ฐ›์Šต๋‹ˆ๋‹ค | `claude install 2.1.131` | +| `claude project purge [path]` | ํ”„๋กœ์ ํŠธ์˜ ๋ชจ๋“  ๋กœ์ปฌ Claude Code ์ƒํƒœ๋ฅผ ์‚ญ์ œํ•ฉ๋‹ˆ๋‹ค (๋Œ€๋ณธ, ์ž‘์—…, ๋””๋ฒ„๊ทธ ๋กœ๊ทธ, ํŒŒ์ผ ํŽธ์ง‘ ๊ธฐ๋ก, ํ”„๋กฌํ”„ํŠธ ๊ธฐ๋ก ๋ฐ `~/.claude.json` ํ•ญ๋ชฉ). ์ƒํ˜ธ ์ž‘์šฉ ์„ ํƒ๊ธฐ๋ฅผ ์‚ฌ์šฉํ•˜๋ ค๋ฉด `[path]`๋ฅผ ์ƒ๋žตํ•˜์‹ญ์‹œ์˜ค. ํ”Œ๋ž˜๊ทธ: `--dry-run`์œผ๋กœ ๋ฏธ๋ฆฌ๋ณด๊ธฐ, `-y/--yes`๋กœ ํ™•์ธ ๊ฑด๋„ˆ๋›ฐ๊ธฐ, `-i/--interactive`๋กœ ๊ฐ ํ•ญ๋ชฉ ํ™•์ธ, `--all`๋กœ ๋ชจ๋“  ํ”„๋กœ์ ํŠธ (v2.1.126+) | `claude project purge ~/work/repo --dry-run` | +| `claude plugin prune` | ๊ณ ์•„ ์ƒํƒœ์˜ ์ž๋™ ์„ค์น˜ ํ”Œ๋Ÿฌ๊ทธ์ธ ์ข…์†์„ฑ์„ ์ œ๊ฑฐํ•ฉ๋‹ˆ๋‹ค (๋ถ€๋ชจ ํ”Œ๋Ÿฌ๊ทธ์ธ ์—†์Œ). `plugin uninstall --prune`์€ ๋Œ€์ƒ ์ œ๊ฑฐ ํ›„ ๋™์ผํ•œ ์—ฐ์‡„ ์ œ๊ฑฐ๋ฅผ ์ˆ˜ํ–‰ํ•ฉ๋‹ˆ๋‹ค (v2.1.121+) | `claude plugin prune` | +| `claude ultrareview [target]` | `/ultrareview`๋ฅผ ๋น„๋Œ€ํ™”ํ˜•์œผ๋กœ ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค. ๊ฒฐ๊ณผ๋ฅผ ํ‘œ์ค€ ์ถœ๋ ฅ์œผ๋กœ ์ถœ๋ ฅํ•˜๊ณ , ์„ฑ๊ณต ์‹œ 0, ์‹คํŒจ ์‹œ 1์„ ๋ฐ˜ํ™˜ํ•ฉ๋‹ˆ๋‹ค. ์›์‹œ ํŽ˜์ด๋กœ๋“œ๋ฅผ ์œ„ํ•ด์„œ๋Š” `--json`์„, 30๋ถ„ ๊ธฐ๋ณธ๊ฐ’์„ ์žฌ์ •์˜ํ•˜๋ ค๋ฉด `--timeout `๋ฅผ ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค (v2.1.120+) | `claude ultrareview 1234 --json` | +| `claude auth login` | ๋กœ๊ทธ์ธํ•ฉ๋‹ˆ๋‹ค (`--email`, `--sso` ์ง€์›). v2.1.126๋ถ€ํ„ฐ ๋ธŒ๋ผ์šฐ์ € ์ฝœ๋ฐฑ์ด ๋กœ์ปฌํ˜ธ์ŠคํŠธ์— ๋„๋‹ฌํ•  ์ˆ˜ ์—†์„ ๋•Œ (WSL2, SSH, ์ปจํ…Œ์ด๋„ˆ) ํ„ฐ๋ฏธ๋„์— ๋ถ™์—ฌ๋„ฃ์€ OAuth ์ฝ”๋“œ๋ฅผ ํด๋ฐฑ์œผ๋กœ ๋ฐ›์Šต๋‹ˆ๋‹ค | `claude auth login --email user@example.com` | +| `claude auth logout` | ํ˜„์žฌ ๊ณ„์ •์—์„œ ๋กœ๊ทธ์•„์›ƒํ•ฉ๋‹ˆ๋‹ค | `claude auth logout` | +| `claude auth status` | ์ธ์ฆ ์ƒํƒœ๋ฅผ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค (๋กœ๊ทธ์ธ๋˜์–ด ์žˆ์œผ๋ฉด 0, ์•„๋‹ˆ๋ฉด 1์„ ๋ฐ˜ํ™˜) | `claude auth status` | + +## ํ•ต์‹ฌ ํ”Œ๋ž˜๊ทธ + +| Flag | Description | Example | +|------|-------------|---------| +| `-p, --print` | ๋Œ€ํ™”ํ˜• ๋ชจ๋“œ ์—†์ด ์‘๋‹ต์„ ์ถœ๋ ฅํ•ฉ๋‹ˆ๋‹ค | `claude -p "query"` | +| `-c, --continue` | ๊ฐ€์žฅ ์ตœ๊ทผ ๋Œ€ํ™”๋ฅผ ๋กœ๋“œํ•ฉ๋‹ˆ๋‹ค | `claude --continue` | +| `-r, --resume` | ID ๋˜๋Š” ์ด๋ฆ„์œผ๋กœ ํŠน์ • ์„ธ์…˜์„ ์žฌ๊ฐœํ•ฉ๋‹ˆ๋‹ค | `claude --resume auth-refactor` | +| `-v, --version` | ๋ฒ„์ „ ๋ฒˆํ˜ธ๋ฅผ ์ถœ๋ ฅํ•ฉ๋‹ˆ๋‹ค | `claude -v` | +| `-w, --worktree` | ๊ณ ๋ฆฝ๋œ Git ์›ŒํฌํŠธ๋ฆฌ์—์„œ ์‹œ์ž‘ํ•ฉ๋‹ˆ๋‹ค | `claude -w` | +| `-n, --name` | ์„ธ์…˜ ํ‘œ์‹œ ์ด๋ฆ„ | `claude -n "auth-refactor"` | +| `--from-pr ` | ํ’€/๋จธ์ง€ ์š”์ฒญ์— ์—ฐ๊ฒฐ๋œ ์„ธ์…˜์„ ์žฌ๊ฐœํ•ฉ๋‹ˆ๋‹ค. v2.1.119๋ถ€ํ„ฐ GitHub (ํด๋ผ์šฐ๋“œ + ์—”ํ„ฐํ”„๋ผ์ด์ฆˆ), GitLab MR, Bitbucket PR URL์„ ๋ฐ›์Šต๋‹ˆ๋‹ค; ์ด์ „์—๋Š” GitHub.com๋งŒ ๊ฐ€๋Šฅํ–ˆ์Šต๋‹ˆ๋‹ค | `claude --from-pr 42` or `claude --from-pr https://gitlab.example.com/org/repo/-/merge_requests/17` | +| `--remote "task"` | claude.ai์—์„œ ์›น ์„ธ์…˜์„ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค | `claude --remote "implement API"` | +| `--remote-control, --rc` | ์›๊ฒฉ ์ œ์–ด๋ฅผ ํ†ตํ•œ ๋Œ€ํ™”ํ˜• ์„ธ์…˜ | `claude --rc` | +| `--teleport` | ์›น ์„ธ์…˜์„ ๋กœ์ปฌ์—์„œ ์žฌ๊ฐœํ•ฉ๋‹ˆ๋‹ค | `claude --teleport` | +| `--teammate-mode` | ์—์ด์ „ํŠธ ํŒ€ ํ‘œ์‹œ ๋ชจ๋“œ | `claude --teammate-mode tmux` | +| `--bare` | ์ตœ์†Œ ๋ชจ๋“œ (ํ›…, ์Šคํ‚ฌ, ํ”Œ๋Ÿฌ๊ทธ์ธ, MCP, ์ž๋™ ๋ฉ”๋ชจ๋ฆฌ, CLAUDE.md ๊ฑด๋„ˆ๋›ฐ๊ธฐ) | `claude --bare` | +| `--safe-mode` | ๋ชจ๋“  ์‚ฌ์šฉ์ž ์ •์˜๋ฅผ ๋น„ํ™œ์„ฑํ™”ํ•œ ์ƒํƒœ๋กœ ์‹œ์ž‘ํ•˜์—ฌ (CLAUDE.md, ํ”Œ๋Ÿฌ๊ทธ์ธ, ์Šคํ‚ฌ, ํ›…, MCP) ๊ตฌ์„ฑ ๋ฌธ์ œ๋ฅผ ๊ฒฉ๋ฆฌํ•ฉ๋‹ˆ๋‹ค; `CLAUDE_CODE_SAFE_MODE=1`๋„ ๊ฐ€๋Šฅํ•ฉ๋‹ˆ๋‹ค (v2.1.169) | `claude --safe-mode` | +| `--enable-auto-mode` | ์ž๋™ ๊ถŒํ•œ ๋ชจ๋“œ๋ฅผ ์ž ๊ธˆ ํ•ด์ œํ•ฉ๋‹ˆ๋‹ค (Opus 4.7์˜ Max ๊ตฌ๋…์ž์—๊ฒŒ๋Š” ๋” ์ด์ƒ ํ•„์š”ํ•˜์ง€ ์•Š์Œ) | `claude --enable-auto-mode` | +| `--channels` | MCP ์ฑ„๋„ ํ”Œ๋Ÿฌ๊ทธ์ธ์„ ๊ตฌ๋…ํ•ฉ๋‹ˆ๋‹ค | `claude --channels discord,telegram` | +| `--chrome` / `--no-chrome` | Chrome ๋ธŒ๋ผ์šฐ์ € ํ†ตํ•ฉ์„ ํ™œ์„ฑํ™”/๋น„ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค | `claude --chrome` | +| `--effort` | ์‚ฌ๊ณ  ๋…ธ๋ ฅ ์ˆ˜์ค€์„ ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค | `claude --effort high` | +| `--init` / `--init-only` | ์ดˆ๊ธฐํ™” ํ›…์„ ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค | `claude --init` | +| `--maintenance` | ์œ ์ง€๋ณด์ˆ˜ ํ›…์„ ์‹คํ–‰ํ•˜๊ณ  ์ข…๋ฃŒํ•ฉ๋‹ˆ๋‹ค | `claude --maintenance` | +| `--disable-slash-commands` | ๋ชจ๋“  ์Šคํ‚ฌ๊ณผ ์Šฌ๋ž˜์‹œ ๋ช…๋ น์„ ๋น„ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค | `claude --disable-slash-commands` | +| `--no-session-persistence` | ์„ธ์…˜ ์ €์žฅ์„ ๋น„ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค (์ธ์‡„ ๋ชจ๋“œ) | `claude -p --no-session-persistence "query"` | +| `--exclude-dynamic-system-prompt-sections` | ๋” ๋‚˜์€ ํ”„๋กฌํ”„ํŠธ ์บ์‹œ ์ ์ค‘๋ฅ ์„ ์œ„ํ•ด ์‹œ์Šคํ…œ ํ”„๋กฌํ”„ํŠธ์—์„œ ๋™์  ์„น์…˜์„ ์ œ์™ธํ•ฉ๋‹ˆ๋‹ค | `claude -p --exclude-dynamic-system-prompt-sections "query"` | + +### ๋Œ€ํ™”ํ˜• ๋ชจ๋“œ vs ์ธ์‡„ ๋ชจ๋“œ + +```mermaid +graph LR + A["claude"] -->|Default| B["Interactive REPL"] + A -->|"-p flag"| C["Print Mode"] + B -->|Features| D["Multi-turn conversation
Tab completion
History
Slash commands"] + C -->|Features| E["Single query
Scriptable
Pipeable
JSON output"] +``` + +**๋Œ€ํ™”ํ˜• ๋ชจ๋“œ** (๊ธฐ๋ณธ๊ฐ’): +```bash +# ๋Œ€ํ™”ํ˜• ์„ธ์…˜์„ ์‹œ์ž‘ํ•ฉ๋‹ˆ๋‹ค +claude + +# ์ดˆ๊ธฐ ํ”„๋กฌํ”„ํŠธ๋กœ ์‹œ์ž‘ํ•ฉ๋‹ˆ๋‹ค +claude "explain the authentication flow" +``` + +**์ธ์‡„ ๋ชจ๋“œ** (๋น„๋Œ€ํ™”ํ˜•): +```bash +# ๋‹จ์ผ ์ฟผ๋ฆฌ ํ›„ ์ข…๋ฃŒํ•ฉ๋‹ˆ๋‹ค +claude -p "what does this function do?" + +# ํŒŒ์ผ ์ฝ˜ํ…์ธ ๋ฅผ ์ฒ˜๋ฆฌํ•ฉ๋‹ˆ๋‹ค +cat error.log | claude -p "explain this error" + +# ๋‹ค๋ฅธ ๋„๊ตฌ์™€ ์—ฐ๊ฒฐํ•ฉ๋‹ˆ๋‹ค +claude -p "list todos" | grep "URGENT" +``` + +## ๋ชจ๋ธ ๋ฐ ๊ตฌ์„ฑ + +| Flag | Description | Example | +|------|-------------|---------| +| `--model` | ๋ชจ๋ธ์„ ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค (sonnet, opus, haiku ๋˜๋Š” ์ „์ฒด ์ด๋ฆ„) | `claude --model opus` | +| `--fallback-model` | ๊ธฐ๋ณธ ๋ชจ๋ธ์ด ๊ณผ๋ถ€ํ•˜๋˜๊ฑฐ๋‚˜ ์‚ฌ์šฉ ๋ถˆ๊ฐ€๋Šฅํ•  ๋•Œ ์ž๋™ ๋ชจ๋ธ ํด๋ฐฑ; `fallbackModel` ์„ค์ •์„ ํ†ตํ•ด ์ตœ๋Œ€ 3๊ฐœ๊นŒ์ง€ ๊ตฌ์„ฑํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. v2.1.166๋ถ€ํ„ฐ ๋Œ€ํ™”ํ˜• ์„ธ์…˜์—๋„ ์ ์šฉ๋ฉ๋‹ˆ๋‹ค (์ด์ „์—๋Š” ์ธ์‡„ ๋ชจ๋“œ ์ „์šฉ) | `claude -p --fallback-model sonnet "query"` | +| `--agent` | ์„ธ์…˜์— ์‚ฌ์šฉํ•  ์—์ด์ „ํŠธ๋ฅผ ์ง€์ •ํ•ฉ๋‹ˆ๋‹ค | `claude --agent my-custom-agent` | +| `--agents` | JSON์„ ํ†ตํ•ด ์‚ฌ์šฉ์ž ์ •์˜ ์„œ๋ธŒ์—์ด์ „ํŠธ๋ฅผ ์ •์˜ํ•ฉ๋‹ˆ๋‹ค | [์—์ด์ „ํŠธ ๊ตฌ์„ฑ](#์—์ด์ „ํŠธ-๊ตฌ์„ฑ) ์ฐธ์กฐ | +| `--effort` | ๋…ธ๋ ฅ ์ˆ˜์ค€์„ ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค (low, medium, high, xhigh, max) | `claude --effort xhigh` | + +### ๋ชจ๋ธ ์„ ํƒ ์˜ˆ์‹œ + +```bash +# ๋ณต์žกํ•œ ์ž‘์—…์„ ์œ„ํ•ด Opus 4.8์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค +claude --model opus "design a caching strategy" + +# ๋น ๋ฅธ ์ž‘์—…์„ ์œ„ํ•ด Haiku 4.5๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค +claude --model haiku -p "format this JSON" + +# ์ „์ฒด ๋ชจ๋ธ ์ด๋ฆ„ +claude --model claude-sonnet-4-6-20250929 "review this code" + +# ์•ˆ์ •์„ฑ์„ ์œ„ํ•œ ํด๋ฐฑ ์‚ฌ์šฉ +claude -p --model opus --fallback-model sonnet "analyze architecture" + +# opusplan ์‚ฌ์šฉ (Opus๊ฐ€ ๊ณ„ํšํ•˜๊ณ  Sonnet์ด ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค) +claude --model opusplan "design and implement the caching layer" +``` + +> **๊ฒŒ์ดํŠธ์›จ์ด ๋ชจ๋ธ ํƒ์ƒ‰ (v2.1.129+, ์„ ํƒ ์‚ฌํ•ญ)**: `ANTHROPIC_BASE_URL`์ด Anthropic ํ˜ธํ™˜ ๊ฒŒ์ดํŠธ์›จ์ด๋ฅผ ๊ฐ€๋ฆฌํ‚ฌ ๋•Œ, `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1`์„ ์„ค์ •ํ•˜์—ฌ ๊ฒŒ์ดํŠธ์›จ์ด์˜ `/v1/models` ์—”๋“œํฌ์ธํŠธ์—์„œ `/model`์„ ์ฑ„์›๋‹ˆ๋‹ค. ํ™˜๊ฒฝ ๋ณ€์ˆ˜๊ฐ€ ์—†์œผ๋ฉด `/model`์€ ๋‚ด์žฅ๋œ ์ •์  ๋ชฉ๋ก์œผ๋กœ ํด๋ฐฑํ•ฉ๋‹ˆ๋‹ค. ์ด ํ”Œ๋ž˜๊ทธ๋Š” ์‚ฌ์šฉ์ž๊ฐ€ ์‚ฌ์šฉํ•  ๊ถŒํ•œ์ด ์—†๋Š” ๋ชจ๋ธ์„ ๋ฐœ๊ฒฌํ•  ์ˆ˜ ์žˆ๊ธฐ ๋•Œ๋ฌธ์— ์„ ํƒ ์‚ฌํ•ญ์ž…๋‹ˆ๋‹ค (v2.1.129์—์„œ ๋ณ€๊ฒฝ๋จ). v2.1.126์—์„œ๋Š” ์•”๋ฌต์ ์ด์—ˆ์œผ๋ฉฐ ํ•ด๋‹น ๋™์ž‘์€ ๋˜๋Œ๋ ค์กŒ์Šต๋‹ˆ๋‹ค. + +## ์‹œ์Šคํ…œ ํ”„๋กฌํ”„ํŠธ ์‚ฌ์šฉ์ž ์ •์˜ + +| Flag | Description | Example | +|------|-------------|---------| +| `--system-prompt` | ์ „์ฒด ๊ธฐ๋ณธ ํ”„๋กฌํ”„ํŠธ๋ฅผ ๋Œ€์ฒดํ•ฉ๋‹ˆ๋‹ค | `claude --system-prompt "You are a Python expert"` | +| `--system-prompt-file` | ํŒŒ์ผ์—์„œ ํ”„๋กฌํ”„ํŠธ๋ฅผ ๋กœ๋“œํ•ฉ๋‹ˆ๋‹ค (์ธ์‡„ ๋ชจ๋“œ) | `claude -p --system-prompt-file ./prompt.txt "query"` | +| `--append-system-prompt` | ๊ธฐ๋ณธ ํ”„๋กฌํ”„ํŠธ์— ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค | `claude --append-system-prompt "Always use TypeScript"` | + +### ์‹œ์Šคํ…œ ํ”„๋กฌํ”„ํŠธ ์˜ˆ์‹œ + +```bash +# ์™„์ „ํ•œ ์‚ฌ์šฉ์ž ์ •์˜ ํŽ˜๋ฅด์†Œ๋‚˜ +claude --system-prompt "You are a senior security engineer. Focus on vulnerabilities." + +# ํŠน์ • ์ง€์‹œ์‚ฌํ•ญ ์ถ”๊ฐ€ +claude --append-system-prompt "Always include unit tests with code examples" + +# ํŒŒ์ผ์—์„œ ๋ณต์žกํ•œ ํ”„๋กฌํ”„ํŠธ ๋กœ๋“œ +claude -p --system-prompt-file ./prompts/code-reviewer.txt "review main.py" +``` + +### ์‹œ์Šคํ…œ ํ”„๋กฌํ”„ํŠธ ํ”Œ๋ž˜๊ทธ ๋น„๊ต + +| Flag | Behavior | Interactive | Print | +|------|----------|-------------|-------| +| `--system-prompt` | ์ „์ฒด ๊ธฐ๋ณธ ์‹œ์Šคํ…œ ํ”„๋กฌํ”„ํŠธ๋ฅผ ๋Œ€์ฒดํ•ฉ๋‹ˆ๋‹ค | โœ… | โœ… | +| `--system-prompt-file` | ํŒŒ์ผ์˜ ํ”„๋กฌํ”„ํŠธ๋กœ ๋Œ€์ฒดํ•ฉ๋‹ˆ๋‹ค | โŒ | โœ… | +| `--append-system-prompt` | ๊ธฐ๋ณธ ์‹œ์Šคํ…œ ํ”„๋กฌํ”„ํŠธ์— ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค | โœ… | โœ… | + +**`--system-prompt-file`์€ ์ธ์‡„ ๋ชจ๋“œ์—์„œ๋งŒ ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค. ๋Œ€ํ™”ํ˜• ๋ชจ๋“œ์—์„œ๋Š” `--system-prompt` ๋˜๋Š” `--append-system-prompt`๋ฅผ ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค.** + +## ๋„๊ตฌ ๋ฐ ๊ถŒํ•œ ๊ด€๋ฆฌ + +| Flag | Description | Example | +|------|-------------|---------| +| `--tools` | ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ๋‚ด์žฅ ๋„๊ตฌ๋ฅผ ์ œํ•œํ•ฉ๋‹ˆ๋‹ค | `claude -p --tools "Bash,Edit,Read" "query"` | +| `--allowedTools` | ํ”„๋กฌํ”„ํŠธ ์—†์ด ์‹คํ–‰๋˜๋Š” ๋„๊ตฌ | `"Bash(git log:*)" "Read"` | +| `--disallowedTools` | ์ปจํ…์ŠคํŠธ์—์„œ ์ œ๊ฑฐ๋œ ๋„๊ตฌ | `"Bash(rm:*)" "Edit"` | +| `--dangerously-skip-permissions` | ๋ชจ๋“  ๊ถŒํ•œ ํ”„๋กฌํ”„ํŠธ๋ฅผ ๊ฑด๋„ˆ๋œ๋‹ˆ๋‹ค | `claude --dangerously-skip-permissions` | +| `--permission-mode` | ์ง€์ •๋œ ๊ถŒํ•œ ๋ชจ๋“œ์—์„œ ์‹œ์ž‘ํ•ฉ๋‹ˆ๋‹ค | `claude --permission-mode auto` | +| `--permission-prompt-tool` | ๊ถŒํ•œ ์ฒ˜๋ฆฌ๋ฅผ ์œ„ํ•œ MCP ๋„๊ตฌ | `claude -p --permission-prompt-tool mcp_auth "query"` | +| `--enable-auto-mode` | ์ž๋™ ๊ถŒํ•œ ๋ชจ๋“œ๋ฅผ ์ž ๊ธˆ ํ•ด์ œํ•ฉ๋‹ˆ๋‹ค | `claude --enable-auto-mode` | + +> **Glob / Grep ๊ฐ์ฃผ (v2.1.113+)**: ๋„ค์ดํ‹ฐ๋ธŒ macOS/Linux ๋นŒ๋“œ์—์„œ๋Š” `Glob` ๋ฐ `Grep`์ด ๋ณ„๋„์˜ ์ผ๋“ฑ ๋„๊ตฌ๊ฐ€ ์•„๋‹Œ Bash ๋„๊ตฌ๋ฅผ ํ†ตํ•ด ํ˜ธ์ถœ๋˜๋Š” ๋‚ด์žฅ `bfs` ๋ฐ `ugrep` ๋ฐ”์ด๋„ˆ๋ฆฌ๋กœ ์ œ๊ณต๋ฉ๋‹ˆ๋‹ค. Windows ๋ฐ npm ๋ฒˆ๋“ค(JS) ์„ค์น˜๋Š” ์—ฌ์ „ํžˆ ์ด๋ฅผ ๋…๋ฆฝํ˜• ๋„๊ตฌ๋กœ ๋…ธ์ถœํ•ฉ๋‹ˆ๋‹ค. ์„œ๋ธŒ์—์ด์ „ํŠธ `allowedTools` / `disallowedTools` ๋ชฉ๋ก์˜ ๊ฒฝ์šฐ ๋ฐฑ์—”๋“œ ๋Œ€์ฒด๋Š” ํˆฌ๋ช…ํ•ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  ํ”Œ๋žซํผ์—์„œ `Glob` / `Grep`์„ ๊ตฌ์„ฑ์—์„œ ๊ณ„์† ์ฐธ์กฐํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +> **PowerShell ์ž๋™ ์Šน์ธ (v2.1.119)**: PowerShell ๋„๊ตฌ ๋ช…๋ น์€ Bash ๋ช…๋ น๊ณผ ๋™์ผํ•œ ๋ฐฉ์‹์œผ๋กœ ๊ถŒํ•œ ๋ชจ๋“œ์—์„œ ์ž๋™ ์Šน์ธ๋  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. `Bash(...)` ๊ทœ์น™์— ์ด๋ฏธ ์‚ฌ์šฉํ•˜๊ณ  ์žˆ๋Š” ๊ฒƒ๊ณผ ๋™์ผํ•œ ๋งค์ฒ˜ ๊ตฌ๋ฌธ์„ ์‚ฌ์šฉํ•˜์—ฌ PowerShell ๊ถŒํ•œ์˜ ๋ฒ”์œ„๋ฅผ ์ง€์ •ํ•˜์‹ญ์‹œ์˜ค. ์˜ˆ๋ฅผ ๋“ค์–ด, `PowerShell(Get-ChildItem:*)`๊ณผ ๊ฐ™์Šต๋‹ˆ๋‹ค. + +> **์žฌ๊ฐœ ์‹œ `--permission-mode` ์ ์šฉ (v2.1.132+)**: `claude -p --continue --permission-mode plan` (๋ฐ `--resume`)์€ ์ด์ œ ์ด ํ”Œ๋ž˜๊ทธ๋ฅผ ์กด์ค‘ํ•ฉ๋‹ˆ๋‹ค. ์ด์ „ ๋ฒ„์ „์—์„œ๋Š” ์„ธ์…˜์„ ์žฌ๊ฐœํ•  ๋•Œ `--permission-mode`๋ฅผ ์ž๋™์œผ๋กœ ์‚ญ์ œํ•˜์—ฌ, ํ”Œ๋ž˜๊ทธ๋ฅผ ๋‹ค์‹œ ์ „๋‹ฌํ•˜์ง€ ์•Š๊ณ  ์žฌ๊ฐœ๋œ ๊ณ„ํš ๋ชจ๋“œ ์„ธ์…˜์ด ์ž๋™์œผ๋กœ ๋‹ค์šด๊ทธ๋ ˆ์ด๋“œ๋˜๋Š” ๋ฌธ์ œ๊ฐ€ ์žˆ์—ˆ๋Š”๋ฐ, ์ด๋Š” ํ•ด๊ฒฐ๋˜์—ˆ์Šต๋‹ˆ๋‹ค. + +### ๊ถŒํ•œ ์˜ˆ์‹œ + +```bash +# ์ฝ”๋“œ ๊ฒ€ํ† ๋ฅผ ์œ„ํ•œ ์ฝ๊ธฐ ์ „์šฉ ๋ชจ๋“œ +claude --permission-mode plan "review this codebase" + +# ์•ˆ์ „ํ•œ ๋„๊ตฌ๋กœ๋งŒ ์ œํ•œ +claude --tools "Read,Grep,Glob" -p "find all TODO comments" + +# ํ”„๋กฌํ”„ํŠธ ์—†์ด ํŠน์ • git ๋ช…๋ น ํ—ˆ์šฉ +claude --allowedTools "Bash(git status:*)" "Bash(git log:*)" + +# ์œ„ํ—˜ํ•œ ์ž‘์—… ์ฐจ๋‹จ +claude --disallowedTools "Bash(rm -rf:*)" "Bash(git push --force:*)" +``` + +> **๋งค๊ฐœ๋ณ€์ˆ˜ ์ผ์น˜ `Tool(param:value)` (v2.1.178)**: ๊ถŒํ•œ ๊ทœ์น™์€ `Tool` (๋ชจ๋“  ์‚ฌ์šฉ) ๋˜๋Š” `Tool(specifier)` ํ˜•์‹์„ ๋”ฐ๋ฆ…๋‹ˆ๋‹ค. v2.1.178๋ถ€ํ„ฐ ์ง€์ •์ž๋Š” ๋ช…๋ น ๋˜๋Š” ๊ฒฝ๋กœ ํŒจํ„ด๋ฟ๋งŒ ์•„๋‹ˆ๋ผ ์™€์ผ๋“œ์นด๋“œ ์ง€์›์„ ํ†ตํ•ด ๋„๊ตฌ์˜ ์ž…๋ ฅ **๋งค๊ฐœ๋ณ€์ˆ˜**์™€๋„ ์ผ์น˜ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค(`Tool(param:value)` ํ˜•์‹ ์‚ฌ์šฉ). ์ด๋Š” `Bash(...)` ๋ช…๋ น ์ ‘๋‘์‚ฌ(์˜ˆ: `Bash(npm run test *)`) ๋ฐ `Read(...)` ๊ฒฝ๋กœ glob(์˜ˆ: `Read(./.env.*)`)์— ์ด๋ฏธ ์‚ฌ์šฉํ•˜๋Š” ์ผ์น˜ ๋ฐฉ์‹์„ ์ผ๋ฐ˜ํ™”ํ•˜์—ฌ ๋‹ค๋ฅธ ๋„๊ตฌ๋„ ์ธ์ˆ˜์— ๋”ฐ๋ผ ๋ฒ”์œ„๊ฐ€ ์ง€์ •๋  ์ˆ˜ ์žˆ๋„๋ก ํ•ฉ๋‹ˆ๋‹ค. ๊ทœ์น™์„ ์ž‘์„ฑํ•˜๊ธฐ ์ „์— ๋„๊ตฌ๋ณ„ ์˜ˆ์‹œ ๋ฌธ์ž์—ด์€ ์ •ํ™•ํ•œ ๋งค๊ฐœ๋ณ€์ˆ˜ ์ด๋ฆ„์ด ๋„๊ตฌ๋งˆ๋‹ค ๋‹ค๋ฅด๋ฏ€๋กœ [๊ถŒํ•œ ์ฐธ์กฐ](https://code.claude.com/docs/en/settings)๋ฅผ ํ™•์ธํ•˜์‹ญ์‹œ์˜ค. + +## ์ถœ๋ ฅ ๋ฐ ํ˜•์‹ + +| Flag | Description | Options | Example | +|------|-------------|---------|---------| +| `--output-format` | ์ถœ๋ ฅ ํ˜•์‹์„ ์ง€์ •ํ•ฉ๋‹ˆ๋‹ค (์ธ์‡„ ๋ชจ๋“œ) | `text`, `json`, `stream-json` | `claude -p --output-format json "query"` | +| `--input-format` | ์ž…๋ ฅ ํ˜•์‹์„ ์ง€์ •ํ•ฉ๋‹ˆ๋‹ค (์ธ์‡„ ๋ชจ๋“œ) | `text`, `stream-json` | `claude -p --input-format stream-json` | +| `--verbose` | ์ƒ์„ธ ๋กœ๊น…์„ ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค | | `claude --verbose` | +| `--include-partial-messages` | ์ŠคํŠธ๋ฆฌ๋ฐ ์ด๋ฒคํŠธ๋ฅผ ํฌํ•จํ•ฉ๋‹ˆ๋‹ค | `stream-json` ํ•„์š” | `claude -p --output-format stream-json --include-partial-messages "query"` | +| `--json-schema` | ์Šคํ‚ค๋งˆ์™€ ์ผ์น˜ํ•˜๋Š” ์œ ํšจ์„ฑ ๊ฒ€์‚ฌ๋œ JSON์„ ๊ฐ€์ ธ์˜ต๋‹ˆ๋‹ค | | `claude -p --json-schema '{"type":"object"}' "query"` | +| `--max-budget-usd` | ์ธ์‡„ ๋ชจ๋“œ์— ๋Œ€ํ•œ ์ตœ๋Œ€ ์ง€์ถœ | | `claude -p --max-budget-usd 5.00 "query"` | + +### ์ถœ๋ ฅ ํ˜•์‹ ์˜ˆ์‹œ + +```bash +# ์ผ๋ฐ˜ ํ…์ŠคํŠธ (๊ธฐ๋ณธ๊ฐ’) +claude -p "explain this code" + +# ํ”„๋กœ๊ทธ๋ž˜๋ฐ ์‚ฌ์šฉ์„ ์œ„ํ•œ JSON +claude -p --output-format json "list all functions in main.py" + +# ์‹ค์‹œ๊ฐ„ ์ฒ˜๋ฆฌ๋ฅผ ์œ„ํ•œ ์ŠคํŠธ๋ฆฌ๋ฐ JSON +claude -p --output-format stream-json "generate a long report" + +# ์Šคํ‚ค๋งˆ ์œ ํšจ์„ฑ ๊ฒ€์‚ฌ๋ฅผ ํ†ตํ•œ ๊ตฌ์กฐํ™”๋œ ์ถœ๋ ฅ +claude -p --json-schema '{"type":"object","properties":{"bugs":{"type":"array"}}}' \ + "find bugs in this code and return as JSON" +``` + +## ์ž‘์—… ๊ณต๊ฐ„ ๋ฐ ๋””๋ ‰ํ† ๋ฆฌ + +| Flag | Description | Example | +|------|-------------|---------| +| `--add-dir` | ์ถ”๊ฐ€ ์ž‘์—… ๋””๋ ‰ํ† ๋ฆฌ๋ฅผ ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค | `claude --add-dir ../apps ../lib` | +| `--setting-sources` | ์‰ผํ‘œ๋กœ ๊ตฌ๋ถ„๋œ ์„ค์ • ์†Œ์Šค | `claude --setting-sources user,project` | + +> **`/config` ์˜์†์„ฑ (v2.1.119)**: `/config` ๋ช…๋ น์„ ํ†ตํ•ด ๋Œ€ํ™”ํ˜•์œผ๋กœ ๋ณ€๊ฒฝ๋œ ์‚ฌํ•ญ์€ ์ด์ œ `~/.claude/settings.json`์— ๊ธฐ๋ก๋˜๋ฉฐ ์ผ๋ฐ˜์ ์ธ ์šฐ์„  ์ˆœ์œ„ ์ฒด์ธ(์ •์ฑ… โ†’ ๋กœ์ปฌ โ†’ ํ”„๋กœ์ ํŠธ โ†’ ์‚ฌ์šฉ์ž)์— ์ฐธ์—ฌํ•ฉ๋‹ˆ๋‹ค. v2.1.119 ์ด์ „์—๋Š” ์ผ๋ถ€ `/config` ๋ณ€๊ฒฝ ์‚ฌํ•ญ์ด ์„ธ์…˜ ์ „์šฉ์ด์—ˆ์Šต๋‹ˆ๋‹ค. ์ „์ฒด ์šฐ์„  ์ˆœ์œ„ ์ˆœ์„œ๋Š” [๋ฉ”๋ชจ๋ฆฌ ๋ฐ ์„ค์ •](../02-memory/README.md)์„ ์ฐธ์กฐํ•˜์‹ญ์‹œ์˜ค. +| `--settings` | ํŒŒ์ผ ๋˜๋Š” JSON์—์„œ ์„ค์ •์„ ๋กœ๋“œํ•ฉ๋‹ˆ๋‹ค | `claude --settings ./settings.json` | +| `--plugin-dir` | ๋””๋ ‰ํ† ๋ฆฌ์—์„œ ํ”Œ๋Ÿฌ๊ทธ์ธ์„ ๋กœ๋“œํ•ฉ๋‹ˆ๋‹ค (๋ฐ˜๋ณต ๊ฐ€๋Šฅ) | `claude --plugin-dir ./my-plugin` | + +### ๋‹ค์ค‘ ๋””๋ ‰ํ† ๋ฆฌ ์˜ˆ์‹œ + +```bash +# ์—ฌ๋Ÿฌ ํ”„๋กœ์ ํŠธ ๋””๋ ‰ํ† ๋ฆฌ์—์„œ ์ž‘์—…ํ•ฉ๋‹ˆ๋‹ค +claude --add-dir ../frontend ../backend ../shared "find all API endpoints" + +# ์‚ฌ์šฉ์ž ์ •์˜ ์„ค์ • ๋กœ๋“œ +claude --settings '{"model":"opus","verbose":true}' "complex task" +``` + +## MCP ๊ตฌ์„ฑ + +| Flag | Description | Example | +|------|-------------|---------| +| `--mcp-config` | JSON์—์„œ MCP ์„œ๋ฒ„๋ฅผ ๋กœ๋“œํ•ฉ๋‹ˆ๋‹ค | `claude --mcp-config ./mcp.json` | +| `--strict-mcp-config` | ์ง€์ •๋œ MCP ๊ตฌ์„ฑ๋งŒ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค | `claude --strict-mcp-config --mcp-config ./mcp.json` | +| `--channels` | MCP ์ฑ„๋„ ํ”Œ๋Ÿฌ๊ทธ์ธ์„ ๊ตฌ๋…ํ•ฉ๋‹ˆ๋‹ค | `claude --channels discord,telegram` | + +### MCP ์˜ˆ์‹œ + +```bash +# GitHub MCP ์„œ๋ฒ„ ๋กœ๋“œ +claude --mcp-config ./github-mcp.json "list open PRs" + +# ์—„๊ฒฉ ๋ชจ๋“œ - ์ง€์ •๋œ ์„œ๋ฒ„๋งŒ ์‚ฌ์šฉ +claude --strict-mcp-config --mcp-config ./production-mcp.json "deploy to staging" +``` + +## ์„ธ์…˜ ๊ด€๋ฆฌ + +| Flag | Description | Example | +|------|-------------|---------| +| `--session-id` | ํŠน์ • ์„ธ์…˜ ID (UUID)๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค | `claude --session-id "550e8400-..."` | +| `--fork-session` | ์žฌ๊ฐœ ์‹œ ์ƒˆ ์„ธ์…˜์„ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค | `claude --resume abc123 --fork-session` | + +### ์„ธ์…˜ ์˜ˆ์‹œ + +```bash +# ๋งˆ์ง€๋ง‰ ๋Œ€ํ™”๋ฅผ ๊ณ„์†ํ•ฉ๋‹ˆ๋‹ค +claude -c + +# ์ด๋ฆ„์ด ์ง€์ •๋œ ์„ธ์…˜์„ ์žฌ๊ฐœํ•ฉ๋‹ˆ๋‹ค +claude -r "feature-auth" "continue implementing login" + +# ์‹คํ—˜์„ ์œ„ํ•ด ์„ธ์…˜์„ ํฌํฌํ•ฉ๋‹ˆ๋‹ค +claude --resume feature-auth --fork-session "try OAuth instead" + +# ๋‹ค๋ฅธ ๊ธฐ๋Šฅ ์„ธ์…˜ ๊ฐ„ ์ „ํ™˜ +claude -r "feature-payments" "continue with Stripe integration" +``` + +### ์„ธ์…˜ ํฌํฌ + +๊ธฐ์กด ์„ธ์…˜์—์„œ ๋ธŒ๋žœ์น˜๋ฅผ ์ƒ์„ฑํ•˜์—ฌ ์‹คํ—˜ํ•ฉ๋‹ˆ๋‹ค: + +```bash +# ๋‹ค๋ฅธ ์ ‘๊ทผ ๋ฐฉ์‹์„ ์‹œ๋„ํ•˜๊ธฐ ์œ„ํ•ด ์„ธ์…˜์„ ํฌํฌํ•ฉ๋‹ˆ๋‹ค +claude --resume abc123 --fork-session "try alternative implementation" + +# ์‚ฌ์šฉ์ž ์ •์˜ ๋ฉ”์‹œ์ง€๋กœ ํฌํฌํ•ฉ๋‹ˆ๋‹ค +claude -r "feature-auth" --fork-session "test with different architecture" +``` + +**์‚ฌ์šฉ ์‚ฌ๋ก€:** +- ์›๋ณธ ์„ธ์…˜์„ ์žƒ์ง€ ์•Š๊ณ  ๋‹ค๋ฅธ ๊ตฌํ˜„์„ ์‹œ๋„ํ•ฉ๋‹ˆ๋‹ค +- ๋‹ค๋ฅธ ์ ‘๊ทผ ๋ฐฉ์‹์„ ๋ณ‘๋ ฌ๋กœ ์‹คํ—˜ํ•ฉ๋‹ˆ๋‹ค +- ์„ฑ๊ณต์ ์ธ ์ž‘์—…์—์„œ ๋ธŒ๋žœ์น˜๋ฅผ ์ƒ์„ฑํ•˜์—ฌ ๋ณ€ํ˜•์„ ๋งŒ๋“ญ๋‹ˆ๋‹ค +- ์ฃผ์š” ์„ธ์…˜์— ์˜ํ–ฅ์„ ์ฃผ์ง€ ์•Š๊ณ  ๋ณ€๊ฒฝ ์‚ฌํ•ญ์„ ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค + +์›๋ณธ ์„ธ์…˜์€ ๋ณ€๊ฒฝ๋˜์ง€ ์•Š๊ณ , ํฌํฌ๋Š” ์ƒˆ๋กœ์šด ๋…๋ฆฝ์ ์ธ ์„ธ์…˜์ด ๋ฉ๋‹ˆ๋‹ค. + +### ํ”„๋กœ์ ํŠธ ์ƒํƒœ ์ •๋ฆฌ (v2.1.126+) + +`claude project purge`๋Š” ํ”„๋กœ์ ํŠธ์˜ ๋ชจ๋“  ๋กœ์ปฌ Claude Code ์ƒํƒœ๋ฅผ ์‚ญ์ œํ•ฉ๋‹ˆ๋‹ค โ€” ๋Œ€๋ณธ, ์ž‘์—… ๋ชฉ๋ก, ๋””๋ฒ„๊ทธ ๋กœ๊ทธ, ํŒŒ์ผ ํŽธ์ง‘ ๊ธฐ๋ก, ํ”„๋กฌํ”„ํŠธ ๊ธฐ๋ก ์ค„, ๊ทธ๋ฆฌ๊ณ  ํ”„๋กœ์ ํŠธ์˜ `~/.claude.json` ํ•ญ๋ชฉ. ์‚ญ์ œ๋ฅผ ๋ฏธ๋ฆฌ ๋ณด๋ ค๋ฉด ๋จผ์ € `--dry-run`์„ ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค. `--all`์€ ์‹œ์Šคํ…œ์˜ ๋ชจ๋“  ํ”„๋กœ์ ํŠธ๋ฅผ ํƒ์ƒ‰ํ•ฉ๋‹ˆ๋‹ค. + +```bash +# ์‚ญ์ œ๋  ๋‚ด์šฉ์„ ๋ฏธ๋ฆฌ ๋ด…๋‹ˆ๋‹ค (์•ˆ์ „) +claude project purge ~/work/repo --dry-run + +# ํŠน์ • ํ”„๋กœ์ ํŠธ์˜ ์ƒํƒœ๋ฅผ ํ”„๋กฌํ”„ํŠธ ์—†์ด ์‚ญ์ œํ•ฉ๋‹ˆ๋‹ค +claude project purge ~/work/repo --yes + +# ๋ชจ๋“  ํ”„๋กœ์ ํŠธ๋ฅผ ๋Œ€ํ™”ํ˜•์œผ๋กœ ํƒ์ƒ‰ํ•ฉ๋‹ˆ๋‹ค +claude project purge --all --interactive +``` + +## ๊ณ ๊ธ‰ ๊ธฐ๋Šฅ + +| Flag | Description | Example | +|------|-------------|---------| +| `--chrome` | Chrome ๋ธŒ๋ผ์šฐ์ € ํ†ตํ•ฉ์„ ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค | `claude --chrome` | +| `--no-chrome` | Chrome ๋ธŒ๋ผ์šฐ์ € ํ†ตํ•ฉ์„ ๋น„ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค | `claude --no-chrome` | +| `--ide` | ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ๊ฒฝ์šฐ IDE์— ์ž๋™ ์—ฐ๊ฒฐํ•ฉ๋‹ˆ๋‹ค | `claude --ide` | +| `--max-turns` | ์—์ด์ „ํŠธ ํ„ด์„ ์ œํ•œํ•ฉ๋‹ˆ๋‹ค (๋น„๋Œ€ํ™”ํ˜•) | `claude -p --max-turns 3 "query"` | +| `--debug` | ํ•„ํ„ฐ๋ง์œผ๋กœ ๋””๋ฒ„๊ทธ ๋ชจ๋“œ๋ฅผ ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค | `claude --debug "api,mcp"` | +| `--enable-lsp-logging` | ์ƒ์„ธ LSP ๋กœ๊น…์„ ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค | `claude --enable-lsp-logging` | +| `--betas` | API ์š”์ฒญ์„ ์œ„ํ•œ ๋ฒ ํƒ€ ํ—ค๋” | `claude --betas interleaved-thinking` | +| `--plugin-dir` | ๋””๋ ‰ํ† ๋ฆฌ์—์„œ ํ”Œ๋Ÿฌ๊ทธ์ธ์„ ๋กœ๋“œํ•ฉ๋‹ˆ๋‹ค (๋ฐ˜๋ณต ๊ฐ€๋Šฅ) | `claude --plugin-dir ./my-plugin` | +| `--enable-auto-mode` | ์ž๋™ ๊ถŒํ•œ ๋ชจ๋“œ๋ฅผ ์ž ๊ธˆ ํ•ด์ œํ•ฉ๋‹ˆ๋‹ค | `claude --enable-auto-mode` | +| `--effort` | ์‚ฌ๊ณ  ๋…ธ๋ ฅ ์ˆ˜์ค€์„ ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค | `claude --effort high` | +| `--bare` | ์ตœ์†Œ ๋ชจ๋“œ (ํ›…, ์Šคํ‚ฌ, ํ”Œ๋Ÿฌ๊ทธ์ธ, MCP, ์ž๋™ ๋ฉ”๋ชจ๋ฆฌ, CLAUDE.md ๊ฑด๋„ˆ๋›ฐ๊ธฐ) | `claude --bare` | +| `--channels` | MCP ์ฑ„๋„ ํ”Œ๋Ÿฌ๊ทธ์ธ์„ ๊ตฌ๋…ํ•ฉ๋‹ˆ๋‹ค | `claude --channels discord` | +| `--tmux` | ์›ŒํฌํŠธ๋ฆฌ๋ฅผ ์œ„ํ•œ tmux ์„ธ์…˜์„ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค | `claude --tmux` | +| `--fork-session` | ์žฌ๊ฐœ ์‹œ ์ƒˆ ์„ธ์…˜ ID๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค | `claude --resume abc --fork-session` | +| `--max-budget-usd` | ์ตœ๋Œ€ ์ง€์ถœ (์ธ์‡„ ๋ชจ๋“œ) | `claude -p --max-budget-usd 5.00 "query"` | +| `--json-schema` | ์œ ํšจ์„ฑ ๊ฒ€์‚ฌ๋œ JSON ์ถœ๋ ฅ | `claude -p --json-schema '{"type":"object"}' "q"` | + +### ํ”Œ๋žซํผ ๋ฐ ํ…Œ๋งˆ ์ฐธ๊ณ  ์‚ฌํ•ญ (v2.1.112) + +- **Windows์˜ PowerShell ๋„๊ตฌ**: Windows์— ์ „์šฉ PowerShell ๋„๊ตฌ๊ฐ€ ์ถœ์‹œ๋˜๊ณ  ์žˆ์œผ๋ฉฐ ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋ฅผ ํ†ตํ•ด ์ œ์–ดํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. +- **์ž๋™ (ํ„ฐ๋ฏธ๋„ ์ผ์น˜) ํ…Œ๋งˆ**: ์ƒˆ๋กœ์šด "์ž๋™ (ํ„ฐ๋ฏธ๋„ ์ผ์น˜)" ํ…Œ๋งˆ๋Š” Claude Code์˜ ๋ฐ๊ธฐ/์–ด๋‘ก๊ธฐ ์™ธ๊ด€์„ ํ„ฐ๋ฏธ๋„๊ณผ ๋™๊ธฐํ™”ํ•ฉ๋‹ˆ๋‹ค. +- **๋” ์กฐ์šฉํ•œ ๊ถŒํ•œ ํ”„๋กฌํ”„ํŠธ**: ์ฝ๊ธฐ ์ „์šฉ `Bash` ํ˜ธ์ถœ ๋ฐ `Glob` ํŒจํ„ด์€ ๋” ์ด์ƒ ๊ถŒํ•œ ํ”„๋กฌํ”„ํŠธ๋ฅผ ํŠธ๋ฆฌ๊ฑฐํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. + +### ๊ณ ๊ธ‰ ์˜ˆ์‹œ + +```bash +# ์ž์œจ ํ–‰๋™์„ ์ œํ•œํ•ฉ๋‹ˆ๋‹ค +claude -p --max-turns 5 "refactor this module" + +# API ํ˜ธ์ถœ ๋””๋ฒ„๊ทธ +claude --debug "api" "test query" + +# IDE ํ†ตํ•ฉ ํ™œ์„ฑํ™” +claude --ide "help me with this file" +``` + +## ์—์ด์ „ํŠธ ๊ตฌ์„ฑ + +`--agents` ํ”Œ๋ž˜๊ทธ๋Š” ์„ธ์…˜์„ ์œ„ํ•œ ์‚ฌ์šฉ์ž ์ •์˜ ์„œ๋ธŒ์—์ด์ „ํŠธ๋ฅผ ์ •์˜ํ•˜๋Š” JSON ๊ฐ์ฒด๋ฅผ ๋ฐ›์Šต๋‹ˆ๋‹ค. + +### ์—์ด์ „ํŠธ JSON ํ˜•์‹ + +```json +{ + "agent-name": { + "description": "Required: when to invoke this agent", + "prompt": "Required: system prompt for the agent", + "tools": ["Optional", "array", "of", "tools"], + "model": "optional: sonnet|opus|haiku" + } +} +``` + +**ํ•„์ˆ˜ ํ•„๋“œ:** +- `description` - ์ด ์—์ด์ „ํŠธ๋ฅผ ์–ธ์ œ ํ˜ธ์ถœํ• ์ง€ ์„ค๋ช…ํ•˜๋Š” ์ž์—ฐ์–ด ์„ค๋ช… +- `prompt` - ์—์ด์ „ํŠธ์˜ ์—ญํ• ๊ณผ ๋™์ž‘์„ ์ •์˜ํ•˜๋Š” ์‹œ์Šคํ…œ ํ”„๋กฌํ”„ํŠธ + +**์„ ํƒ ํ•„๋“œ:** +- `tools` - ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ๋„๊ตฌ ๋ฐฐ์—ด (์ƒ๋žต ์‹œ ๋ชจ๋“  ๋„๊ตฌ ์ƒ์†) + - ํ˜•์‹: `["Read", "Grep", "Glob", "Bash"]` +- `model` - ์‚ฌ์šฉํ•  ๋ชจ๋ธ: `sonnet`, `opus`, ๋˜๋Š” `haiku` + +### ์™„์ „ํ•œ ์—์ด์ „ํŠธ ์˜ˆ์‹œ + +```json +{ + "code-reviewer": { + "description": "Expert code reviewer. Use proactively after code changes.", + "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.", + "tools": ["Read", "Grep", "Glob", "Bash"], + "model": "sonnet" + }, + "debugger": { + "description": "Debugging specialist for errors and test failures.", + "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes.", + "tools": ["Read", "Edit", "Bash", "Grep"], + "model": "opus" + }, + "documenter": { + "description": "Documentation specialist for generating guides.", + "prompt": "You are a technical writer. Create clear, comprehensive documentation.", + "tools": ["Read", "Write"], + "model": "haiku" + } +} +``` + +### ์—์ด์ „ํŠธ ๋ช…๋ น ์˜ˆ์‹œ + +```bash +# ์ธ๋ผ์ธ์œผ๋กœ ์‚ฌ์šฉ์ž ์ •์˜ ์—์ด์ „ํŠธ ์ •์˜ +claude --agents '{ + "security-auditor": { + "description": "Security specialist for vulnerability analysis", + "prompt": "You are a security expert. Find vulnerabilities and suggest fixes.", + "tools": ["Read", "Grep", "Glob"], + "model": "opus" + } +}' "audit this codebase for security issues" + +# ํŒŒ์ผ์—์„œ ์—์ด์ „ํŠธ ๋กœ๋“œ +claude --agents "$(cat ~/.claude/agents.json)" "review the auth module" + +# ๋‹ค๋ฅธ ํ”Œ๋ž˜๊ทธ์™€ ๊ฒฐํ•ฉ +claude -p --agents "$(cat agents.json)" --model sonnet "analyze performance" +``` + +### ์—์ด์ „ํŠธ ์šฐ์„ ์ˆœ์œ„ + +์—ฌ๋Ÿฌ ์—์ด์ „ํŠธ ์ •์˜๊ฐ€ ์กด์žฌํ•˜๋Š” ๊ฒฝ์šฐ ๋‹ค์Œ ์šฐ์„ ์ˆœ์œ„ ์ˆœ์„œ๋กœ ๋กœ๋“œ๋ฉ๋‹ˆ๋‹ค: +1. **CLI ์ •์˜** (`--agents` ํ”Œ๋ž˜๊ทธ) - ์„ธ์…˜๋ณ„ +2. **ํ”„๋กœ์ ํŠธ ์ˆ˜์ค€** (`.claude/agents/`) - ํ˜„์žฌ ํ”„๋กœ์ ํŠธ +3. **์‚ฌ์šฉ์ž ์ˆ˜์ค€** (`~/.claude/agents/`) - ๋ชจ๋“  ํ”„๋กœ์ ํŠธ + +CLI ์ •์˜ ์—์ด์ „ํŠธ๋Š” ์„ธ์…˜์— ๋Œ€ํ•ด ํ”„๋กœ์ ํŠธ ๋ฐ ์‚ฌ์šฉ์ž ์—์ด์ „ํŠธ ๋ชจ๋‘๋ฅผ ์žฌ์ •์˜ํ•ฉ๋‹ˆ๋‹ค. ํ”„๋กœ์ ํŠธ ์ˆ˜์ค€ ์—์ด์ „ํŠธ๋Š” ์ด๋ฆ„์ด ์ถฉ๋Œํ•  ๋•Œ ์‚ฌ์šฉ์ž ์ˆ˜์ค€ ์—์ด์ „ํŠธ๋ฅผ ์žฌ์ •์˜ํ•ฉ๋‹ˆ๋‹ค. ํ”Œ๋Ÿฌ๊ทธ์ธ ์ˆ˜์ค€ ์—์ด์ „ํŠธ๋ฅผ ํฌํ•จํ•œ ์ „์ฒด ์šฐ์„ ์ˆœ์œ„ ํ‘œ๋Š” [๋ ˆ์Šจ 04 โ€” ์„œ๋ธŒ์—์ด์ „ํŠธ](../04-subagents/README.md#file-locations)๋ฅผ ์ฐธ์กฐํ•˜์‹ญ์‹œ์˜ค. + +### ์—์ด์ „ํŠธ ๋ทฐ (`claude agents`, v2.1.139+) + +> **์—ฐ๊ตฌ ๋ฏธ๋ฆฌ๋ณด๊ธฐ** โ€” ๊ธฐ๋Šฅ์€ ์ผ์ƒ์ ์ธ ์‚ฌ์šฉ์— ์ถฉ๋ถ„ํžˆ ์•ˆ์ •์ ์ด์ง€๋งŒ ๋ณ€๊ฒฝ๋  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +`claude agents`๋Š” **์—์ด์ „ํŠธ ๋ทฐ**๋ฅผ ์—ฝ๋‹ˆ๋‹ค. ์ด ๋ทฐ๋Š” ํ˜„์žฌ ์ƒํƒœ(`running`, `blocked on you`, `done`)์™€ ํ•จ๊ป˜ ์‹œ์Šคํ…œ์˜ ๋ชจ๋“  Claude Code ์„ธ์…˜ ๋ชฉ๋ก์„ ํ•œ๋ˆˆ์— ๋ณผ ์ˆ˜ ์žˆ๋„๋ก ํ•ฉ๋‹ˆ๋‹ค. ์ด๋Š” ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์—์ด์ „ํŠธ, ์˜ˆ์•ฝ๋œ ์ž‘์—… ๋˜๋Š” `--bg`๋กœ ์‹œ์ž‘๋œ ์„ธ์…˜์„ ์‹คํ–‰ํ•  ๋•Œ ์—ฌ๋Ÿฌ ํ„ฐ๋ฏธ๋„ ํƒญ์„ ๊ด€๋ฆฌํ•˜๋Š” ๋ฒˆ๊ฑฐ๋กœ์›€์„ ๋Œ€์ฒดํ•ฉ๋‹ˆ๋‹ค. + +```bash +# ์—์ด์ „ํŠธ ๋ทฐ๋ฅผ ์—ฝ๋‹ˆ๋‹ค +claude agents +``` + +๋ทฐ์—์„œ ์„ธ์…˜์„ ๋””์ŠคํŒจ์น˜ํ•  ๋•Œ (๋˜๋Š” `claude --bg `๋ฅผ ํ†ตํ•ด) `claude` ์ž์ฒด์— ์ „๋‹ฌํ•˜๋Š” ๊ฒƒ๊ณผ ๋™์ผํ•œ ๊ตฌ์„ฑ ํ”Œ๋ž˜๊ทธ๋ฅผ ์ „๋‹ฌํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์—์ด์ „ํŠธ ๋ทฐ ๋””์ŠคํŒจ์Šค ๊ฒฝ๋กœ๋ฅผ ์œ„ํ•ด ๋„์ž…๋œ ํ”Œ๋ž˜๊ทธ: + +| Flag | Since | Description | +|------|-------|-------------| +| `--cwd ` | v2.1.141 | ์„ธ์…˜ ๋ชฉ๋ก (๋˜๋Š” ์ƒˆ ์„ธ์…˜)์˜ ๋ฒ”์œ„๋ฅผ ํŠน์ • ์ž‘์—… ๋””๋ ‰ํ† ๋ฆฌ๋กœ ์ง€์ •ํ•ฉ๋‹ˆ๋‹ค | +| `--add-dir ` | v2.1.142 | ๋””์ŠคํŒจ์น˜๋œ ์„ธ์…˜์˜ ์ž‘์—… ๊ณต๊ฐ„์— ๋””๋ ‰ํ† ๋ฆฌ๋ฅผ ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค | +| `--settings ` | v2.1.142 | ๋””์ŠคํŒจ์น˜๋œ ์„ธ์…˜์— ํŠน์ • `settings.json`์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค | +| `--mcp-config ` | v2.1.142 | ๋””์ŠคํŒจ์น˜๋œ ์„ธ์…˜์— ํŠน์ • MCP ๊ตฌ์„ฑ์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค | +| `--plugin-dir ` | v2.1.142 | ๋””์ŠคํŒจ์น˜๋œ ์„ธ์…˜์— ํŠน์ • ํ”Œ๋Ÿฌ๊ทธ์ธ ๋””๋ ‰ํ† ๋ฆฌ๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค | +| `--permission-mode ` | v2.1.142 | ๋””์ŠคํŒจ์น˜๋œ ์„ธ์…˜์— ๊ถŒํ•œ ๋ชจ๋“œ (`plan`, `acceptEdits`, `auto` ๋“ฑ)๋ฅผ ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค | +| `--model ` | v2.1.142 | ๋””์ŠคํŒจ์น˜๋œ ์„ธ์…˜์— ๋ชจ๋ธ์„ ๊ณ ์ •ํ•ฉ๋‹ˆ๋‹ค | +| `--effort ` | v2.1.142 | ๋…ธ๋ ฅ ์ˆ˜์ค€ (`low`/`medium`/`high`/`xhigh`/`max`)์„ ๊ณ ์ •ํ•ฉ๋‹ˆ๋‹ค | +| `--dangerously-skip-permissions` | v2.1.142 | ๊ถŒํ•œ ํ”„๋กฌํ”„ํŠธ ์—†์ด ๋””์ŠคํŒจ์น˜๋œ ์„ธ์…˜์„ ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค (์ƒŒ๋“œ๋ฐ•์Šค์—์„œ๋งŒ ์‚ฌ์šฉ) | +| `--json` | v2.1.145 | ์Šคํฌ๋ฆฝํŠธ ์ž‘์„ฑ (์ƒํƒœ ํ‘œ์‹œ์ค„, ์„ธ์…˜ ์„ ํƒ๊ธฐ, tmux-resurrect ํ†ตํ•ฉ)์„ ์œ„ํ•ด ์—์ด์ „ํŠธ ๋ชฉ๋ก์„ ๊ธฐ๊ณ„๊ฐ€ ์ฝ์„ ์ˆ˜ ์žˆ๋Š” JSON์œผ๋กœ ์ถœ๋ ฅํ•ฉ๋‹ˆ๋‹ค | + +์ž‘์—…์„ ์™„๋ฃŒํ–ˆ์ง€๋งŒ ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์‰˜์„ ์—ด์–ด๋‘” ์„ธ์…˜์€ "Working"์—์„œ "Completed"๋กœ ์ด๋™ํ•ฉ๋‹ˆ๋‹ค (v2.1.141 ์ˆ˜์ •). ์—ฐ๊ฒฐ๋œ ์—์ด์ „ํŠธ ์„ธ์…˜ ๋‚ด์—์„œ `Shift+Tab`์€ ์ž๋™ ๋ชจ๋“œ๋ฅผ ํฌํ•จํ•œ ๊ถŒํ•œ ๋ชจ๋“œ๋ฅผ ์ˆœํ™˜ํ•ฉ๋‹ˆ๋‹ค (v2.1.143). + +**์„ธ์…˜ ๊ณ ์ •** โ€” `claude agents`์˜ ์„ธ์…˜์—์„œ `Ctrl+T`๋ฅผ ๋ˆŒ๋Ÿฌ ์„ธ์…˜์„ ๊ณ ์ •ํ•ฉ๋‹ˆ๋‹ค (v2.1.147). ๊ณ ์ •๋œ ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์„ธ์…˜์€ ์œ ํœด ์ƒํƒœ์ผ ๋•Œ๋„ ํ™œ์„ฑ ์ƒํƒœ๋ฅผ ์œ ์ง€ํ•˜๊ณ , Claude Code ์—…๋ฐ์ดํŠธ๋ฅผ ์ ์šฉํ•˜๊ธฐ ์œ„ํ•ด ์ œ์ž๋ฆฌ์—์„œ ๋‹ค์‹œ ์‹œ์ž‘๋˜๋ฉฐ, ๊ณ ์ •๋˜์ง€ ์•Š์€ ์„ธ์…˜ ์ดํ›„์—๋งŒ ๋ฉ”๋ชจ๋ฆฌ ๋ถ€์กฑ ์‹œ ํ•ด์ œ๋ฉ๋‹ˆ๋‹ค. (์ด `Ctrl+T`๋Š” ์—์ด์ „ํŠธ ๋ทฐ์— ๋ฒ”์œ„๊ฐ€ ์ง€์ •๋ฉ๋‹ˆ๋‹ค; ์ฃผ ์„ธ์…˜์—์„œ๋Š” ์ž‘์—… ๋ชฉ๋ก ๋ทฐ๋ฅผ ์ „ํ™˜ํ•ฉ๋‹ˆ๋‹ค.) + +--- + +## ๊ณ ๊ฐ€์น˜ ์‚ฌ์šฉ ์‚ฌ๋ก€ + +### 1. CI/CD ํ†ตํ•ฉ + +CI/CD ํŒŒ์ดํ”„๋ผ์ธ์—์„œ Claude Code๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ์ž๋™ํ™”๋œ ์ฝ”๋“œ ๊ฒ€ํ† , ํ…Œ์ŠคํŠธ ๋ฐ ๋ฌธ์„œํ™”๋ฅผ ์ˆ˜ํ–‰ํ•ฉ๋‹ˆ๋‹ค. + +**GitHub Actions ์˜ˆ์‹œ:** + +```yaml +name: AI Code Review + +on: [pull_request] + +jobs: + review: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Install Claude Code + run: npm install -g @anthropic-ai/claude-code + + - name: Run Code Review + env: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + run: | + claude -p --output-format json \ + --max-turns 1 \ + "Review the changes in this PR for: + - Security vulnerabilities + - Performance issues + - Code quality + Output as JSON with 'issues' array" > review.json + + - name: Post Review Comment + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const review = JSON.parse(fs.readFileSync('review.json', 'utf8')); + // Process and post review comments +``` + +**Jenkins ํŒŒ์ดํ”„๋ผ์ธ:** + +```groovy +pipeline { + agent any + stages { + stage('AI Review') { + steps { + sh ''' + claude -p --output-format json \ + --max-turns 3 \ + "Analyze test coverage and suggest missing tests" \ + > coverage-analysis.json + ''' + } + } + } +} +``` + +**ํ—ค๋“œ๋ฆฌ์Šค `ultrareview` (v2.1.120+):** + +```yaml +# .github/workflows/ultrareview.yml +- name: Claude ultrareview + run: claude ultrareview ${{ github.event.pull_request.number }} --json > review.json +``` + +`claude ultrareview`๋Š” ๊นจ๋—ํ•œ ๊ฒ€ํ†  ์‹œ 0์„ ๋ฐ˜ํ™˜ํ•˜๊ณ , ๋ฐœ๊ฒฌ ์‚ฌํ•ญ์ด ๋ณด๊ณ ๋  ๋•Œ 1์„ ๋ฐ˜ํ™˜ํ•˜๋ฏ€๋กœ ์ฆ‰์‹œ PR ๊ฒŒ์ดํŠธ๋กœ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. 30๋ถ„ ๊ธฐ๋ณธ๊ฐ’์„ ์žฌ์ •์˜ํ•˜๋ ค๋ฉด `--timeout `๋ฅผ ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค. + +### 2. ์Šคํฌ๋ฆฝํŠธ ํŒŒ์ดํ”„๋ผ์ธ + +๋ถ„์„์„ ์œ„ํ•ด ํŒŒ์ผ, ๋กœ๊ทธ ๋ฐ ๋ฐ์ดํ„ฐ๋ฅผ Claude๋ฅผ ํ†ตํ•ด ์ฒ˜๋ฆฌํ•ฉ๋‹ˆ๋‹ค. + +**๋กœ๊ทธ ๋ถ„์„:** + +```bash +# ์˜ค๋ฅ˜ ๋กœ๊ทธ ๋ถ„์„ +tail -1000 /var/log/app/error.log | claude -p "summarize these errors and suggest fixes" + +# ์•ก์„ธ์Šค ๋กœ๊ทธ์—์„œ ํŒจํ„ด ์ฐพ๊ธฐ +cat access.log | claude -p "identify suspicious access patterns" + +# Git ๊ธฐ๋ก ๋ถ„์„ +git log --oneline -50 | claude -p "summarize recent development activity" +``` + +**์ฝ”๋“œ ์ฒ˜๋ฆฌ:** + +```bash +# ํŠน์ • ํŒŒ์ผ ๊ฒ€ํ†  +cat src/auth.ts | claude -p "review this authentication code for security issues" + +# ๋ฌธ์„œ ์ƒ์„ฑ +cat src/api/*.ts | claude -p "generate API documentation in markdown" + +# TODO ์ฐพ๊ธฐ ๋ฐ ์šฐ์„ ์ˆœ์œ„ ์ง€์ • +grep -r "TODO" src/ | claude -p "prioritize these TODOs by importance" +``` + +### 3. ๋‹ค์ค‘ ์„ธ์…˜ ์›Œํฌํ”Œ๋กœ + +์—ฌ๋Ÿฌ ๋Œ€ํ™” ์Šค๋ ˆ๋“œ๋กœ ๋ณต์žกํ•œ ํ”„๋กœ์ ํŠธ๋ฅผ ๊ด€๋ฆฌํ•ฉ๋‹ˆ๋‹ค. + +```bash +# ๊ธฐ๋Šฅ ๋ธŒ๋žœ์น˜ ์„ธ์…˜ ์‹œ์ž‘ +claude -r "feature-auth" "let's implement user authentication" + +# ๋‚˜์ค‘์— ์„ธ์…˜ ๊ณ„์† +claude -r "feature-auth" "add password reset functionality" + +# ๋‹ค๋ฅธ ์ ‘๊ทผ ๋ฐฉ์‹์„ ์‹œ๋„ํ•˜๊ธฐ ์œ„ํ•ด ํฌํฌ +claude --resume feature-auth --fork-session "try OAuth instead" + +# ๋‹ค๋ฅธ ๊ธฐ๋Šฅ ์„ธ์…˜ ๊ฐ„ ์ „ํ™˜ +claude -r "feature-payments" "continue with Stripe integration" +``` + +### 4. ์‚ฌ์šฉ์ž ์ •์˜ ์—์ด์ „ํŠธ ๊ตฌ์„ฑ + +ํŒ€์˜ ์›Œํฌํ”Œ๋กœ์— ๋งž๋Š” ์ „๋ฌธ ์—์ด์ „ํŠธ๋ฅผ ์ •์˜ํ•ฉ๋‹ˆ๋‹ค. + +```bash +# ์—์ด์ „ํŠธ ๊ตฌ์„ฑ์„ ํŒŒ์ผ์— ์ €์žฅ +cat > ~/.claude/agents.json << 'EOF' +{ + "reviewer": { + "description": "Code reviewer for PR reviews", + "prompt": "Review code for quality, security, and maintainability.", + "model": "opus" + }, + "documenter": { + "description": "Documentation specialist", + "prompt": "Generate clear, comprehensive documentation.", + "model": "sonnet" + }, + "refactorer": { + "description": "Code refactoring expert", + "prompt": "Suggest and implement clean code refactoring.", + "tools": ["Read", "Edit", "Glob"] + } +} +EOF + +# ์„ธ์…˜์—์„œ ์—์ด์ „ํŠธ ์‚ฌ์šฉ +claude --agents "$(cat ~/.claude/agents.json)" "review the auth module" +``` + +### 5. ๋ฐฐ์น˜ ์ฒ˜๋ฆฌ + +์ผ๊ด€๋œ ์„ค์ •์œผ๋กœ ์—ฌ๋Ÿฌ ์ฟผ๋ฆฌ๋ฅผ ์ฒ˜๋ฆฌํ•ฉ๋‹ˆ๋‹ค. + +```bash +# ์—ฌ๋Ÿฌ ํŒŒ์ผ ์ฒ˜๋ฆฌ +for file in src/*.ts; do + echo "Processing $file..." + claude -p --model haiku "summarize this file: $(cat $file)" >> summaries.md +done + +# ๋ฐฐ์น˜ ์ฝ”๋“œ ๊ฒ€ํ†  +find src -name "*.py" -exec sh -c ' + echo "## $1" >> review.md + cat "$1" | claude -p "brief code review" >> review.md +' _ {} \; + +# ๋ชจ๋“  ๋ชจ๋“ˆ์— ๋Œ€ํ•œ ํ…Œ์ŠคํŠธ ์ƒ์„ฑ +for module in $(ls src/modules/); do + claude -p "generate unit tests for src/modules/$module" > "tests/$module.test.ts" +done +``` + +### 6. ๋ณด์•ˆ ์ธ์‹ ๊ฐœ๋ฐœ + +์•ˆ์ „ํ•œ ์ž‘์—…์„ ์œ„ํ•ด ๊ถŒํ•œ ์ œ์–ด๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + +```bash +# ์ฝ๊ธฐ ์ „์šฉ ๋ณด์•ˆ ๊ฐ์‚ฌ +claude --permission-mode plan \ + --tools "Read,Grep,Glob" \ + "audit this codebase for security vulnerabilities" + +# ์œ„ํ—˜ํ•œ ๋ช…๋ น ์ฐจ๋‹จ +claude --disallowedTools "Bash(rm:*)" "Bash(curl:*)" "Bash(wget:*)" \ + "help me clean up this project" + +# ์ œํ•œ๋œ ์ž๋™ํ™” +claude -p --max-turns 2 \ + --allowedTools "Read" "Glob" \ + "find all hardcoded credentials" +``` + +### 7. JSON API ํ†ตํ•ฉ + +`jq` ํŒŒ์‹ฑ์„ ์‚ฌ์šฉํ•˜์—ฌ Claude๋ฅผ ๋„๊ตฌ์šฉ ํ”„๋กœ๊ทธ๋ž˜๋ฐ ๊ฐ€๋Šฅ API๋กœ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + +```bash +# ๊ตฌ์กฐํ™”๋œ ๋ถ„์„ ๊ฐ€์ ธ์˜ค๊ธฐ +claude -p --output-format json \ + --json-schema '{"type":"object","properties":{"functions":{"type":"array"},"complexity":{"type":"string"}}}' \ + "analyze main.py and return function list with complexity rating" + +# ์ฒ˜๋ฆฌ๋ฅผ ์œ„ํ•ด jq์™€ ํ†ตํ•ฉ +claude -p --output-format json "list all API endpoints" | jq '.endpoints[]' + +# ์Šคํฌ๋ฆฝํŠธ์—์„œ ์‚ฌ์šฉ +RESULT=$(claude -p --output-format json "is this code secure? answer with {secure: boolean, issues: []}" < code.py) +if echo "$RESULT" | jq -e '.secure == false' > /dev/null; then + echo "Security issues found!" + echo "$RESULT" | jq '.issues[]' +fi +``` + +### jq ํŒŒ์‹ฑ ์˜ˆ์‹œ + +`jq`๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ Claude์˜ JSON ์ถœ๋ ฅ์„ ํŒŒ์‹ฑํ•˜๊ณ  ์ฒ˜๋ฆฌํ•ฉ๋‹ˆ๋‹ค: + +```bash +# ํŠน์ • ํ•„๋“œ ์ถ”์ถœ +claude -p --output-format json "analyze this code" | jq '.result' + +# ๋ฐฐ์—ด ์š”์†Œ ํ•„ํ„ฐ๋ง +claude -p --output-format json "list issues" | jq -r '.issues[] | select(.severity=="high")' + +# ์—ฌ๋Ÿฌ ํ•„๋“œ ์ถ”์ถœ +claude -p --output-format json "describe the project" | jq -r '.{name, version, description}' + +# CSV๋กœ ๋ณ€ํ™˜ +claude -p --output-format json "list functions" | jq -r '.functions[] | [.name, .lineCount] | @csv' + +# ์กฐ๊ฑด๋ถ€ ์ฒ˜๋ฆฌ +claude -p --output-format json "check security" | jq 'if .vulnerabilities | length > 0 then "UNSAFE" else "SAFE" end' + +# ์ค‘์ฒฉ ๊ฐ’ ์ถ”์ถœ +claude -p --output-format json "analyze performance" | jq '.metrics.cpu.usage' + +# ์ „์ฒด ๋ฐฐ์—ด ์ฒ˜๋ฆฌ +claude -p --output-format json "find todos" | jq '.todos | length' + +# ์ถœ๋ ฅ ๋ณ€ํ™˜ +claude -p --output-format json "list improvements" | jq 'map({title: .title, priority: .priority})' +``` + +--- + +## ๋ชจ๋ธ + +Claude Code๋Š” ๋‹ค์–‘ํ•œ ๊ธฐ๋Šฅ์„ ๊ฐ€์ง„ ์—ฌ๋Ÿฌ ๋ชจ๋ธ์„ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค: + +| Model | ID | Context Window | Notes | +|-------|-----|----------------|-------| +| Opus 4.8 | `claude-opus-4-8` | 1M ํ† ํฐ | ๊ฐ€์žฅ ์œ ๋Šฅํ•จ; ์ ์‘ํ˜• ๋…ธ๋ ฅ ์ˆ˜์ค€ `low โ†’ max`; ๊ธฐ๋ณธ ๋…ธ๋ ฅ `high` (v2.1.154) | +| Sonnet 4.6 | `claude-sonnet-4-6` | 1M ํ† ํฐ | ๊ท ํ˜• ์žกํžŒ ์†๋„์™€ ๊ธฐ๋Šฅ; Pro/Max ๊ตฌ๋…์ž์˜ ๊ธฐ๋ณธ ๋…ธ๋ ฅ์€ v2.1.117์—์„œ `medium`์—์„œ `high`๋กœ ์ƒํ–ฅ ์กฐ์ •๋จ | +| Haiku 4.5 | `claude-haiku-4-5` | 200K ํ† ํฐ | ๊ฐ€์žฅ ๋น ๋ฅด๊ณ , ๋น ๋ฅธ ์ž‘์—…์— ์ตœ์ ; ๋…ธ๋ ฅ ์ˆ˜์ค€ ์—†์Œ | +| Fable 5 | `claude-fable-5` | โ€” | Mythos ๋“ฑ๊ธ‰ ๋ชจ๋ธ, ์ผ๋ฐ˜์ ์ธ ์‚ฌ์šฉ์— ์•ˆ์ „ํ•˜๊ฒŒ ๋งŒ๋“ค์–ด์ง (v2.1.170) | + +### ๋ชจ๋ธ ์„ ํƒ + +```bash +# ์งง์€ ์ด๋ฆ„ ์‚ฌ์šฉ +claude --model opus "complex architectural review" +claude --model sonnet "implement this feature" +claude --model haiku -p "format this JSON" + +# opusplan ๋ณ„์นญ ์‚ฌ์šฉ (Opus๊ฐ€ ๊ณ„ํšํ•˜๊ณ  Sonnet์ด ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค) +claude --model opusplan "design and implement the API" + +# ์„ธ์…˜ ์ค‘ ๋น ๋ฅธ ๋ชจ๋“œ ์ „ํ™˜ +/fast +``` + +> **๋น ๋ฅธ ๋ชจ๋“œ๋Š” ์ด์ œ Opus 4.8์—์„œ ์‹คํ–‰๋ฉ๋‹ˆ๋‹ค (v2.1.154)**: v2.1.154๋ถ€ํ„ฐ `/fast`๋Š” ์—ฐ๊ตฌ ๋ฏธ๋ฆฌ๋ณด๊ธฐ๋กœ ๊ธฐ๋ณธ์ ์œผ๋กœ **Opus 4.8**์—์„œ ์‹คํ–‰๋ฉ๋‹ˆ๋‹ค. ์ด๋Š” ํ‘œ์ค€ ์†๋„์˜ ์•ฝ 2๋ฐฐ์ด๋ฉฐ ์ถœ๋ ฅ ์†๋„๋Š” ์•ฝ 2.5๋ฐฐ์ž…๋‹ˆ๋‹ค. ์ด์ „์—๋Š” v2.1.142์—์„œ Opus 4.6์—์„œ Opus 4.7๋กœ ์ „ํ™˜๋˜์—ˆ์Šต๋‹ˆ๋‹ค. `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋Š” **v2.1.154์—์„œ ๋” ์ด์ƒ ์‚ฌ์šฉ๋˜์ง€ ์•Š์œผ๋ฉฐ 2026-06-01์— ์ œ๊ฑฐ๋˜์—ˆ์Šต๋‹ˆ๋‹ค**. ํ˜„์žฌ Opus 4.6์—์„œ ๋น ๋ฅธ ๋ชจ๋“œ๋ฅผ ์‚ฌ์šฉํ•˜๋ ค๋ฉด `/model claude-opus-4-6[1m]`์„ ์‹คํ–‰ํ•œ ๋‹ค์Œ `/fast on`์„ ์‹คํ–‰ํ•˜์‹ญ์‹œ์˜ค. + +### ๋…ธ๋ ฅ ์ˆ˜์ค€ (Opus 4.8 / Opus 4.7) + +Opus 4.8 ๋ฐ Opus 4.7์€ ๊ฐ€์žฅ ๊ฐ€๋ฒผ์šด ๊ฒƒ๋ถ€ํ„ฐ ๊ฐ€์žฅ ๋ฌด๊ฑฐ์šด ๊ฒƒ๊นŒ์ง€ `low` (โ—‹), `medium` (โ—), `high` (โ—), `xhigh`, `max` ์ˆœ์„œ๋กœ ๋…ธ๋ ฅ ์ˆ˜์ค€์„ ๊ฐ€์ง„ ์ ์‘ํ˜• ์ถ”๋ก ์„ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค. **๊ธฐ๋ณธ๊ฐ’**์€ Opus 4.8 (v2.1.154๋ถ€ํ„ฐ), Opus 4.6, Sonnet 4.6์—์„œ๋Š” `high`์ด๊ณ , Opus 4.7์—์„œ๋Š” `xhigh`์ž…๋‹ˆ๋‹ค. `xhigh`๋Š” Opus 4.8 ๋ฐ Opus 4.7์—์„œ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. `max`๋Š” Opus 4.8/4.7/4.6 ๋ฐ Sonnet 4.6 (์„ธ์…˜ ์ „์šฉ)์—์„œ ์ž‘๋™ํ•ฉ๋‹ˆ๋‹ค. Haiku 4.5์—๋Š” ๋…ธ๋ ฅ ์ˆ˜์ค€์ด ์—†์Šต๋‹ˆ๋‹ค. Opus 4.6 / Sonnet 4.6์˜ ๊ฒฝ์šฐ Pro/Max ๊ตฌ๋…์ž์˜ ๊ธฐ๋ณธ ๋…ธ๋ ฅ์€ v2.1.117์—์„œ `medium`์—์„œ `high`๋กœ ์ƒํ–ฅ ์กฐ์ •๋˜์—ˆ์Šต๋‹ˆ๋‹ค. + +```bash +# CLI ํ”Œ๋ž˜๊ทธ๋ฅผ ํ†ตํ•ด ๋…ธ๋ ฅ ์ˆ˜์ค€ ์„ค์ • +claude --effort high "complex review" + +# ์Šฌ๋ž˜์‹œ ๋ช…๋ น์„ ํ†ตํ•ด ๋…ธ๋ ฅ ์ˆ˜์ค€ ์„ค์ • +/effort high + +# ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋ฅผ ํ†ตํ•ด ๋…ธ๋ ฅ ์ˆ˜์ค€ ์„ค์ • +export CLAUDE_CODE_EFFORT_LEVEL=high # low, medium, high, xhigh (Opus 4.8/4.7), ๋˜๋Š” max โ€” ๊ธฐ๋ณธ๊ฐ’์€ Opus 4.8์—์„œ high +``` + +ํ”„๋กฌํ”„ํŠธ์˜ "ultrathink" ํ‚ค์›Œ๋“œ๋Š” ๊นŠ์€ ์ถ”๋ก ์„ ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค. `/effort` ๋ฉ”๋‰ด๋Š” ๋˜ํ•œ **๋ชจ๋ธ ๋…ธ๋ ฅ ์ˆ˜์ค€์ด ์•„๋‹Œ** `ultracode`๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. ์ด๋Š” `xhigh`๋ฅผ ๋ณด๋‚ด๊ณ  Claude๊ฐ€ ๋™์  ์›Œํฌํ”Œ๋กœ๋ฅผ ์˜ค์ผ€์ŠคํŠธ๋ ˆ์ด์…˜ํ•˜๋„๋ก ํ•ฉ๋‹ˆ๋‹ค (์„ธ์…˜ ์ „์šฉ). + +--- + +## ์ฃผ์š” ํ™˜๊ฒฝ ๋ณ€์ˆ˜ + +| Variable | Description | +|----------|-------------| +| `ANTHROPIC_API_KEY` | ์ธ์ฆ์„ ์œ„ํ•œ API ํ‚ค | +| `ANTHROPIC_MODEL` | ๊ธฐ๋ณธ ๋ชจ๋ธ ์žฌ์ •์˜ | +| `ANTHROPIC_CUSTOM_MODEL_OPTION` | API๋ฅผ ์œ„ํ•œ ์‚ฌ์šฉ์ž ์ •์˜ ๋ชจ๋ธ ์˜ต์…˜ | +| `ANTHROPIC_DEFAULT_OPUS_MODEL` | ๊ธฐ๋ณธ Opus ๋ชจ๋ธ ID ์žฌ์ •์˜ | +| `ANTHROPIC_DEFAULT_SONNET_MODEL` | ๊ธฐ๋ณธ Sonnet ๋ชจ๋ธ ID ์žฌ์ •์˜ | +| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | ๊ธฐ๋ณธ Haiku ๋ชจ๋ธ ID ์žฌ์ •์˜ | +| `MAX_THINKING_TOKENS` | ํ™•์žฅ๋œ ์‚ฌ๊ณ  ํ† ํฐ ์˜ˆ์‚ฐ ์„ค์ • | +| `CLAUDE_CODE_EFFORT_LEVEL` | ๋…ธ๋ ฅ ์ˆ˜์ค€ ์„ค์ • (`low`/`medium`/`high`/`xhigh`/`max`) โ€” ๊ธฐ๋ณธ๊ฐ’์€ Opus 4.8์—์„œ `high` (Opus 4.7์—์„œ `xhigh`); `xhigh`๋Š” Opus 4.8/4.7 ํ•„์š”; `max`๋Š” Opus 4.8/4.7/4.6 ๋ฐ Sonnet 4.6์—์„œ ์ž‘๋™ | +| `CLAUDE_CODE_SIMPLE` | `--bare` ํ”Œ๋ž˜๊ทธ๋กœ ์„ค์ •๋˜๋Š” ์ตœ์†Œ ๋ชจ๋“œ | +| `CLAUDE_CODE_SAFE_MODE` | ๋ชจ๋“  ์‚ฌ์šฉ์ž ์ •์˜๋ฅผ ๋น„ํ™œ์„ฑํ™”ํ•œ ์ƒํƒœ๋กœ ์‹œ์ž‘ํ•˜๋ ค๋ฉด `1`๋กœ ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค (CLAUDE.md, ํ”Œ๋Ÿฌ๊ทธ์ธ, ์Šคํ‚ฌ, ํ›…, MCP) โ€” ๊ตฌ์„ฑ ๋ฌธ์ œ ๊ฒฉ๋ฆฌ๋ฅผ ์œ„ํ•œ `--safe-mode`์˜ ํ™˜๊ฒฝ ๋ณ€์ˆ˜ ํ˜•์‹ (v2.1.169) | +| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | ๋ชจ๋ธ์—์„œ ๋ฒˆ๋“ค๋œ ์Šคํ‚ฌ, ์›Œํฌํ”Œ๋กœ, ๋ช…๋ น์„ ์ˆจ๊ธฐ๋ ค๋ฉด `1`๋กœ ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค (v2.1.169) | +| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | ์ž๋™ CLAUDE.md ์—…๋ฐ์ดํŠธ๋ฅผ ๋น„ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค | +| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž‘์—… ์‹คํ–‰์„ ๋น„ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค | +| `CLAUDE_CODE_DISABLE_CRON` | ์˜ˆ์•ฝ/ํฌ๋ก  ์ž‘์—…์„ ๋น„ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค | +| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | Git ๊ด€๋ จ ์ง€์นจ์„ ๋น„ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค | +| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | ํ„ฐ๋ฏธ๋„ ์ œ๋ชฉ ์—…๋ฐ์ดํŠธ๋ฅผ ๋น„ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค | +| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | 1M ํ† ํฐ ์ปจํ…์ŠคํŠธ ์ฐฝ์„ ๋น„ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค | +| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | ์ „์ฒด ํ™”๋ฉด ๋ชจ๋“œ์—์„œ ๋งˆ์šฐ์Šค ํด๋ฆญ/๋“œ๋ž˜๊ทธ/ํ˜ธ๋ฒ„๋ฅผ ๋น„ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค; ํœ  ์Šคํฌ๋กค์€ ์—ฌ์ „ํžˆ ์ž‘๋™ํ•ฉ๋‹ˆ๋‹ค (v2.1.195+) | +| `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK` | ๋น„์ŠคํŠธ๋ฆฌ๋ฐ ํด๋ฐฑ์„ ๋น„ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค | +| `CLAUDE_CODE_ENABLE_TASKS` | ์ž‘์—… ๋ชฉ๋ก ๊ธฐ๋Šฅ์„ ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค | +| `CLAUDE_CODE_TASK_LIST_ID` | ์„ธ์…˜ ๊ฐ„์— ๊ณต์œ ๋˜๋Š” ์ด๋ฆ„ ์ง€์ •๋œ ์ž‘์—… ๋””๋ ‰ํ† ๋ฆฌ | +| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | ํ”„๋กฌํ”„ํŠธ ์ œ์•ˆ์„ ์ „ํ™˜ํ•ฉ๋‹ˆ๋‹ค (`true`/`false`) | +| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | ์‹คํ—˜์ ์ธ ์—์ด์ „ํŠธ ํŒ€์„ ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค | +| `CLAUDE_CODE_NEW_INIT` | ์ƒˆ๋กœ์šด ์ดˆ๊ธฐํ™” ํ๋ฆ„์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค | +| `CLAUDE_CODE_SUBAGENT_MODEL` | ์„œ๋ธŒ์—์ด์ „ํŠธ ์‹คํ–‰์„ ์œ„ํ•œ ๋ชจ๋ธ | +| `CLAUDE_CODE_PLUGIN_SEED_DIR` | ํ”Œ๋Ÿฌ๊ทธ์ธ ์‹œ๋“œ ํŒŒ์ผ ๋””๋ ‰ํ† ๋ฆฌ | +| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | ์„œ๋ธŒํ”„๋กœ์„ธ์Šค์—์„œ ์ œ๊ฑฐํ•  ํ™˜๊ฒฝ ๋ณ€์ˆ˜ | +| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | ์ž๋™ ์••์ถ• ๋ฐฑ๋ถ„์œจ์„ ์žฌ์ •์˜ํ•ฉ๋‹ˆ๋‹ค | +| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | ์ŠคํŠธ๋ฆผ ์œ ํœด ์‹œ๊ฐ„ ์ดˆ๊ณผ (๋ฐ€๋ฆฌ์ดˆ) | +| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | ์Šฌ๋ž˜์‹œ ๋ช…๋ น ๋„๊ตฌ์˜ ๋ฌธ์ž ์˜ˆ์‚ฐ | +| `ENABLE_TOOL_SEARCH` | ๋„๊ตฌ ๊ฒ€์ƒ‰ ๊ธฐ๋Šฅ์„ ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค | +| `MAX_MCP_OUTPUT_TOKENS` | MCP ๋„๊ตฌ ์ถœ๋ ฅ์˜ ์ตœ๋Œ€ ํ† ํฐ | +| `CLAUDE_CODE_PERFORCE_MODE` | Perforce ๋ชจ๋“œ๋ฅผ ํ™œ์„ฑํ™”ํ•˜๋ ค๋ฉด `1`๋กœ ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค โ€” ํŒŒ์ผ์„ ๊ธฐ๋ณธ์ ์œผ๋กœ ์ฝ๊ธฐ ์ „์šฉ์œผ๋กœ ์ฒ˜๋ฆฌํ•ฉ๋‹ˆ๋‹ค (Perforce/P4 ๋ฒ„์ „ ์ œ์–ด ์›Œํฌํ”Œ๋กœ์šฉ) (v2.1.98์— ์ถ”๊ฐ€๋จ) | +| `DISABLE_UPDATES` | ์ˆ˜๋™ `claude update`๋ฅผ ํฌํ•จํ•œ ๋ชจ๋“  ์—…๋ฐ์ดํŠธ ๊ฒฝ๋กœ๋ฅผ ์ฐจ๋‹จํ•ฉ๋‹ˆ๋‹ค. ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž๋™ ์—…๋ฐ์ดํŠธ๋งŒ ์ฐจ๋‹จํ•˜๋Š” `DISABLE_AUTOUPDATER`๋ณด๋‹ค ์—„๊ฒฉํ•ฉ๋‹ˆ๋‹ค (v2.1.118+) | +| `CLAUDE_CODE_HIDE_CWD` | `1`๋กœ ์„ค์ •ํ•˜๋ฉด ์‹œ์ž‘ ๋กœ๊ณ ์— ํ˜„์žฌ ์ž‘์—… ๋””๋ ‰ํ† ๋ฆฌ๋ฅผ ์ˆจ๊น๋‹ˆ๋‹ค (๊ฐœ์ธ ์ •๋ณด ๋ณดํ˜ธ / ํ™”๋ฉด ๊ณต์œ  ์‚ฌ์šฉ) (v2.1.119+) | +| `CLAUDE_CODE_FORK_SUBAGENT` | ์™ธ๋ถ€ ๋นŒ๋“œ (Bedrock, Vertex, Foundry)์—์„œ ํฌํฌ๋œ ์„œ๋ธŒ์—์ด์ „ํŠธ๋ฅผ ํ™œ์„ฑํ™”ํ•˜๋ ค๋ฉด `1`๋กœ ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค. ํฌํฌ๋œ ์„œ๋ธŒ์—์ด์ „ํŠธ๊ฐ€ GA์ธ Anthropic API์—๋Š” ์˜ํ–ฅ์„ ๋ฏธ์น˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค (v2.1.117+) | +| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | ์ „์ฒด ํ™”๋ฉด ๋Œ€์ฒด ํ™”๋ฉด ๋ Œ๋”๋Ÿฌ๋ฅผ ์‚ฌ์šฉํ•˜์ง€ ์•Š์œผ๋ ค๋ฉด `1`๋กœ ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค. ์„ธ์…˜์€ ์ผ๋ฐ˜ ํ„ฐ๋ฏธ๋„ ์Šคํฌ๋กค๋ฐฑ์— ์œ ์ง€๋ฉ๋‹ˆ๋‹ค. ๋Œ€๋ณธ์„ ๋กœ๊ทธ๋กœ ํŒŒ์ดํ”„ํ•˜๊ฑฐ๋‚˜ `script(1)`์™€ ํŽ˜์–ด๋งํ•  ๋•Œ ์œ ์šฉํ•ฉ๋‹ˆ๋‹ค (v2.1.132+). | +| `CLAUDE_CODE_SESSION_ID` | Claude Code๊ฐ€ ์‹œ์ž‘ํ•œ ๋ชจ๋“  Bash ๋„๊ตฌ ์„œ๋ธŒํ”„๋กœ์„ธ์Šค์— ์„ค์ •๋ฉ๋‹ˆ๋‹ค. ํ›… ์ž…๋ ฅ JSON์˜ `session_id`์™€ ๊ฐ™์Šต๋‹ˆ๋‹ค. Bash ๋กœ๊ทธ๋ฅผ ํ›… ์›๊ฒฉ ์ธก์ •๊ณผ ์—ฐ๊ด€์‹œํ‚ค๋Š” ๋ฐ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค (v2.1.132+). | +| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | OpenTelemetry ๋ฐ์ดํ„ฐ๋ฅผ ์บก์ฒ˜ํ•˜๋Š” ์กฐ์ง์„ ์œ„ํ•ด Anthropic์˜ ์„ธ์…˜ ํ’ˆ์งˆ ์„ค๋ฌธ์กฐ์‚ฌ๋ฅผ ๋‹ค์‹œ ํ™œ์„ฑํ™”ํ•˜๋ ค๋ฉด `1`๋กœ ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค. OTEL ๋ฐฐํฌ์—์„œ๋Š” ๊ธฐ๋ณธ์ ์œผ๋กœ ๊บผ์ ธ ์žˆ์Šต๋‹ˆ๋‹ค (v2.1.136+). | +| `OTEL_LOG_TOOL_DETAILS` | OpenTelemetry ์ด๋ฒคํŠธ์—์„œ ์‚ฌ์šฉ์ž ์ •์˜ ๋ฐ MCP ๋ช…๋ น ์ด๋ฆ„์„ ๋น„ํ‘œ์‹œ ์ฒ˜๋ฆฌ ํ•ด์ œํ•˜๋ ค๋ฉด `1`๋กœ ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค (v2.1.117+). ๋น„ํ‘œ์‹œ ์ฒ˜๋ฆฌ๋Š” ๊ธฐ๋ณธ๊ฐ’์œผ๋กœ ์œ ์ง€๋ฉ๋‹ˆ๋‹ค. | +| `ANTHROPIC_BEDROCK_SERVICE_TIER` | Bedrock ์„œ๋น„์Šค ํ‹ฐ์–ด๋ฅผ ์„ ํƒํ•ฉ๋‹ˆ๋‹ค: `default`, `flex`, ๋˜๋Š” `priority` (v2.1.122+) | +| `AI_AGENT` | ์„œ๋ธŒํ”„๋กœ์„ธ์Šค์— ์ž๋™์œผ๋กœ ์„ค์ •๋˜๋ฏ€๋กœ ์™ธ๋ถ€ CLI (์˜ˆ: `gh`)๊ฐ€ ํŠธ๋ž˜ํ”ฝ์„ Claude Code์— ๊ท€์†์‹œํ‚ฌ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค (v2.1.120+) | +| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | ์ž๋™ ๊ฐ์ง€๊ฐ€ ์‹คํŒจํ•˜๋Š” ํ„ฐ๋ฏธ๋„ (์˜ˆ: Emacs `eat`)์˜ ๋™๊ธฐ ์ถœ๋ ฅ์„ ๊ฐ•์ œํ•˜๋ ค๋ฉด `1`๋กœ ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค (v2.1.129+) | +| `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` | Homebrew/WinGet ์„ค์น˜ (์ผ๋ฐ˜์ ์œผ๋กœ ์ž๋™ ์—…๋ฐ์ดํŠธ๋˜์ง€ ์•Š์Œ)์˜ ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์—…๊ทธ๋ ˆ์ด๋“œ๋ฅผ ํ™œ์„ฑํ™”ํ•˜๋ ค๋ฉด `1`๋กœ ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค (v2.1.129+) | +| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | `ANTHROPIC_BASE_URL`์ด ์„ค์ •๋˜์–ด ์žˆ์„ ๋•Œ ๊ฒŒ์ดํŠธ์›จ์ด `/v1/models` ๊ฒ€์ƒ‰์„ ์„ ํƒํ•˜๋ ค๋ฉด `1`๋กœ ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค. ์—†์œผ๋ฉด `/model`์€ ๋‚ด์žฅ๋œ ์ •์  ๋ชฉ๋ก์„ ๋ณด์—ฌ์ค๋‹ˆ๋‹ค (v2.1.129+) | +| `CLAUDE_CODE_ENABLE_AUTO_MODE` | Bedrock, Vertex, Foundry์—์„œ Opus 4.7/4.8์˜ ์ž๋™ ๋ชจ๋“œ๋ฅผ ์„ ํƒํ•˜๋ ค๋ฉด `1`๋กœ ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค (v2.1.158+) | +| `CLAUDE_CLIENT_PRESENCE_FILE` | ๊ธฐ๊ณ„์— ์žˆ์„ ๋•Œ ๋ชจ๋ฐ”์ผ ํ‘ธ์‹œ ์•Œ๋ฆผ์„ ์–ต์ œํ•˜๋Š” ๋งˆ์ปค ํŒŒ์ผ์„ ๊ฐ€๋ฆฌํ‚ต๋‹ˆ๋‹ค (v2.1.181+). ์ฐธ๊ณ : ์ด๋ฆ„์€ `CLAUDE_CLIENT_PRESENCE_FILE`์ด๋ฉฐ `CLAUDE_CODE_CLIENT_PRESENCE_FILE`์ด ์•„๋‹™๋‹ˆ๋‹ค. | +| `CLAUDE_CODE_MAX_RETRIES` | API ์žฌ์‹œ๋„ ์ตœ๋Œ€ ํšŸ์ˆ˜. v2.1.186๋ถ€ํ„ฐ 15ํšŒ๋กœ ์ œํ•œ๋ฉ๋‹ˆ๋‹ค. | +| `CLAUDE_CODE_RETRY_WATCHDOG` | `CLAUDE_CODE_MAX_RETRIES`๋ฅผ ์˜ฌ๋ฆฌ๋Š” ๋Œ€์•ˆ์œผ๋กœ, ๋ฌด์ธ ์„ธ์…˜์— ๊ถŒ์žฅ๋˜๋Š” ์žฌ์‹œ๋„ ์ œ์–ด์ž…๋‹ˆ๋‹ค (v2.1.186+). | +| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | ์‘๋‹ต ์—†์ด ์ง€์—ฐ๋˜๋Š” ์›๊ฒฉ MCP ๋„๊ตฌ ํ˜ธ์ถœ์˜ 5๋ถ„ ์œ ํœด ์ค‘๋‹จ ์‹œ๊ฐ„์„ ์žฌ์ •์˜ํ•ฉ๋‹ˆ๋‹ค (v2.1.187+). | +| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | **์ œ๊ฑฐ๋จ (v2.1.160๋ถ€ํ„ฐ ์ž‘๋™ ์•ˆ ํ•จ).** ์ด์ „์—๋Š” ๋น ๋ฅธ ๋ชจ๋“œ (`/fast`)๋ฅผ Opus 4.6์— ๊ณ ์ •ํ–ˆ์Šต๋‹ˆ๋‹ค. ํ˜„์žฌ Opus 4.6์—์„œ ๋น ๋ฅธ ๋ชจ๋“œ๋ฅผ ์‚ฌ์šฉํ•˜๋ ค๋ฉด `/model claude-opus-4-6[1m]`์„ ์‹คํ–‰ํ•œ ๋‹ค์Œ `/fast on`์„ ์‹คํ–‰ํ•˜์‹ญ์‹œ์˜ค. | + +> **Vertex AI์˜ `ENABLE_TOOL_SEARCH` (v2.1.119+)**: ๋„๊ตฌ ๊ฒ€์ƒ‰์€ **Google Cloud Vertex AI ๋ฐฐํฌ์—์„œ๋Š” ๊ธฐ๋ณธ์ ์œผ๋กœ ๋น„ํ™œ์„ฑํ™”**๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. Vertex์—์„œ ๋„๊ตฌ ๊ฒ€์ƒ‰ ๊ธฐ๋Šฅ์„ ์›ํ•˜๋Š” ์‚ฌ์šฉ์ž๋Š” `export ENABLE_TOOL_SEARCH=true`๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ๋ช…์‹œ์ ์œผ๋กœ ์„ ํƒํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. ์ง์ ‘ Anthropic API์—์„œ๋Š” ๊ธฐ๋ณธ์ ์œผ๋กœ ํ™œ์„ฑํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. + +--- + +## Settings.json ํ‚ค + +์ด๋Ÿฌํ•œ ํ‚ค๋Š” ํ”Œ๋ž˜๊ทธ๋‚˜ ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋กœ ์ „๋‹ฌ๋˜๋Š” ๋Œ€์‹  `settings.json` ํŒŒ์ผ (์‚ฌ์šฉ์ž ๋ฒ”์œ„์˜ ๊ฒฝ์šฐ `~/.claude/settings.json`, ํ”„๋กœ์ ํŠธ ๋ฒ”์œ„์˜ ๊ฒฝ์šฐ `.claude/settings.json`)์— ์žˆ์Šต๋‹ˆ๋‹ค. ์•„๋ž˜ ํ‘œ๋Š” ์ตœ๊ทผ ์ถ”๊ฐ€๋œ ๋ช‡ ๊ฐ€์ง€ UI/UX ํ‚ค๋ฅผ ๋‹ค๋ฃจ๋ฉฐ, ๊ด€๋ฆฌ๋˜๋Š” `enforceAvailableModels` ํ‚ค์— ๋Œ€ํ•ด์„œ๋Š” [๊ณ ๊ธ‰ ๊ธฐ๋Šฅ โ†’ ๊ด€๋ฆฌ๋˜๋Š” ์„ค์ •](../09-advanced-features/README.md#available-managed-settings)์„ ์ฐธ์กฐํ•˜์‹ญ์‹œ์˜ค. + +| Key | Description | +|-----|-------------| +| `respondToBashCommands` | (v2.1.186) `!` bash ๋ช…๋ น์˜ ์ถœ๋ ฅ์— ์ž๋™์œผ๋กœ ์‘๋‹ตํ•ฉ๋‹ˆ๋‹ค. ๊ธฐ๋ณธ๊ฐ’์€ `true`์ž…๋‹ˆ๋‹ค. ์ปจํ…์ŠคํŠธ ์ „์šฉ (v2.1.186 ์ด์ „) ๋™์ž‘์„ ์œ„ํ•ด์„œ๋Š” `false`๋กœ ์„ค์ •ํ•˜์‹ญ์‹œ์˜ค. [๊ณ ๊ธ‰ ๊ธฐ๋Šฅ โ†’ Bash ๋ชจ๋“œ](../09-advanced-features/README.md#bash-mode)๋ฅผ ์ฐธ์กฐํ•˜์‹ญ์‹œ์˜ค. | +| `wheelScrollAccelerationEnabled` | (v2.1.174) ์ „์ฒด ํ™”๋ฉด ๋ Œ๋”๋Ÿฌ์—์„œ ๋งˆ์šฐ์Šค ํœ  ์Šคํฌ๋กค ๊ฐ€์†์„ ๋น„ํ™œ์„ฑํ™”ํ•˜๋ ค๋ฉด `false`๋กœ ์„ค์ •ํ•˜์‹ญ์‹œ์˜ค. ๋น ๋ฅธ ํœ  ์›€์ง์ž„์ด ๋„ˆ๋ฌด ๋งŽ์ด ์ง€๋‚˜์น  ๋•Œ ์œ ์šฉํ•ฉ๋‹ˆ๋‹ค. | +| `footerLinksRegexes` | (v2.1.176) ์ผ์น˜ํ•˜๋Š” ๋งํฌ๋ฅผ ๋ฐ”๋‹ฅ๊ธ€ ํ–‰์— ๋ฐฐ์ง€๋กœ ๋ Œ๋”๋งํ•˜๋Š” ์ •๊ทœ์‹ ๋ฐฐ์—ด์ž…๋‹ˆ๋‹ค. ์‚ฌ์šฉ์ž ๋˜๋Š” ๊ด€๋ฆฌ ์„ค์ •์—์„œ ๊ตฌ์„ฑ ๊ฐ€๋Šฅํ•ฉ๋‹ˆ๋‹ค. | +| `language` | Claude์˜ ์„ ํ˜ธ ์‘๋‹ต ์–ธ์–ด์™€ ์Œ์„ฑ ๋ฐ›์•„์“ฐ๊ธฐ ์–ธ์–ด๋ฅผ ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค (์˜ˆ: `"french"`, `"japanese"`). **v2.1.176**๋ถ€ํ„ฐ ์ž๋™ ์ƒ์„ฑ๋˜๋Š” ์„ธ์…˜ ์ œ๋ชฉ์— ์‚ฌ์šฉ๋˜๋Š” ์–ธ์–ด๋„ ๊ณ ์ •ํ•ฉ๋‹ˆ๋‹ค. | + +```json +{ + "wheelScrollAccelerationEnabled": false, + "language": "french", + "footerLinksRegexes": ["https://jira\\.example\\.com/.*"] +} +``` + +--- + +## ๋น ๋ฅธ ์ฐธ์กฐ + +### ๊ฐ€์žฅ ์ผ๋ฐ˜์ ์ธ ๋ช…๋ น + +```bash +# ๋Œ€ํ™”ํ˜• ์„ธ์…˜ +claude + +# ๊ฐ„๋‹จํ•œ ์งˆ๋ฌธ +claude -p "how do I..." + +# ๋Œ€ํ™” ๊ณ„์† +claude -c + +# ํŒŒ์ผ ์ฒ˜๋ฆฌ +cat file.py | claude -p "review this" + +# ์Šคํฌ๋ฆฝํŠธ์šฉ JSON ์ถœ๋ ฅ +claude -p --output-format json "query" +``` + +### ํ”Œ๋ž˜๊ทธ ์กฐํ•ฉ + +| Use Case | Command | +|----------|---------| +| ๋น ๋ฅธ ์ฝ”๋“œ ๊ฒ€ํ†  | `cat file \| claude -p "review"` | +| ๊ตฌ์กฐํ™”๋œ ์ถœ๋ ฅ | `claude -p --output-format json "query"` | +| ์•ˆ์ „ํ•œ ํƒ์ƒ‰ | `claude --permission-mode plan` | +| ์•ˆ์ „ํ•œ ์ž์œจ ๋ชจ๋“œ | `claude --enable-auto-mode --permission-mode auto` | +| CI/CD ํ†ตํ•ฉ | `claude -p --max-turns 3 --output-format json` | +| ์ž‘์—… ์žฌ๊ฐœ | `claude -r "session-name"` | +| ์‚ฌ์šฉ์ž ์ •์˜ ๋ชจ๋ธ | `claude --model opus "complex task"` | +| ์ตœ์†Œ ๋ชจ๋“œ | `claude --bare "quick query"` | +| ์˜ˆ์‚ฐ ์ œํ•œ ์‹คํ–‰ | `claude -p --max-budget-usd 2.00 "analyze code"` | + +--- + +## ๋ฌธ์ œ ํ•ด๊ฒฐ + +### ๋ช…๋ น์„ ์ฐพ์„ ์ˆ˜ ์—†์Œ + +**๋ฌธ์ œ:** `claude: command not found` + +**ํ•ด๊ฒฐ์ฑ…:** +- Claude Code ์„ค์น˜: `npm install -g @anthropic-ai/claude-code` +- PATH์— npm ์ „์—ญ bin ๋””๋ ‰ํ† ๋ฆฌ๊ฐ€ ํฌํ•จ๋˜์–ด ์žˆ๋Š”์ง€ ํ™•์ธ +- ์ „์ฒด ๊ฒฝ๋กœ๋กœ ์‹คํ–‰ ์‹œ๋„: `npx claude` + +### API ํ‚ค ๋ฌธ์ œ + +**๋ฌธ์ œ:** ์ธ์ฆ ์‹คํŒจ + +**ํ•ด๊ฒฐ์ฑ…:** +- API ํ‚ค ์„ค์ •: `export ANTHROPIC_API_KEY=your-key` +- ํ‚ค๊ฐ€ ์œ ํšจํ•˜๊ณ  ์ถฉ๋ถ„ํ•œ ํฌ๋ ˆ๋”ง์ด ์žˆ๋Š”์ง€ ํ™•์ธ +- ์š”์ฒญ๋œ ๋ชจ๋ธ์— ๋Œ€ํ•œ ํ‚ค ๊ถŒํ•œ ํ™•์ธ + +### ์„ธ์…˜์„ ์ฐพ์„ ์ˆ˜ ์—†์Œ + +**๋ฌธ์ œ:** ์„ธ์…˜์„ ์žฌ๊ฐœํ•  ์ˆ˜ ์—†์Œ + +**ํ•ด๊ฒฐ์ฑ…:** +- ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ์„ธ์…˜ ๋ชฉ๋ก์„ ํ™•์ธํ•˜์—ฌ ์˜ฌ๋ฐ”๋ฅธ ์ด๋ฆ„/ID ์ฐพ๊ธฐ +- ์„ธ์…˜์€ ๋น„ํ™œ๋™ ๊ธฐ๊ฐ„ ํ›„ ๋งŒ๋ฃŒ๋  ์ˆ˜ ์žˆ์Œ +- `-c`๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ๊ฐ€์žฅ ์ตœ๊ทผ ์„ธ์…˜ ๊ณ„์† + +### ์ถœ๋ ฅ ํ˜•์‹ ๋ฌธ์ œ + +**๋ฌธ์ œ:** JSON ์ถœ๋ ฅ์ด ์ž˜๋ชป๋จ + +**ํ•ด๊ฒฐ์ฑ…:** +- `--json-schema`๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ๊ตฌ์กฐ ๊ฐ•์ œ ์ ์šฉ +- ํ”„๋กฌํ”„ํŠธ์— ๋ช…์‹œ์ ์ธ JSON ์ง€์นจ ์ถ”๊ฐ€ +- `--output-format json` ์‚ฌ์šฉ (ํ”„๋กฌํ”„ํŠธ์—์„œ JSON์„ ์š”์ฒญํ•˜๋Š” ๊ฒƒ๋งŒ์œผ๋กœ๋Š” ๋ถ€์กฑ) + +### ๊ถŒํ•œ ๊ฑฐ๋ถ€ + +**๋ฌธ์ œ:** ๋„๊ตฌ ์‹คํ–‰์ด ์ฐจ๋‹จ๋จ + +**ํ•ด๊ฒฐ์ฑ…:** +- `--permission-mode` ์„ค์ • ํ™•์ธ +- `--allowedTools` ๋ฐ `--disallowedTools` ํ”Œ๋ž˜๊ทธ ๊ฒ€ํ†  +- ์ž๋™ํ™”๋ฅผ ์œ„ํ•ด `--dangerously-skip-permissions` ์‚ฌ์šฉ (์ฃผ์˜ ์š”๋ง) + +--- + +## ์ถ”๊ฐ€ ์ž๋ฃŒ + +- **[๊ณต์‹ CLI ์ฐธ์กฐ](https://code.claude.com/docs/en/cli-reference)** - ์ „์ฒด ๋ช…๋ น ์ฐธ์กฐ +- **[ํ—ค๋“œ๋ฆฌ์Šค ๋ชจ๋“œ ๋ฌธ์„œ](https://code.claude.com/docs/en/headless)** - ์ž๋™ํ™”๋œ ์‹คํ–‰ +- **[์Šฌ๋ž˜์‹œ ๋ช…๋ น](../01-slash-commands/)** - Claude ๋‚ด์˜ ์‚ฌ์šฉ์ž ์ •์˜ ๋‹จ์ถ•ํ‚ค +- **[๋ฉ”๋ชจ๋ฆฌ ๊ฐ€์ด๋“œ](../02-memory/)** - CLAUDE.md๋ฅผ ํ†ตํ•œ ์˜๊ตฌ ์ปจํ…์ŠคํŠธ +- **[MCP ํ”„๋กœํ† ์ฝœ](../05-mcp/)** - ์™ธ๋ถ€ ๋„๊ตฌ ํ†ตํ•ฉ +- **[๊ณ ๊ธ‰ ๊ธฐ๋Šฅ](../09-advanced-features/)** - ๊ณ„ํš ๋ชจ๋“œ, ํ™•์žฅ๋œ ์‚ฌ๊ณ  +- **[์„œ๋ธŒ์—์ด์ „ํŠธ ๊ฐ€์ด๋“œ](../04-subagents/)** - ์œ„์ž„๋œ ์ž‘์—… ์‹คํ–‰ + +--- + +* [Claude ์‚ฌ์šฉ๋ฒ•](../) ๊ฐ€์ด๋“œ ์‹œ๋ฆฌ์ฆˆ์˜ ์ผ๋ถ€์ž…๋‹ˆ๋‹ค * + +--- + +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: 2026๋…„ 6์›” 28์ผ +**Claude Code ๋ฒ„์ „**: 2.1.195 +**์ถœ์ฒ˜**: +- https://code.claude.com/docs/en/cli-reference +- https://code.claude.com/docs/en/env-vars +- https://code.claude.com/docs/en/changelog#2-1-174 +- https://code.claude.com/docs/en/changelog#2-1-176 +- https://code.claude.com/docs/en/changelog +- https://code.claude.com/docs/en/settings +- https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md +- https://docs.anthropic.com/en/docs/claude-code/cli-reference +- https://code.claude.com/docs/en/troubleshooting +- https://code.claude.com/docs/en/slash-commands +- https://code.claude.com/docs/en/model-config +- https://platform.claude.com/docs/en/about-claude/models/overview +- https://www.anthropic.com/news/claude-opus-4-8 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.117 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.139 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.142 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.154 +- https://code.claude.com/docs/en/plugins +- https://code.claude.com/docs/en/overview +**ํ˜ธํ™˜ ๋ชจ๋ธ**: Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5 diff --git a/ko/CATALOG.md b/ko/CATALOG.md new file mode 100644 index 00000000..8348c046 --- /dev/null +++ b/ko/CATALOG.md @@ -0,0 +1,559 @@ + + + Claude How To + + +# Claude Code ๊ธฐ๋Šฅ ์นดํƒˆ๋กœ๊ทธ + +> Claude Code์˜ ๋ชจ๋“  ๊ธฐ๋Šฅ(๋ช…๋ น์–ด, ์—์ด์ „ํŠธ, ์Šคํ‚ฌ, ํ”Œ๋Ÿฌ๊ทธ์ธ, ํ›…)์— ๋Œ€ํ•œ ๋น ๋ฅธ ์ฐธ์กฐ ๊ฐ€์ด๋“œ์ž…๋‹ˆ๋‹ค. + +**ํƒ์ƒ‰**: [Commands](#slash-commands) | [Permission Modes](#permission-modes) | [Subagents](#subagents) | [Skills](#skills) | [Plugins](#plugins) | [MCP Servers](#mcp-servers) | [Hooks](#hooks) | [Memory](#memory-files) | [New Features](#new-features-may-2026) + +--- + +## ์š”์•ฝ + +| Feature | Built-in | Examples | Total | Reference | +|---------|----------|----------|-------|-----------| +| **Slash Commands** | 60+ | 8 | 68+ | [01-slash-commands/](01-slash-commands/) | +| **Subagents** | 6 | 11 | 17 | [04-subagents/](04-subagents/) | +| **Skills** | ๊ธฐ๋ณธ ์ œ๊ณต 9๊ฐœ | 6 | 15 | [03-skills/](03-skills/) | +| **Plugins** | - | 3 | 3 | [07-plugins/](07-plugins/) | +| **MCP Servers** | 1 | 8 | 9 | [05-mcp/](05-mcp/) | +| **Hooks** | ์ด๋ฒคํŠธ 29๊ฐœ | 8 | 8 | [06-hooks/](06-hooks/) | +| **Memory** | ์œ ํ˜• 7๊ฐœ | 3 | 3 | [02-memory/](02-memory/) | +| **ํ•ฉ๊ณ„** | **103** | **47** | **125** | | + +--- + +## Slash Commands + +๋ช…๋ น์–ด๋Š” ์‚ฌ์šฉ์ž๊ฐ€ ์ง์ ‘ ์‹คํ–‰ํ•˜์—ฌ ํŠน์ • ์ž‘์—…์„ ์ˆ˜ํ–‰ํ•˜๋Š” ๋‹จ์ถ• ๋ช…๋ น์ž…๋‹ˆ๋‹ค. + +### ๊ธฐ๋ณธ ์ œ๊ณต ๋ช…๋ น์–ด + +| Command | Description | When to Use | +|---------|-------------|-------------| +| `/help` | ๋„์›€๋ง ์ •๋ณด ํ‘œ์‹œ | ์‹œ์ž‘ํ•˜๊ธฐ, ๋ช…๋ น์–ด ํ•™์Šต | +| `/btw` | ๋ฉ”์ธ ์ปจํ…์ŠคํŠธ๋ฅผ ์˜ค์—ผ์‹œํ‚ค์ง€ ์•Š๋Š” ์ž„์‹œ ์งˆ๋ฌธ | ์งง์€ ์ฃผ์ œ ์ „ํ™˜ ์งˆ๋ฌธ | +| `/chrome` | Chrome ์—ฐ๋™ ์„ค์ • | ๋ธŒ๋ผ์šฐ์ € ์ž๋™ํ™” | +| `/clear` | ๋Œ€ํ™” ๊ธฐ๋ก ์‚ญ์ œ | ์ƒˆ๋กœ ์‹œ์ž‘, ์ปจํ…์ŠคํŠธ ์ถ•์†Œ | +| `/diff` | ๋Œ€ํ™”ํ˜• diff ๋ทฐ์–ด | ๋ณ€๊ฒฝ ์‚ฌํ•ญ ๊ฒ€ํ†  | +| `/config` | ์„ค์ • ์กฐํšŒ/์ˆ˜์ • | ๋™์ž‘ ์‚ฌ์šฉ์ž ์ง€์ • | +| `/status` | ์„ธ์…˜ ์ƒํƒœ ํ‘œ์‹œ | ํ˜„์žฌ ์ƒํƒœ ํ™•์ธ | +| `/agents` | ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ์—์ด์ „ํŠธ ๋ชฉ๋ก ํ‘œ์‹œ | ์œ„์ž„ ๊ฐ€๋Šฅํ•œ ์—์ด์ „ํŠธ ํ™•์ธ | +| `/skills` | ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ์Šคํ‚ฌ ๋ชฉ๋ก ํ‘œ์‹œ | ์ž๋™ ํ˜ธ์ถœ ๊ธฐ๋Šฅ ํ™•์ธ | +| `/hooks` | ๊ตฌ์„ฑ๋œ ํ›… ๋ชฉ๋ก ํ‘œ์‹œ | ์ž๋™ํ™” ๋””๋ฒ„๊น… | +| `/insights` | ์„ธ์…˜ ํŒจํ„ด ๋ถ„์„ | ์„ธ์…˜ ์ตœ์ ํ™” | +| `/install-slack-app` | Claude Slack ์•ฑ ์„ค์น˜ | Slack ์—ฐ๋™ | +| `/keybindings` | ํ‚ค๋ณด๋“œ ๋‹จ์ถ•ํ‚ค ์‚ฌ์šฉ์ž ์ง€์ • | ๋‹จ์ถ•ํ‚ค ์„ค์ • | +| `/mcp` | MCP ์„œ๋ฒ„ ๋ชฉ๋ก ํ‘œ์‹œ | ์™ธ๋ถ€ ์—ฐ๋™ ํ™•์ธ | +| `/memory` | ๋กœ๋“œ๋œ ๋ฉ”๋ชจ๋ฆฌ ํŒŒ์ผ ํ‘œ์‹œ | ์ปจํ…์ŠคํŠธ ๋กœ๋”ฉ ๋””๋ฒ„๊น… | +| `/mobile` | ๋ชจ๋ฐ”์ผ QR ์ฝ”๋“œ ์ƒ์„ฑ | ๋ชจ๋ฐ”์ผ ์ ‘์† | +| `/passes` | ์‚ฌ์šฉ ํŒจ์Šค ์กฐํšŒ | ๊ตฌ๋… ์ •๋ณด ํ™•์ธ | +| `/plugin` | ํ”Œ๋Ÿฌ๊ทธ์ธ ๊ด€๋ฆฌ | ํ™•์žฅ ๊ธฐ๋Šฅ ์„ค์น˜/์ œ๊ฑฐ | +| `/plan` | ๊ณ„ํš ๋ชจ๋“œ ์ง„์ž… | ๋ณต์žกํ•œ ๊ตฌํ˜„ ์ž‘์—… | +| `/proactive` | `/loop`์˜ ๋ณ„์นญ (v2.1.105) | `/loop`์™€ ๋™์ผ | +| `/recap` | ์„ธ์…˜์— ๋‹ค์‹œ ๋Œ์•„์™”์„ ๋•Œ ์š”์•ฝ ํ‘œ์‹œ | ์ž๋ฆฌ๋ฅผ ๋น„์šด ํ›„ ์ž‘์—… ๋‚ด์šฉ ํ™•์ธ | +| `/rewind` | ์ฒดํฌํฌ์ธํŠธ๋กœ ๋˜๋Œ๋ฆฌ๊ธฐ | ๋ณ€๊ฒฝ ์‚ฌํ•ญ ์ทจ์†Œ, ๋Œ€์•ˆ ํƒ์ƒ‰ | +| `/checkpoint` | ์ฒดํฌํฌ์ธํŠธ ๊ด€๋ฆฌ | ์ƒํƒœ ์ €์žฅ/๋ณต์› | +| `/cost` | `/usage`์˜ ๋น„์šฉ ํƒญ์„ ์—ฌ๋Š” ๋‹จ์ถ• ๋ณ„์นญ (v2.1.118+) | ๋น„์šฉ ๋ชจ๋‹ˆํ„ฐ๋ง | +| `/context` | ์ปจํ…์ŠคํŠธ ์ฐฝ ์‚ฌ์šฉ๋Ÿ‰ ํ‘œ์‹œ | ๋Œ€ํ™” ๊ธธ์ด ๊ด€๋ฆฌ | +| `/export` | ๋Œ€ํ™” ๋‚ด๋ณด๋‚ด๊ธฐ | ์ฐธ์กฐ์šฉ ์ €์žฅ | +| `/usage-credits` | ์ถ”๊ฐ€ ์‚ฌ์šฉ ํ•œ๋„ ์„ค์ • (`/extra-usage`์—์„œ ์ด๋ฆ„ ๋ณ€๊ฒฝ, v2.1.144, ๊ธฐ์กด ์ด๋ฆ„๋„ ๋ณ„์นญ์œผ๋กœ ์‚ฌ์šฉ ๊ฐ€๋Šฅ) | ์‚ฌ์šฉ๋Ÿ‰ ์ œํ•œ ๊ด€๋ฆฌ | +| `/feedback` | ํ”ผ๋“œ๋ฐฑ ๋˜๋Š” ๋ฒ„๊ทธ ๋ฆฌํฌํŠธ ์ œ์ถœ | ๋ฌธ์ œ ์‹ ๊ณ  | +| `/login` | Anthropic ์ธ์ฆ | ๊ธฐ๋Šฅ ์‚ฌ์šฉ | +| `/logout` | ๋กœ๊ทธ์•„์›ƒ | ๊ณ„์ • ์ „ํ™˜ | +| `/sandbox` | ์ƒŒ๋“œ๋ฐ•์Šค ๋ชจ๋“œ ์ „ํ™˜ | ์•ˆ์ „ํ•œ ๋ช…๋ น ์‹คํ–‰ | +| `/doctor` | ์ง„๋‹จ ์‹คํ–‰ | ๋ฌธ์ œ ํ•ด๊ฒฐ | +| `/reload-plugins` | ์„ค์น˜๋œ ํ”Œ๋Ÿฌ๊ทธ์ธ ๋‹ค์‹œ ๋กœ๋“œ | ํ”Œ๋Ÿฌ๊ทธ์ธ ๊ด€๋ฆฌ | +| `/reload-skills` | ์žฌ์‹œ์ž‘ ์—†์ด ์Šคํ‚ฌ ๋””๋ ‰ํ„ฐ๋ฆฌ ๋‹ค์‹œ ๊ฒ€์ƒ‰ (v2.1.152) | ์Šคํ‚ฌ ๊ด€๋ฆฌ | +| `/workflows` | ์‹คํ–‰ ์ค‘ ๋ฐ ์™„๋ฃŒ๋œ ๋™์  ์›Œํฌํ”Œ๋กœ ์‹คํ–‰ ๋‚ด์—ญ ํ‘œ์‹œ (v2.1.154) | ๋ฉ€ํ‹ฐ ์—์ด์ „ํŠธ ์˜ค์ผ€์ŠคํŠธ๋ ˆ์ด์…˜ | +| `/release-notes` | ๋ฆด๋ฆฌ์Šค ๋…ธํŠธ ํ‘œ์‹œ | ์ƒˆ๋กœ์šด ๊ธฐ๋Šฅ ํ™•์ธ | +| `/remote-control` | ์›๊ฒฉ ์ œ์–ด ํ™œ์„ฑํ™” | ์›๊ฒฉ ์ ‘์† | +| `/permissions` | ๊ถŒํ•œ ๊ด€๋ฆฌ | ์ ‘๊ทผ ๊ถŒํ•œ ์ œ์–ด | +| `/session` | ์„ธ์…˜ ๊ด€๋ฆฌ | ๋‹ค์ค‘ ์„ธ์…˜ ์›Œํฌํ”Œ๋กœ | +| `/rename` | ํ˜„์žฌ ์„ธ์…˜ ์ด๋ฆ„ ๋ณ€๊ฒฝ | ์„ธ์…˜ ์ •๋ฆฌ | +| `/resume` | ์ด์ „ ์„ธ์…˜ ์ด์–ด์„œ ์ž‘์—… | ์ž‘์—… ๊ณ„์†ํ•˜๊ธฐ | +| `/todo` | ํ•  ์ผ ๋ชฉ๋ก ์กฐํšŒ/๊ด€๋ฆฌ | ์ž‘์—… ์ถ”์  | +| `/tui` | ์ „์ฒด ํ™”๋ฉด TUI(Text User Interface) ๋ชจ๋“œ ์ „ํ™˜ | ์ „์ฒด ํ™”๋ฉด/tmux์—์„œ ๊นœ๋นก์ž„ ์—†๋Š” ์ถœ๋ ฅ | +| `/tasks` | ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž‘์—… ํ‘œ์‹œ | ๋น„๋™๊ธฐ ์ž‘์—… ๋ชจ๋‹ˆํ„ฐ๋ง | +| `/copy` | ๋งˆ์ง€๋ง‰ ์‘๋‹ต์„ ํด๋ฆฝ๋ณด๋“œ๋กœ ๋ณต์‚ฌ | ์ถœ๋ ฅ๋ฌผ ๋น ๋ฅด๊ฒŒ ๊ณต์œ  | +| `/teleport` | ๋‹ค๋ฅธ ์ปดํ“จํ„ฐ๋กœ ์„ธ์…˜ ์ „์†ก | ์›๊ฒฉ์œผ๋กœ ์ž‘์—… ์ด์–ด๊ฐ€๊ธฐ | +| `/desktop` | Claude Desktop ์•ฑ ์—ด๊ธฐ | ๋ฐ์Šคํฌํ†ฑ ์ธํ„ฐํŽ˜์ด์Šค๋กœ ์ „ํ™˜ | +| `/theme` | ์ƒ‰์ƒ ํ…Œ๋งˆ ๋ณ€๊ฒฝ. v2.1.118๋ถ€ํ„ฐ `~/.claude/themes/.json`์˜ ์‚ฌ์šฉ์ž ์ •์˜ ํ…Œ๋งˆ ์ง€์›(ํ”Œ๋Ÿฌ๊ทธ์ธ์€ `themes/` ๋””๋ ‰ํ„ฐ๋ฆฌ๋ฅผ ํฌํ•จ ๊ฐ€๋Šฅ) | ํ™”๋ฉด ํ…Œ๋งˆ ์‚ฌ์šฉ์ž ์ง€์ • | +| `/usage` | ์‚ฌ์šฉ๋Ÿ‰/๋น„์šฉ/ํ†ต๊ณ„๋ฅผ ํ†ตํ•ฉํ•œ ๊ณต์‹ ๋ช…๋ น์–ด(`/cost`์™€ `/stats` ํ†ตํ•ฉ, v2.1.118). v2.1.149๋ถ€ํ„ฐ ๋น„์šฉ์„ ์Šคํ‚ฌ, ์„œ๋ธŒ์—์ด์ „ํŠธ, ํ”Œ๋Ÿฌ๊ทธ์ธ, MCP ์„œ๋ฒ„๋ณ„๋กœ ๊ตฌ๋ถ„ํ•˜์—ฌ ํ‘œ์‹œ. **VSCode ํ™•์žฅ**(v2.1.174)์—์„œ๋Š” `/usage` ๋Œ€ํ™”์ƒ์ž์— ์บ์‹œ ๋ฏธ์Šค, ๊ธด ์ปจํ…์ŠคํŠธ ๋น„์šฉ, ์„œ๋ธŒ์—์ด์ „ํŠธ, ์Šคํ‚ฌ/์—์ด์ „ํŠธ/ํ”Œ๋Ÿฌ๊ทธ์ธ/MCP๋ณ„ 24์‹œ๊ฐ„ ๋ฐ 7์ผ ์‚ฌ์šฉ๋Ÿ‰ ๋ถ„์„์ด ์ถ”๊ฐ€๋จ | ์‚ฌ์šฉ๋Ÿ‰ ๋ฐ ๋น„์šฉ ๋ชจ๋‹ˆํ„ฐ๋ง | +| `/focus` | ์ง‘์ค‘ ๋ณด๊ธฐ ๋ชจ๋“œ ์ „ํ™˜ | ๊ธด ์ž‘์—… ์ค‘ ํ™”๋ฉด ์žก์Œ ์ตœ์†Œํ™” | +| `/fork` | ํ˜„์žฌ ๋Œ€ํ™” ๋ถ„๊ธฐ | ๋Œ€์•ˆ ํƒ์ƒ‰ | +| `/stats` | `/usage`์˜ ํ†ต๊ณ„ ํƒญ์„ ์—ฌ๋Š” ๋‹จ์ถ• ๋ณ„์นญ (v2.1.118+) | ์„ธ์…˜ ํ†ต๊ณ„ ํ™•์ธ | +| `/statusline` | ์ƒํƒœ ํ‘œ์‹œ์ค„ ๊ตฌ์„ฑ | ์ƒํƒœ ํ‘œ์‹œ ์‚ฌ์šฉ์ž ์ง€์ • | +| `/stickers` | ์„ธ์…˜ ์Šคํ‹ฐ์ปค ๋ณด๊ธฐ | ์žฌ๋ฏธ ์š”์†Œ | +| `/fast` | ๋น ๋ฅธ ์ถœ๋ ฅ ๋ชจ๋“œ ์ „ํ™˜ | ์‘๋‹ต ์†๋„ ํ–ฅ์ƒ | +| `/terminal-setup` | ํ„ฐ๋ฏธ๋„ ์—ฐ๋™ ์„ค์ • | ํ„ฐ๋ฏธ๋„ ๊ธฐ๋Šฅ ์„ค์ • | +| `/undo` | `/rewind`์˜ ๋ณ„์นญ (v2.1.108) | `/rewind`์™€ ๋™์ผ | +| `/upgrade` | ์—…๋ฐ์ดํŠธ ํ™•์ธ | ๋ฒ„์ „ ๊ด€๋ฆฌ | +| `/team-onboarding` | ํ˜„์žฌ ํ”„๋กœ์ ํŠธ์˜ Claude Code ์‚ฌ์šฉ ๋‚ด์—ญ์„ ๊ธฐ๋ฐ˜์œผ๋กœ ํŒ€์› ์˜จ๋ณด๋”ฉ ๊ฐ€์ด๋“œ ์ƒ์„ฑ | ์‹ ๊ทœ ํŒ€์› ์˜จ๋ณด๋”ฉ (v2.1.101) | +| `/ultraplan` | ๊ณ„ํš ์ž‘์—…์„ ์›น ๊ธฐ๋ฐ˜ Claude Code ์„ธ์…˜์˜ ๊ณ„ํš ๋ชจ๋“œ๋กœ ์œ„์ž„ | ๋Œ€๊ทœ๋ชจ ๊ณ„ํš ์ž‘์—… ์˜คํ”„๋กœ๋“œ (Research Preview, v2.1.91+) | +| `/ultrareview` | ํ˜„์žฌ ๋ณ€๊ฒฝ ์‚ฌํ•ญ์— ๋Œ€ํ•ด ํด๋ผ์šฐ๋“œ ๊ธฐ๋ฐ˜ ๋ฉ€ํ‹ฐ ์—์ด์ „ํŠธ ์ฝ”๋“œ ๋ฆฌ๋ทฐ ์‹คํ–‰ | ๋ณ‘ํ•ฉ ์ „ ์‹ฌ์ธต ์ฝ”๋“œ ๋ฆฌ๋ทฐ (v2.1.112) | +| `/less-permission-prompts` | ๋Œ€ํ™” ๊ธฐ๋ก์„ ๋ถ„์„ํ•˜์—ฌ ์ž์ฃผ ์‚ฌ์šฉํ•˜๋Š” ์ฝ๊ธฐ ์ „์šฉ ๋„๊ตฌ์˜ ํ—ˆ์šฉ ๋ชฉ๋ก์„ ์šฐ์„ ์ˆœ์œ„์— ๋”ฐ๋ผ ์ œ์•ˆ | ๋ฐ˜๋ณต์ ์ธ ๊ถŒํ•œ ์š”์ฒญ ๊ฐ์†Œ (v2.1.112) | + +### ์‚ฌ์šฉ์ž ์ •์˜ ๋ช…๋ น์–ด (์˜ˆ์‹œ) + +| Command | Description | When to Use | Scope | Installation | +|---------|-------------|-------------|-------|--------------| +| `/optimize` | ์ฝ”๋“œ ์ตœ์ ํ™” ๋ถ„์„ | ์„ฑ๋Šฅ ๊ฐœ์„  | ํ”„๋กœ์ ํŠธ | `cp 01-slash-commands/optimize.md .claude/commands/` | +| `/pr` | Pull Request ์ค€๋น„ | PR ์ œ์ถœ ์ „ | ํ”„๋กœ์ ํŠธ | `cp 01-slash-commands/pr.md .claude/commands/` | +| `/generate-api-docs` | API ๋ฌธ์„œ ์ƒ์„ฑ | API ๋ฌธ์„œํ™” | ํ”„๋กœ์ ํŠธ | `cp 01-slash-commands/generate-api-docs.md .claude/commands/` | +| `/commit` | ์ปจํ…์ŠคํŠธ๋ฅผ ๋ฐ˜์˜ํ•œ Git ์ปค๋ฐ‹ ์ƒ์„ฑ | ๋ณ€๊ฒฝ ์‚ฌํ•ญ ์ปค๋ฐ‹ | ์‚ฌ์šฉ์ž | `cp 01-slash-commands/commit.md .claude/commands/` | +| `/push-all` | ์Šคํ…Œ์ด์ง•, ์ปค๋ฐ‹ ๋ฐ ํ‘ธ์‹œ ์ˆ˜ํ–‰ | ๋น ๋ฅธ ๋ฐฐํฌ | ์‚ฌ์šฉ์ž | `cp 01-slash-commands/push-all.md .claude/commands/` | +| `/doc-refactor` | ๋ฌธ์„œ ๊ตฌ์กฐ ์žฌ๊ตฌ์„ฑ | ๋ฌธ์„œ ๊ฐœ์„  | ํ”„๋กœ์ ํŠธ | `cp 01-slash-commands/doc-refactor.md .claude/commands/` | +| `/setup-ci-cd` | CI/CD ํŒŒ์ดํ”„๋ผ์ธ ์„ค์ • | ์‹ ๊ทœ ํ”„๋กœ์ ํŠธ | ํ”„๋กœ์ ํŠธ | `cp 01-slash-commands/setup-ci-cd.md .claude/commands/` | +| `/unit-test-expand` | ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€ ํ™•์žฅ | ํ…Œ์ŠคํŠธ ํ’ˆ์งˆ ํ–ฅ์ƒ | ํ”„๋กœ์ ํŠธ | `cp 01-slash-commands/unit-test-expand.md .claude/commands/` | + +> **Scope**: `User` = ๊ฐœ์ธ ์›Œํฌํ”Œ๋กœ(`~/.claude/commands/`), `Project` = ํŒ€ ๊ณต์œ (`.claude/commands/`) + +**์ฐธ๊ณ  ์ž๋ฃŒ**: [01-slash-commands/](01-slash-commands/) | [Official Docs](https://code.claude.com/docs/en/interactive-mode) + +**๋น ๋ฅธ ์„ค์น˜(๋ชจ๋“  ์‚ฌ์šฉ์ž ์ •์˜ ๋ช…๋ น์–ด)**: +```bash +cp 01-slash-commands/*.md .claude/commands/ +``` + +--- + +## Permission Modes + +Claude Code๋Š” ๋„๊ตฌ ์‚ฌ์šฉ ๊ถŒํ•œ์„ ์ œ์–ดํ•˜๋Š” 6๊ฐ€์ง€ ๊ถŒํ•œ ๋ชจ๋“œ๋ฅผ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค. + +| Mode | Description | When to Use | +|------|-------------|-------------| +| `default` | ๋ชจ๋“  ๋„๊ตฌ ํ˜ธ์ถœ ์‹œ๋งˆ๋‹ค ๊ถŒํ•œ ์š”์ฒญ | ์ผ๋ฐ˜์ ์ธ ๋Œ€ํ™”ํ˜• ์‚ฌ์šฉ | +| `acceptEdits` | ํŒŒ์ผ ์ˆ˜์ •์€ ์ž๋™ ์Šน์ธํ•˜๊ณ  ๋‚˜๋จธ์ง€๋Š” ๊ถŒํ•œ ์š”์ฒญ | ์‹ ๋ขฐํ•  ์ˆ˜ ์žˆ๋Š” ํŽธ์ง‘ ์›Œํฌํ”Œ๋กœ | +| `plan` | ์ฝ๊ธฐ ์ „์šฉ ๋„๊ตฌ๋งŒ ํ—ˆ์šฉ, ์“ฐ๊ธฐ ๊ธˆ์ง€ | ๊ณ„ํš ์ˆ˜๋ฆฝ ๋ฐ ํƒ์ƒ‰ | +| `auto` | ๋ชจ๋“  ๋„๊ตฌ๋ฅผ ๊ถŒํ•œ ์š”์ฒญ ์—†์ด ํ—ˆ์šฉ | ์™„์ „ ์ž์œจ ์‹คํ–‰ (Research Preview) | +| `bypassPermissions` | ๋ชจ๋“  ๊ถŒํ•œ ํ™•์ธ ๊ฑด๋„ˆ๋›ฐ๊ธฐ | CI/CD, ํ—ค๋“œ๋ฆฌ์Šค ํ™˜๊ฒฝ | +| `dontAsk` | ๊ถŒํ•œ์ด ํ•„์š”ํ•œ ๋„๊ตฌ๋Š” ๊ฑด๋„ˆ๋œ€ | ๋น„๋Œ€ํ™”ํ˜• ์Šคํฌ๋ฆฝํŠธ | + +> **์ฐธ๊ณ **: `auto` ๋ชจ๋“œ๋Š” 2026๋…„ 3์›” ๊ธฐ์ค€ Research Preview ๊ธฐ๋Šฅ์ž…๋‹ˆ๋‹ค. `bypassPermissions`๋Š” ์‹ ๋ขฐํ•  ์ˆ˜ ์žˆ๋Š” ์ƒŒ๋“œ๋ฐ•์Šค ํ™˜๊ฒฝ์—์„œ๋งŒ ์‚ฌ์šฉํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. + +**์ฐธ๊ณ  ์ž๋ฃŒ**: [Official Docs](https://code.claude.com/docs/en/permissions) + +--- + +## Subagents + +ํŠน์ • ์ž‘์—…์„ ์œ„ํ•ด ๋…๋ฆฝ๋œ ์ปจํ…์ŠคํŠธ๋ฅผ ์‚ฌ์šฉํ•˜๋Š” ์ „๋ฌธ AI ๋ณด์กฐ ์—์ด์ „ํŠธ์ž…๋‹ˆ๋‹ค. + +> **์ค‘์ฒฉ ์ƒ์„ฑ(v2.1.172)**: ์„œ๋ธŒ์—์ด์ „ํŠธ๋Š” ์ตœ๋Œ€ 5๋‹จ๊ณ„๊นŒ์ง€ ์ž์‹ ์˜ ์„œ๋ธŒ์—์ด์ „ํŠธ๋ฅผ ์ƒ์„ฑํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์ด์ „ ๋ฒ„์ „์—์„œ๋Š” ์ค‘์ฒฉ ์ƒ์„ฑ์ด ์ง€์›๋˜์ง€ ์•Š์•˜์Šต๋‹ˆ๋‹ค. ํŠน์ • ์„œ๋ธŒ์—์ด์ „ํŠธ๋งŒ ์ƒ์„ฑํ•˜๋„๋ก ์ œํ•œํ•˜๋Š” `Agent(agent_type)` ๋ฌธ๋ฒ•์€ [04-subagents/README.md](04-subagents/README.md#restrict-spawnable-subagents)๋ฅผ ์ฐธ๊ณ ํ•˜์„ธ์š”. + +### ๊ธฐ๋ณธ ์ œ๊ณต ์„œ๋ธŒ์—์ด์ „ํŠธ + +| Agent | Description | Tools | Model | When to Use | +|-------|-------------|-------|-------|-------------| +| **general-purpose** | ๋‹ค๋‹จ๊ณ„ ์ž‘์—…, ์กฐ์‚ฌ | ๋ชจ๋“  ๋„๊ตฌ | ์ƒ์œ„ ๋ชจ๋ธ ์ƒ์† | ๋ณต์žกํ•œ ์กฐ์‚ฌ, ๋‹ค์ค‘ ํŒŒ์ผ ์ž‘์—… | +| **Plan** | ๊ตฌํ˜„ ๊ณ„ํš ์ˆ˜๋ฆฝ | Read, Glob, Grep, Bash | ์ƒ์œ„ ๋ชจ๋ธ ์ƒ์† | ์•„ํ‚คํ…์ฒ˜ ์„ค๊ณ„, ๊ณ„ํš ์ˆ˜๋ฆฝ | +| **Explore** | ์ฝ”๋“œ๋ฒ ์ด์Šค ํƒ์ƒ‰ | Read, Glob, Grep | Haiku 4.5 | ๋น ๋ฅธ ๊ฒ€์ƒ‰, ์ฝ”๋“œ ์ดํ•ด | +| **Bash** | ๋ช…๋ น ์‹คํ–‰ | Bash | ์ƒ์œ„ ๋ชจ๋ธ ์ƒ์† | Git ์ž‘์—…, ํ„ฐ๋ฏธ๋„ ์ž‘์—… | +| **statusline-setup** | ์ƒํƒœ ํ‘œ์‹œ์ค„ ๊ตฌ์„ฑ | Bash, Read, Write | Sonnet 4.6 | ์ƒํƒœ ํ‘œ์‹œ์ค„ ์„ค์ • | +| **Claude Code Guide** | ๋„์›€๋ง ๋ฐ ๋ฌธ์„œ | Read, Glob, Grep | Haiku 4.5 | ๋„์›€๋ง ํ™•์ธ, ๊ธฐ๋Šฅ ํ•™์Šต | + +### ์„œ๋ธŒ์—์ด์ „ํŠธ ์„ค์ • ํ•„๋“œ + +| Field | Type | Description | +|-------|------|-------------| +| `name` | string | ์—์ด์ „ํŠธ ์‹๋ณ„์ž | +| `description` | string | ์—์ด์ „ํŠธ์˜ ์—ญํ•  | +| `model` | string | ์‚ฌ์šฉํ•  ๋ชจ๋ธ ์žฌ์ •์˜(์˜ˆ: `haiku-4.5`) | +| `tools` | array | ํ—ˆ์šฉ๋œ ๋„๊ตฌ ๋ชฉ๋ก | +| `effort` | string | ์ถ”๋ก  ์ˆ˜์ค€(`low`, `medium`, `high`) | +| `initialPrompt` | string | ์—์ด์ „ํŠธ ์‹œ์ž‘ ์‹œ ์ฃผ์ž…๋˜๋Š” ์‹œ์Šคํ…œ ํ”„๋กฌํ”„ํŠธ | +| `disallowedTools` | array | ๋ช…์‹œ์ ์œผ๋กœ ๊ธˆ์ง€๋œ ๋„๊ตฌ ๋ชฉ๋ก | + +### ์‚ฌ์šฉ์ž ์ •์˜ ์„œ๋ธŒ์—์ด์ „ํŠธ (์˜ˆ์‹œ) + +| Agent | Description | When to Use | Scope | Installation | +|-------|-------------|-------------|-------|--------------| +| `code-reviewer` | ์ข…ํ•ฉ ์ฝ”๋“œ ํ’ˆ์งˆ ๊ฒ€ํ†  | ์ฝ”๋“œ ๋ฆฌ๋ทฐ | ํ”„๋กœ์ ํŠธ | `cp 04-subagents/code-reviewer.md .claude/agents/` | +| `code-architect` | ๊ธฐ๋Šฅ ์•„ํ‚คํ…์ฒ˜ ์„ค๊ณ„ | ์‹ ๊ทœ ๊ธฐ๋Šฅ ์„ค๊ณ„ | ํ”„๋กœ์ ํŠธ | `cp 04-subagents/code-architect.md .claude/agents/` | +| `code-explorer` | ์‹ฌ์ธต ์ฝ”๋“œ๋ฒ ์ด์Šค ๋ถ„์„ | ๊ธฐ์กด ๊ธฐ๋Šฅ ๋ถ„์„ | ํ”„๋กœ์ ํŠธ | `cp 04-subagents/code-explorer.md .claude/agents/` | +| `clean-code-reviewer` | Clean Code ์›์น™ ๊ธฐ๋ฐ˜ ๋ฆฌ๋ทฐ | ์œ ์ง€๋ณด์ˆ˜์„ฑ ๊ฒ€ํ†  | ํ”„๋กœ์ ํŠธ | `cp 04-subagents/clean-code-reviewer.md .claude/agents/` | +| `test-engineer` | ํ…Œ์ŠคํŠธ ์ „๋žต ๋ฐ ์ปค๋ฒ„๋ฆฌ์ง€ | ํ…Œ์ŠคํŠธ ๊ณ„ํš | ํ”„๋กœ์ ํŠธ | `cp 04-subagents/test-engineer.md .claude/agents/` | +| `documentation-writer` | ๊ธฐ์ˆ  ๋ฌธ์„œ ์ž‘์„ฑ | API ๋ฌธ์„œ, ๊ฐ€์ด๋“œ | ํ”„๋กœ์ ํŠธ | `cp 04-subagents/documentation-writer.md .claude/agents/` | +| `secure-reviewer` | ๋ณด์•ˆ ์ค‘์‹ฌ ์ฝ”๋“œ ๋ฆฌ๋ทฐ | ๋ณด์•ˆ ๊ฐ์‚ฌ | ํ”„๋กœ์ ํŠธ | `cp 04-subagents/secure-reviewer.md .claude/agents/` | +| `implementation-agent` | ์ „์ฒด ๊ธฐ๋Šฅ ๊ตฌํ˜„ | ๊ธฐ๋Šฅ ๊ฐœ๋ฐœ | ํ”„๋กœ์ ํŠธ | `cp 04-subagents/implementation-agent.md .claude/agents/` | +| `debugger` | ๊ทผ๋ณธ ์›์ธ ๋ถ„์„ | ๋ฒ„๊ทธ ์กฐ์‚ฌ | ์‚ฌ์šฉ์ž | `cp 04-subagents/debugger.md .claude/agents/` | +| `data-scientist` | SQL ์ฟผ๋ฆฌ ๋ฐ ๋ฐ์ดํ„ฐ ๋ถ„์„ | ๋ฐ์ดํ„ฐ ์ž‘์—… | ์‚ฌ์šฉ์ž | `cp 04-subagents/data-scientist.md .claude/agents/` | +| `performance-optimizer` | ํ”„๋กœํŒŒ์ผ๋ง ๋ฐ ์„ฑ๋Šฅ ํŠœ๋‹ | ๋ณ‘๋ชฉ ๋ถ„์„ | ํ”„๋กœ์ ํŠธ | `cp 04-subagents/performance-optimizer.md .claude/agents/` | + +> **Scope**: `User` = ๊ฐœ์ธ(`~/.claude/agents/`), `Project` = ํŒ€ ๊ณต์œ (`.claude/agents/`) + +**์ฐธ๊ณ  ์ž๋ฃŒ**: [04-subagents/](04-subagents/) | [Official Docs](https://code.claude.com/docs/en/sub-agents) + +**๋น ๋ฅธ ์„ค์น˜(๋ชจ๋“  ์‚ฌ์šฉ์ž ์ •์˜ ์—์ด์ „ํŠธ)**: +```bash +cp 04-subagents/*.md .claude/agents/ +``` + +--- + +## Skills + +์ง€์นจ, ์Šคํฌ๋ฆฝํŠธ, ํ…œํ”Œ๋ฆฟ์„ ํฌํ•จํ•˜๋ฉฐ ํ•„์š” ์‹œ ์ž๋™์œผ๋กœ ํ˜ธ์ถœ๋˜๋Š” ๊ธฐ๋Šฅ์ž…๋‹ˆ๋‹ค. + +### ์˜ˆ์‹œ ์Šคํ‚ฌ + +| Skill | Description | When Auto-Invoked | Scope | Installation | +|-------|-------------|-------------------|-------|--------------| +| `code-review-specialist` | ์ข…ํ•ฉ ์ฝ”๋“œ ๋ฆฌ๋ทฐ | "Review this code", "Check quality" | ํ”„๋กœ์ ํŠธ | `cp -r 03-skills/code-review-specialist .claude/skills/` | +| `brand-voice` | ๋ธŒ๋žœ๋“œ ์ผ๊ด€์„ฑ ๊ฒ€์‚ฌ | ๋งˆ์ผ€ํŒ… ๋ฌธ์„œ ์ž‘์„ฑ | ํ”„๋กœ์ ํŠธ | `cp -r 03-skills/brand-voice .claude/skills/` | +| `doc-generator` | API ๋ฌธ์„œ ์ƒ์„ฑ | "Generate docs", "Document API" | ํ”„๋กœ์ ํŠธ | `cp -r 03-skills/doc-generator .claude/skills/` | +| `refactor` | Martin Fowler ๋ฐฉ์‹์˜ ์ฒด๊ณ„์ ์ธ ์ฝ”๋“œ ๋ฆฌํŒฉํ„ฐ๋ง | "Refactor this", "Clean up code" | ์‚ฌ์šฉ์ž | `cp -r 03-skills/refactor ~/.claude/skills/` | + +> **Scope**: `User` = ๊ฐœ์ธ(`~/.claude/skills/`), `Project` = ํŒ€ ๊ณต์œ (`.claude/skills/`) +### Skill Structure + +``` +~/.claude/skills/skill-name/ +โ”œโ”€โ”€ SKILL.md # Skill definition & instructions +โ”œโ”€โ”€ scripts/ # Helper scripts +โ””โ”€โ”€ templates/ # Output templates +``` + +### Skill Frontmatter Fields + +์Šคํ‚ฌ์€ `SKILL.md`์—์„œ ์„ค์ •์„ ์œ„ํ•œ YAML ํ”„๋ก ํŠธ๋งคํ„ฐ๋ฅผ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค. + +| Field | Type | Description | +|-------|------|-------------| +| `name` | string | ์Šคํ‚ฌ ํ‘œ์‹œ ์ด๋ฆ„ | +| `description` | string | ์Šคํ‚ฌ์˜ ๊ธฐ๋Šฅ ์„ค๋ช… | +| `autoInvoke` | array | ์ž๋™ ํ˜ธ์ถœ์„ ์œ„ํ•œ ํŠธ๋ฆฌ๊ฑฐ ๋ฌธ๊ตฌ | +| `effort` | string | ์ถ”๋ก  ์ˆ˜์ค€ (`low`, `medium`, `high`) | +| `shell` | string | ์Šคํฌ๋ฆฝํŠธ์— ์‚ฌ์šฉํ•  ์…ธ (`bash`, `zsh`, `sh`) | + +**์ฐธ๊ณ  ์ž๋ฃŒ**: [03-skills/](03-skills/) | [Official Docs](https://code.claude.com/docs/en/skills) + +**๋น ๋ฅธ ์„ค์น˜(๋ชจ๋“  ์Šคํ‚ฌ)**: +```bash +cp -r 03-skills/* ~/.claude/skills/ +``` + +### ๊ธฐ๋ณธ ์ œ๊ณต ์Šคํ‚ฌ + +| Skill | Description | When Auto-Invoked | +|-------|-------------|-------------------| +| `/batch` | ์—ฌ๋Ÿฌ ํŒŒ์ผ์— ํ”„๋กฌํ”„ํŠธ ์‹คํ–‰ | ์ผ๊ด„ ์ž‘์—… | +| `/claude-api` | Claude API๋ฅผ ์‚ฌ์šฉํ•œ ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜ ๊ฐœ๋ฐœ | API ๊ฐœ๋ฐœ | +| `/debug` | ์‹คํŒจํ•œ ํ…Œ์ŠคํŠธ ๋ฐ ์˜ค๋ฅ˜ ๋””๋ฒ„๊น… | ๋””๋ฒ„๊น… ์ž‘์—… | +| `/fewer-permission-prompts` | ๋Œ€ํ™” ๊ธฐ๋ก์„ ๋ถ„์„ํ•˜์—ฌ ์šฐ์„ ์ˆœ์œ„๊ฐ€ ์ง€์ •๋œ ํ—ˆ์šฉ ๋ชฉ๋ก ์ œ์•ˆ | ๋ฐ˜๋ณต์ ์ธ ๊ถŒํ•œ ์š”์ฒญ ๊ฐ์†Œ | +| `/loop` | ์ผ์ • ๊ฐ„๊ฒฉ์œผ๋กœ ํ”„๋กฌํ”„ํŠธ ์‹คํ–‰ | ๋ฐ˜๋ณต ์ž‘์—… | +| `/run` *(v2.1.145+)* | ํ”„๋กœ์ ํŠธ ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜์„ ์‹คํ–‰ํ•˜์—ฌ ๋ณ€๊ฒฝ ์‚ฌํ•ญ ํ™•์ธ | ์‹ค์ œ ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜์—์„œ ๋ณ€๊ฒฝ ์‚ฌํ•ญ ๊ฒ€์ฆ | +| `/run-skill-generator` *(v2.1.145+)* | ํŠน์ • ํ”„๋กœ์ ํŠธ์—์„œ `/run`/`/verify`๋ฅผ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ๋„๋ก ์„ค์ • | `/run` ์ตœ์ดˆ ํ”„๋กœ์ ํŠธ ์„ค์ • | +| `/code-review` | ํ˜„์žฌ diff๋ฅผ ์„ ํƒํ•œ ์ถ”๋ก  ์ˆ˜์ค€(์˜ˆ: `/code-review high`)์œผ๋กœ ๊ฒ€ํ† ํ•˜์—ฌ ์ •ํ™•์„ฑ ๋ฐ ๋ฒ„๊ทธ๋ฅผ ํ™•์ธ. `--comment`๋ฅผ ์ง€์ •ํ•˜๋ฉด ๊ฒฐ๊ณผ๋ฅผ PR์˜ ์ธ๋ผ์ธ ๋Œ“๊ธ€๋กœ ๊ฒŒ์‹œ | ์ฝ”๋“œ ์ž‘์„ฑ ํ›„, PR ๋ณ‘ํ•ฉ ์ „ | +| `/simplify` *(v2.1.154๋ถ€ํ„ฐ ๋‹ค์‹œ ๋…๋ฆฝ ๊ธฐ๋Šฅ)* | ์ •๋ฆฌ๋งŒ ์ˆ˜ํ–‰ํ•˜๋Š” ๋ฆฌ๋ทฐ(์žฌ์‚ฌ์šฉ, ๋‹จ์ˆœํ™”, ํšจ์œจ์„ฑ, ์ถ”์ƒํ™” ์ˆ˜์ค€)๋ฅผ ์‹คํ–‰ํ•˜๊ณ  ์ˆ˜์ • ์‚ฌํ•ญ์„ ์ ์šฉ. ๋ฒ„๊ทธ ํƒ์ง€๋Š” ์ˆ˜ํ–‰ํ•˜์ง€ ์•Š์Œ | ๋ฒ„๊ทธ ํƒ์ง€ ์—†์ด ์ฝ”๋“œ ์ •๋ฆฌ | +| `/verify` *(v2.1.145+)* | ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜์„ ๋นŒ๋“œ, ์‹คํ–‰ ๋ฐ ํ™•์ธํ•˜์—ฌ ์ˆ˜์ • ์‚ฌํ•ญ์ด ์ œ๋Œ€๋กœ ๋™์ž‘ํ•˜๋Š”์ง€ ๊ฒ€์ฆ | ์ˆ˜์ • ์‚ฌํ•ญ์˜ ์ „์ฒด ๋™์ž‘ ๊ฒ€์ฆ | + +--- + +## Plugins + +๋ช…๋ น์–ด, ์—์ด์ „ํŠธ, MCP ์„œ๋ฒ„ ๋ฐ ํ›…์„ ๋ฌถ์–ด์„œ ์ œ๊ณตํ•˜๋Š” ๊ธฐ๋Šฅ ๋ชจ์Œ์ž…๋‹ˆ๋‹ค. + +### ํ”Œ๋Ÿฌ๊ทธ์ธ ์˜ˆ์‹œ + +| Plugin | Description | Components | When to Use | Scope | Installation | +|--------|-------------|------------|-------------|-------|--------------| +| `pr-review` | PR ๋ฆฌ๋ทฐ ์›Œํฌํ”Œ๋กœ | ๋ช…๋ น์–ด 3๊ฐœ, ์—์ด์ „ํŠธ 3๊ฐœ, GitHub MCP | ์ฝ”๋“œ ๋ฆฌ๋ทฐ | ํ”„๋กœ์ ํŠธ | `/plugin install pr-review` | +| `devops-automation` | ๋ฐฐํฌ ๋ฐ ๋ชจ๋‹ˆํ„ฐ๋ง | ๋ช…๋ น์–ด 4๊ฐœ, ์—์ด์ „ํŠธ 3๊ฐœ, K8s MCP | DevOps ์ž‘์—… | ํ”„๋กœ์ ํŠธ | `/plugin install devops-automation` | +| `documentation` | ๋ฌธ์„œ ์ƒ์„ฑ ๋ชจ์Œ | ๋ช…๋ น์–ด 4๊ฐœ, ์—์ด์ „ํŠธ 3๊ฐœ, ํ…œํ”Œ๋ฆฟ | ๋ฌธ์„œ ์ž‘์„ฑ | ํ”„๋กœ์ ํŠธ | `/plugin install documentation` | + +> **Scope**: `Project` = ํŒ€ ๊ณต์œ , `User` = ๊ฐœ์ธ ์›Œํฌํ”Œ๋กœ + +### ํ”Œ๋Ÿฌ๊ทธ์ธ ๊ตฌ์กฐ + +``` +.claude-plugin/ +โ”œโ”€โ”€ plugin.json # ๋งค๋‹ˆํŽ˜์ŠคํŠธ ํŒŒ์ผ +โ”œโ”€โ”€ commands/ # Slash Commands +โ”œโ”€โ”€ agents/ # Subagents +โ”œโ”€โ”€ skills/ # Skills +โ”œโ”€โ”€ mcp/ # MCP ์„ค์ • +โ”œโ”€โ”€ hooks/ # Hook ์Šคํฌ๋ฆฝํŠธ +โ””โ”€โ”€ scripts/ # ์œ ํ‹ธ๋ฆฌํ‹ฐ ์Šคํฌ๋ฆฝํŠธ +``` + +**์ฐธ๊ณ  ์ž๋ฃŒ**: [07-plugins/](07-plugins/) | [Official Docs](https://code.claude.com/docs/en/plugins) + +**ํ”Œ๋Ÿฌ๊ทธ์ธ ๊ด€๋ฆฌ ๋ช…๋ น์–ด**: +```bash +/plugin list # ์„ค์น˜๋œ ํ”Œ๋Ÿฌ๊ทธ์ธ ๋ชฉ๋ก +/plugin install # ํ”Œ๋Ÿฌ๊ทธ์ธ ์„ค์น˜ +/plugin remove # ํ”Œ๋Ÿฌ๊ทธ์ธ ์ œ๊ฑฐ +/plugin update # ํ”Œ๋Ÿฌ๊ทธ์ธ ์—…๋ฐ์ดํŠธ +``` + +--- + +## MCP Servers + +์™ธ๋ถ€ ๋„๊ตฌ ๋ฐ API์— ์ ‘๊ทผํ•˜๊ธฐ ์œ„ํ•œ Model Context Protocol ์„œ๋ฒ„์ž…๋‹ˆ๋‹ค. + +### ์ผ๋ฐ˜์ ์œผ๋กœ ์‚ฌ์šฉํ•˜๋Š” MCP ์„œ๋ฒ„ + +| Server | Description | When to Use | Scope | Installation | +|--------|-------------|-------------|-------|--------------| +| **GitHub** | PR ๊ด€๋ฆฌ, ์ด์Šˆ, ์ฝ”๋“œ | GitHub ์›Œํฌํ”Œ๋กœ | ํ”„๋กœ์ ํŠธ | `claude mcp add github -- npx -y @modelcontextprotocol/server-github` | +| **Database** | SQL ์ฟผ๋ฆฌ ๋ฐ ๋ฐ์ดํ„ฐ ์ ‘๊ทผ | ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ์ž‘์—… | ํ”„๋กœ์ ํŠธ | `claude mcp add db -- npx -y @modelcontextprotocol/server-postgres` | +| **Filesystem** | ๊ณ ๊ธ‰ ํŒŒ์ผ ์ž‘์—… | ๋ณต์žกํ•œ ํŒŒ์ผ ์ž‘์—… | ์‚ฌ์šฉ์ž | `claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem` | +| **Slack** | ํŒ€ ์ปค๋ฎค๋‹ˆ์ผ€์ด์…˜ | ์•Œ๋ฆผ, ์—…๋ฐ์ดํŠธ | ํ”„๋กœ์ ํŠธ | ์„ค์ •์—์„œ ๊ตฌ์„ฑ | +| **Google Docs** | ๋ฌธ์„œ ์ ‘๊ทผ | ๋ฌธ์„œ ํŽธ์ง‘ ๋ฐ ๊ฒ€ํ†  | ํ”„๋กœ์ ํŠธ | ์„ค์ •์—์„œ ๊ตฌ์„ฑ | +| **Asana** | ํ”„๋กœ์ ํŠธ ๊ด€๋ฆฌ | ์ž‘์—… ์ถ”์  | ํ”„๋กœ์ ํŠธ | ์„ค์ •์—์„œ ๊ตฌ์„ฑ | +| **Stripe** | ๊ฒฐ์ œ ๋ฐ์ดํ„ฐ | ์žฌ๋ฌด ๋ถ„์„ | ํ”„๋กœ์ ํŠธ | ์„ค์ •์—์„œ ๊ตฌ์„ฑ | +| **Memory** | ์˜๊ตฌ ๋ฉ”๋ชจ๋ฆฌ | ์„ธ์…˜ ๊ฐ„ ๊ธฐ์–ต ์œ ์ง€ | ์‚ฌ์šฉ์ž | ์„ค์ •์—์„œ ๊ตฌ์„ฑ | +| **Context7** | ๋ผ์ด๋ธŒ๋Ÿฌ๋ฆฌ ๋ฌธ์„œ | ์ตœ์‹  ๋ฌธ์„œ ์กฐํšŒ | ๊ธฐ๋ณธ ์ œ๊ณต | ๊ธฐ๋ณธ ์ œ๊ณต | + +> **Scope**: `Project` = ํŒ€(`.mcp.json`), `User` = ๊ฐœ์ธ(`~/.claude.json`), `Built-in` = ๊ธฐ๋ณธ ์ œ๊ณต + +### MCP ์„ค์ • ์˜ˆ์‹œ + +```json +{ + "mcpServers": { + "github": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github"], + "env": { + "GITHUB_TOKEN": "${GITHUB_TOKEN}" + } + } + } +} +``` + +**์ฐธ๊ณ  ์ž๋ฃŒ**: [05-mcp/](05-mcp/) | [MCP Protocol Docs](https://modelcontextprotocol.io) + +**๋น ๋ฅธ ์„ค์น˜(GitHub MCP)**: +```bash +export GITHUB_TOKEN="your_token" && claude mcp add github -- npx -y @modelcontextprotocol/server-github +``` + +--- + +## Hooks + +Claude Code ์ด๋ฒคํŠธ ๋ฐœ์ƒ ์‹œ ์…ธ ๋ช…๋ น์„ ์‹คํ–‰ํ•˜๋Š” ์ด๋ฒคํŠธ ๊ธฐ๋ฐ˜ ์ž๋™ํ™” ๊ธฐ๋Šฅ์ž…๋‹ˆ๋‹ค. + +### Hook ์ด๋ฒคํŠธ + +| Event | Description | When Triggered | Use Cases | +|-------|-------------|----------------|-----------| +| `SessionStart` | ์„ธ์…˜ ์‹œ์ž‘ ๋˜๋Š” ์žฌ๊ฐœ | ์„ธ์…˜ ์ดˆ๊ธฐํ™” ์‹œ | ์ดˆ๊ธฐ ์„ค์ • ์ž‘์—… | +| `Setup` | ์ดˆ๊ธฐ ํ™˜๊ฒฝ ์„ค์ •(์„ธ์…˜๋‹น 1ํšŒ) | ์ตœ์ดˆ ์„ธ์…˜ ๋ถ€ํŠธ์ŠคํŠธ๋žฉ | ๋„๊ตฌ ์ค€๋น„, ์˜์กด์„ฑ ์„ค์น˜ | +| `InstructionsLoaded` | ์ง€์นจ ๋กœ๋“œ ์™„๋ฃŒ | CLAUDE.md ๋˜๋Š” ๊ทœ์น™ ํŒŒ์ผ ๋กœ๋“œ | ์‚ฌ์šฉ์ž ์ •์˜ ์ง€์นจ ์ฒ˜๋ฆฌ | +| `UserPromptSubmit` | ํ”„๋กฌํ”„ํŠธ ์ฒ˜๋ฆฌ ์ „ | ์‚ฌ์šฉ์ž๊ฐ€ ๋ฉ”์‹œ์ง€๋ฅผ ์ „์†กํ•  ๋•Œ | ์ž…๋ ฅ ๊ฒ€์ฆ | +| `UserPromptExpansion` | ์‚ฌ์šฉ์ž ํ”„๋กฌํ”„ํŠธ ํ™•์žฅ(@๋ฉ˜์…˜, Slash Commands ํ•ด์„) | ํ™•์žฅ ํ›„, ์ œ์ถœ ์ „ | ํ™•์žฅ๋œ ํ”„๋กฌํ”„ํŠธ ๋ณ€ํ™˜ ๋˜๋Š” ๊ฒ€์‚ฌ | +| `PreToolUse` | ๋„๊ตฌ ์‹คํ–‰ ์ „ | ๋ชจ๋“  ๋„๊ตฌ ์‹คํ–‰ ์ „ | ๊ฒ€์ฆ, ๋กœ๊น… | +| `PermissionRequest` | ๊ถŒํ•œ ์š”์ฒญ ๋Œ€ํ™”์ƒ์ž ํ‘œ์‹œ | ๋ฏผ๊ฐํ•œ ์ž‘์—… ์ „ | ์‚ฌ์šฉ์ž ์ •์˜ ์Šน์ธ ์ ˆ์ฐจ | +| `PermissionDenied` | ์‚ฌ์šฉ์ž๊ฐ€ ๊ถŒํ•œ ์š”์ฒญ์„ ๊ฑฐ๋ถ€ | ๊ถŒํ•œ ๊ฑฐ๋ถ€ ํ›„ | ๋กœ๊น…, ๋ถ„์„, ์ •์ฑ… ์ ์šฉ | +| `PostToolUse` | ๋„๊ตฌ ์‹คํ–‰ ์„ฑ๊ณต ํ›„ | ๋ชจ๋“  ๋„๊ตฌ ์‹คํ–‰ ์™„๋ฃŒ ํ›„ | ํฌ๋งทํŒ…, ์•Œ๋ฆผ | +| `PostToolUseFailure` | ๋„๊ตฌ ์‹คํ–‰ ์‹คํŒจ | ๋„๊ตฌ ์˜ค๋ฅ˜ ๋ฐœ์ƒ ํ›„ | ์˜ค๋ฅ˜ ์ฒ˜๋ฆฌ, ๋กœ๊น… | +| `PostToolBatch` | ๋„๊ตฌ ์‹คํ–‰ ๋ฌถ์Œ ์™„๋ฃŒ ํ›„ | ๋„๊ตฌ ๋ฐฐ์น˜ ์ข…๋ฃŒ ์‹œ | ์ง‘๊ณ„ ๋ณด๊ณ , ์ผ๊ด„ ๊ฒ€์ฆ | +| `Notification` | ์•Œ๋ฆผ ์ „์†ก | Claude๊ฐ€ ์•Œ๋ฆผ์„ ๋ณด๋‚ผ ๋•Œ | ์™ธ๋ถ€ ์•Œ๋ฆผ | +| `SubagentStart` | ์„œ๋ธŒ์—์ด์ „ํŠธ ์ƒ์„ฑ | ์„œ๋ธŒ์—์ด์ „ํŠธ ์ž‘์—… ์‹œ์ž‘ | ์„œ๋ธŒ์—์ด์ „ํŠธ ์ปจํ…์ŠคํŠธ ์ดˆ๊ธฐํ™” | +| `SubagentStop` | ์„œ๋ธŒ์—์ด์ „ํŠธ ์ข…๋ฃŒ | ์„œ๋ธŒ์—์ด์ „ํŠธ ์ž‘์—… ์™„๋ฃŒ | ํ›„์† ์ž‘์—… ์‹คํ–‰ | +| `Stop` | Claude ์‘๋‹ต ์™„๋ฃŒ | ์‘๋‹ต ์ข…๋ฃŒ | ์ •๋ฆฌ ์ž‘์—…, ๋ณด๊ณ  | +| `StopFailure` | API ์˜ค๋ฅ˜๋กœ ํ„ด ์ข…๋ฃŒ | API ์˜ค๋ฅ˜ ๋ฐœ์ƒ | ์˜ค๋ฅ˜ ๋ณต๊ตฌ, ๋กœ๊น… | +| `TeammateIdle` | ํŒ€์› ์—์ด์ „ํŠธ ๋Œ€๊ธฐ ์ƒํƒœ | ์—์ด์ „ํŠธ ํŒ€ ํ˜‘์—… ์ค‘ | ์ž‘์—… ๋ถ„๋ฐฐ | +| `TaskCompleted` | ์ž‘์—… ์™„๋ฃŒ ํ‘œ์‹œ | ์ž‘์—… ์™„๋ฃŒ ์‹œ | ์ž‘์—… ํ›„ ์ฒ˜๋ฆฌ | +| `TaskCreated` | TaskCreate๋ฅผ ํ†ตํ•ด ์ž‘์—… ์ƒ์„ฑ | ์ƒˆ ์ž‘์—… ์ƒ์„ฑ ์‹œ | ์ž‘์—… ์ถ”์ , ๋กœ๊น… | +| `ConfigChange` | ์„ค์ • ๋ณ€๊ฒฝ | ์„ค์ • ์ˆ˜์ • ์‹œ | ์„ค์ • ๋ณ€๊ฒฝ ๋Œ€์‘ | +| `CwdChanged` | ์ž‘์—… ๋””๋ ‰ํ„ฐ๋ฆฌ ๋ณ€๊ฒฝ | ๋””๋ ‰ํ„ฐ๋ฆฌ ๋ณ€๊ฒฝ ์‹œ | ๋””๋ ‰ํ„ฐ๋ฆฌ๋ณ„ ์ดˆ๊ธฐ ์„ค์ • | +| `FileChanged` | ๊ฐ์‹œ ์ค‘์ธ ํŒŒ์ผ ๋ณ€๊ฒฝ | ํŒŒ์ผ ์ˆ˜์ • ์‹œ | ํŒŒ์ผ ๋ชจ๋‹ˆํ„ฐ๋ง, ์žฌ๋นŒ๋“œ | +| `PreCompact` | Compact ์ž‘์—… ์ „ | ์ปจํ…์ŠคํŠธ ์••์ถ• ์ „ | ์ƒํƒœ ๋ณด์กด | +| `PostCompact` | Compact ์ž‘์—… ํ›„ | ์••์ถ• ์™„๋ฃŒ ํ›„ | ํ›„์ฒ˜๋ฆฌ ์ž‘์—… | +| `WorktreeCreate` | Worktree ์ƒ์„ฑ | Git Worktree ์ƒ์„ฑ ์‹œ | Worktree ํ™˜๊ฒฝ ์„ค์ • | +| `WorktreeRemove` | Worktree ์ œ๊ฑฐ | Git Worktree ์ œ๊ฑฐ ์‹œ | Worktree ๋ฆฌ์†Œ์Šค ์ •๋ฆฌ | +| `Elicitation` | MCP ์„œ๋ฒ„๊ฐ€ ์‚ฌ์šฉ์ž ์ž…๋ ฅ ์š”์ฒญ | MCP ์ž…๋ ฅ ์š”์ฒญ ์‹œ | ์ž…๋ ฅ ๊ฒ€์ฆ | +| `ElicitationResult` | ์‚ฌ์šฉ์ž๊ฐ€ ์ž…๋ ฅ ์š”์ฒญ์— ์‘๋‹ต | ์‚ฌ์šฉ์ž ์‘๋‹ต ์‹œ | ์‘๋‹ต ์ฒ˜๋ฆฌ | +| `SessionEnd` | ์„ธ์…˜ ์ข…๋ฃŒ | ์„ธ์…˜ ์ข…๋ฃŒ ์‹œ | ์ •๋ฆฌ ์ž‘์—…, ์ƒํƒœ ์ €์žฅ | + +### Hook ์˜ˆ์‹œ + +| Hook | Description | Event | Scope | Installation | +|------|-------------|-------|-------|--------------| +| `validate-bash.py` | ๋ช…๋ น ๊ฒ€์ฆ | PreToolUse:Bash | ํ”„๋กœ์ ํŠธ | `cp 06-hooks/validate-bash.py .claude/hooks/` | +| `security-scan.py` | ๋ณด์•ˆ ๊ฒ€์‚ฌ | PostToolUse:Write | ํ”„๋กœ์ ํŠธ | `cp 06-hooks/security-scan.py .claude/hooks/` | +| `format-code.sh` | ์ž๋™ ์ฝ”๋“œ ํฌ๋งทํŒ… | PostToolUse:Write | ์‚ฌ์šฉ์ž | `cp 06-hooks/format-code.sh ~/.claude/hooks/` | +| `validate-prompt.py` | ํ”„๋กฌํ”„ํŠธ ๊ฒ€์ฆ | UserPromptSubmit | ํ”„๋กœ์ ํŠธ | `cp 06-hooks/validate-prompt.py .claude/hooks/` | +| `context-tracker.py` | ํ† ํฐ ์‚ฌ์šฉ๋Ÿ‰ ์ถ”์  | Stop | ์‚ฌ์šฉ์ž | `cp 06-hooks/context-tracker.py ~/.claude/hooks/` | +| `pre-commit.sh` | ์ปค๋ฐ‹ ์ „ ๊ฒ€์ฆ | PreToolUse:Bash | ํ”„๋กœ์ ํŠธ | `cp 06-hooks/pre-commit.sh .claude/hooks/` | +| `log-bash.sh` | ๋ช…๋ น ์‹คํ–‰ ๋กœ๊ทธ ๊ธฐ๋ก | PostToolUse:Bash | ์‚ฌ์šฉ์ž | `cp 06-hooks/log-bash.sh ~/.claude/hooks/` | +| `dependency-check.sh` | ๋งค๋‹ˆํŽ˜์ŠคํŠธ ๋ณ€๊ฒฝ ์‹œ ์ทจ์•ฝ์  ๊ฒ€์‚ฌ | PostToolUse:Write | ํ”„๋กœ์ ํŠธ | `cp 06-hooks/dependency-check.sh .claude/hooks/` | + +> **Scope**: `Project` = ํŒ€(`.claude/settings.json`), `User` = ๊ฐœ์ธ(`~/.claude/settings.json`) + +### Hook Configuration + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "command": "~/.claude/hooks/validate-bash.py" + } + ], + "PostToolUse": [ + { + "matcher": "Write", + "command": "~/.claude/hooks/format-code.sh" + } + ] + } +} +``` + +**์ฐธ๊ณ  ์ž๋ฃŒ**: [06-hooks/](06-hooks/) | [Official Docs](https://code.claude.com/docs/en/hooks) + +**๋น ๋ฅธ ์„ค์น˜(๋ชจ๋“  Hook)**: +```bash +mkdir -p ~/.claude/hooks && cp 06-hooks/*.sh ~/.claude/hooks/ && chmod +x ~/.claude/hooks/*.sh +``` + +--- + +## Memory Files + +์„ธ์…˜ ๊ฐ„ ์ž๋™์œผ๋กœ ๋กœ๋“œ๋˜๋Š” ์˜๊ตฌ ์ปจํ…์ŠคํŠธ์ž…๋‹ˆ๋‹ค. + +### ๋ฉ”๋ชจ๋ฆฌ ์œ ํ˜• + +| Type | Location | Scope | When to Use | +|------|----------|-------|-------------| +| **Managed Policy** | ์กฐ์ง์—์„œ ๊ด€๋ฆฌํ•˜๋Š” ์ •์ฑ… | ์กฐ์ง | ์กฐ์ง ์ „์ฒด ํ‘œ์ค€ ์ ์šฉ | +| **Project** | `./CLAUDE.md` | ํ”„๋กœ์ ํŠธ(ํŒ€) | ํŒ€ ํ‘œ์ค€ ๋ฐ ํ”„๋กœ์ ํŠธ ์ปจํ…์ŠคํŠธ | +| **Project Rules** | `.claude/rules/` | ํ”„๋กœ์ ํŠธ(ํŒ€) | ๋ชจ๋“ˆํ˜• ํ”„๋กœ์ ํŠธ ๊ทœ์น™ | +| **User** | `~/.claude/CLAUDE.md` | ์‚ฌ์šฉ์ž(๊ฐœ์ธ) | ๊ฐœ์ธ ์„ค์ • ๋ฐ ์„ ํ˜ธ ์‚ฌํ•ญ | +| **User Rules** | `~/.claude/rules/` | ์‚ฌ์šฉ์ž(๊ฐœ์ธ) | ๋ชจ๋“ˆํ˜• ๊ฐœ์ธ ๊ทœ์น™ | +| **Local** | `./CLAUDE.local.md` | ๋กœ์ปฌ(git ์ œ์™ธ) | ๋จธ์‹ ๋ณ„ ๋กœ์ปฌ ์žฌ์ •์˜(git ์ถ”์  ์ œ์™ธ). ๊ฐœ๋ฐœ์ž๋ณ„ ์žฌ์ •์˜ ํŒŒ์ผ๋กœ https://code.claude.com/docs/en/memory ์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. | +| **Auto Memory** | ์ž๋™ | ์„ธ์…˜ | ์ธ์‚ฌ์ดํŠธ์™€ ์ˆ˜์ • ์‚ฌํ•ญ ์ž๋™ ์ €์žฅ | + +> **Scope**: `Organization` = ๊ด€๋ฆฌ์ž๊ฐ€ ๊ด€๋ฆฌ, `Project` = Git์„ ํ†ตํ•ด ํŒ€๊ณผ ๊ณต์œ , `User` = ๊ฐœ์ธ ์„ค์ •, `Local` = ์ปค๋ฐ‹๋˜์ง€ ์•Š์Œ, `Session` = ์ž๋™ ๊ด€๋ฆฌ + +**์ฐธ๊ณ  ์ž๋ฃŒ**: [02-memory/](02-memory/) | [Official Docs](https://code.claude.com/docs/en/memory) + +**๋น ๋ฅธ ์„ค์น˜**: +```bash +cp 02-memory/project-CLAUDE.md ./CLAUDE.md +cp 02-memory/personal-CLAUDE.md ~/.claude/CLAUDE.md +``` + +--- + +## New Features (May 2026) + +| Feature | Description | How to Use | +|---------|-------------|------------| +| **/focus** | ์ง‘์ค‘ ๋ชจ๋“œ๋ฅผ ์ „ํ™˜ํ•˜์—ฌ ๋ฐฉํ•ด ์š”์†Œ ์—†์ด ์ถœ๋ ฅ ํ‘œ์‹œ (v2.1.110) | ๊ธด ์ž‘์—… ์ค‘ ์‹œ๊ฐ์  ๋ฐฉํ•ด๋ฅผ ์ค„์ด๋ ค๋ฉด `/focus` ์‹คํ–‰ | +| **/proactive** | `/loop`์˜ ๋ณ„์นญ์œผ๋กœ ๋™์ผํ•œ ๋ฐ˜๋ณต ์ž‘์—… ๋™์ž‘ ์ œ๊ณต (v2.1.105) | `/loop` ๋Œ€์‹  `/proactive` ์‚ฌ์šฉ ๊ฐ€๋Šฅ | +| **/recap** | ๊ธฐ์กด ์„ธ์…˜์œผ๋กœ ๋Œ์•„์™”์„ ๋•Œ ์ž‘์—… ์š”์•ฝ ํ‘œ์‹œ (v2.1.108) | ์ž‘์—…์„ ์ค‘๋‹จํ•œ ๋’ค `/recap` ์‹คํ–‰ | +| **/tui** | ์ „์ฒด ํ™”๋ฉด TUI(Text User Interface) ๋ชจ๋“œ ์ „ํ™˜์œผ๋กœ ๊นœ๋นก์ž„ ์—†๋Š” ์ถœ๋ ฅ ์ œ๊ณต (v2.1.110) | ์ „์ฒด ํ™”๋ฉด ํ„ฐ๋ฏธ๋„ ๋˜๋Š” tmux์—์„œ `/tui` ์‚ฌ์šฉ | +| **/undo** | `/rewind`์˜ ๋ณ„์นญ์œผ๋กœ ์ด์ „ ์ฒดํฌํฌ์ธํŠธ๋กœ ๋˜๋Œ๋ฆผ (v2.1.108) | `/rewind` ๋Œ€์‹  `/undo` ์‚ฌ์šฉ ๊ฐ€๋Šฅ | +| **Monitor Tool** | ํด๋ง ๋Œ€์‹  ๋ฐฑ๊ทธ๋ผ์šด๋“œ ๋ช…๋ น์˜ stdout ์ŠคํŠธ๋ฆผ์„ ๊ฐ์‹œํ•˜๊ณ  ์ด๋ฒคํŠธ์— ๋ฐ˜์‘ | [Advanced Features](09-advanced-features/)์˜ Monitor Tool ์‚ฌ์šฉ | +| **/team-onboarding** | ํ”„๋กœ์ ํŠธ์˜ Claude Code ๊ตฌ์„ฑ์„ ๊ธฐ๋ฐ˜์œผ๋กœ ํŒ€์› ์˜จ๋ณด๋”ฉ ๊ฐ€์ด๋“œ ์ž๋™ ์ƒ์„ฑ (v2.1.101) | ํ”„๋กœ์ ํŠธ์—์„œ `/team-onboarding` ์‹คํ–‰ | +| **Ultraplan auto-create** | ์ตœ์ดˆ `/ultraplan` ์‹คํ–‰ ์‹œ ํด๋ผ์šฐ๋“œ ํ™˜๊ฒฝ ์ž๋™ ์ƒ์„ฑ(์ˆ˜๋™ ์„ค์ • ๋ถˆํ•„์š”) (v2.1.101) | `/ultraplan ` ์‚ฌ์šฉ | +| **Remote Control** | API๋ฅผ ํ†ตํ•ด Claude Code ์„ธ์…˜ ์›๊ฒฉ ์ œ์–ด | ์›๊ฒฉ ์ œ์–ด API๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ํ”„๋กฌํ”„ํŠธ ์ „์†ก ๋ฐ ์‘๋‹ต ์ˆ˜์‹  | +| **Web Sessions** | ๋ธŒ๋ผ์šฐ์ € ๊ธฐ๋ฐ˜ ํ™˜๊ฒฝ์—์„œ Claude Code ์‹คํ–‰ | `claude web` ๋˜๋Š” Anthropic Console ์‚ฌ์šฉ | +| **Desktop App** | Claude Code ๋„ค์ดํ‹ฐ๋ธŒ ๋ฐ์Šคํฌํ†ฑ ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜ | `/desktop` ์‚ฌ์šฉ ๋˜๋Š” Anthropic ์›น์‚ฌ์ดํŠธ์—์„œ ๋‹ค์šด๋กœ๋“œ | +| **Agent Teams** | ๊ด€๋ จ ์ž‘์—…์„ ์ˆ˜ํ–‰ํ•˜๋Š” ์—ฌ๋Ÿฌ ์—์ด์ „ํŠธ ํ˜‘์—… | ์ปจํ…์ŠคํŠธ๋ฅผ ๊ณต์œ ํ•˜๋Š” ํŒ€ ์—์ด์ „ํŠธ ๊ตฌ์„ฑ | +| **Task List** | ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž‘์—… ๊ด€๋ฆฌ ๋ฐ ๋ชจ๋‹ˆํ„ฐ๋ง | `/tasks`๋กœ ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž‘์—… ํ™•์ธ ๋ฐ ๊ด€๋ฆฌ | +| **Prompt Suggestions** | ์ปจํ…์ŠคํŠธ ๊ธฐ๋ฐ˜ ๋ช…๋ น์–ด ์ถ”์ฒœ | ํ˜„์žฌ ์ปจํ…์ŠคํŠธ์— ๋”ฐ๋ผ ์ž๋™ ํ‘œ์‹œ | +| **Git Worktrees** | ๋ณ‘๋ ฌ ๊ฐœ๋ฐœ์„ ์œ„ํ•œ ๋…๋ฆฝ๋œ Git Worktree | Worktree ๋ช…๋ น์œผ๋กœ ์•ˆ์ „ํ•œ ๋ณ‘๋ ฌ ๋ธŒ๋žœ์น˜ ์ž‘์—… ์ˆ˜ํ–‰ | +| **Sandboxing** | ์•ˆ์ „ํ•œ ์‹คํ–‰์„ ์œ„ํ•œ ๊ฒฉ๋ฆฌ ํ™˜๊ฒฝ | `/sandbox`๋กœ ์ „ํ™˜ํ•˜์—ฌ ์ œํ•œ๋œ ํ™˜๊ฒฝ์—์„œ ์‹คํ–‰ | +| **MCP OAuth** | MCP ์„œ๋ฒ„์šฉ OAuth ์ธ์ฆ | MCP ์„œ๋ฒ„ ์„ค์ •์—์„œ OAuth ์ž๊ฒฉ ์ฆ๋ช… ๊ตฌ์„ฑ | +| **MCP Tool Search** | MCP ๋„๊ตฌ ๊ฒ€์ƒ‰ ๋ฐ ํƒ์ƒ‰ | ์—ฐ๊ฒฐ๋œ ์„œ๋ฒ„์—์„œ ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ MCP ๋„๊ตฌ ๊ฒ€์ƒ‰ | +| **Scheduled Tasks** | `/loop` ๋ฐ cron ๋„๊ตฌ๋ฅผ ์ด์šฉํ•œ ๋ฐ˜๋ณต ์ž‘์—… ์˜ˆ์•ฝ | `/loop 5m /command` ๋˜๋Š” CronCreate ๋„๊ตฌ ์‚ฌ์šฉ | +| **Chrome Integration** | Headless Chromium์„ ์ด์šฉํ•œ ๋ธŒ๋ผ์šฐ์ € ์ž๋™ํ™” | `--chrome` ํ”Œ๋ž˜๊ทธ ๋˜๋Š” `/chrome` ์‚ฌ์šฉ | +| **Keyboard Customization** | ์กฐํ•ฉ ํ‚ค๋ฅผ ํฌํ•จํ•œ ํ‚ค ๋ฐ”์ธ๋”ฉ ์‚ฌ์šฉ์ž ์ง€์ • | `/keybindings` ๋˜๋Š” `~/.claude/keybindings.json` ์ˆ˜์ • | +| **Auto Mode** | ๊ถŒํ•œ ์š”์ฒญ ์—†์ด ์™„์ „ ์ž๋™ ์‹คํ–‰(Research Preview) | `--mode auto` ๋˜๋Š” `/permissions auto` ์‚ฌ์šฉ (2026๋…„ 3์›”) | +| **Channels** | ๋‹ค์ค‘ ์ฑ„๋„ ํ†ต์‹ (Telegram, Slack ๋“ฑ) (Research Preview) | ์ฑ„๋„ ํ”Œ๋Ÿฌ๊ทธ์ธ ๊ตฌ์„ฑ (2026๋…„ 3์›”) | +| **Voice Dictation** | ํ”„๋กฌํ”„ํŠธ ์Œ์„ฑ ์ž…๋ ฅ | ๋งˆ์ดํฌ ์•„์ด์ฝ˜ ๋˜๋Š” ์Œ์„ฑ ๋‹จ์ถ•ํ‚ค ์‚ฌ์šฉ | +| **Agent Hook Type** | ์…ธ ๋ช…๋ น ๋Œ€์‹  ์„œ๋ธŒ์—์ด์ „ํŠธ๋ฅผ ์‹คํ–‰ํ•˜๋Š” Hook | Hook ์„ค์ •์—์„œ `"type": "agent"` ์ง€์ • | +| **Prompt Hook Type** | ๋Œ€ํ™”์— ํ”„๋กฌํ”„ํŠธ๋ฅผ ์‚ฝ์ž…ํ•˜๋Š” Hook | Hook ์„ค์ •์—์„œ `"type": "prompt"` ์ง€์ • | +| **MCP Elicitation** | ๋„๊ตฌ ์‹คํ–‰ ์ค‘ MCP ์„œ๋ฒ„๊ฐ€ ์‚ฌ์šฉ์ž ์ž…๋ ฅ ์š”์ฒญ ๊ฐ€๋Šฅ | `Elicitation` ๋ฐ `ElicitationResult` Hook ์ด๋ฒคํŠธ ์ฒ˜๋ฆฌ | +| **Plugin LSP Support** | ํ”Œ๋Ÿฌ๊ทธ์ธ์„ ํ†ตํ•œ Language Server Protocol ์—ฐ๋™ | `plugin.json`์—์„œ LSP ์„œ๋ฒ„ ๊ตฌ์„ฑ | +| **Managed Drop-ins** | ์กฐ์ง์—์„œ ๊ด€๋ฆฌํ•˜๋Š” Drop-in ๊ตฌ์„ฑ (v2.1.83) | ๊ด€๋ฆฌ ์ •์ฑ…์œผ๋กœ ์„ค์ •๋˜๋ฉฐ ๋ชจ๋“  ์‚ฌ์šฉ์ž์—๊ฒŒ ์ž๋™ ์ ์šฉ | +| **`claude plugin init`** | `.claude/skills`์— ์ƒˆ ํ”Œ๋Ÿฌ๊ทธ์ธ ๊ณจ๊ฒฉ ์ƒ์„ฑ. ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ์—†์ด ์ž๋™ ๋กœ๋“œ๋จ (v2.1.157) | `claude plugin init ` ์‹คํ–‰ | +| **Auto Mode on Bedrock/Vertex/Foundry** | Opus 4.7/4.8์šฉ Auto Mode๋ฅผ ์„œ๋“œํŒŒํ‹ฐ ์ œ๊ณต์ž์—์„œ๋„ ์‚ฌ์šฉ ๊ฐ€๋Šฅ(์„ ํƒ ๊ธฐ๋Šฅ) (v2.1.158) | `CLAUDE_CODE_ENABLE_AUTO_MODE=1` ์„ค์ • | + +--- + +## Quick Reference Matrix + +### ๊ธฐ๋Šฅ ์„ ํƒ ๊ฐ€์ด๋“œ + +| Need | Recommended Feature | Why | +|------|---------------------|-----| +| ๋น ๋ฅธ ๋‹จ์ถ• ์ž‘์—… | Slash Command | ์ˆ˜๋™ ์‹คํ–‰, ์ฆ‰์‹œ ๋™์ž‘ | +| ์ง€์†์ ์ธ ์ปจํ…์ŠคํŠธ | Memory | ์ž๋™ ๋กœ๋“œ | +| ๋ณต์žกํ•œ ์ž๋™ํ™” | Skill | ์ž๋™ ํ˜ธ์ถœ | +| ์ „๋ฌธ ์ž‘์—… | Subagent | ๋…๋ฆฝ๋œ ์ปจํ…์ŠคํŠธ | +| ์™ธ๋ถ€ ๋ฐ์ดํ„ฐ | MCP Server | ์‹ค์‹œ๊ฐ„ ์ ‘๊ทผ | +| ์ด๋ฒคํŠธ ์ž๋™ํ™” | Hook | ์ด๋ฒคํŠธ ๊ธฐ๋ฐ˜ ์‹คํ–‰ | +| ํ†ตํ•ฉ ์†”๋ฃจ์…˜ | Plugin | ์˜ฌ์ธ์› ๋ฒˆ๋“ค | + +### ์„ค์น˜ ์šฐ์„ ์ˆœ์œ„ + +| Priority | Feature | Command | +|----------|---------|---------| +| 1. ํ•„์ˆ˜ | Memory | `cp 02-memory/project-CLAUDE.md ./CLAUDE.md` | +| 2. ์ผ์ƒ ์‚ฌ์šฉ | Slash Commands | `cp 01-slash-commands/*.md .claude/commands/` | +| 3. ํ’ˆ์งˆ ํ–ฅ์ƒ | Subagents | `cp 04-subagents/*.md .claude/agents/` | +| 4. ์ž๋™ํ™” | Hooks | `cp 06-hooks/*.sh ~/.claude/hooks/ && chmod +x ~/.claude/hooks/*.sh` | +| 5. ์™ธ๋ถ€ ์—ฐ๋™ | MCP | `claude mcp add github -- npx -y @modelcontextprotocol/server-github` | +| 6. ๊ณ ๊ธ‰ ๊ธฐ๋Šฅ | Skills | `cp -r 03-skills/* ~/.claude/skills/` | +| 7. ํ†ตํ•ฉ ๊ธฐ๋Šฅ | Plugins | `/plugin install pr-review` | + +--- + +## Complete One-Command Installation + +์ด ์ €์žฅ์†Œ์˜ ๋ชจ๋“  ์˜ˆ์ œ๋ฅผ ํ•œ ๋ฒˆ์— ์„ค์น˜ํ•ฉ๋‹ˆ๋‹ค. + +```bash +# ๋””๋ ‰ํ„ฐ๋ฆฌ ์ƒ์„ฑ +mkdir -p .claude/{commands,agents,skills} ~/.claude/{hooks,skills} + +# ๋ชจ๋“  ๊ธฐ๋Šฅ ์„ค์น˜ +cp 01-slash-commands/*.md .claude/commands/ && \ +cp 02-memory/project-CLAUDE.md ./CLAUDE.md && \ +cp -r 03-skills/* ~/.claude/skills/ && \ +cp 04-subagents/*.md .claude/agents/ && \ +cp 06-hooks/*.sh ~/.claude/hooks/ && \ +chmod +x ~/.claude/hooks/*.sh +``` + +--- + +## Additional Resources + +- [Official Claude Code Documentation](https://code.claude.com/docs/en/overview) +- [MCP Protocol Specification](https://modelcontextprotocol.io) +- [Learning Roadmap](LEARNING-ROADMAP.md) +- [Main README](README.md) + +--- + +**Last Updated**: June 15, 2026 +**Claude Code Version**: 2.1.176 +**Sources**: +- https://code.claude.com/docs/en/overview +- https://code.claude.com/docs/en/commands +- https://code.claude.com/docs/en/hooks +- https://code.claude.com/docs/en/changelog#2-1-172 +- https://code.claude.com/docs/en/changelog#2-1-174 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.145 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.154 +- https://code.claude.com/docs/en/plugins +- https://code.claude.com/docs/en/cli-reference +**Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5 diff --git a/ko/CHANGELOG.md b/ko/CHANGELOG.md new file mode 100644 index 00000000..40e9f4d9 --- /dev/null +++ b/ko/CHANGELOG.md @@ -0,0 +1,466 @@ +# ๋ณ€๊ฒฝ ๋กœ๊ทธ + +## [v2.1.160] โ€” 2026-06-02 + +### Claude Code v2.1.160์™€ ๋™๊ธฐํ™” + +ํŠœํ† ๋ฆฌ์–ผ ๋ฒ”์œ„๊ฐ€ Claude Code v2.1.160 ๋ฆด๋ฆฌ์Šค๊นŒ์ง€ ํ™•์žฅ๋˜์—ˆ์Šต๋‹ˆ๋‹ค. ์ค‘๊ฐ„์— ์žˆ์—ˆ๋˜ v2.1.156 ๋™๊ธฐํ™”(Claude Opus 4.8, #129)๋Š” ๋ฌธ์„œ์—๋Š” ์ ์šฉ๋˜์—ˆ์œผ๋‚˜ ๋ณ„๋„๋กœ ๋ณ€๊ฒฝ ๋กœ๊ทธ์— ๊ธฐ๋ก๋˜์ง€ ์•Š์•˜์Šต๋‹ˆ๋‹ค. ์ด ํ•ญ๋ชฉ์€ ํ•ด๋‹น ์‹œ์ ๋ถ€ํ„ฐ v2.1.157โ€“v2.1.160 ์‚ฌ์ด์˜ ๋ณ€๊ฒฝ ์‚ฌํ•ญ์„ ๋‹ค๋ฃน๋‹ˆ๋‹ค. ์ด ๋ฒ”์œ„์—์„œ ์น˜๋ช…์ ์ธ ๋ณ€๊ฒฝ ์‚ฌํ•ญ์€ ์—†์—ˆ์œผ๋ฉฐ, ๋ช‡ ๊ฐ€์ง€ ์ƒˆ๋กœ์šด CLI/๊ธฐ๋Šฅ ํ‘œ๋ฉด ์ถ”๊ฐ€์™€ ์ •๊ธฐ์ ์ธ ํ‘ธํ„ฐ ์—…๋ฐ์ดํŠธ๊ฐ€ ์žˆ์—ˆ์Šต๋‹ˆ๋‹ค. ํƒ€์‚ฌ ๊ณต๊ธ‰์ž์˜ ์ž๋™ ๋ชจ๋“œ๋Š” ์ƒˆ๋กœ์šด ๊ธฐ๋ณธ ์„ค์ •์ด ์•„๋‹ˆ๋ผ **์„ ํƒ ์‚ฌํ•ญ**์ž…๋‹ˆ๋‹ค. + +### ์ถ”๊ฐ€๋จ + +- **`claude plugin init ` (v2.1.157)** โ€” `.claude/skills`์— ์ƒˆ ํ”Œ๋Ÿฌ๊ทธ์ธ์„ ์ง์ ‘ ์Šค์บํด๋”ฉํ•ฉ๋‹ˆ๋‹ค. ์—ฌ๊ธฐ์— ๋ฐฐ์น˜๋œ ํ”Œ๋Ÿฌ๊ทธ์ธ์€ ์ด์ œ ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ์—†์ด ์ž๋™์œผ๋กœ ๋กœ๋“œ๋ฉ๋‹ˆ๋‹ค. `10-cli/README.md`, `07-plugins/README.md`, `CATALOG.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- **Bedrock / Vertex / Foundry์˜ ์ž๋™ ๋ชจ๋“œ (v2.1.158)** โ€” Opus 4.7/4.8์šฉ ์„ธ ๊ฐ€์ง€ ํƒ€์‚ฌ ๊ณต๊ธ‰์ž์—์„œ ์ž๋™ ๋ชจ๋“œ๋ฅผ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์œผ๋ฉฐ, `CLAUDE_CODE_ENABLE_AUTO_MODE=1` ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋ฅผ ํ†ตํ•ด **์„ ํƒ ์‚ฌํ•ญ**์œผ๋กœ ํ™œ์„ฑํ™”ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. `09-advanced-features/README.md`, `10-cli/README.md`, `CATALOG.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- **์„ธ์…˜ ์ค‘ `EnterWorktree` ์ „ํ™˜ (v2.1.157)** โ€” `EnterWorktree` ๋„๊ตฌ๋ฅผ ํ†ตํ•ด ์ด์ œ ์„ธ์…˜ ๋‚ด์—์„œ Claude๊ฐ€ ๊ด€๋ฆฌํ•˜๋Š” ์ž‘์—… ํŠธ๋ฆฌ ๊ฐ„์— ์ „ํ™˜ํ•  ์ˆ˜ ์žˆ์œผ๋ฉฐ, ์™„๋ฃŒ๋œ ์ž‘์—… ํŠธ๋ฆฌ๋Š” ์ž ๊ธˆ ํ•ด์ œ ์ƒํƒœ๋กœ ์œ ์ง€๋˜์–ด `git worktree remove`/`prune` ๋ช…๋ น์œผ๋กœ ์ •๋ฆฌํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. `09-advanced-features/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. + +### ๋™์ž‘ ๋ณ€๊ฒฝ + +- **`acceptEdits` ์“ฐ๊ธฐ ์•ˆ์ „ ํ”„๋กฌํ”„ํŠธ (v2.1.160)** โ€” `acceptEdits` ๋ชจ๋“œ์—์„œ๋„ Claude Code๋Š” ์ด์ œ ์…ธ ์‹œ์ž‘ ํŒŒ์ผ(`.zshenv`, `.zlogin`, `.bash_login`, `~/.config/git/`) ๋ฐ ์ฝ”๋“œ ์‹คํ–‰ ๋นŒ๋“œ ๊ตฌ์„ฑ ํŒŒ์ผ(`.npmrc`, `.yarnrc*`, `bunfig.toml`, `.bazelrc`, `.pre-commit-config.yaml`, `.devcontainer/`)์— ์“ฐ๊ธฐ ์ „์— ํ”„๋กฌํ”„ํŠธ๋ฅผ ํ‘œ์‹œํ•ฉ๋‹ˆ๋‹ค. ์ด๋Š” ์˜๋„์น˜ ์•Š์€ ๋ช…๋ น ์‹คํ–‰์œผ๋กœ ์ด์–ด์งˆ ์ˆ˜ ์žˆ๊ธฐ ๋•Œ๋ฌธ์ž…๋‹ˆ๋‹ค. `09-advanced-features/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- **๋™์  ์›Œํฌํ”Œ๋กœ์šฐ ํŠธ๋ฆฌ๊ฑฐ ํ‚ค์›Œ๋“œ `workflow` โ†’ `ultracode` (v2.1.160)** โ€” "workflow" ๋‹จ๋…์œผ๋กœ๋Š” ๋” ์ด์ƒ ๋™์  ์›Œํฌํ”Œ๋กœ์šฐ๋ฅผ ์‹คํ–‰ํ•˜์ง€ ์•Š์œผ๋ฉฐ, ํŠธ๋ฆฌ๊ฑฐ ํ‚ค์›Œ๋“œ๋Š” ์ด์ œ `ultracode`์ž…๋‹ˆ๋‹ค. `09-advanced-features/README.md`์— ๋ช…์‹œ๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. + +### ์ œ๊ฑฐ๋จ + +- **`CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE`๊ฐ€ ์ด์ œ ์•„๋ฌด๋Ÿฐ ๋™์ž‘๋„ ํ•˜์ง€ ์•Š์Œ (v2.1.160)** โ€” ํ•ด๋‹น ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋Š” ์ œ๊ฑฐ๋˜์—ˆ์œผ๋ฉฐ ์ด์ œ ์•„๋ฌด๋Ÿฐ ํšจ๊ณผ๊ฐ€ ์—†์Šต๋‹ˆ๋‹ค. `10-cli/README.md`์˜ ํ™˜๊ฒฝ ๋ณ€์ˆ˜ ํ‘œ ์„ค๋ช…์€ "2026-06-01 ์ œ๊ฑฐ๋จ"์—์„œ "์ œ๊ฑฐ๋จ (v2.1.160๋ถ€ํ„ฐ ์•„๋ฌด๋Ÿฐ ๋™์ž‘๋„ ํ•˜์ง€ ์•Š์Œ)"์œผ๋กœ ์—…๋ฐ์ดํŠธ๋˜์—ˆ์Šต๋‹ˆ๋‹ค. + +### ๋ฌธ์„œ + +- `README.md` ๋‚ด๋ถ€์— ์ผ๊ด€์„ฑ์ด ์—†์—ˆ๋˜ ์„ธ ๊ฐ€์ง€ ๋ฒ„์ „ ๋ฌธ์ž์—ด(๋ฐฐ์ง€ ๋ฐ FAQ ๋ณธ๋ฌธ์ด `2.1.145` / `v2.1.150`์— ๋จธ๋ฌผ๋Ÿฌ ์žˆ์—ˆ์Œ)์„ ์ˆ˜์ •ํ•˜๊ณ  ์˜ค๋ž˜๋œ ์†Œ์Šค ๋งํฌ๋ฅผ ์ •๊ทœํ™”ํ–ˆ์Šต๋‹ˆ๋‹ค. +- ์ผ๊ด€๋œ ๋™๊ธฐํ™”๋ฅผ ์œ„ํ•ด ๋ชจ๋“  ์˜์–ด ๋ฌธ์„œ์˜ ๋ฉ”ํƒ€๋ฐ์ดํ„ฐ ํ‘ธํ„ฐ๊ฐ€ **v2.1.160 / 2026๋…„ 6์›” 2์ผ**๋กœ ์—…๋ฐ์ดํŠธ๋˜์—ˆ์Šต๋‹ˆ๋‹ค. + +## [v2.1.150] โ€” 2026-05-25 + +### Claude Code v2.1.150์™€ ๋™๊ธฐํ™” + +ํŠœํ† ๋ฆฌ์–ผ ๋ฒ”์œ„๊ฐ€ Claude Code v2.1.145 โ†’ v2.1.150 (2026๋…„ 5์›” 23์ผ ๋ฆด๋ฆฌ์Šค)๋กœ ํ™•์žฅ๋˜์—ˆ์Šต๋‹ˆ๋‹ค. ๋งˆ์ง€๋ง‰ ๋™๊ธฐํ™” ์ดํ›„ Anthropic์€ 5๊ฐœ์˜ ํŒจ์น˜(v2.1.146๋ถ€ํ„ฐ v2.1.150๊นŒ์ง€)๋ฅผ ์ œ๊ณตํ–ˆ์Šต๋‹ˆ๋‹ค. ์ฃผ์š” ๋ณ€๊ฒฝ ์‚ฌํ•ญ์€ **๋ฒˆ๋“ค๋œ `/simplify` ์Šคํ‚ฌ์ด `/code-review`๋กœ ์ด๋ฆ„ ๋ณ€๊ฒฝ** (v2.1.146)๋œ ๊ฒƒ์ž…๋‹ˆ๋‹ค. ์ด๋Š” **๋ณ„์นญ ์—†์ด** ์ˆœ์ˆ˜ํ•˜๊ฒŒ ์ด๋ฆ„๋งŒ ๋ณ€๊ฒฝ๋˜์—ˆ์œผ๋ฏ€๋กœ ์ด์ „ ์ด๋ฆ„์€ ๋” ์ด์ƒ ์ž‘๋™ํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ์ด ๋ฆฌํฌ์ง€ํ† ๋ฆฌ์—๋Š” ์ž์ฒด ๋กœ์ปฌ ์ฝ”๋“œ ๊ฒ€ํ†  ์Šคํ‚ฌ๋„ ํฌํ•จ๋˜์–ด ์žˆ์œผ๋ฏ€๋กœ, ์ƒˆ๋กœ์šด ๋‚ด์žฅ ์Šคํ‚ฌ์„ ๊ฐ€๋ฆฌ์ง€ ์•Š๋„๋ก ๋””๋ ‰ํ† ๋ฆฌ ์ด๋ฆ„์ด `code-review-specialist`๋กœ ๋ณ€๊ฒฝ๋˜์—ˆ์Šต๋‹ˆ๋‹ค. ๊ธฐํƒ€ ์ฃผ์š” ๋ณ€๊ฒฝ ์‚ฌํ•ญ์œผ๋กœ๋Š” `/usage`๊ฐ€ ์ด์ œ ๋ฒ”์ฃผ๋ณ„๋กœ ๋น„์šฉ์„ ๋ถ„๋ฅ˜ํ•˜๊ณ , ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์„ธ์…˜์„ `Ctrl+T`๋กœ ๊ณ ์ •ํ•  ์ˆ˜ ์žˆ์œผ๋ฉฐ, ๋งˆํฌ๋‹ค์šด ๋ Œ๋”๋Ÿฌ๊ฐ€ GFM ์ž‘์—… ๋ชฉ๋ก ํ™•์ธ๋ž€์„ ์ง€์›ํ•˜๊ณ , ์ƒˆ๋กœ์šด `allowAllClaudeAiMcps` ๊ด€๋ฆฌ ์„ค์ •์ด ์ถ”๊ฐ€๋˜์—ˆ์Šต๋‹ˆ๋‹ค. ์ด ๋™๊ธฐํ™”๋Š” ๋˜ํ•œ v2.1.143์— ๊ณ ์ •๋˜์–ด ์žˆ๋˜ 4๊ฐœ์˜ ๋ชจ๋“ˆ README(`04-subagents`, `05-mcp`, `07-plugins`, `09-advanced-features`)๋ฅผ ์—…๋ฐ์ดํŠธํ–ˆ์Šต๋‹ˆ๋‹ค. + +### ๋™์ž‘ ๋ณ€๊ฒฝ + +- **`/simplify`๊ฐ€ `/code-review`๋กœ ์ด๋ฆ„ ๋ณ€๊ฒฝ๋จ (v2.1.146)**: ๋ฒˆ๋“ค๋œ ๊ฒ€ํ†  ์Šคํ‚ฌ์€ ์ด์ œ `/code-review`๋กœ ํ˜ธ์ถœ๋˜๋ฉฐ ์„ ํƒ์  ๋…ธ๋ ฅ ์ˆ˜์ค€(์˜ˆ: `/code-review high`)์„ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. `--comment`๋ฅผ ์ „๋‹ฌํ•˜์—ฌ GitHub PR ์ธ๋ผ์ธ ๋Œ“๊ธ€๋กœ ๋ฐœ๊ฒฌ ์‚ฌํ•ญ์„ ๊ฒŒ์‹œํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค(v2.1.147). ์ด์ „ `/simplify` ์ด๋ฆ„์€ ๋” ์ด์ƒ ์ž‘๋™ํ•˜์ง€ ์•Š์œผ๋ฉฐ, ๋ณ„์นญ๋„ ์—†์Šต๋‹ˆ๋‹ค. `01-slash-commands/README.md`, `03-skills/README.md`, `CATALOG.md`, `QUICK_REFERENCE.md`, `claude_concepts_guide.md`์— ์—…๋ฐ์ดํŠธ๋˜์—ˆ์Šต๋‹ˆ๋‹ค. + +### ๋ณ€๊ฒฝ๋จ + +- **๋ฆฌํฌ์ง€ํ† ๋ฆฌ์˜ ๋กœ์ปฌ `code-review` ์Šคํ‚ฌ์„ `code-review-specialist`๋กœ ์ด๋ฆ„ ๋ณ€๊ฒฝ**ํ•˜์—ฌ ์ƒˆ๋กœ์šด ๋‚ด์žฅ `/code-review`์™€ ์ถฉ๋Œ์„ ํ”ผํ–ˆ์Šต๋‹ˆ๋‹ค. ๋””๋ ‰ํ† ๋ฆฌ `03-skills/code-review/` โ†’ `03-skills/code-review-specialist/`๋กœ ๋ณ€๊ฒฝ๋˜์—ˆ์œผ๋ฉฐ, ๋ชจ๋“  ์„ค์น˜ ๋ช…๋ น, ๋””๋ ‰ํ† ๋ฆฌ ํŠธ๋ฆฌ ๋ฐ ์ƒํ˜ธ ์ฐธ์กฐ๊ฐ€ `README.md`, `QUICK_REFERENCE.md`, `INDEX.md`, `CATALOG.md`, `LEARNING-ROADMAP.md`, `claude_concepts_guide.md`, `03-skills/README.md`์— ์—…๋ฐ์ดํŠธ๋˜์—ˆ์Šต๋‹ˆ๋‹ค. ์ถฉ๋Œ๊ณผ ๋‚ด์žฅ ์Šคํ‚ฌ์„ ๊ฐ€๋ฆฌ์ง€ ์•Š๋Š” ๋ฐฉ๋ฒ•์— ๋Œ€ํ•œ ์„ค๋ช…๋„ ์ถ”๊ฐ€๋˜์—ˆ์Šต๋‹ˆ๋‹ค. + +### ์ถ”๊ฐ€๋จ + +- **`/usage` ๋ฒ”์ฃผ๋ณ„ ๋น„์šฉ ๋ถ„์„ (v2.1.149)** โ€” ์ด์ œ ๋น„์šฉ ๋ณด๊ธฐ์— ์ง€์ถœ์ด ๋ฒ”์ฃผ๋ณ„(์Šคํ‚ฌ, ์„œ๋ธŒ ์—์ด์ „ํŠธ, ํ”Œ๋Ÿฌ๊ทธ์ธ, MCP ์„œ๋ฒ„๋ณ„ ๋น„์šฉ)๋กœ ๋ถ„๋ฅ˜๋˜์–ด ํ‘œ์‹œ๋ฉ๋‹ˆ๋‹ค. `CATALOG.md` ๋ฐ `claude_concepts_guide.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- **๊ณ ์ •๋œ ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์„ธ์…˜ โ€” `Ctrl+T` (v2.1.147)** โ€” `claude agents`์—์„œ ์„ธ์…˜์„ ๊ณ ์ •ํ•˜๋ฉด ์œ ํœด ์ƒํƒœ์ผ ๋•Œ ์„ธ์…˜์„ ํ™œ์„ฑ ์ƒํƒœ๋กœ ์œ ์ง€ํ•˜๊ณ , Claude Code ์—…๋ฐ์ดํŠธ๋ฅผ ์ ์šฉํ•˜๊ธฐ ์œ„ํ•ด ์ œ์ž๋ฆฌ์—์„œ ๋‹ค์‹œ ์‹œ์ž‘ํ•˜๋ฉฐ, ๋ฉ”๋ชจ๋ฆฌ ์••๋ฐ• ์‹œ ๊ณ ์ •๋˜์ง€ ์•Š์€ ์„ธ์…˜ ์ดํ›„์—๋งŒ ์ข…๋ฃŒ๋ฉ๋‹ˆ๋‹ค. `10-cli/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- **GFM ์ž‘์—… ๋ชฉ๋ก ํ™•์ธ๋ž€ ๋ Œ๋”๋ง (v2.1.149)** โ€” ๋งˆํฌ๋‹ค์šด ๋ Œ๋”๋Ÿฌ๊ฐ€ ์ด์ œ `- [ ]` / `- [x]`๋ฅผ ํ™•์ธ๋ž€์œผ๋กœ ๋ Œ๋”๋งํ•ฉ๋‹ˆ๋‹ค. `09-advanced-features/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- **`allowAllClaudeAiMcps` ๊ด€๋ฆฌ ์„ค์ • (v2.1.149)** โ€” claude.ai ํด๋ผ์šฐ๋“œ MCP ์ปค๋„ฅํ„ฐ๋ฅผ ์กฐ์ง ์ „์ฒด์—์„œ ๋กœ๋“œํ•  ์ˆ˜ ์žˆ๋„๋ก ํ—ˆ์šฉํ•ฉ๋‹ˆ๋‹ค. `05-mcp/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. + +### ์ œ๊ฑฐ๋จ + +- **Stop/SubagentStop ํ›… ์ž…๋ ฅ ํ•„๋“œ `background_tasks` ๋ฐ `session_crons`** โ€” `06-hooks/README.md` ๋ฐ `resources.md`์—์„œ ์ œ๊ฑฐ๋˜์—ˆ์Šต๋‹ˆ๋‹ค. ์ด๋“ค์€ v2.1.145 ๋ฆด๋ฆฌ์Šค ๋…ธํŠธ์—์„œ ์ถ”๊ฐ€๋˜์—ˆ์ง€๋งŒ ๊ณต์‹ ํ›… ์ฐธ์กฐ ํŽ˜์ด์ง€์—๋Š” ์—ด๊ฑฐ๋˜์–ด ์žˆ์ง€ ์•Š์•„ ๊ฒŒ์‹œ๋œ ์ฐธ์กฐ์™€ ๋ฌธ์„œ์˜ ์ผ๊ด€์„ฑ์„ ์œ ์ง€ํ•˜๊ธฐ ์œ„ํ•ด ์ œ๊ฑฐ๋˜์—ˆ์Šต๋‹ˆ๋‹ค. + +### ๋ฌธ์„œ + +- v2.1.143์—์„œ v2.1.150์œผ๋กœ 4๊ฐœ์˜ ๋ชจ๋“ˆ README๋ฅผ ์—…๋ฐ์ดํŠธํ–ˆ์Šต๋‹ˆ๋‹ค: `04-subagents/README.md`, `05-mcp/README.md`, `07-plugins/README.md`, `09-advanced-features/README.md`. +- ์ผ๊ด€๋œ ๋™๊ธฐํ™”๋ฅผ ์œ„ํ•ด ๋ชจ๋“  ์˜์–ด ๋ฌธ์„œ์˜ ๋ฉ”ํƒ€๋ฐ์ดํ„ฐ ํ‘ธํ„ฐ๊ฐ€ **v2.1.150 / 2026๋…„ 5์›” 25์ผ**๋กœ ์—…๋ฐ์ดํŠธ๋˜์—ˆ์Šต๋‹ˆ๋‹ค. + +## [v2.1.145] โ€” 2026-05-20 + +### Claude Code v2.1.145์™€ ๋™๊ธฐํ™” + +ํŠœํ† ๋ฆฌ์–ผ ๋ฒ”์œ„๊ฐ€ Claude Code v2.1.143 โ†’ v2.1.145 (2026๋…„ 5์›” 19์ผ ๋ฆด๋ฆฌ์Šค)๋กœ ํ™•์žฅ๋˜์—ˆ์Šต๋‹ˆ๋‹ค. ๋งˆ์ง€๋ง‰ ๋™๊ธฐํ™” ์ดํ›„ Anthropic์€ ๋‘ ๊ฐœ์˜ ํŒจ์น˜(v2.1.144 ๋ฐ v2.1.145)๋ฅผ ์ œ๊ณตํ–ˆ์Šต๋‹ˆ๋‹ค. ์ฃผ์š” ๋ณ€๊ฒฝ ์‚ฌํ•ญ: `/extra-usage`๊ฐ€ `/usage-credits`๋กœ ์ด๋ฆ„ ๋ณ€๊ฒฝ, `/model`์ด ๊ธฐ๋ณธ์ ์œผ๋กœ ์„ธ์…˜ ์ „์šฉ์œผ๋กœ ๋ณ€๊ฒฝ, ์„ธ ๊ฐ€์ง€ ์ƒˆ๋กœ์šด ๋ฒˆ๋“ค ์Šคํ‚ฌ(`/run`, `/verify`, `/run-skill-generator`) ์ถ”๊ฐ€, Stop/SubagentStop ํ›… ์ž…๋ ฅ ํ•„๋“œ `background_tasks` ๋ฐ `session_crons` ์ถ”๊ฐ€, ์Šคํฌ๋ฆฝํŒ…์„ ์œ„ํ•œ `claude agents --json` ์ถ”๊ฐ€, ๊ทธ๋ฆฌ๊ณ  ๋ฒ ์–ด ํ™˜๊ฒฝ ๋ณ€์ˆ˜ Bash ์ž๋™ ์Šน์ธ ์ทจ์•ฝ์ ์„ ํ•ด๊ฒฐํ•˜๋Š” ๋ณด์•ˆ ์ˆ˜์ •์ด ์žˆ์—ˆ์Šต๋‹ˆ๋‹ค. ์ด ๋™๊ธฐํ™”๋Š” ๋˜ํ•œ v2.1.143 ๋™๊ธฐํ™”์—์„œ ๋ˆ„๋ฝ๋˜์–ด ์—ฌ์ „ํžˆ v2.1.138์— ๊ณ ์ •๋˜์–ด ์žˆ๋˜ 6๊ฐœ์˜ ์ตœ์ƒ์œ„ ์ฐธ์กฐ ๋ฌธ์„œ(`LEARNING-ROADMAP.md`, `QUICK_REFERENCE.md`, `INDEX.md`, `resources.md`, `claude_concepts_guide.md`, `STYLE_GUIDE.md`)๋ฅผ ์—…๋ฐ์ดํŠธํ–ˆ์Šต๋‹ˆ๋‹ค. + +### ์ถ”๊ฐ€๋จ + +- `/usage-credits` ์Šฌ๋ž˜์‹œ ๋ช…๋ น (v2.1.144) โ€” `/extra-usage`๋ฅผ ๋Œ€์ฒดํ•˜๋Š” ๊ธฐ๋ณธ ์ด๋ฆ„์ž…๋‹ˆ๋‹ค. `/extra-usage`๋Š” ์—ฌ์ „ํžˆ ๋ณ„์นญ์œผ๋กœ ์ž‘๋™ํ•ฉ๋‹ˆ๋‹ค. `01-slash-commands/README.md` ๋ฐ `CATALOG.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- ์„ธ ๊ฐ€์ง€ ์ƒˆ๋กœ์šด ๋ฒˆ๋“ค ์Šคํ‚ฌ (v2.1.145) โ€” `/run` (๋ณ€๊ฒฝ ์‚ฌํ•ญ์ด ์‹คํ–‰๋˜๋Š” ๊ฒƒ์„ ํ™•์ธํ•˜๊ธฐ ์œ„ํ•ด ํ”„๋กœ์ ํŠธ ์•ฑ์„ ์‹œ์ž‘ํ•จ), `/verify` (์ˆ˜์ • ์‚ฌํ•ญ์ด ์ž‘๋™ํ•˜๋Š”์ง€ ํ™•์ธํ•˜๊ธฐ ์œ„ํ•ด ์•ฑ์„ ๋นŒ๋“œ, ์‹คํ–‰ ๋ฐ ๊ด€์ฐฐํ•จ), `/run-skill-generator` (ํ”„๋กœ์ ํŠธ๋ณ„ ์Šคํ‚ฌ์„ ์ƒ์„ฑํ•˜์—ฌ `/run`/`/verify`๊ฐ€ ํŠน์ • ํ”„๋กœ์ ํŠธ๋ฅผ ์ฒ˜๋ฆฌํ•˜๋Š” ๋ฐฉ๋ฒ•์„ ๊ฐ€๋ฅด์นจ). `03-skills/README.md`, `CATALOG.md`, `QUICK_REFERENCE.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. ๋ฒˆ๋“ค ์Šคํ‚ฌ์˜ ํ‘œ์ค€ ๊ฐœ์ˆ˜๋ฅผ **9๊ฐœ**๋กœ ๋Š˜๋ฆฝ๋‹ˆ๋‹ค. +- Stop/SubagentStop ํ›… ์ž…๋ ฅ ํ•„๋“œ `background_tasks` ๋ฐ `session_crons` (v2.1.145) โ€” ํ›… ์ž‘์„ฑ์ž๋Š” ์ด๋ฅผ ์ฝ์–ด ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž‘์—…์ด๋‚˜ ์˜ˆ์•ฝ๋œ ์ž‘์—…์ด ์•„์ง ๋ณด๋ฅ˜ ์ค‘์ธ ๋™์•ˆ ์ค‘์ง€๋ฅผ ์ฐจ๋‹จํ• ์ง€ ๊ฒฐ์ •ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. `06-hooks/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `claude agents --json` (v2.1.145) โ€” ์Šคํฌ๋ฆฝํŒ…(์ƒํƒœ ํ‘œ์‹œ์ค„, ์„ธ์…˜ ์„ ํƒ๊ธฐ, tmux-resurrect)์„ ์œ„ํ•ด ์—์ด์ „ํŠธ ๋ชฉ๋ก์„ ๊ธฐ๊ณ„๊ฐ€ ์ฝ์„ ์ˆ˜ ์žˆ๋Š” JSON ํ˜•์‹์œผ๋กœ ์ถœ๋ ฅํ•ฉ๋‹ˆ๋‹ค. `10-cli/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- ์š”์•ฝ ํ‘œ์—์„œ ๋ˆ„๋ฝ๋˜์—ˆ๋˜ 5๊ฐœ์˜ ํ›… ์ด๋ฒคํŠธ ํ–‰ โ€” `Setup`, `UserPromptExpansion`, `PermissionDenied`, `PostToolBatch` (์„ค๋ช…์—์„œ๋Š” ์ด๋ฏธ "29๊ฐœ ์ด๋ฒคํŠธ"๋ผ๊ณ  ์ฃผ์žฅํ–ˆ์ง€๋งŒ, `CATALOG.md`, `claude_concepts_guide.md`, `INDEX.md`์˜ ์š”์•ฝ ํ‘œ์—๋Š” 25๊ฐœ๋งŒ ๋‚˜์—ด๋˜์–ด ์žˆ์—ˆ์Šต๋‹ˆ๋‹ค). + +### ๋™์ž‘ ๋ณ€๊ฒฝ + +- **`/model`์ด ๊ธฐ๋ณธ์ ์œผ๋กœ ์„ธ์…˜ ์ „์šฉ์œผ๋กœ ๋ณ€๊ฒฝ๋จ (v2.1.144)**: ๋ชจ๋ธ ์„ ํƒ์€ ์ด์ œ ํ˜„์žฌ ์„ธ์…˜์—๋งŒ ์ ์šฉ๋ฉ๋‹ˆ๋‹ค. ์„ ํƒ ํ›„ `d`๋ฅผ ๋ˆŒ๋Ÿฌ ํ–ฅํ›„ ์„ธ์…˜์„ ์œ„ํ•œ ์ƒˆ๋กœ์šด ๊ธฐ๋ณธ๊ฐ’์œผ๋กœ ์„ค์ •ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. `01-slash-commands/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- **Bash ๋ฒ ์–ด env-var ์ž๋™ ์Šน์ธ ์ทจ์•ฝ์  ํ•ด๊ฒฐ (v2.1.145 ๋ณด์•ˆ ์ˆ˜์ •)**: `FOO=bar somecommand` ํ˜•์‹์˜ ๋ช…๋ น์€ `FOO=bar`๋งŒ ํ—ˆ์šฉ ๋ชฉ๋ก์— ์žˆ์—ˆ์„ ๋•Œ ๋” ์ด์ƒ ์ž๋™ ์Šน์ธ๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ์ „์ฒด ๋ช…๋ น์„ ํฌํ•จํ•˜๋Š” `Bash(...)` ๊ถŒํ•œ ๊ทœ์น™์„ ํ†ตํ•ด ํ•ด๋‹น ๋ช…๋ น์„ ๋ช…์‹œ์ ์œผ๋กœ ๋‹ค์‹œ ํ—ˆ์šฉํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. `06-hooks/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- **`context: fork` ๋ฌดํ•œ ๋ฃจํ”„ ์ˆ˜์ • (v2.1.145)**: `context: fork`๋ฅผ ์‚ฌ์šฉํ•˜๋Š” ์Šคํ‚ฌ์ด ์ด์ „์— ๋“œ๋ฌผ๊ฒŒ ๋ฌดํ•œ ์žฌํ˜ธ์ถœ ๋ฃจํ”„๋ฅผ ํŠธ๋ฆฌ๊ฑฐํ•  ์ˆ˜ ์žˆ์—ˆ์Šต๋‹ˆ๋‹ค. `03-skills/README.md`์— ์ฐธ๊ณ  ์‚ฌํ•ญ์œผ๋กœ ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. + +### ๋ฌธ์„œ + +- v2.1.138์—์„œ v2.1.145๋กœ 6๊ฐœ์˜ ์ตœ์ƒ์œ„ ์ฐธ์กฐ ๋ฌธ์„œ(`LEARNING-ROADMAP.md`, `QUICK_REFERENCE.md`, `INDEX.md`, `resources.md`, `claude_concepts_guide.md`, `STYLE_GUIDE.md`)๋ฅผ ์—…๋ฐ์ดํŠธํ–ˆ์Šต๋‹ˆ๋‹ค. +- ๋ฒˆ๋“ค ์Šคํ‚ฌ ๋ถˆ์ผ์น˜๋ฅผ ์ˆ˜์ •ํ–ˆ์Šต๋‹ˆ๋‹ค โ€” `CATALOG.md`, `QUICK_REFERENCE.md`, `03-skills/README.md`๋Š” ์ด์ „์— ์„ธ ๊ฐ€์ง€ ๋‹ค๋ฅธ 5๊ฐœ ํ•ญ๋ชฉ ๋ชฉ๋ก์„ ๋‚˜์—ดํ–ˆ์Šต๋‹ˆ๋‹ค. ์ด๋ฅผ ํ‘œ์ค€ 9๊ฐœ(`/batch`, `/claude-api`, `/debug`, `/fewer-permission-prompts`, `/loop`, `/run`, `/run-skill-generator`, `/simplify`, `/verify`)๋กœ ์กฐ์ •ํ–ˆ์Šต๋‹ˆ๋‹ค. `QUICK_REFERENCE.md` ์…€์—๋Š” `/voice`์™€ `/browse`๊ฐ€ ๋ฒˆ๋“ค ์Šคํ‚ฌ๋กœ ์ž˜๋ชป ๋‚˜์—ด๋˜์–ด ์žˆ์—ˆ๋Š”๋ฐ, ๋‘˜ ๋‹ค ๋ฒˆ๋“ค ์Šคํ‚ฌ์ด ์•„๋‹™๋‹ˆ๋‹ค. +- `QUICK_REFERENCE.md` ๋ฐ `resources.md`์—์„œ "New Features (March 2026)" โ†’ "New Features (May 2026)"๋กœ ์ด๋ฆ„์„ ๋ณ€๊ฒฝํ•˜์—ฌ ๋ฆฌํฌ์ง€ํ† ๋ฆฌ์˜ ๋‹ค๋ฅธ ๋ถ€๋ถ„๊ณผ ์ผ์น˜์‹œ์ผฐ์Šต๋‹ˆ๋‹ค. +- `README.md`์˜ ๋ฒ„์ „ ๋ฐฐ์ง€๋ฅผ `2.1.138`์—์„œ `2.1.145`๋กœ ์—…๋ฐ์ดํŠธํ•˜๊ณ  ๋ณธ๋ฌธ์˜ "latest: v2.1.138" ๋‘ ๊ฐ€์ง€ ์ฃผ์žฅ์„ ์—…๋ฐ์ดํŠธํ–ˆ์Šต๋‹ˆ๋‹ค. +- ๊ธฐ์—ฌ์ž๋“ค์ด ํ˜„์žฌ ๋ฒ„์ „์„ ๋ณต์‚ฌํ•˜๋„๋ก STYLE_GUIDE ์ƒ˜ํ”Œ ๋ฉ”ํƒ€๋ฐ์ดํ„ฐ ํ‘ธํ„ฐ๋ฅผ `2.1.97`์—์„œ `2.1.145`๋กœ ์—…๋ฐ์ดํŠธํ–ˆ์Šต๋‹ˆ๋‹ค. + +## [v2.1.143] โ€” 2026-05-19 + +### Claude Code v2.1.143์™€ ๋™๊ธฐํ™” + +ํŠœํ† ๋ฆฌ์–ผ ๋ฒ”์œ„๊ฐ€ Claude Code v2.1.138 โ†’ v2.1.143 (2026๋…„ 5์›” 15์ผ ๋ฆด๋ฆฌ์Šค)๋กœ ํ™•์žฅ๋˜์—ˆ์Šต๋‹ˆ๋‹ค. ๋งˆ์ง€๋ง‰ ๋™๊ธฐํ™” ์ดํ›„ Anthropic์€ 5๊ฐœ์˜ ํŒจ์น˜(v2.1.139โ€“v2.1.143)๋ฅผ ์ œ๊ณตํ–ˆ์Šต๋‹ˆ๋‹ค. ์ฃผ์š” ๋ณ€๊ฒฝ ์‚ฌํ•ญ: `/goal` ๋ฐ `/scroll-speed` ์Šฌ๋ž˜์‹œ ๋ช…๋ น, ์ „์ฒด ๋””์ŠคํŒจ์น˜ ํ”Œ๋ž˜๊ทธ ์„ธํŠธ๊ฐ€ ํฌํ•จ๋œ `claude agents` ์—์ด์ „ํŠธ ๋ทฐ(์—ฐ๊ตฌ ๋ฏธ๋ฆฌ๋ณด๊ธฐ), Stop ํ›… ์•ˆ์ „ ์ œํ•œ, ํ›… ์‹คํ–‰ ํ˜•์‹(`args`), PostToolUse์˜ `continueOnBlock`, ํ›… `terminalSequence` ์ถœ๋ ฅ, Opus 4.7์„ ๊ธฐ๋ณธ์œผ๋กœ ํ•˜๋Š” ๋น ๋ฅธ ๋ชจ๋“œ, Bedrock/Vertex/Foundry์šฉ Windows์—์„œ PowerShell ๊ธฐ๋ณธ ์„ค์ •, ๊ทธ๋ฆฌ๊ณ  `worktree.bgIsolation` ์„ค์ •์ด ์ถ”๊ฐ€๋˜์—ˆ์Šต๋‹ˆ๋‹ค. + +### ์ถ”๊ฐ€๋จ + +- `/goal ` ์Šฌ๋ž˜์‹œ ๋ช…๋ น (v2.1.139) โ€” ๊ฒฝ๊ณผ ์‹œ๊ฐ„, ํ„ด ์ˆ˜, ํ† ํฐ ์‚ฌ์šฉ๋Ÿ‰์„ ๋ณด์—ฌ์ฃผ๋Š” ์‹ค์‹œ๊ฐ„ ์˜ค๋ฒ„๋ ˆ์ด ํŒจ๋„๊ณผ ํ•จ๊ป˜ ์„ธ์…˜ ์ˆ˜์ค€ ์™„๋ฃŒ ์กฐ๊ฑด์„ ๋“ฑ๋กํ•ฉ๋‹ˆ๋‹ค. `01-slash-commands/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์œผ๋ฉฐ `10-cli/README.md`์—์„œ ์ƒํ˜ธ ์—ฐ๊ฒฐ๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `/scroll-speed <ยฑN>` ์Šฌ๋ž˜์‹œ ๋ช…๋ น (v2.1.139) โ€” TUI ์‹ค์‹œ๊ฐ„ ๋ฏธ๋ฆฌ๋ณด๊ธฐ ์Šคํฌ๋กค ์†๋„๋ฅผ ์กฐ์ •ํ•˜๋ฉฐ, ๋จธ์‹ ๋ณ„๋กœ ์œ ์ง€๋ฉ๋‹ˆ๋‹ค. `01-slash-commands/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `claude agents` ์—์ด์ „ํŠธ ๋ทฐ (์—ฐ๊ตฌ ๋ฏธ๋ฆฌ๋ณด๊ธฐ, v2.1.139)์™€ ๋””์ŠคํŒจ์น˜ ํ”Œ๋ž˜๊ทธ `--cwd` (v2.1.141), `--add-dir`, `--settings`, `--mcp-config`, `--plugin-dir`, `--permission-mode`, `--model`, `--effort`, `--dangerously-skip-permissions` (v2.1.142)๊ฐ€ ์ถ”๊ฐ€๋˜์—ˆ์Šต๋‹ˆ๋‹ค. `10-cli/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `claude plugin details ` (v2.1.139) โ€” ์ „์ฒด ํ”Œ๋Ÿฌ๊ทธ์ธ ๋ชฉ๋ก๊ณผ ํ„ด๋ณ„/ํ˜ธ์ถœ๋ณ„ ์˜ˆ์ƒ ํ† ํฐ ๋น„์šฉ ์ถ”์ •์น˜๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. v2.1.142์—์„œ๋Š” ์„ธ๋ถ€ ์ •๋ณด ์ฐฝ์— LSP ์„œ๋ฒ„๊ฐ€ ์ถ”๊ฐ€๋˜์—ˆ์Šต๋‹ˆ๋‹ค. `07-plugins/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `/plugin` ์ฐพ์•„๋ณด๊ธฐ ์ฐฝ์— ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ์ปจํ…์ŠคํŠธ ๋น„์šฉ ์˜ˆ์ƒ์น˜ (v2.1.143)๊ฐ€ ์ถ”๊ฐ€๋˜์—ˆ์Šต๋‹ˆ๋‹ค. `07-plugins/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- ํ›… **์‹คํ–‰ ํ˜•์‹** (`args: string[]`, v2.1.139) โ€” ์…ธ ํŒŒ์‹ฑ ์—†์ด ์ง์ ‘ `execve()`๋ฅผ ์ƒ์„ฑํ•˜๋ฉฐ, ์…ธ ํ˜•์‹ `command` ํ•„๋“œ์™€ ์ƒํ˜ธ ๋ฐฐํƒ€์ ์ž…๋‹ˆ๋‹ค. `06-hooks/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- PostToolUse์˜ ํ›… `continueOnBlock: true` ํ•„๋“œ (v2.1.139) โ€” ์ฐจ๋‹จ๋œ ๋„๊ตฌ ๊ฒฐ๊ณผ๋ฅผ ํ„ด์„ ์ค‘๋‹จํ•˜๋Š” ๋Œ€์‹  `tool_result`๋กœ Claude์— ๋‹ค์‹œ ์ „๋‹ฌํ•ฉ๋‹ˆ๋‹ค. `06-hooks/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- ํ›… `terminalSequence` JSON ์ถœ๋ ฅ ํ•„๋“œ (v2.1.141) โ€” ๋ฐ์Šคํฌํ†ฑ ์•Œ๋ฆผ, ์ฐฝ ์ œ๋ชฉ ๋ฐ ๋ฒจ์†Œ๋ฆฌ๋ฅผ ์œ„ํ•œ ์›์‹œ OSC ์ด์Šค์ผ€์ดํ”„ ์‹œํ€€์Šค๋ฅผ ๋ฐฉ์ถœํ•ฉ๋‹ˆ๋‹ค. `06-hooks/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `worktree.bgIsolation: "none"` ์„ค์ • (v2.1.143) โ€” ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์„ธ์…˜์€ ๊ฒฉ๋ฆฌ๋œ ์ž‘์—… ํŠธ๋ฆฌ ๋Œ€์‹  ํ˜„์žฌ ์ž‘์—… ๋ณต์‚ฌ๋ณธ์„ ์ง์ ‘ ํŽธ์ง‘ํ•ฉ๋‹ˆ๋‹ค. `09-advanced-features/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `CLAUDE_PROJECT_DIR`์€ ์ด์ œ ๋ชจ๋“  MCP stdio ์„œ๋ฒ„์˜ ํ™˜๊ฒฝ์œผ๋กœ ์ „๋‹ฌ๋˜๋ฉฐ (v2.1.139), ํ”Œ๋Ÿฌ๊ทธ์ธ ๋ฐ ํ”„๋กœ์ ํŠธ `.mcp.json` `command`/`args`/`env` ํ•„๋“œ์—์„œ `${CLAUDE_PROJECT_DIR}` ๋Œ€์ฒด๊ฐ€ ์ง€์›๋ฉ๋‹ˆ๋‹ค. `05-mcp/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- ์„œ๋ธŒ ์—์ด์ „ํŠธ OTEL ํ—ค๋” `x-claude-code-agent-id` ๋ฐ `x-claude-code-parent-agent-id` (v2.1.139)๋Š” `claude_code.llm_request` OTEL ์ŠคํŒฌ์˜ `agent_id` / `parent_agent_id` ์†์„ฑ์œผ๋กœ ๋…ธ์ถœ๋ฉ๋‹ˆ๋‹ค. `04-subagents/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1` (v2.1.142) โ€” v2.1.142 ๊ธฐ๋ณธ๊ฐ’์ด Opus 4.7๋กœ ๋ณ€๊ฒฝ๋œ ํ›„ ๋น ๋ฅธ ๋ชจ๋“œ๋ฅผ Opus 4.6์œผ๋กœ ๋˜๋Œ๋ฆฝ๋‹ˆ๋‹ค. `10-cli/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `CLAUDE_CODE_USE_POWERSHELL_TOOL=0` ๋ฐ `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1` (v2.1.143) โ€” ๊ธฐ๋ณธ ํ™œ์„ฑํ™”๋œ PowerShell ๋„๊ตฌ๋ฅผ ์„ ํƒ ํ•ด์ œํ•˜๊ฑฐ๋‚˜, `-ExecutionPolicy Bypass` ๋Œ€์‹  ์‹œ์Šคํ…œ ์‹คํ–‰ ์ •์ฑ…์„ ๋”ฐ๋ฅด๋„๋ก ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค. `09-advanced-features/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` (v2.1.143) โ€” Stop ํ›…์— ๋Œ€ํ•œ 8ํšŒ ์—ฐ์† ๋ธ”๋ก ์•ˆ์ „ ์ œํ•œ์„ ์žฌ์ •์˜ํ•ฉ๋‹ˆ๋‹ค(๋น„ํ™œ์„ฑํ™”ํ•˜๋ ค๋ฉด `0`์œผ๋กœ ์„ค์ •). `06-hooks/README.md` ๋ฐ `09-advanced-features/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1` (v2.1.141) โ€” SSH ํ‚ค๊ฐ€ ์—†๋Š” CI ๋Ÿฌ๋„ˆ๋ฅผ ์œ„ํ•ด ํ”Œ๋Ÿฌ๊ทธ์ธ ์„ค์น˜ ์‹œ GitHub ํ”Œ๋Ÿฌ๊ทธ์ธ ์†Œ์Šค๋ฅผ HTTPS๋ฅผ ํ†ตํ•ด ๊ฐ•์ œ๋กœ ํด๋ก ํ•˜๋„๋ก ํ•ฉ๋‹ˆ๋‹ค. `07-plugins/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `ANTHROPIC_WORKSPACE_ID` (v2.1.141) โ€” ์—ฐํ•ฉ ์›Œํฌ๋กœ๋“œ ID ํ† ํฐ์„ ํŠน์ • ์ž‘์—… ๊ณต๊ฐ„์œผ๋กœ ๋ฒ”์œ„ ์ง€์ •ํ•ฉ๋‹ˆ๋‹ค. `09-advanced-features/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- ์ตœ์ƒ์œ„ `SKILL.md` ํ”Œ๋Ÿฌ๊ทธ์ธ ํŒจํ„ด (v2.1.142) โ€” ์ตœ์ƒ์œ„ `SKILL.md`๋งŒ ์žˆ๊ณ  `skills/` ํ•˜์œ„ ๋””๋ ‰ํ† ๋ฆฌ๊ฐ€ ์—†๋Š” ํ”Œ๋Ÿฌ๊ทธ์ธ์€ ๋‹จ์ผ ์Šคํ‚ฌ๋กœ ํ‘œ์‹œ๋ฉ๋‹ˆ๋‹ค. `07-plugins/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `/schedule`์˜ ํ”Œ๋Ÿฌ๊ทธ์ธ ๋งˆ์ผ€ํŒ… ์ด๋ฆ„ **Routines** (Anthropic ๋ธ”๋กœ๊ทธ, 2026-05-14) โ€” `09-advanced-features/README.md`์— ํ•œ ์ค„ ๋ฉ”๋ชจ๋กœ ํ‘œ์‹œ๋ฉ๋‹ˆ๋‹ค. CLI ํ‘œ๋ฉด์€ `/schedule`๋กœ ์œ ์ง€๋ฉ๋‹ˆ๋‹ค. + +### ๋™์ž‘ ๋ณ€๊ฒฝ + +- **๋น ๋ฅธ ๋ชจ๋“œ ๊ธฐ๋ณธ๊ฐ’์ด Opus 4.7๋กœ ๋ณ€๊ฒฝ๋จ (v2.1.142)**: `/fast`๋Š” ์ด์ œ ๊ธฐ๋ณธ์ ์œผ๋กœ Opus 4.7์„ ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค(์ด์ „์—๋Š” Opus 4.6). `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1`์„ ์„ค์ •ํ•˜์—ฌ ๋‹ค์‹œ ์„ ํƒํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. +- **Bedrock/Vertex/Foundry์šฉ Windows์—์„œ PowerShell ๋„๊ตฌ๊ฐ€ ๊ธฐ๋ณธ์ ์œผ๋กœ ํ™œ์„ฑํ™”๋จ (v2.1.143)**: Claude Code๋Š” `-ExecutionPolicy Bypass`๋กœ PowerShell์„ ํ˜ธ์ถœํ•ฉ๋‹ˆ๋‹ค. `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1` (์‹œ์Šคํ…œ ์ •์ฑ… ๋”ฐ๋ฅด๊ธฐ) ๋˜๋Š” `CLAUDE_CODE_USE_POWERSHELL_TOOL=0` (๋„๊ตฌ ๋น„ํ™œ์„ฑํ™”)์œผ๋กœ ์„ ํƒ ํ•ด์ œํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. +- **API ํ‚ค ์ธ์ฆ ์„ค์ • ์‹œ ์›๊ฒฉ ์ œ์–ด, `/schedule`, claude.ai MCP ์ปค๋„ฅํ„ฐ ๋ฐ ์•Œ๋ฆผ ๊ธฐ๋ณธ ์„ค์ • ์ž๋™ ๋น„ํ™œ์„ฑํ™” (v2.1.139)**: `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, ๋˜๋Š” `apiKeyHelper`๋ฅผ ์„ค์ •ํ•˜๋ฉด claude.ai ๋กœ๊ทธ์ธ๋„ ํ™œ์„ฑํ™”๋˜์–ด ์žˆ๋”๋ผ๋„ 4๊ฐ€์ง€ claude.ai ์—ฐ๊ฒฐ ํ‘œ๋ฉด์ด ๋ชจ๋‘ ๋น„ํ™œ์„ฑํ™”๋ฉ๋‹ˆ๋‹ค. +- **Stop ํ›… ๋ธ”๋ก ๋ฃจํ”„๊ฐ€ 8ํšŒ ์—ฐ์† ๋ธ”๋ก์œผ๋กœ ์ œํ•œ๋จ (v2.1.143)**: 8ํšŒ ์—ฐ์† ๋ธ”๋ก ์ดํ›„ ์„ธ์…˜์ด ๊ฒฝ๊ณ ์™€ ํ•จ๊ป˜ ์ข…๋ฃŒ๋˜์–ด ๋ฒ„๊ทธ๊ฐ€ ์žˆ๋Š” Stop ํ›…์ด ์„ธ์…˜์„ ๋ฌดํ•œ์ • ๋ฐ˜๋ณตํ•˜๋Š” ๊ฒƒ์„ ๋ฐฉ์ง€ํ•ฉ๋‹ˆ๋‹ค. `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`์œผ๋กœ ์žฌ์ •์˜ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. +- **`subagent_type` ๋งค์นญ์ด ์ด์ œ ๋Œ€์†Œ๋ฌธ์ž ๋ฐ ๊ตฌ๋ถ„์ž ๋น„๊ตฌ๋ถ„์œผ๋กœ ๋ณ€๊ฒฝ๋จ (v2.1.140)**: `code-reviewer`, `Code Reviewer`, `code_reviewer` ๋ชจ๋‘ ๋™์ผํ•œ ์—์ด์ „ํŠธ๋กœ ํ•ด์„๋ฉ๋‹ˆ๋‹ค. `04-subagents/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. + +### ๋ณ€๊ฒฝ๋จ + +- `Setup` ํ›…์ด v2.1.138์— ์ถ”๊ฐ€๋œ ํ›„, ์ตœ์ƒ์œ„ ์ฐธ์กฐ ๋ฌธ์„œ(`README.md`, `CATALOG.md`)๊ฐ€ `28 hook events`์—์„œ `29 hook events`๋กœ ์—…๋ฐ์ดํŠธ๋˜์—ˆ์Šต๋‹ˆ๋‹ค. ์ด๋Š” `06-hooks/README.md` ๋ฐ `LEARNING-ROADMAP.md`์™€ ์ผ์น˜ํ•ฉ๋‹ˆ๋‹ค. + +### ๋ฒˆ์—ญ์ž๋ฅผ ์œ„ํ•œ ์ฐธ๊ณ  ์‚ฌํ•ญ + +- ํŠœํ† ๋ฆฌ์–ผ ๋ฒˆ์—ญ(`vi/`, `ja/`, `uk/`, `zh/`)์€ ์˜์–ด๋ฅผ ๋”ฐ๋ฆ…๋‹ˆ๋‹ค. ์ด๋ฒˆ ๋ผ์šด๋“œ์˜ ๋ชจ๋“ˆ README ๋ฐ ์œ„ ๋ณ€๊ฒฝ ๋กœ๊ทธ์˜ ์ฐจ์ด์ ์„ ๋™๊ธฐํ™”ํ•˜์‹ญ์‹œ์˜ค. ํ‘ธํ„ฐ๋Š” `์ตœ์ข… ์—…๋ฐ์ดํŠธ: 2026๋…„ 5์›” 19์ผ` ๋ฐ `Claude Code ๋ฒ„์ „: 2.1.143`์„ ๋ฐ˜์˜ํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. + +## [v2.1.138] โ€” 2026-05-09 + +### Claude Code v2.1.138์™€ ๋™๊ธฐํ™” + +ํŠœํ† ๋ฆฌ์–ผ ๋ฒ”์œ„๊ฐ€ Claude Code v2.1.131 โ†’ v2.1.138 (2026๋…„ 5์›” 9์ผ ๋ฆด๋ฆฌ์Šค)๋กœ ํ™•์žฅ๋˜์—ˆ์Šต๋‹ˆ๋‹ค. ๋งˆ์ง€๋ง‰ ๋™๊ธฐํ™” ์ดํ›„ Anthropic์€ v2.1.132๋ถ€ํ„ฐ v2.1.138๊นŒ์ง€ 7๊ฐœ์˜ ํŒจ์น˜๋ฅผ ์ œ๊ณตํ–ˆ์Šต๋‹ˆ๋‹ค. + +### ์ถ”๊ฐ€๋จ (์˜๋ฌธ ๋ฌธ์„œ) + +- `worktree.baseRef` ์„ค์ • (v2.1.133) โ€” `claude --worktree`๊ฐ€ `origin/` (`"fresh"`, ๊ธฐ๋ณธ๊ฐ’)์—์„œ ๋ถ„๊ธฐํ• ์ง€ ์•„๋‹ˆ๋ฉด ๋กœ์ปฌ `HEAD` (`"head"`)์—์„œ ๋ถ„๊ธฐํ• ์ง€ ์ œ์–ดํ•ฉ๋‹ˆ๋‹ค. **๋™์ž‘ ๋ณ€๊ฒฝ**: `"fresh"` ๊ธฐ๋ณธ๊ฐ’์€ v2.1.128์˜ ๋™์ž‘์„ ๋˜๋Œ๋ฆฌ๋ฏ€๋กœ, v2.1.128 ์ดํ›„ ๋กœ์ปฌ `HEAD` ๋ถ„๊ธฐ์— ์˜์กดํ–ˆ๋˜ ์‚ฌ์šฉ์ž๋Š” ๋‹ค์‹œ ์„ ํƒํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. `09-advanced-features/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `autoMode.hard_deny` ๊ด€๋ฆฌ ํ‚ค (v2.1.136) โ€” ์ถ”๋ก ๋œ ์‚ฌ์šฉ์ž ์˜๋„์™€ ๊ด€๊ณ„์—†์ด ํŠน์ • ์ข…๋ฅ˜์˜ ์ž‘์—…์„ ์ฐจ๋‹จํ•˜๋Š” ๋ถ„๋ฅ˜์ž ๊ทœ์น™ ๋ฐฐ์—ด์ž…๋‹ˆ๋‹ค. ์ž๋™ ๋ชจ๋“œ์—์„œ ์ ˆ๋Œ€๋กœ ์‹คํ–‰๋˜์–ด์„œ๋Š” ์•ˆ ๋˜๋Š” ์ž‘์—…(์˜ˆ: `rm -rf /`, ๋ณดํ˜ธ๋œ ๋ธŒ๋žœ์น˜๋กœ ๊ฐ•์ œ ํ‘ธ์‹œ)์— ์‚ฌ์šฉ๋ฉ๋‹ˆ๋‹ค. `soft_deny`์™€ ๋‹ฌ๋ฆฌ, ํ•˜๋“œ ๊ฑฐ๋ถ€ ๊ทœ์น™์€ ๋ถ„๋ฅ˜์ž์— ์˜ํ•ด ํ˜‘์ƒ๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. `09-advanced-features/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `parentSettingsBehavior` ๊ด€๋ฆฌ ํ‚ค (v2.1.133 ์ด์ƒ, ๊ด€๋ฆฌ์ž ๋“ฑ๊ธ‰) โ€” SDK์˜ `managedSettings`๊ฐ€ ์ƒ์œ„ ํ”„๋กœ์„ธ์Šค ์„ค์ •๊ณผ ๋ณ‘ํ•ฉ๋˜๋Š” ๋ฐฉ์‹์„ ์ œ์–ดํ•ฉ๋‹ˆ๋‹ค. `"first-wins"`๋Š” ๊ธฐ์กด ์šฐ์„  ์ˆœ์œ„๋ฅผ ์œ ์ง€ํ•˜๊ณ , `"merge"`๋Š” ๊ฐ’์„ ๊นŠ์ด ๋ณ‘ํ•ฉํ•ฉ๋‹ˆ๋‹ค. `09-advanced-features/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `Setup` ํ›… ์ด๋ฒคํŠธ โ€” ์ดˆ๊ธฐ ํ™˜๊ฒฝ ์„ค์ •(์„ธ์…˜๋‹น 1ํšŒ); ๋„๊ตฌ๋ฅผ ํ”„๋กœ๋น„์ €๋‹ํ•˜๊ฑฐ๋‚˜ ์ข…์†์„ฑ์„ ์„ค์น˜ํ•˜๋Š” ๋ฐ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. ๋ฌธ์„œํ™”๋œ ํ›… ์ด๋ฒคํŠธ ์ด ๊ฐœ์ˆ˜๊ฐ€ 28๊ฐœ์—์„œ 29๊ฐœ๋กœ ์ฆ๊ฐ€ํ–ˆ์Šต๋‹ˆ๋‹ค. `06-hooks/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- ํ›… ์ž…๋ ฅ JSON์˜ `effort.level` ํ•„๋“œ (v2.1.133) โ€” ํ™œ์„ฑ ๋…ธ๋ ฅ ์ˆ˜์ค€(`low`/`medium`/`high`/`xhigh`/`max`)์„ ํ›…์— ๋…ธ์ถœํ•ฉ๋‹ˆ๋‹ค. `06-hooks/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- Bash ์„œ๋ธŒํ”„๋กœ์„ธ์Šค์˜ `CLAUDE_CODE_SESSION_ID` ํ™˜๊ฒฝ ๋ณ€์ˆ˜ (v2.1.132) โ€” ํ›… ์ž…๋ ฅ JSON์˜ `session_id` ํ•„๋“œ์™€ ์ผ์น˜ํ•˜๋Š” ์„ธ์…˜ UUID๋กœ, Bash ๋กœ๊ทธ๋ฅผ ํ›… ํ…”๋ ˆ๋ฉ”ํŠธ๋ฆฌ์™€ ์—ฐ๊ด€์‹œํ‚ค๋Š” ๋ฐ ์‚ฌ์šฉ๋ฉ๋‹ˆ๋‹ค. `06-hooks/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- Bash ์„œ๋ธŒํ”„๋กœ์„ธ์Šค์˜ `CLAUDE_EFFORT` ํ™˜๊ฒฝ ๋ณ€์ˆ˜ (v2.1.133) โ€” ํ›… ์ž…๋ ฅ JSON์˜ `effort.level`๊ณผ ์ผ์น˜ํ•˜๋Š” ํ™œ์„ฑ ๋…ธ๋ ฅ ์ˆ˜์ค€์ž…๋‹ˆ๋‹ค. `06-hooks/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `sandbox.bwrapPath` ๋ฐ `sandbox.socatPath` ์„ค์ • (v2.1.133 ์ด์ƒ, Linux/WSL) โ€” `bubblewrap` ๋ฐ `socat`์˜ ๋น„ํ‘œ์ค€ ์„ค์น˜ ์œ„์น˜๋ฅผ Claude Code์— ์ง€์ •ํ•ฉ๋‹ˆ๋‹ค. ๊ธฐ๋ณธ๊ฐ’์€ `$PATH` ๊ฒ€์ƒ‰์ž…๋‹ˆ๋‹ค. `09-advanced-features/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` ํ™˜๊ฒฝ ๋ณ€์ˆ˜ (v2.1.132). `09-advanced-features/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` ํ™˜๊ฒฝ ๋ณ€์ˆ˜ (v2.1.136) โ€” OpenTelemetry ๋ฐ์ดํ„ฐ๋ฅผ ์บก์ฒ˜ํ•˜๋Š” ์กฐ์ง์„ ์œ„ํ•ด ์„ธ์…˜ ํ’ˆ์งˆ ์„ค๋ฌธ์กฐ์‚ฌ๋ฅผ ๋‹ค์‹œ ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค. OTEL ๋ฐฐํฌ์—์„œ๋Š” ๊ธฐ๋ณธ์ ์œผ๋กœ ๋น„ํ™œ์„ฑํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. `09-advanced-features/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. + +### ๋ณ€๊ฒฝ๋จ + +- **๋™์ž‘ ๋ณ€๊ฒฝ**: ๊ณ„ํš ๋ชจ๋“œ๋Š” ์ด์ œ `permissions.allow`์— ์ผ์น˜ํ•˜๋Š” `Edit(...)` ๊ทœ์น™์ด ์žˆ๋Š” ๊ฒฝ์šฐ์—๋„ ๋ชจ๋“  ํŒŒ์ผ ์“ฐ๊ธฐ๋ฅผ ๋ฌด์กฐ๊ฑด ์ฐจ๋‹จํ•ฉ๋‹ˆ๋‹ค(v2.1.136). ์ด์ „์—๋Š” ๊ด€๋Œ€ํ•œ `Edit(...)` ๊ทœ์น™์ด ๊ณ„ํš ๋ชจ๋“œ์—์„œ ์“ฐ๊ธฐ๋ฅผ ํ—ˆ์šฉํ•  ์ˆ˜ ์žˆ์—ˆ์ง€๋งŒ, ํ•ด๋‹น ์šฐํšŒ ๊ฒฝ๋กœ๋Š” ํ์‡„๋˜์—ˆ์Šต๋‹ˆ๋‹ค. ์ด์ „ ๋™์ž‘์— ์˜์กดํ–ˆ๋˜ ์›Œํฌํ”Œ๋กœ์šฐ๋Š” ํŽธ์ง‘ ์ „์— ๊ณ„ํš ๋ชจ๋“œ(`Shift+Tab`)๋ฅผ ์ข…๋ฃŒํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. `09-advanced-features/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- ํ”Œ๋Ÿฌ๊ทธ์ธ ๊ณต๋ฐฑ ์Šฌ๋ž˜์‹œ ๋ช…๋ น(์˜ˆ: `/myplugin review`)์€ ์ด์ œ `/myplugin:review`๋กœ ํ•ด์„๋ฉ๋‹ˆ๋‹ค. ํ”Œ๋Ÿฌ๊ทธ์ธ `skills` ๊ตฌ์„ฑ ํ•ญ๋ชฉ์€ ๋” ์ด์ƒ ๊ธฐ๋ณธ `skills/` ๋””๋ ‰ํ† ๋ฆฌ๋ฅผ ์ˆจ๊ธฐ์ง€ ์•Š์œผ๋ฉฐ, ๋‘˜ ๋‹ค ๋ณ‘ํ•ฉ๋ฉ๋‹ˆ๋‹ค. `07-plugins/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- MCP ์„œ๋ฒ„๋Š” ์ด์ œ `/clear` ๋ช…๋ น์„ ์‹คํ–‰ํ•ด๋„ ์œ ์ง€๋ฉ๋‹ˆ๋‹ค(v2.1.132 ์ด์ƒ). `05-mcp/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- ์„œ๋ธŒ ์—์ด์ „ํŠธ๋Š” ์Šคํ‚ฌ ๋„๊ตฌ(v2.1.133)๋ฅผ ํ†ตํ•ด ํ”„๋กœ์ ํŠธ, ์‚ฌ์šฉ์ž ๋ฐ ํ”Œ๋Ÿฌ๊ทธ์ธ ์Šคํ‚ฌ์„ ๊ฒ€์ƒ‰ํ•ฉ๋‹ˆ๋‹ค. `04-subagents/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `--permission-mode`๋Š” ์ด์ œ ๊ณ„ํš ๋ชจ๋“œ ์„ธ์…˜์„ ์žฌ๊ฐœํ•  ๋•Œ ์ ์šฉ๋ฉ๋‹ˆ๋‹ค(v2.1.132). `09-advanced-features/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `CronList` ์ถœ๋ ฅ์— ์ด์ œ ํ•œ์ •์ž ๋ฐ ์˜ˆ์•ฝ๋œ ํ”„๋กฌํ”„ํŠธ ๋ณธ๋ฌธ์ด ํฌํ•จ๋˜์–ด(v2.1.136), ๊ฐ cron์ด ๋ฌด์—‡์„ ์‹คํ–‰ํ• ์ง€ ์—ด์–ด๋ณด์ง€ ์•Š๊ณ ๋„ ๊ฐ์‚ฌํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. `09-advanced-features/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. + +### ์ˆ˜์ •๋จ + +- OAuth ์ƒˆ๋กœ ๊ณ ์นจ ํ† ํฐ ๋™์‹œ ์ƒˆ๋กœ ๊ณ ์นจ ๊ฒฝ์Ÿ ์กฐ๊ฑด์„ ์ˆ˜์ •ํ–ˆ์Šต๋‹ˆ๋‹ค. +- INDEX.md ๊ฐœ์ˆ˜ ๋ถˆ์ผ์น˜: ์Šคํ‚ฌ 28 โ†’ 16, ํ”Œ๋Ÿฌ๊ทธ์ธ 40 โ†’ 27, ํ›… ์Šคํฌ๋ฆฝํŠธ 8 โ†’ 9 (๋งˆํฌ๋‹ค์šด ์ฝ˜ํ…์ธ  ํŠธ๋ฆฌ์—์„œ ๋‹ค์‹œ ๊ณ„์‚ฐ๋จ). ์ƒˆ๋กœ์šด ์ด๊ณ„๋Š” ๋นŒ๋“œ ์•„ํ‹ฐํŒฉํŠธ ๋ฐ ๊ตฌ์„ฑ ๋Œ€์‹  ํŠœํ† ๋ฆฌ์–ผ ์ฝ˜ํ…์ธ ์— ๊ฐœ์ˆ˜๋ฅผ ์ œํ•œํ•˜๋Š” `.md` ์ „์šฉ ๋ฐฉ๋ฒ•๋ก ์„ ๋ฐ˜์˜ํ•ฉ๋‹ˆ๋‹ค. +- `CATALOG.md` (v2.1.118 โ†’ v2.1.138) ๋ฐ `claude_concepts_guide.md` (v2.1.117 โ†’ v2.1.138)์˜ ์˜ค๋ž˜๋œ ์†Œ์Šค URL์„ ์ˆ˜์ •ํ–ˆ์Šต๋‹ˆ๋‹ค. ๊ฐœ๋… ๊ฐ€์ด๋“œ์—์„œ ์ค‘๋ณต๋œ ๋ ˆ๊ฑฐ์‹œ ํ‘ธํ„ฐ๋ฅผ ์ œ๊ฑฐํ–ˆ์Šต๋‹ˆ๋‹ค. + +### ๋ฒˆ์—ญ ๊ด€๋ฆฌ์ž๋ฅผ ์œ„ํ•œ ์ฐธ๊ณ  ์‚ฌํ•ญ + +`vi/`, `zh/`, `uk/`, `ja/` ๋กœ์ปฌ๋ผ์ด์ฆˆ๋œ ํŠธ๋ฆฌ๋Š” ์ปค๋ฎค๋‹ˆํ‹ฐ์—์„œ ์œ ์ง€ ๊ด€๋ฆฌ๋˜๋ฉฐ ์˜์–ด ์›๋ณธ๋ณด๋‹ค ์ง€์—ฐ๋  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ๋ฒˆ์—ญ์„ ๋™๊ธฐํ™”ํ•˜๋Š” ๊ธฐ์—ฌ์ž๋Š” ์ด ๋ฆด๋ฆฌ์Šค์—์„œ ์—…๋ฐ์ดํŠธ๋œ ์˜์–ด ํŒŒ์ผ๊ณผ ์ฐจ์ด์ ์„ ๋น„๊ตํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. + +## [v2.1.131] โ€” 2026-05-06 + +### Claude Code v2.1.131์™€ ๋™๊ธฐํ™” + +ํŠœํ† ๋ฆฌ์–ผ ๋ฒ”์œ„๊ฐ€ Claude Code v2.1.126 โ†’ v2.1.131 (2026๋…„ 5์›” 6์ผ ๋ฆด๋ฆฌ์Šค)๋กœ ํ™•์žฅ๋˜์—ˆ์Šต๋‹ˆ๋‹ค. ๋งˆ์ง€๋ง‰ ๋™๊ธฐํ™” ์ดํ›„ Anthropic์€ v2.1.128, v2.1.129, v2.1.131์„ ์ œ๊ณตํ–ˆ์Šต๋‹ˆ๋‹ค. v2.1.127 ๋ฐ v2.1.130์€ ๊ฑด๋„ˆ๋›ฐ์–ด์กŒ๊ณ  ๊ณต๊ฐœ์ ์œผ๋กœ ๋ฆด๋ฆฌ์Šค๋˜์ง€ ์•Š์•˜์Šต๋‹ˆ๋‹ค. + +### ์ถ”๊ฐ€๋จ (์˜๋ฌธ ๋ฌธ์„œ) + +- `--plugin-url ` ํ”Œ๋ž˜๊ทธ (v2.1.129) โ€” ํ˜„์žฌ ์„ธ์…˜์„ ์œ„ํ•ด URL์—์„œ ํ”Œ๋Ÿฌ๊ทธ์ธ `.zip` ์•„์นด์ด๋ธŒ๋ฅผ ๊ฐ€์ ธ์˜ต๋‹ˆ๋‹ค. ๋ฐ˜๋ณต ๊ฐ€๋Šฅํ•ฉ๋‹ˆ๋‹ค. `07-plugins/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `CLAUDE_CODE_FORCE_SYNC_OUTPUT` ํ™˜๊ฒฝ ๋ณ€์ˆ˜ (v2.1.129) โ€” ์ž๋™ ๊ฐ์ง€๊ฐ€ ์‹คํŒจํ•˜๋Š” ํ„ฐ๋ฏธ๋„(์˜ˆ: Emacs `eat`)์— ๋Œ€ํ•ด ๋™๊ธฐ์‹ ์ถœ๋ ฅ์„ ๊ฐ•์ œํ•ฉ๋‹ˆ๋‹ค. `10-cli/README.md` ๋ฐ `09-advanced-features/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` ํ™˜๊ฒฝ ๋ณ€์ˆ˜ (v2.1.129) โ€” Homebrew/WinGet ์„ค์น˜(์ผ๋ฐ˜์ ์œผ๋กœ ์ž๋™ ์—…๋ฐ์ดํŠธ๋˜์ง€ ์•Š์Œ)์— ๋Œ€ํ•œ ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์—…๊ทธ๋ ˆ์ด๋“œ๋ฅผ ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค. `10-cli/README.md` ๋ฐ `09-advanced-features/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` ํ™˜๊ฒฝ ๋ณ€์ˆ˜ (v2.1.129) โ€” `/v1/models` ๊ฒŒ์ดํŠธ์›จ์ด ๊ฒ€์ƒ‰์— ์˜ตํŠธ์ธํ•˜๋Š” ๋ฐ ํ•„์š”ํ•ฉ๋‹ˆ๋‹ค(๋ณ€๊ฒฝ๋จ ์„น์…˜ ์ฐธ์กฐ). `10-cli/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `disableRemoteControl` ์„ค์ • (v2.1.128) โ€” ๊ด€๋ฆฌ์ž๋Š” ๊ด€๋ฆฌ/์ •์ฑ… ๋ฒ”์œ„ ์„ค์ •์„ ํ†ตํ•ด `claude remote-control` ๋ฐ `/remote-control`์„ ์ฐจ๋‹จํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. `09-advanced-features/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `--plugin-dir`๋Š” ๋””๋ ‰ํ† ๋ฆฌ ์ž…๋ ฅ๊ณผ ํ•จ๊ป˜ `.zip` ์•„์นด์ด๋ธŒ๋ฅผ ํ—ˆ์šฉํ•ฉ๋‹ˆ๋‹ค(v2.1.128). `07-plugins/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `skillOverrides`๋Š” ๊ธฐ์กด์˜ `"on"`/`"off"` ์™ธ์— `"name-only"` ๋ฐ `"user-invocable-only"`๋ฅผ ํ—ˆ์šฉํ•ฉ๋‹ˆ๋‹ค(v2.1.129). `03-skills/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. + +### ๋ณ€๊ฒฝ๋จ + +- **๋™์ž‘ ๋ณ€๊ฒฝ**: ๊ฒŒ์ดํŠธ์›จ์ด `/v1/models` ๊ฒ€์ƒ‰์ด ์ด์ œ **์„ ํƒ ์‚ฌํ•ญ**์œผ๋กœ ๋ณ€๊ฒฝ๋˜์—ˆ์Šต๋‹ˆ๋‹ค(v2.1.129). ์ด์ „(v2.1.126)์—๋Š” `ANTHROPIC_BASE_URL`์„ ์„ค์ •ํ•˜๋ฉด ๊ฒŒ์ดํŠธ์›จ์ด์˜ `/v1/models` ์—”๋“œํฌ์ธํŠธ์—์„œ `/model`์ด ์ž๋™์œผ๋กœ ์ฑ„์›Œ์กŒ์Šต๋‹ˆ๋‹ค. v2.1.129๋ถ€ํ„ฐ๋Š” ์‚ฌ์šฉ์ž๊ฐ€ ์ถ”๊ฐ€๋กœ `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1`์„ ์„ค์ •ํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. ์ด ํ™˜๊ฒฝ ๋ณ€์ˆ˜๊ฐ€ ์—†์œผ๋ฉด `/model`์€ ๋‚ด์žฅ๋œ ์ •์  ๋ชฉ๋ก์œผ๋กœ ๋Œ€์ฒด๋ฉ๋‹ˆ๋‹ค. `10-cli/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `/mcp`๋Š” ์„œ๋ฒ„๋ณ„ ๋„๊ตฌ ์ˆ˜๋ฅผ ํ‘œ์‹œํ•˜๊ณ , 0๊ฐœ์˜ ๋„๊ตฌ๋ฅผ ๋ณด๊ณ ํ•˜๋Š” ์„œ๋ฒ„๋ฅผ ์‹œ๊ฐ์ ์œผ๋กœ ํ‘œ์‹œํ•ฉ๋‹ˆ๋‹ค(v2.1.128). `05-mcp/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- ์ธ์ˆ˜๊ฐ€ ์—†๋Š” `/color`๋Š” ๋ฌด์ž‘์œ„ ์„ธ์…˜ ์ƒ‰์ƒ์„ ์„ ํƒํ•ฉ๋‹ˆ๋‹ค(v2.1.128). ๋ช…์‹œ์ ์ธ `/color `๋Š” ํŠน์ • ์ƒ‰์ƒ์„ ๊ณ„์† ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค. `01-slash-commands/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `--channels` ํ”Œ๋ž˜๊ทธ๋Š” ์ด์ œ API ํ‚ค(์ฝ˜์†”) ์ธ์ฆ๊ณผ ํ•จ๊ป˜ ์ž‘๋™ํ•ฉ๋‹ˆ๋‹ค(v2.1.128). ์ด์ „ ๋ฆด๋ฆฌ์Šค์—์„œ๋Š” Pro/Max OAuth๊ฐ€ ํ•„์š”ํ–ˆ์Šต๋‹ˆ๋‹ค. `09-advanced-features/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- Ctrl+R ๊ธฐ๋ก ์„ ํƒ๊ธฐ๋Š” ๊ธฐ๋ณธ์ ์œผ๋กœ **๋ชจ๋“  ํ”„๋กœ์ ํŠธ์˜ ๋ชจ๋“  ํ”„๋กฌํ”„ํŠธ**๋ฅผ ํ‘œ์‹œํ•ฉ๋‹ˆ๋‹ค(v2.1.129). ์„ ํƒ๊ธฐ ๋‚ด์—์„œ Ctrl+S๋ฅผ ๋ˆŒ๋Ÿฌ ํ˜„์žฌ ํ”„๋กœ์ ํŠธ๋กœ ๋ฒ”์œ„๋ฅผ ์ขํž ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. `09-advanced-features/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `/context`๋Š” ๋” ์ด์ƒ ASCII ์‹œ๊ฐํ™”๋ฅผ ๋Œ€ํ™”์— ๋คํ”„ํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค(v2.1.129). ์‹œ๊ฐํ™”๋Š” UI ๋‚ด์—์„œ๋งŒ ํ‘œ์‹œ๋˜๋ฉฐ, ํ˜ธ์ถœ๋‹น ์•ฝ 1.6k ํ† ํฐ ๋น„์šฉ์ด ๋” ์ด์ƒ ๋ฐœ์ƒํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. `09-advanced-features/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- ๋“œ๋ž˜๊ทธ ์•ค ๋“œ๋กญ์—์„œ ๋„ˆ๋ฌด ํฐ ์ด๋ฏธ์ง€๋Š” ์ž๋™์œผ๋กœ ์ถ•์†Œ๋ฉ๋‹ˆ๋‹ค(v2.1.128) โ€” ์ด์ „ ๋ฒ„์ „์—์„œ๋Š” ์ด๋ฏธ์ง€๋ฅผ ์ฆ‰์‹œ ๊ฑฐ๋ถ€ํ–ˆ์Šต๋‹ˆ๋‹ค. + +### ์ˆ˜์ •๋จ + +- Windows์—์„œ VS Code ํ™•์žฅ ํ™œ์„ฑํ™” ๋ฌธ์ œ๋ฅผ ์ˆ˜์ •ํ–ˆ์Šต๋‹ˆ๋‹ค(v2.1.131). +- Mantle ์—”๋“œํฌ์ธํŠธ ์ธ์ฆ ๋ฌธ์ œ๋ฅผ ์ˆ˜์ •ํ–ˆ์Šต๋‹ˆ๋‹ค(v2.1.131). +- 1์‹œ๊ฐ„ ํ”„๋กฌํ”„ํŠธ ์บ์‹œ TTL์ด ๋” ์ด์ƒ 5๋ถ„์œผ๋กœ ์ž˜๋ฆฌ์ง€ ์•Š์Šต๋‹ˆ๋‹ค(v2.1.129). +- 10MB๋ณด๋‹ค ํฐ stdin ํŽ˜์ด๋กœ๋“œ์—์„œ ๋ฐœ์ƒํ•˜๋Š” ์ถฉ๋Œ ๋ฌธ์ œ๋ฅผ ์ˆ˜์ •ํ–ˆ์Šต๋‹ˆ๋‹ค(v2.1.128). + +### ๋ฒˆ์—ญ ๊ด€๋ฆฌ์ž๋ฅผ ์œ„ํ•œ ์ฐธ๊ณ  ์‚ฌํ•ญ + +`vi/`, `zh/`, `uk/`, `ja/` ๋กœ์ปฌ๋ผ์ด์ฆˆ๋œ ํŠธ๋ฆฌ๋Š” ์ปค๋ฎค๋‹ˆํ‹ฐ์—์„œ ์œ ์ง€ ๊ด€๋ฆฌ๋˜๋ฉฐ ์˜์–ด ์›๋ณธ๋ณด๋‹ค ์ง€์—ฐ๋  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ๋ฒˆ์—ญ์„ ๋™๊ธฐํ™”ํ•˜๋Š” ๊ธฐ์—ฌ์ž๋Š” ์ด ๋ฆด๋ฆฌ์Šค์—์„œ ์—…๋ฐ์ดํŠธ๋œ ์˜์–ด ํŒŒ์ผ๊ณผ ์ฐจ์ด์ ์„ ๋น„๊ตํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. + +## [v2.1.126] โ€” 2026-05-02 + +### Claude Code v2.1.126์™€ ๋™๊ธฐํ™” + +ํŠœํ† ๋ฆฌ์–ผ ๋ฒ”์œ„๊ฐ€ Claude Code v2.1.119 โ†’ v2.1.126 (2026๋…„ 5์›” 1์ผ ๋ฆด๋ฆฌ์Šค)๋กœ ํ™•์žฅ๋˜์—ˆ์Šต๋‹ˆ๋‹ค. v2.1.120์€ ์ฒซ ๋ฆด๋ฆฌ์Šค ๋‹น์ผ(2026๋…„ 4์›” 24์ผ) ๋กค๋ฐฑ๋˜์—ˆ์ง€๋งŒ, ์›๋ž˜ ๋ณด๊ณ ๋œ ํšŒ๊ท€ ๋ฌธ์ œ๊ฐ€ ์ˆ˜์ •๋˜์–ด 2026๋…„ 4์›” 28์ผ์— ์„ฑ๊ณต์ ์œผ๋กœ ์žฌ๋ฆด๋ฆฌ์Šค๋˜์—ˆ์Šต๋‹ˆ๋‹ค. v2.1.124์™€ v2.1.125๋Š” Anthropic์— ์˜ํ•ด ๊ฑด๋„ˆ๋›ฐ์–ด์กŒ๊ณ  ๋ฆด๋ฆฌ์Šค๋˜์ง€ ์•Š์•˜์Šต๋‹ˆ๋‹ค. + +### ์ถ”๊ฐ€๋จ (์˜๋ฌธ ๋ฌธ์„œ) + +- `claude project purge [path]` ์„œ๋ธŒ์ปค๋งจ๋“œ (v2.1.126) โ€” ํ”„๋กœ์ ํŠธ์˜ ๋ชจ๋“  Claude Code ์ƒํƒœ(๋Œ€ํ™” ๊ธฐ๋ก, ์ž‘์—…, ๋””๋ฒ„๊ทธ ๋กœ๊ทธ, ํŒŒ์ผ ํŽธ์ง‘ ๊ธฐ๋ก, ํ”„๋กฌํ”„ํŠธ ๊ธฐ๋ก, `~/.claude.json` ํ•ญ๋ชฉ)๋ฅผ ์‚ญ์ œํ•ฉ๋‹ˆ๋‹ค. `--dry-run`, `-y/--yes`, `-i/--interactive`, `--all` ์˜ต์…˜์„ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค. `10-cli/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `claude plugin prune` ์„œ๋ธŒ์ปค๋งจ๋“œ (v2.1.121) โ€” ๊ณ ์•„ ์ƒํƒœ์˜ ์ž๋™ ์„ค์น˜๋œ ํ”Œ๋Ÿฌ๊ทธ์ธ ์ข…์†์„ฑ์„ ์ œ๊ฑฐํ•ฉ๋‹ˆ๋‹ค. `plugin uninstall --prune`์€ ์—ฐ์‡„์ ์œผ๋กœ ์ž‘๋™ํ•ฉ๋‹ˆ๋‹ค. `07-plugins/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `claude ultrareview [target]` ์„œ๋ธŒ์ปค๋งจ๋“œ (v2.1.120) โ€” CI/์Šคํฌ๋ฆฝํŠธ์—์„œ `/ultrareview`๋ฅผ ๋น„๋Œ€ํ™”ํ˜•์œผ๋กœ ์‹คํ–‰ํ•˜๊ณ , ๋ฐœ๊ฒฌ ์‚ฌํ•ญ์„ ํ‘œ์ค€ ์ถœ๋ ฅ์œผ๋กœ ์ธ์‡„ํ•˜๋ฉฐ, ์„ฑ๊ณต ์‹œ 0, ์‹คํŒจ ์‹œ 1๋กœ ์ข…๋ฃŒํ•ฉ๋‹ˆ๋‹ค. `--json` ๋ฐ `--timeout ` ์˜ต์…˜์„ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค. `10-cli/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- ์Šคํ‚ฌ ๋‚ด์šฉ ๋‚ด์—์„œ `${CLAUDE_EFFORT}` ํ”Œ๋ ˆ์ด์Šคํ™€๋” ์‚ฌ์šฉ ๊ฐ€๋Šฅ (v2.1.120) โ€” ํ˜„์žฌ ๋…ธ๋ ฅ ์ˆ˜์ค€์œผ๋กœ ํ•ด์„๋ฉ๋‹ˆ๋‹ค. `03-skills/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹คใ€‚ +- `alwaysLoad` MCP ์„œ๋ฒ„ ๊ตฌ์„ฑ ์˜ต์…˜ (v2.1.121) โ€” `true`์ธ ๊ฒฝ์šฐ, ํ•ด๋‹น ์„œ๋ฒ„์˜ ๋ชจ๋“  ๋„๊ตฌ๋Š” ๋„๊ตฌ ๊ฒ€์ƒ‰ ์—ฐ๊ธฐ๋ฅผ ๊ฑด๋„ˆ๋œ๋‹ˆ๋‹ค. `05-mcp/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `PostToolUse.hookSpecificOutput.updatedToolOutput`์€ ์ด์ œ ๋ชจ๋“  ๋„๊ตฌ์—์„œ ์ž‘๋™ํ•ฉ๋‹ˆ๋‹ค(v2.1.121). ์ด์ „์—๋Š” MCP ์ „์šฉ์ด์—ˆ์Šต๋‹ˆ๋‹ค. `06-hooks/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `ANTHROPIC_BEDROCK_SERVICE_TIER` ํ™˜๊ฒฝ ๋ณ€์ˆ˜ (v2.1.122) โ€” Bedrock ์„œ๋น„์Šค ํ‹ฐ์–ด(`default`, `flex`, `priority`)๋ฅผ ์„ ํƒํ•ฉ๋‹ˆ๋‹ค. `10-cli/README.md` ํ™˜๊ฒฝ ๋ณ€์ˆ˜ ํ‘œ์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `--dangerously-skip-permissions` ํ™•์žฅ ๊ฒฝ๋กœ ์ ์šฉ ๋ฒ”์œ„ (v2.1.121, v2.1.126) โ€” ์ด์ œ `.claude/skills/`, `.claude/agents/`, `.claude/commands/`, `.claude/`, `.git/`, `.vscode/`, ์…ธ ๊ตฌ์„ฑ ํŒŒ์ผ์— ๋Œ€ํ•œ ์“ฐ๊ธฐ ํ”„๋กฌํ”„ํŠธ๋ฅผ ์šฐํšŒํ•ฉ๋‹ˆ๋‹ค. ์น˜๋ช…์ ์ธ ์‚ญ์ œ ๋ช…๋ น(`rm -rf /` ๋“ฑ)์€ ์—ฌ์ „ํžˆ ํ”„๋กฌํ”„ํŠธ๋ฅผ ํ‘œ์‹œํ•ฉ๋‹ˆ๋‹ค. `09-advanced-features/README.md`์˜ ๊ถŒํ•œ ๋ชจ๋“œ ์„น์…˜์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- OAuth ์ฝ”๋“œ ๋ถ™์—ฌ๋„ฃ๊ธฐ ํด๋ฐฑ (v2.1.126) โ€” ๋ธŒ๋ผ์šฐ์ € ์ฝœ๋ฐฑ์ด localhost์— ๋„๋‹ฌํ•  ์ˆ˜ ์—†์„ ๋•Œ(WSL2, SSH, ์ปจํ…Œ์ด๋„ˆ), `claude auth login`์€ ํ„ฐ๋ฏธ๋„์— ๋ถ™์—ฌ๋„ฃ์€ OAuth ์ฝ”๋“œ๋ฅผ ํ—ˆ์šฉํ•ฉ๋‹ˆ๋‹ค. `10-cli/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `/skills` ๋ฉ”๋‰ด์˜ ์ž…๋ ฅ ํ•„ํ„ฐ๋ง ๊ธฐ๋Šฅ (v2.1.121). `03-skills/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `AI_AGENT` ํ™˜๊ฒฝ ๋ณ€์ˆ˜ (v2.1.120) โ€” `gh`๊ฐ€ ํŠธ๋ž˜ํ”ฝ์„ Claude Code์— ๊ท€์†์‹œํ‚ฌ ์ˆ˜ ์žˆ๋„๋ก ์„œ๋ธŒํ”„๋กœ์„ธ์Šค์— ์„ค์ •๋ฉ๋‹ˆ๋‹ค. `10-cli/README.md` ํ™˜๊ฒฝ ๋ณ€์ˆ˜ ํ‘œ์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. + +### ๋ณ€๊ฒฝ๋จ + +- `--from-pr` (v2.1.119) ๋ฐ `/resume` PR-URL ๊ฒ€์ƒ‰ (v2.1.122)์€ ์ด์ œ GitHub, GitHub Enterprise, GitLab ๋ฐ Bitbucket URL์„ ๋ชจ๋‘ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค. +- Windows: Git for Windows / Git Bash๋Š” ๋” ์ด์ƒ ํ•„์š”ํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค(v2.1.120) โ€” Git Bash๊ฐ€ ์—†๋Š” ๊ฒฝ์šฐ Claude Code๋Š” PowerShell์„ ์…ธ ๋„๊ตฌ๋กœ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. v2.1.126๋ถ€ํ„ฐ๋Š” PowerShell ๋„๊ตฌ๊ฐ€ ํ™œ์„ฑํ™”๋˜๋ฉด PowerShell์ด ๊ธฐ๋ณธ ์…ธ์ด ๋ฉ๋‹ˆ๋‹ค. Microsoft Store, PATH๊ฐ€ ์—†๋Š” MSI, ๋˜๋Š” `.NET ์ „์—ญ ๋„๊ตฌ`๋ฅผ ํ†ตํ•ด ์„ค์น˜๋œ PowerShell 7๊นŒ์ง€ ๊ฐ์ง€ ๋ฒ”์œ„๊ฐ€ ํ™•์žฅ๋˜์—ˆ์Šต๋‹ˆ๋‹ค. `09-advanced-features/README.md` ํ”Œ๋žซํผ ๋…ธํŠธ์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `ANTHROPIC_BASE_URL`์ด Anthropic ํ˜ธํ™˜ ๊ฒŒ์ดํŠธ์›จ์ด๋ฅผ ๊ฐ€๋ฆฌํ‚ฌ ๋•Œ, `/model` ์„ ํƒ๊ธฐ๋Š” ์ด์ œ ๊ฒŒ์ดํŠธ์›จ์ด์˜ `/v1/models` ์—”๋“œํฌ์ธํŠธ์—์„œ ๋ชจ๋ธ์„ ๋‚˜์—ดํ•ฉ๋‹ˆ๋‹ค(v2.1.126). `10-cli/README.md`์— ๋ฌธ์„œํ™”๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- `--dangerously-skip-permissions`๋Š” ์ด์ œ ํ›จ์”ฌ ๋” ๋„“์€ ํ—ˆ์šฉ ๋ชฉ๋ก์— ๋Œ€ํ•œ ์“ฐ๊ธฐ ํ”„๋กฌํ”„ํŠธ๋ฅผ ๋” ์ด์ƒ ํ‘œ์‹œํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค(์ถ”๊ฐ€๋จ ์„น์…˜ ์ฐธ์กฐ). ์น˜๋ช…์ ์ธ ์ œ๊ฑฐ ๋ช…๋ น์€ ์—ฌ์ „ํžˆ ํ”„๋กฌํ”„ํŠธ๋ฅผ ํ‘œ์‹œํ•ฉ๋‹ˆ๋‹ค. +- ์ด๋ฏธ์ง€ ๋ถ™์—ฌ๋„ฃ๊ธฐ ์ž๋™ ์ถ•์†Œ (v2.1.126) โ€” 2000px๋ณด๋‹ค ํฐ ์ด๋ฏธ์ง€๋Š” ๋ถ™์—ฌ๋„ฃ๊ธฐ ์‹œ ์ž๋™์œผ๋กœ ์ถ•์†Œ๋ฉ๋‹ˆ๋‹ค. ๊ธฐ๋ก์— ์žˆ๋Š” ๋„ˆ๋ฌด ํฐ ์ด๋ฏธ์ง€๋Š” ์ž๋™์œผ๋กœ ์ œ๊ฑฐ๋˜๊ณ  ์š”์ฒญ์ด ์žฌ์‹œ๋„๋ฉ๋‹ˆ๋‹ค. (์•ˆ์ „/UX ์ฐธ๊ณ  ์‚ฌํ•ญ์œผ๋กœ์„œ๋งŒ ํŠœํ† ๋ฆฌ์–ผ๊ณผ ๊ด€๋ จ์ด ์žˆ์Šต๋‹ˆ๋‹ค.) + +### ๋ณด์•ˆ + +- ๋” ๋†’์€ ์šฐ์„ ์ˆœ์œ„์˜ ๊ด€๋ฆฌ ์„ค์ • ์†Œ์Šค์— `sandbox` ๋ธ”๋ก์ด ์—†์„ ๋•Œ `allowManagedDomainsOnly` / `allowManagedReadPathsOnly`๊ฐ€ ๋ฌด์‹œ๋˜๋˜ ๋ฌธ์ œ๋ฅผ ์ˆ˜์ •ํ–ˆ์Šต๋‹ˆ๋‹ค(v2.1.126). + +### ๋ฒˆ์—ญ ๊ด€๋ฆฌ์ž๋ฅผ ์œ„ํ•œ ์ฐธ๊ณ  ์‚ฌํ•ญ + +`vi/`, `zh/`, `uk/`, `ja/` ๋กœ์ปฌ๋ผ์ด์ฆˆ๋œ ํŠธ๋ฆฌ๋Š” ์ปค๋ฎค๋‹ˆํ‹ฐ์—์„œ ์œ ์ง€ ๊ด€๋ฆฌ๋˜๋ฉฐ ์˜์–ด ์›๋ณธ๋ณด๋‹ค ์ง€์—ฐ๋  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ๋ฒˆ์—ญ์„ ๋™๊ธฐํ™”ํ•˜๋Š” ๊ธฐ์—ฌ์ž๋Š” ์ด ๋ฆด๋ฆฌ์Šค์—์„œ ์—…๋ฐ์ดํŠธ๋œ ์˜์–ด ํŒŒ์ผ๊ณผ ์ฐจ์ด์ ์„ ๋น„๊ตํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. + +## [v2.4.0] โ€” 2026-04-27 + +### Claude Code v2.1.119์™€ ๋™๊ธฐํ™” + +ํŠœํ† ๋ฆฌ์–ผ ๋ฒ”์œ„๊ฐ€ Claude Code v2.1.112 โ†’ v2.1.119 (2026๋…„ 4์›” 23์ผ ๋ฆด๋ฆฌ์Šค)๋กœ ํ™•์žฅ๋˜์—ˆ์Šต๋‹ˆ๋‹ค. v2.1.120์€ 4์›” 24์ผ์— ๊ฒŒ์‹œ๋˜์—ˆ์œผ๋‚˜, ํšŒ๊ท€ ๋ฌธ์ œ๋กœ ์ธํ•ด ๊ฐ™์€ ๋‚  ์ž ์‹œ ๋กค๋ฐฑ๋œ ํ›„ 4์›” 28์ผ์— ์ˆ˜์ • ์‚ฌํ•ญ๊ณผ ํ•จ๊ป˜ ์žฌ๋ฆด๋ฆฌ์Šค๋˜์–ด ์ด์ œ ์ผ๋ฐ˜ ๋ฆด๋ฆฌ์Šค ๋ผ์ธ์˜ ์ผ๋ถ€๊ฐ€ ๋˜์—ˆ์Šต๋‹ˆ๋‹ค. ์ดํ›„ v2.1.126 (2026๋…„ 5์›” 1์ผ)์€ ๋‹ค์Œ ์•ˆ์ •์ ์ธ ๋ชฉํ‘œ์ด๋ฉฐ ์œ„ v2.1.126 ํ•ญ๋ชฉ์—์„œ ๋‹ค๋ฃจ๊ณ  ์žˆ์Šต๋‹ˆ๋‹ค. + +### ์ถ”๊ฐ€๋จ (์˜๋ฌธ ๋ฌธ์„œ) + +- ๋„ค์ดํ‹ฐ๋ธŒ ๋ฐ”์ด๋„ˆ๋ฆฌ ํŒจํ‚ค์ง• ์ฐธ๊ณ  ์‚ฌํ•ญ (v2.1.113) โ€” CLI๋Š” ์ด์ œ ํ”Œ๋žซํผ๋ณ„ ๋„ค์ดํ‹ฐ๋ธŒ ๋ฐ”์ด๋„ˆ๋ฆฌ๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. +- ๋„ค์ดํ‹ฐ๋ธŒ macOS/Linux ๋นŒ๋“œ์—์„œ `bfs`/`ugrep` Glob/Grep ๋Œ€์ฒด ๊ฐ์ฃผ (v2.1.117) +- ์˜ˆ์ œ์™€ ํ•จ๊ป˜ `mcp_tool` ํ›… ์œ ํ˜• (v2.1.118) +- PostToolUse / PostToolUseFailure ์ž…๋ ฅ์˜ `duration_ms` ํ•„๋“œ (v2.1.119) +- `prUrlTemplate` ์„ค์ • (v2.1.119) ๋ฐ ํ™•์žฅ๋œ `--from-pr` ๊ณต๊ธ‰์ž ๋ชฉ๋ก (GitLab, Bitbucket) +- `cleanupPeriodDays` ํ™•์žฅ ๋ฒ”์œ„ (์ฒดํฌํฌ์ธํŠธ + ์ž‘์—… + ์…ธ ์Šค๋ƒ…์ƒท + ๋ฐฑ์—…, v2.1.117) +- ๋ชจ๋“  ๋ผ์ดํ”„์‚ฌ์ดํด ์ด๋ฒคํŠธ์—์„œ ํ”Œ๋Ÿฌ๊ทธ์ธ ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ๊ฐ•์ œ ์ ์šฉ (v2.1.117) ๋ฐ `hostPattern`/`pathPattern` ์ •๊ทœ์‹ (v2.1.119) +- ์ƒˆ๋กœ์šด ํ™˜๊ฒฝ ๋ณ€์ˆ˜: `DISABLE_UPDATES`, `CLAUDE_CODE_HIDE_CWD`, `CLAUDE_CODE_FORK_SUBAGENT`, `OTEL_LOG_TOOL_DETAILS`, `ENABLE_TOOL_SEARCH` Vertex ์„ ํƒ์  ์ฐธ์—ฌ +- ์ƒˆ๋กœ์šด ์Šฌ๋ž˜์‹œ ๋ช…๋ น: `/btw`, ์‚ฌ์šฉ์ž ์ •์˜ ํ…Œ๋งˆ๋ฅผ ํฌํ•จํ•œ `/theme` +- `/usage` ํ‘œ์ค€ ๋ช…๋ น ( `/cost` + `/stats` ๋ณ‘ํ•ฉ, v2.1.118) +- ํฌํฌ๋œ ์„œ๋ธŒ ์—์ด์ „ํŠธ (`CLAUDE_CODE_FORK_SUBAGENT=1`, v2.1.117) +- ์ž๋™ ๋ชจ๋“œ `"$defaults"` ํ† ํฐ (v2.1.118) +- `wslInheritsWindowsSettings` ๊ด€๋ฆฌ ์ •์ฑ… (v2.1.118) +- Vim ์‹œ๊ฐ/์‹œ๊ฐ-๋ผ์ธ ๋ชจ๋“œ (v2.1.118) +- `claude install [version]` ๋ฐ `claude plugin tag` ์„œ๋ธŒ์ปค๋งจ๋“œ + +### ๋ณ€๊ฒฝ๋จ + +- ๋ฌธ์„œ ํ˜ธ์ŠคํŠธ๊ฐ€ ์ด์ „๋˜์—ˆ์Šต๋‹ˆ๋‹ค: `docs.anthropic.com/en/docs/claude-code/*` โ†’ `code.claude.com/docs/en/*` +- Opus 4.7 ๋…ธ๋ ฅ ์ˆ˜์ค€: `xhigh`๋Š” 2026๋…„ 4์›” 16์ผ ์ถœ์‹œ ์ดํ›„ Claude Code์˜ ๊ธฐ๋ณธ๊ฐ’์ด ๋˜์—ˆ์Šต๋‹ˆ๋‹ค. Opus 4.7 ๋„ค์ดํ‹ฐ๋ธŒ ์ปจํ…์ŠคํŠธ ์ฐฝ์€ 1M์œผ๋กœ ํ™•์ธ๋˜์—ˆ์Šต๋‹ˆ๋‹ค (v2.1.117์—์„œ `/context`๊ฐ€ 200K๋กœ ์ž˜๋ชป ๊ณ„์‚ฐํ•˜๋˜ ๋ฌธ์ œ ์ˆ˜์ •). +- Pro/Max ๊ตฌ๋…์ž์˜ Opus 4.6 / Sonnet 4.6 ๊ธฐ๋ณธ ๋…ธ๋ ฅ ์ˆ˜์ค€์ด `medium`์—์„œ `high`๋กœ ์ƒํ–ฅ ์กฐ์ •๋˜์—ˆ์Šต๋‹ˆ๋‹ค (v2.1.117). +- `STYLE_GUIDE.md`์˜ ์†Œ์Šค URL์ด Claude Apps ๋ฌธ์„œ์—์„œ `code.claude.com/docs/en/changelog`๋กœ ์—…๋ฐ์ดํŠธ๋˜์—ˆ์Šต๋‹ˆ๋‹ค. + +### ์‚ฌ์šฉ ์ค‘๋‹จ๋จ (์ถ”์  ์ค‘, ์ œ๊ฑฐ๋˜์ง€ ์•Š์Œ) + +- `includeCoAuthoredBy` ์„ค์ • โ†’ `attribution.commit` / `attribution.pr` ์‚ฌ์šฉ +- `voiceEnabled` ์„ค์ • โ†’ `voice.enabled` ์‚ฌ์šฉ + +### ๋ฒˆ์—ญ ๊ด€๋ฆฌ์ž๋ฅผ ์œ„ํ•œ ์ฐธ๊ณ  ์‚ฌํ•ญ + +`vi/`, `zh/`, `uk/` ๋กœ์ปฌ๋ผ์ด์ฆˆ๋œ ํŠธ๋ฆฌ๋Š” ์ปค๋ฎค๋‹ˆํ‹ฐ์—์„œ ์œ ์ง€ ๊ด€๋ฆฌ๋˜๋ฉฐ ์˜์–ด ์›๋ณธ๋ณด๋‹ค ์ง€์—ฐ๋  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ๋ฒˆ์—ญ์„ ๋™๊ธฐํ™”ํ•˜๋Š” ๊ธฐ์—ฌ์ž๋Š” ์ด ๋ฆด๋ฆฌ์Šค์—์„œ ์—…๋ฐ์ดํŠธ๋œ ์˜์–ด ํŒŒ์ผ๊ณผ ์ฐจ์ด์ ์„ ๋น„๊ตํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. + +## v2.1.112 โ€” 2026-04-16 + +### ์ฃผ์š” ๋ณ€๊ฒฝ ์‚ฌํ•ญ + +- ๋ชจ๋“  ์˜์–ด ํŠœํ† ๋ฆฌ์–ผ์„ Claude Code v2.1.112 ๋ฐ ์ƒˆ๋กœ์šด Opus 4.7 ๋ชจ๋ธ(`claude-opus-4-7`)๊ณผ ๋™๊ธฐํ™”ํ–ˆ์Šต๋‹ˆ๋‹ค. ์—ฌ๊ธฐ์—๋Š” ์ƒˆ๋กœ์šด `xhigh` ๋…ธ๋ ฅ ์ˆ˜์ค€(Opus 4.7์˜ ๊ธฐ๋ณธ๊ฐ’์œผ๋กœ `high`์™€ `max` ์‚ฌ์ด), ๋‘ ๊ฐ€์ง€ ์ƒˆ๋กœ์šด ๋‚ด์žฅ ์Šฌ๋ž˜์‹œ ๋ช…๋ น(`/ultrareview`, `/less-permission-prompts`), Opus 4.7 Max ๊ตฌ๋…์ž์—๊ฒŒ ๋” ์ด์ƒ `--enable-auto-mode`๊ฐ€ ํ•„์š” ์—†๋Š” ์ž๋™ ๋ชจ๋“œ, Windows์˜ PowerShell ๋„๊ตฌ, "์ž๋™(ํ„ฐ๋ฏธ๋„ ์ผ์น˜)" ํ…Œ๋งˆ, ๊ทธ๋ฆฌ๊ณ  ํ”„๋กฌํ”„ํŠธ ์ด๋ฆ„์„ ๋”ฐ์„œ ๋ช…๋ช…๋œ ๊ณ„ํš ํŒŒ์ผ์ด ํฌํ•จ๋ฉ๋‹ˆ๋‹ค. ๋ชจ๋“  18๊ฐœ EN ๋ฌธ์„œ ํ‘ธํ„ฐ๋Š” Claude Code v2.1.112๋กœ ์—…๋ฐ์ดํŠธ๋˜์—ˆ์Šต๋‹ˆ๋‹ค. @Luong NGUYEN + +### ๊ธฐ๋Šฅ + +- ๋ชจ๋“  ๋ชจ๋“ˆ, ์ตœ์ƒ์œ„ ๋ฌธ์„œ, ์˜ˆ์ œ ๋ฐ ์ฐธ์กฐ์— ๊ฑธ์ณ ์™„์ „ํ•œ ์šฐํฌ๋ผ์ด๋‚˜์–ด(uk) ํ˜„์ง€ํ™” ์ถ”๊ฐ€ (039dde2) @Evgenij I + +### ๋ฒ„๊ทธ ์ˆ˜์ • + +- pre-tool-check.sh ํ›… ํ”„๋กœํ† ์ฝœ ๋ฒ„๊ทธ ์ˆ˜์ • (bce7cf8) @yarlinghe +- CI ํ†ต๊ณผ๋ฅผ ์œ„ํ•ด ์ž˜๋ชป๋œ ๋จธ๋ฉ”์ด๋“œ ์˜ˆ์ œ๋ฅผ ํ…์ŠคํŠธ ๋ธ”๋ก์œผ๋กœ ๋ณ€๊ฒฝ (b8a7b1f) @Evgenij I +- ์šฐํฌ๋ผ์ด๋‚˜์–ด claude_concepts_guide.md ToC์˜ CP1251 ์ธ์ฝ”๋”ฉ ์ˆ˜์ • (d970cc6) @Evgenij I +- ์Šคํ… ์šฐํฌ๋ผ์ด๋‚˜์–ด README๋ฅผ ์ „์ฒด ๋ฒˆ์—ญ์œผ๋กœ ๊ต์ฒดํ•˜๊ณ  ๊นจ์ง„ ์•ต์ปค ์ˆ˜์ • (f6d73e2) @Evgenij I +- ๋ชจ๋“  ํ‘ธํ„ฐ์— Claude Code ๋ฒ„์ „์„ 2.1.97๋กœ ์ˆ˜์ • (63a1416) @Luong NGUYEN +- 2026-04-09 ๋ฌธ์„œ ์ •ํ™•์„ฑ ์—…๋ฐ์ดํŠธ ์ ์šฉ (e015f39) @Luong NGUYEN + +### ๋ฌธ์„œ + +- Claude Code v2.1.112 (Opus 4.7, `xhigh` ๋…ธ๋ ฅ, `/ultrareview`, `/less-permission-prompts`, PowerShell ๋„๊ตฌ, ์ž๋™ ์ผ์น˜ ํ„ฐ๋ฏธ๋„ ํ…Œ๋งˆ)์™€ ๋™๊ธฐํ™” @Luong NGUYEN +- Claude Code v2.1.110 (TUI, ํ‘ธ์‹œ ์•Œ๋ฆผ, ์„ธ์…˜ ์š”์•ฝ)๊ณผ ๋™๊ธฐํ™” (15f0085) @Luong NGUYEN +- `/team-onboarding`, `/ultraplan`, Monitor ๋„๊ตฌ์™€ ํ•จ๊ป˜ Claude Code v2.1.101๊ณผ ๋™๊ธฐํ™” (2deba3a) @Luong NGUYEN +- ๋ฒ ํŠธ๋‚จ์–ด ๋ฌธ์„œ๋ฅผ ์˜์–ด ์›๋ณธ๊ณผ ๋™๊ธฐํ™” (561c6cb) @Thiรชn Toรกn +- ๋ชจ๋“  ํŒŒ์ผ์˜ ์ตœ์ข… ์—…๋ฐ์ดํŠธ ๋‚ ์งœ ๋ฐ Claude Code ๋ฒ„์ „ ์—…๋ฐ์ดํŠธ (7f2e773) @Luong NGUYEN +- ์–ธ์–ด ์ „ํ™˜๊ธฐ์— ์šฐํฌ๋ผ์ด๋‚˜์–ด ๋งํฌ ์ถ”๊ฐ€ (9c224ff) @Luong NGUYEN +- ๊ธฐ์—ฌ์ž ์„น์…˜ ์ œ๊ฑฐ (f07313d) @Luong NGUYEN +- GitHub ์ง€ํ‘œ๋ฅผ 21,800๊ฐœ ์ด์ƒ์˜ ๋ณ„, 2,585๊ฐœ ์ด์ƒ์˜ ํฌํฌ๋กœ ์—…๋ฐ์ดํŠธ (4f55374) @Luong NGUYEN + +**์ „์ฒด ๋ณ€๊ฒฝ ๋กœ๊ทธ**: https://github.com/luongnv89/claude-howto/compare/v2.3.0...v2.1.112 + +--- + +## v2.3.0 โ€” 2026-04-07 + +### ๊ธฐ๋Šฅ + +- ์–ธ์–ด๋ณ„ EPUB ์•„ํ‹ฐํŒฉํŠธ ๋นŒ๋“œ ๋ฐ ๊ฒŒ์‹œ (90e9c30) @Thiรชn Toรกn +- 06-hooks์— ๋ˆ„๋ฝ๋œ pre-tool-check.sh ํ›… ์ถ”๊ฐ€ (b511ed1) @JiayuWang +- zh/ ๋””๋ ‰ํ† ๋ฆฌ์— ์ค‘๊ตญ์–ด ๋ฒˆ์—ญ ์ถ”๊ฐ€ (89e89d4) @Luong NGUYEN +- ์„ฑ๋Šฅ ์ตœ์ ํ™” ์„œ๋ธŒ ์—์ด์ „ํŠธ ๋ฐ ์ข…์†์„ฑ ํ™•์ธ ํ›… ์ถ”๊ฐ€ (f53d080) @qk + +### ๋ฒ„๊ทธ ์ˆ˜์ • + +- Windows Git Bash ํ˜ธํ™˜์„ฑ + stdin JSON ํ”„๋กœํ† ์ฝœ ์ˆ˜์ • (2cbb10c) @Luong NGUYEN +- 08-checkpoints์˜ autoCheckpoint ๊ตฌ์„ฑ ๋ฌธ์„œ ์ˆ˜์ • (749c79f) @JiayuWang +- SVG ์ด๋ฏธ์ง€๋ฅผ ์ž๋ฆฌ ํ‘œ์‹œ์ž๋กœ ๋Œ€์ฒดํ•˜๋Š” ๋Œ€์‹  ์ž„๋ฒ ๋“œ (1b16709) @Thiรชn Toรกn +- ๋ฉ”๋ชจ๋ฆฌ README์˜ ์ค‘์ฒฉ ์ฝ”๋“œ ํŽœ์Šค ๋ Œ๋”๋ง ์ˆ˜์ • (ce24423) @Zhaoshan Duan +- ์Šค์ฟผ์‹œ ๋ณ‘ํ•ฉ์œผ๋กœ ๋ˆ„๋ฝ๋œ ๊ฒ€ํ†  ์ˆ˜์ • ์‚ฌํ•ญ ์ ์šฉ (34259ca) @Luong NGUYEN +- ํ›… ์Šคํฌ๋ฆฝํŠธ๊ฐ€ Windows Git Bash์™€ ํ˜ธํ™˜๋˜๋„๋ก ํ•˜๊ณ  stdin JSON ํ”„๋กœํ† ์ฝœ ์‚ฌ์šฉ (107153d) @binyu li + +### ๋ฌธ์„œ + +- ๋ชจ๋“  ํŠœํ† ๋ฆฌ์–ผ์„ ์ตœ์‹  Claude Code ๋ฌธ์„œ(2026๋…„ 4์›”)์™€ ๋™๊ธฐํ™” (72d3b01) @Luong NGUYEN +- ์–ธ์–ด ์ „ํ™˜๊ธฐ์— ์ค‘๊ตญ์–ด ๋งํฌ ์ถ”๊ฐ€ (6cbaa4d) @Luong NGUYEN +- ์˜์–ด์™€ ๋ฒ ํŠธ๋‚จ์–ด ๊ฐ„ ์–ธ์–ด ์ „ํ™˜๊ธฐ ์ถ”๊ฐ€ (100c45e) @Luong NGUYEN +- GitHub #1 Trending ๋ฐฐ์ง€ ์ถ”๊ฐ€ (0ca8c37) @Luong NGUYEN +- ์ปจํ…์ŠคํŠธ ์˜์—ญ ๋ชจ๋‹ˆํ„ฐ๋ง์„ ์œ„ํ•œ cc-context-stats ์†Œ๊ฐœ (d41b335) @Luong NGUYEN +- luongnv89/skills ์ปฌ๋ ‰์…˜ ๋ฐ luongnv89/asm ์Šคํ‚ฌ ๊ด€๋ฆฌ์ž ์†Œ๊ฐœ (7e3c0b6) @Luong NGUYEN +- ํ˜„์žฌ GitHub ์ง€ํ‘œ(5,900๊ฐœ ์ด์ƒ์˜ ๋ณ„, 690๊ฐœ ์ด์ƒ์˜ ํฌํฌ)๋ฅผ ๋ฐ˜์˜ํ•˜๋„๋ก README ํ†ต๊ณ„ ์—…๋ฐ์ดํŠธ (5001525) @Luong NGUYEN +- ํ˜„์žฌ GitHub ์ง€ํ‘œ(3,900๊ฐœ ์ด์ƒ์˜ ๋ณ„, 460๊ฐœ ์ด์ƒ์˜ ํฌํฌ)๋ฅผ ๋ฐ˜์˜ํ•˜๋„๋ก README ํ†ต๊ณ„ ์—…๋ฐ์ดํŠธ (9cb92d6) @Luong NGUYEN + +### ๋ฆฌํŒฉํ† ๋ง + +- Kroki HTTP ์ข…์†์„ฑ์„ ๋กœ์ปฌ mmdc ๋ Œ๋”๋ง์œผ๋กœ ๋Œ€์ฒด (e76bbe4) @Luong NGUYEN +- ํ’ˆ์งˆ ๊ฒ€์‚ฌ๋ฅผ pre-commit์œผ๋กœ ์ด๋™, CI๋Š” 2์ฐจ ํ†ต๊ณผ๋กœ ์‚ฌ์šฉ (6d1e0ae) @Luong NGUYEN +- ์ž๋™ ๋ชจ๋“œ ๊ถŒํ•œ ๊ธฐ์ค€์„  ์ขํžˆ๊ธฐ (2790fb2) @Luong NGUYEN +- auto-adapt ํ›…์„ ์ผํšŒ์„ฑ ๊ถŒํ•œ ์„ค์ • ์Šคํฌ๋ฆฝํŠธ๋กœ ๊ต์ฒด (995a5d6) @Luong NGUYEN + +### ๊ธฐํƒ€ + +- ํ’ˆ์งˆ ๊ฒŒ์ดํŠธ๋ฅผ ์™ผ์ชฝ์œผ๋กœ ์ด๋™ โ€” mypy๋ฅผ pre-commit์— ์ถ”๊ฐ€ํ•˜๊ณ  CI ์‹คํŒจ ์ˆ˜์ • (699fb39) @Luong NGUYEN +- ๋ฒ ํŠธ๋‚จ์–ด (Tiแบฟng Viแป‡t) ํ˜„์ง€ํ™” ์ถ”๊ฐ€ (a70777e) @Thiรชn Toรกn + +**์ „์ฒด ๋ณ€๊ฒฝ ๋กœ๊ทธ**: https://github.com/luongnv89/claude-howto/compare/v2.2.0...v2.3.0 + +--- + +## v2.2.0 โ€” 2026-03-26 + +### ๋ฌธ์„œ + +- ๋ชจ๋“  ํŠœํ† ๋ฆฌ์–ผ ๋ฐ ์ฐธ์กฐ๋ฅผ Claude Code v2.1.84์™€ ๋™๊ธฐํ™” (f78c094) @luongnv89 + - ์Šฌ๋ž˜์‹œ ๋ช…๋ น์„ 55๊ฐœ ์ด์ƒ์˜ ๋‚ด์žฅ + 5๊ฐœ์˜ ๋ฒˆ๋“ค ์Šคํ‚ฌ๋กœ ์—…๋ฐ์ดํŠธํ•˜๊ณ , 3๊ฐœ๋Š” ์‚ฌ์šฉ ์ค‘๋‹จ๋จ์œผ๋กœ ํ‘œ์‹œ + - ํ›… ์ด๋ฒคํŠธ๋ฅผ 18๊ฐœ์—์„œ 25๊ฐœ๋กœ ํ™•์žฅํ•˜๊ณ , `agent` ํ›… ์œ ํ˜• ์ถ”๊ฐ€ (ํ˜„์žฌ 4๊ฐœ ์œ ํ˜•) + - ๊ณ ๊ธ‰ ๊ธฐ๋Šฅ์— ์ž๋™ ๋ชจ๋“œ, ์ฑ„๋„, ์Œ์„ฑ ๋ฐ›์•„์“ฐ๊ธฐ ์ถ”๊ฐ€ + - `effort`, `shell` ์Šคํ‚ฌ ํ”„๋ก ํŠธ๋งคํ„ฐ ํ•„๋“œ ์ถ”๊ฐ€; `initialPrompt`, `disallowedTools` ์—์ด์ „ํŠธ ํ•„๋“œ ์ถ”๊ฐ€ + - WebSocket MCP ์ „์†ก, ์œ ๋„, 2KB ๋„๊ตฌ ์ œํ•œ ์ถ”๊ฐ€ + - ํ”Œ๋Ÿฌ๊ทธ์ธ LSP ์ง€์›, `userConfig`, `${CLAUDE_PLUGIN_DATA}` ์ถ”๊ฐ€ + - ๋ชจ๋“  ์ฐธ์กฐ ๋ฌธ์„œ(CATALOG, QUICK_REFERENCE, LEARNING-ROADMAP, INDEX) ์—…๋ฐ์ดํŠธ +- README๋ฅผ ๋žœ๋”ฉ ํŽ˜์ด์ง€ ๊ตฌ์กฐํ™”๋œ ๊ฐ€์ด๋“œ๋กœ ์žฌ์ž‘์„ฑ (32a0776) @luongnv89 + +### ๋ฒ„๊ทธ ์ˆ˜์ • + +- CI ์ค€์ˆ˜๋ฅผ ์œ„ํ•ด ๋ˆ„๋ฝ๋œ cSpell ๋‹จ์–ด ๋ฐ README ์„น์…˜ ์ถ”๊ฐ€ (93f9d51) @luongnv89 +- cSpell ์‚ฌ์ „์— `Sandboxing` ์ถ”๊ฐ€ (b80ce6f) @luongnv89 + +**์ „์ฒด ๋ณ€๊ฒฝ ๋กœ๊ทธ**: https://github.com/luongnv89/claude-howto/compare/v2.1.1...v2.2.0 + +--- + +## v2.1.1 โ€” 2026-03-13 + +### ๋ฒ„๊ทธ ์ˆ˜์ • + +- CI ๋งํฌ ๊ฒ€์‚ฌ ์‹คํŒจ์˜ ์›์ธ์ด ๋˜๋Š” ์ฃฝ์€ ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ๋งํฌ ์ œ๊ฑฐ (3fdf0d6) @luongnv89 +- cSpell ์‚ฌ์ „์— `sandboxed` ๋ฐ `pycache` ์ถ”๊ฐ€ (dc64618) @luongnv89 + +**์ „์ฒด ๋ณ€๊ฒฝ ๋กœ๊ทธ**: https://github.com/luongnv89/claude-howto/compare/v2.1.0...v2.1.1 + +--- + +## v2.1.0 โ€” 2026-03-13 + +### ๊ธฐ๋Šฅ + +- ์ž๊ธฐ ํ‰๊ฐ€ ๋ฐ ๋ ˆ์Šจ ํ€ด์ฆˆ ์Šคํ‚ฌ์„ ํ†ตํ•œ ์ ์‘ํ˜• ํ•™์Šต ๊ฒฝ๋กœ ์ถ”๊ฐ€ (1ef46cd) @luongnv89 + - `/self-assessment` โ€” 10๊ฐ€์ง€ ๊ธฐ๋Šฅ ์˜์—ญ์— ๊ฑธ์นœ ๋Œ€ํ™”ํ˜• ์ˆ™๋ จ๋„ ํ€ด์ฆˆ์™€ ๊ฐœ์ธํ™”๋œ ํ•™์Šต ๊ฒฝ๋กœ + - `/lesson-quiz [lesson]` โ€” 8-10๊ฐœ์˜ ๋ชฉํ‘œ ์งˆ๋ฌธ์œผ๋กœ ๊ตฌ์„ฑ๋œ ๋ ˆ์Šจ๋ณ„ ์ง€์‹ ํ™•์ธ + +### ๋ฒ„๊ทธ ์ˆ˜์ • + +- ๊นจ์ง„ URL, ์‚ฌ์šฉ ์ค‘๋‹จ๋œ ํ•ญ๋ชฉ, ์˜ค๋ž˜๋œ ์ฐธ์กฐ ์—…๋ฐ์ดํŠธ (8fe4520) @luongnv89 +- ๋ฆฌ์†Œ์Šค ๋ฐ ์ž๊ธฐ ํ‰๊ฐ€ ์Šคํ‚ฌ์˜ ๊นจ์ง„ ๋งํฌ ์ˆ˜์ • (7a05863) @luongnv89 +- ๊ฐœ๋… ๊ฐ€์ด๋“œ์˜ ์ค‘์ฒฉ ์ฝ”๋“œ ๋ธ”๋ก์— ๋ฌผ๊ฒฐํ‘œ ํŽœ์Šค ์‚ฌ์šฉ (5f82719) @VikalpP +- cSpell ์‚ฌ์ „์— ๋ˆ„๋ฝ๋œ ๋‹จ์–ด ์ถ”๊ฐ€ (8df7572) @luongnv89 + +### ๋ฌธ์„œ + +- 5๋‹จ๊ณ„ QA โ€” ๋ฌธ์„œ ์ „์ฒด์˜ ์ผ๊ด€์„ฑ, URL ๋ฐ ์šฉ์–ด ์ˆ˜์ • (00bbe4c) @luongnv89 +- 3-4๋‹จ๊ณ„ ์™„๋ฃŒ โ€” ์ƒˆ๋กœ์šด ๊ธฐ๋Šฅ ์ ์šฉ ๋ฒ”์œ„ ๋ฐ ์ฐธ์กฐ ๋ฌธ์„œ ์—…๋ฐ์ดํŠธ (132de29) @luongnv89 +- MCP ์ปจํ…์ŠคํŠธ ์˜ค๋ฒ„๋กœ๋“œ ์„น์…˜์— MCPorter ๋Ÿฐํƒ€์ž„ ์ถ”๊ฐ€ (ef52705) @luongnv89 +- 6๊ฐœ ๊ฐ€์ด๋“œ์— ๊ฑธ์ณ ๋ˆ„๋ฝ๋œ ๋ช…๋ น, ๊ธฐ๋Šฅ ๋ฐ ์„ค์ • ์ถ”๊ฐ€ (4bc8f15) @luongnv89 +- ๊ธฐ์กด ๋ฆฌํฌ์ง€ํ† ๋ฆฌ ๊ทœ์น™์„ ๊ธฐ๋ฐ˜์œผ๋กœ ์Šคํƒ€์ผ ๊ฐ€์ด๋“œ ์ถ”๊ฐ€ (84141d0) @luongnv89 +- ๊ฐ€์ด๋“œ ๋น„๊ต ํ‘œ์— ์ž๊ธฐ ํ‰๊ฐ€ ํ–‰ ์ถ”๊ฐ€ (8fe0c96) @luongnv89 +- PR #7์— ๋Œ€ํ•œ ๊ธฐ์—ฌ์ž ๋ชฉ๋ก์— VikalpP ์ถ”๊ฐ€ (d5b4350) @luongnv89 +- README ๋ฐ ๋กœ๋“œ๋งต์— ์ž๊ธฐ ํ‰๊ฐ€ ๋ฐ ๋ ˆ์Šจ ํ€ด์ฆˆ ์Šคํ‚ฌ ์ฐธ์กฐ ์ถ”๊ฐ€ (d5a6106) @luongnv89 + +### ์ƒˆ๋กœ์šด ๊ธฐ์—ฌ์ž + +- @VikalpP ๋‹˜์ด #7์—์„œ ์ฒซ ๊ธฐ์—ฌ๋ฅผ ํ–ˆ์Šต๋‹ˆ๋‹ค. + +**์ „์ฒด ๋ณ€๊ฒฝ ๋กœ๊ทธ**: https://github.com/luongnv89/claude-howto/compare/v2.0.0...v2.1.0 + +--- + +## v2.0.0 โ€” 2026-02-01 + +### ๊ธฐ๋Šฅ + +- ๋ชจ๋“  ๋ฌธ์„œ๋ฅผ Claude Code 2026๋…„ 2์›” ๊ธฐ๋Šฅ๊ณผ ๋™๊ธฐํ™” (487c96d) + - 10๊ฐœ ํŠœํ† ๋ฆฌ์–ผ ๋””๋ ‰ํ† ๋ฆฌ์™€ 7๊ฐœ ์ฐธ์กฐ ๋ฌธ์„œ์— ๊ฑธ์ณ 26๊ฐœ ํŒŒ์ผ ์—…๋ฐ์ดํŠธ + - **์ž๋™ ๋ฉ”๋ชจ๋ฆฌ** โ€” ํ”„๋กœ์ ํŠธ๋ณ„ ์˜๊ตฌ ํ•™์Šต ๊ธฐ๋Šฅ ๋ฌธ์„œ ์ถ”๊ฐ€ + - **์›๊ฒฉ ์ œ์–ด**, **์›น ์„ธ์…˜**, **๋ฐ์Šคํฌํ†ฑ ์•ฑ** ๋ฌธ์„œ ์ถ”๊ฐ€ + - **์—์ด์ „ํŠธ ํŒ€** (์‹คํ—˜์  ๋‹ค์ค‘ ์—์ด์ „ํŠธ ํ˜‘์—…) ๋ฌธ์„œ ์ถ”๊ฐ€ + - **MCP OAuth 2.0**, **๋„๊ตฌ ๊ฒ€์ƒ‰**, **Claude.ai ์ปค๋„ฅํ„ฐ** ๋ฌธ์„œ ์ถ”๊ฐ€ + - ์„œ๋ธŒ ์—์ด์ „ํŠธ์šฉ **์˜๊ตฌ ๋ฉ”๋ชจ๋ฆฌ** ๋ฐ **์ž‘์—… ํŠธ๋ฆฌ ๊ฒฉ๋ฆฌ** ๋ฌธ์„œ ์ถ”๊ฐ€ + - **๋ฐฑ๊ทธ๋ผ์šด๋“œ ์„œ๋ธŒ ์—์ด์ „ํŠธ**, **์ž‘์—… ๋ชฉ๋ก**, **ํ”„๋กฌํ”„ํŠธ ์ œ์•ˆ** ๋ฌธ์„œ ์ถ”๊ฐ€ + - **์ƒŒ๋“œ๋ฐ•์‹ฑ** ๋ฐ **๊ด€๋ฆฌ ์„ค์ •** (์—”ํ„ฐํ”„๋ผ์ด์ฆˆ) ๋ฌธ์„œ ์ถ”๊ฐ€ + - **HTTP ํ›…** ๋ฐ 7๊ฐ€์ง€ ์ƒˆ๋กœ์šด ํ›… ์ด๋ฒคํŠธ ๋ฌธ์„œ ์ถ”๊ฐ€ + - **ํ”Œ๋Ÿฌ๊ทธ์ธ ์„ค์ •**, **LSP ์„œ๋ฒ„**, ๋งˆ์ผ“ํ”Œ๋ ˆ์ด์Šค ์—…๋ฐ์ดํŠธ ๋ฌธ์„œ ์ถ”๊ฐ€ + - **์ฒดํฌํฌ์ธํŠธ์—์„œ ์š”์•ฝ** ๋˜๊ฐ๊ธฐ ์˜ต์…˜ ๋ฌธ์„œ ์ถ”๊ฐ€ + - 17๊ฐ€์ง€ ์ƒˆ๋กœ์šด ์Šฌ๋ž˜์‹œ ๋ช…๋ น(`/fork`, `/desktop`, `/teleport`, `/tasks`, `/fast` ๋“ฑ) ๋ฌธ์„œํ™” + - ์ƒˆ๋กœ์šด CLI ํ”Œ๋ž˜๊ทธ(`--worktree`, `--from-pr`, `--remote`, `--teleport`, `--teammate-mode` ๋“ฑ) ๋ฌธ์„œํ™” + - ์ž๋™ ๋ฉ”๋ชจ๋ฆฌ, ๋…ธ๋ ฅ ์ˆ˜์ค€, ์—์ด์ „ํŠธ ํŒ€ ๋“ฑ์„ ์œ„ํ•œ ์ƒˆ๋กœ์šด ํ™˜๊ฒฝ ๋ณ€์ˆ˜ ๋ฌธ์„œํ™” + +### ๋””์ž์ธ + +- ๋กœ๊ณ ๋ฅผ ์ตœ์†Œํ•œ์˜ ํŒ”๋ ˆํŠธ๋ฅผ ๊ฐ€์ง„ ์ปดํŒจ์Šค-๊ด„ํ˜ธ ๋ชจ์–‘์œผ๋กœ ์žฌ๋””์ž์ธ (20779db) + +### ๋ฒ„๊ทธ ์ˆ˜์ • / ์ •์ • + +- ๋ชจ๋ธ ์ด๋ฆ„ ์—…๋ฐ์ดํŠธ: Sonnet 4.5 โ†’ **Sonnet 4.6**, Opus 4.5 โ†’ **Opus 4.6** +- ๊ถŒํ•œ ๋ชจ๋“œ ์ด๋ฆ„ ์ˆ˜์ •: ๊ฐ€์ƒ์˜ "Unrestricted/Confirm/Read-only"๋ฅผ ์‹ค์ œ `default`/`acceptEdits`/`plan`/`dontAsk`/`bypassPermissions`๋กœ ๊ต์ฒด +- ํ›… ์ด๋ฒคํŠธ ์ˆ˜์ •: ๊ฐ€์ƒ์˜ `PreCommit`/`PostCommit`/`PrePush`๋ฅผ ์ œ๊ฑฐํ•˜๊ณ  ์‹ค์ œ ์ด๋ฒคํŠธ(`SubagentStart`, `WorktreeCreate`, `ConfigChange` ๋“ฑ) ์ถ”๊ฐ€ +- CLI ๊ตฌ๋ฌธ ์ˆ˜์ •: `claude-code --headless`๋ฅผ `claude -p` (์ธ์‡„ ๋ชจ๋“œ)๋กœ ๊ต์ฒด +- ์ฒดํฌํฌ์ธํŠธ ๋ช…๋ น ์ˆ˜์ •: ๊ฐ€์ƒ์˜ `/checkpoint save/list/rewind/diff`๋ฅผ ์‹ค์ œ `Esc+Esc` / `/rewind` ์ธํ„ฐํŽ˜์ด์Šค๋กœ ๊ต์ฒด +- ์„ธ์…˜ ๊ด€๋ฆฌ ์ˆ˜์ •: ๊ฐ€์ƒ์˜ `/session list/new/switch/save`๋ฅผ ์‹ค์ œ `/resume`/`/rename`/`/fork`๋กœ ๊ต์ฒด +- ํ”Œ๋Ÿฌ๊ทธ์ธ ๋งค๋‹ˆํŽ˜์ŠคํŠธ ํ˜•์‹ ์ˆ˜์ •: `plugin.yaml` โ†’ `.claude-plugin/plugin.json`์œผ๋กœ ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ +- MCP ๊ตฌ์„ฑ ๊ฒฝ๋กœ ์ˆ˜์ •: `~/.claude/mcp.json` โ†’ `.mcp.json` (ํ”„๋กœ์ ํŠธ) / `~/.claude.json` (์‚ฌ์šฉ์ž) +- ๋ฌธ์„œ URL ์ˆ˜์ •: `docs.claude.com` โ†’ `docs.anthropic.com`; ๊ฐ€์ƒ์˜ `plugins.claude.com` ์ œ๊ฑฐ +- ์—ฌ๋Ÿฌ ํŒŒ์ผ์—์„œ ๊ฐ€์ƒ์˜ ๊ตฌ์„ฑ ํ•„๋“œ ์ œ๊ฑฐ +- ๋ชจ๋“  "์ตœ์ข… ์—…๋ฐ์ดํŠธ" ๋‚ ์งœ๋ฅผ 2026๋…„ 2์›”๋กœ ์—…๋ฐ์ดํŠธ + +**์ „์ฒด ๋ณ€๊ฒฝ ๋กœ๊ทธ**: https://github.com/luongnv89/claude-howto/compare/20779db...v2.0.0 diff --git a/ko/CODE_OF_CONDUCT.md b/ko/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..2e923e08 --- /dev/null +++ b/ko/CODE_OF_CONDUCT.md @@ -0,0 +1,222 @@ +# ๊ธฐ์—ฌ์ž ํ–‰๋™ ๊ฐ•๋ น + +## ์šฐ๋ฆฌ์˜ ์•ฝ์† + +์šฐ๋ฆฌ๋Š” ๋ชจ๋‘๋ฅผ ์œ„ํ•œ ํ™˜์˜๋ฐ›๊ณ  ์˜๊ฐ์„ ์ฃผ๋Š” ์ปค๋ฎค๋‹ˆํ‹ฐ๋ฅผ ์ œ๊ณตํ•˜๊ธฐ ์œ„ํ•ด ๋…ธ๋ ฅํ•ฉ๋‹ˆ๋‹ค. ์šฐ๋ฆฌ๋Š” ์—ฐ๋ น, ์ฒด๊ฒฉ, ๊ณ„๊ธ‰, ์žฅ์• , ๋ฏผ์กฑ์„ฑ, ์„ฑ์  ํŠน์„ฑ, ์„ฑ ์ •์ฒด์„ฑ ๋ฐ ํ‘œํ˜„, ๊ฒฝํ—˜ ์ˆ˜์ค€, ๊ต์œก ์ˆ˜์ค€, ์‚ฌํšŒ๊ฒฝ์ œ์  ์ง€์œ„, ๊ตญ์ , ์™ธ๋ชจ, ์ธ์ข…, ์ข…๊ต ๋˜๋Š” ์„ฑ์  ์ •์ฒด์„ฑ๊ณผ ์ง€ํ–ฅ์— ๊ด€๊ณ„์—†์ด ๋ˆ„๊ตฌ๋‚˜ ๊ดด๋กญํž˜ ์—†์ด ์ปค๋ฎค๋‹ˆํ‹ฐ์— ์ฐธ์—ฌํ•  ์ˆ˜ ์žˆ๋„๋ก ์•ฝ์†ํ•ฉ๋‹ˆ๋‹ค. + +์šฐ๋ฆฌ๋Š” ๋ชจ๋“  ๊ธฐ์—ฌ์ž๊ฐ€ ์กด์ค‘๋ฐ›๊ณ , ๊ฐ€์น˜ ์žˆ๊ฒŒ ์—ฌ๊ฒจ์ง€๋ฉฐ, ์ž์‹ ์˜ ์—ญ๋Ÿ‰์„ ์ตœ๋Œ€ํ•œ ๋ฐœํœ˜ํ•  ์ˆ˜ ์žˆ๋Š” ๊ธ์ •์ ์ด๊ณ  ํฌ์šฉ์ ์ด๋ฉฐ ์•ˆ์ „ํ•œ ํ™˜๊ฒฝ์„ ์ œ๊ณตํ•˜๊ธฐ ์œ„ํ•ด ์ตœ์„ ์„ ๋‹คํ•ฉ๋‹ˆ๋‹ค. + +## ์šฐ๋ฆฌ์˜ ๊ธฐ์ค€ + +๊ธ์ •์ ์ธ ํ™˜๊ฒฝ์„ ๋งŒ๋“œ๋Š” ๋ฐ ๊ธฐ์—ฌํ•˜๋Š” ํ–‰๋™์˜ ์˜ˆ์‹œ๋Š” ๋‹ค์Œ๊ณผ ๊ฐ™์Šต๋‹ˆ๋‹ค. + +### ์กด์ค‘ํ•˜๊ธฐ +- ํ™˜์˜ํ•˜๊ณ  ํฌ์šฉ์ ์ธ ์–ธ์–ด๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +- ์„œ๋กœ ๋‹ค๋ฅธ ์˜๊ฒฌ, ๊ด€์ , ๊ฒฝํ—˜์„ ์กด์ค‘ํ•ฉ๋‹ˆ๋‹ค. +- ๊ฑด์„ค์ ์ธ ๋น„ํŒ์„ ์—ด๋ฆฐ ์ž์„ธ๋กœ ๋ฐ›์•„๋“ค์ž…๋‹ˆ๋‹ค. +- ๋ฌธํ™”์ ยท์–ธ์–ด์  ์ฐจ์ด๋ฅผ ์กด์ค‘ํ•ฉ๋‹ˆ๋‹ค. +- ๋‹ค์–‘ํ•œ ๋ฐฐ๊ฒฝ์„ ์ธ์ •ํ•˜๊ณ  ์กด์ค‘ํ•ฉ๋‹ˆ๋‹ค. + +### ํ˜‘๋ ฅํ•˜๊ธฐ +- ๊ฐˆ๋“ฑ ํ•ด๊ฒฐ์„ ์œ„ํ•ด ํ•จ๊ป˜ ๋…ธ๋ ฅํ•ฉ๋‹ˆ๋‹ค. +- ๋‹ค๋ฅธ ์‚ฌ๋žŒ์˜ ๊ธฐ์—ฌ๋ฅผ ์ธ์ •ํ•˜๊ณ  ๊ณต๋กœ๋ฅผ ๋ถ€์—ฌํ•ฉ๋‹ˆ๋‹ค. +- ๋‹ค๋ฅธ ์‚ฌ๋žŒ๋“ค์ด ๋ฐฐ์šฐ๊ณ  ์„ฑ์žฅํ•  ์ˆ˜ ์žˆ๋„๋ก ๋•์Šต๋‹ˆ๋‹ค. +- ์ง€์‹์„ ๊ณต์œ ํ•˜๊ณ  ์ ๊ทน์ ์œผ๋กœ ์งˆ๋ฌธํ•ฉ๋‹ˆ๋‹ค. +- ์ปค๋ฎค๋‹ˆํ‹ฐ ๊ตฌ์„ฑ์›์„ ์ง€์›ํ•ฉ๋‹ˆ๋‹ค. + +### ์ „๋ฌธ์„ฑ ์œ ์ง€ํ•˜๊ธฐ +- ๋…ผ์˜๋ฅผ ์ƒ์‚ฐ์ ์ด๊ณ  ๋ชฉ์ ์— ๋งž๊ฒŒ ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. +- ๋น„ํ•˜ํ•˜๊ฑฐ๋‚˜ ๋ชจ์š•์ ์ธ ๋ฐœ์–ธ์„ ํ”ผํ•ฉ๋‹ˆ๋‹ค. +- ์ด์Šˆ์™€ ํ† ๋ก ์—์„œ ์ฃผ์ œ๋ฅผ ๋ฒ—์–ด๋‚˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. +- ๋ช…ํ™•ํ•˜๊ณ  ์กด์ค‘ํ•˜๋Š” ๋ฐฉ์‹์œผ๋กœ ์†Œํ†ตํ•ฉ๋‹ˆ๋‹ค. +- ๋‹ค๋ฅธ ์‚ฌ๋žŒ์˜ ๋ฉ”์‹œ์ง€์— ์„ ์˜๊ฐ€ ์žˆ๋‹ค๊ณ  ๊ฐ€์ •ํ•ฉ๋‹ˆ๋‹ค. + +### ํฌ์šฉ์„ฑ ์‹ค์ฒœํ•˜๊ธฐ +- ์ƒˆ๋กœ์šด ๊ธฐ์—ฌ์ž๋ฅผ ํ™˜์˜ํ•ฉ๋‹ˆ๋‹ค. +- ํ”„๋กœ์ ํŠธ์— ์ฒ˜์Œ ์ฐธ์—ฌํ•˜๋Š” ์‚ฌ๋žŒ๋“ค์˜ ์ ์‘์„ ๋•์Šต๋‹ˆ๋‹ค. +- ๊ฑด์„ค์ ์ธ ํ”ผ๋“œ๋ฐฑ์„ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. +- ๋‹ค์–‘ํ•œ ๊ด€์ ์„ ๊ฐ€์ง„ ์‚ฌ๋žŒ๋“ค์„ ํฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +- ์กฐ์šฉํ•œ ๋ชฉ์†Œ๋ฆฌ๋„ ๋“ค๋ฆด ์ˆ˜ ์žˆ๋Š” ํ™˜๊ฒฝ์„ ๋งŒ๋“ญ๋‹ˆ๋‹ค. + +## ํ—ˆ์šฉ๋˜์ง€ ์•Š๋Š” ํ–‰๋™ + +๋‹ค์Œ ํ–‰๋™์€ ๊ดด๋กญํž˜์œผ๋กœ ๊ฐ„์ฃผ๋˜๋ฉฐ ์ปค๋ฎค๋‹ˆํ‹ฐ ๋‚ด์—์„œ ํ—ˆ์šฉ๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. + +### ๊ดด๋กญํž˜ ๋ฐ ์ฐจ๋ณ„ +- ์„ฑ๋ณ„, ์„ฑ ์ •์ฒด์„ฑ ๋ฐ ํ‘œํ˜„, ์„ฑ์  ์ง€ํ–ฅ, ์žฅ์• , ์ •์‹  ์งˆํ™˜, ์‹ ๊ฒฝ๋‹ค์–‘์„ฑ, ์™ธ๋ชจ, ์ฒด๊ฒฉ, ๋‚˜์ด, ์ธ์ข… ๋˜๋Š” ์ข…๊ต์™€ ๊ด€๋ จ๋œ ๋ชจ์š•์ ์ธ ๋ฐœ์–ธ +- ๊ฐœ์ธ์˜ ์ƒํ™œ ๋ฐฉ์‹์ด๋‚˜ ์„ ํƒ์— ๋Œ€ํ•œ ์›์น˜ ์•Š๋Š” ๋น„๋‚œ ๋˜๋Š” ํ‰๊ฐ€ +- ์˜๋„์ ์œผ๋กœ ์ž˜๋ชป๋œ ์„ฑ๋ณ„ ํ˜ธ์นญ์„ ์‚ฌ์šฉํ•˜๊ฑฐ๋‚˜ ์‚ฌ์šฉ์ด ์ค‘๋‹จ๋œ ์ด๋ฆ„(dead name)์„ ์‚ฌ์šฉํ•˜๋Š” ํ–‰์œ„ +- ๋ถˆํ•„์š”ํ•˜๊ฑฐ๋‚˜ ์ฃผ์ œ์™€ ๋ฌด๊ด€ํ•œ ์„ฑ์  ์ด๋ฏธ์ง€ ๋˜๋Š” ํ–‰๋™ +- ๋™์˜ ์—†์ด ์ด๋ฃจ์–ด์ง€๋Š” ์‹ ์ฒด ์ ‘์ด‰ ๋˜๋Š” ์ค‘๋‹จ ์š”์ฒญ ์ดํ›„์—๋„ ๊ณ„์†๋˜๋Š” ์‹ ์ฒด ์ ‘์ด‰ ํ–‰์œ„ + +### ํ•™๋Œ€์  ํ–‰๋™ +- ํŠน์ •์ธ์„ ๋Œ€์ƒ์œผ๋กœ ํ•œ ํญ๋ ฅ ์œ„ํ˜‘ ๋˜๋Š” ํญ๋ ฅ์ ์ธ ์–ธ์–ด ์‚ฌ์šฉ +- ๊ฐœ์ธ์„ ํ–ฅํ•œ ํญ๋ ฅ ์„ ๋™ ๋˜๋Š” ํญ๋ ฅ์  ๋ฐœ์–ธ +- ์˜๋„์ ์ธ ์œ„ํ˜‘ ๋ฐ ํ˜‘๋ฐ• +- ์Šคํ† ํ‚น ๋˜๋Š” ์ง€์†์ ์ธ ์ถ”์  +- ๋ฐ˜๋ณต์ ์ธ ์ ‘์ด‰์„ ํ†ตํ•œ ๊ดด๋กญํž˜ +- ํ•ฉ๋ฆฌ์ ์œผ๋กœ ๋ถ€์ ์ ˆํ•˜๋‹ค๊ณ  ํŒ๋‹จ๋  ์ˆ˜ ์žˆ๋Š” ๊ธฐํƒ€ ๋ชจ๋“  ํ–‰๋™ + +### ์˜จ๋ผ์ธ ๊ดด๋กญํž˜ +- ์˜จ๋ผ์ธ ํ† ๋ก ์„ ์ง€์†์ ์œผ๋กœ ๋ฐฉํ•ดํ•˜๋Š” ํ–‰์œ„ +- ํƒ€์ธ์˜ ๊ฐœ์ธ์ •๋ณด ๊ณต๊ฐœ(doxxing) +- ์›์น˜ ์•Š๋Š” ์„ฑ์  ๊ด€์‹ฌ ๋˜๋Š” ์ ‘๊ทผ +- ํŠธ๋กค๋ง ๋˜๋Š” ์˜๋„์ ์ธ ๋ฐฉํ•ด ํ–‰์œ„ +- ์ŠคํŒธ ๋˜๋Š” ๋ฐ˜๋ณต์ ์ธ ๊ด‘๊ณ  +- ํ—ˆ์œ„ ์ •๋ณด ๋˜๋Š” ์˜ค์ •๋ณด ์œ ํฌ + +### ๋ณด๋ณต ํ–‰์œ„ +- ์œ„๋ฐ˜ ์‚ฌํ•ญ์„ ์‹ ๊ณ ํ•œ ์‚ฌ๋žŒ์—๊ฒŒ ๋ณด๋ณตํ•˜๋Š” ํ–‰๋™ +- ๋ถ€์ ์ ˆํ•œ ํ–‰๋™์„ ์‹ ๊ณ ํ–ˆ๋‹ค๋Š” ์ด์œ ๋กœ ๋ถ€๋‹นํ•˜๊ฒŒ ๋Œ€์šฐํ•˜๋Š” ํ–‰๋™ +- ๋ณด๋ณต ๋ชฉ์ ์œผ๋กœ ์‹ ๊ณ ๋ฅผ ์œ„ํ˜‘ํ•˜๋Š” ํ–‰๋™ + +## ์ ์šฉ ๋ฒ”์œ„ + +์ด ํ–‰๋™ ๊ฐ•๋ น์€ ๋‹ค์Œ์— ์ ์šฉ๋ฉ๋‹ˆ๋‹ค. +- ๋ชจ๋“  ์ปค๋ฎค๋‹ˆํ‹ฐ ๊ณต๊ฐ„(GitHub Issues, Pull Requests, Discussions ๋“ฑ) +- ํ”„๋กœ์ ํŠธ ์ €์žฅ์†Œ ๋ฐ ๋ฌธ์„œ +- ํ”„๋กœ์ ํŠธ๊ฐ€ ์ฃผ์ตœํ•˜๊ฑฐ๋‚˜ ๋Œ€ํ‘œํ•˜๋Š” ํ–‰์‚ฌ ๋ฐ ๋ชจ์ž„ +- ํ”„๋กœ์ ํŠธ ๋˜๋Š” ์ปค๋ฎค๋‹ˆํ‹ฐ๋ฅผ ๋Œ€ํ‘œํ•˜๋Š” ๊ณต๊ฐœ ๊ณต๊ฐ„ +- ํ”„๋กœ์ ํŠธ ์—…๋ฌด์™€ ๊ด€๋ จ๋œ ๋น„๊ณต๊ฐœ ์ปค๋ฎค๋‹ˆ์ผ€์ด์…˜ + +์ด ํ–‰๋™ ๊ฐ•๋ น์€ ๋ชจ๋“  ํ”„๋กœ์ ํŠธ ๊ณต๊ฐ„์— ์ ์šฉ๋˜๋ฉฐ, ๊ฐœ์ธ์ด ๊ณต๊ฐœ ๊ณต๊ฐ„์—์„œ ํ”„๋กœ์ ํŠธ ๋˜๋Š” ์ปค๋ฎค๋‹ˆํ‹ฐ๋ฅผ ๋Œ€ํ‘œํ•˜๋Š” ๊ฒฝ์šฐ์—๋„ ์ ์šฉ๋ฉ๋‹ˆ๋‹ค. ํ”„๋กœ์ ํŠธ๋ฅผ ๋Œ€ํ‘œํ•˜๋Š” ์˜ˆ์‹œ๋กœ๋Š” ๊ณต์‹ ํ”„๋กœ์ ํŠธ ์ด๋ฉ”์ผ ์ฃผ์†Œ ์‚ฌ์šฉ, ๊ณต์‹ ์†Œ์…œ ๋ฏธ๋””์–ด ๊ณ„์ •์„ ํ†ตํ•œ ๊ฒŒ์‹œ๋ฌผ ์ž‘์„ฑ, ์˜จ๋ผ์ธ ๋˜๋Š” ์˜คํ”„๋ผ์ธ ํ–‰์‚ฌ์—์„œ ๊ณต์‹ ๋Œ€ํ‘œ ์—ญํ•  ์ˆ˜ํ–‰ ๋“ฑ์ด ์žˆ์Šต๋‹ˆ๋‹ค. + +## ์‹œํ–‰ + +์ปค๋ฎค๋‹ˆํ‹ฐ ๋ฆฌ๋”๋Š” ํ—ˆ์šฉ ๊ฐ€๋Šฅํ•œ ํ–‰๋™ ๊ธฐ์ค€์„ ๋ช…ํ™•ํžˆ ํ•˜๊ณ  ์ด๋ฅผ ์ง‘ํ–‰ํ•  ์ฑ…์ž„์ด ์žˆ์œผ๋ฉฐ, ๋ถ€์ ์ ˆํ•˜๊ฑฐ๋‚˜ ์œ„ํ˜‘์ ์ด๊ฑฐ๋‚˜ ๊ณต๊ฒฉ์ ์ด๊ฑฐ๋‚˜ ํ•ด๋กญ๋‹ค๊ณ  ํŒ๋‹จ๋˜๋Š” ํ–‰๋™์— ๋Œ€ํ•ด ๊ณต์ •ํ•˜๊ณ  ์ ์ ˆํ•œ ์‹œ์ • ์กฐ์น˜๋ฅผ ์ทจํ•ฉ๋‹ˆ๋‹ค. + +### ์œ„๋ฐ˜ ์‚ฌํ•ญ ์‹ ๊ณ  + +ํ—ˆ์šฉ๋˜์ง€ ์•Š๋Š” ํ–‰๋™์„ ๊ฒฝํ—˜ํ•˜๊ฑฐ๋‚˜ ๋ชฉ๊ฒฉํ–ˆ๊ฑฐ๋‚˜ ๋‹ค๋ฅธ ์šฐ๋ ค ์‚ฌํ•ญ์ด ์žˆ๋Š” ๊ฒฝ์šฐ ๋‹ค์Œ ๋ฐฉ๋ฒ•์œผ๋กœ ์‹ ๊ณ ํ•ด ์ฃผ์„ธ์š”. + +1. **์ด๋ฉ”์ผ**: ํ”„๋กœ์ ํŠธ ๊ด€๋ฆฌ์ž์—๊ฒŒ ์—ฐ๋ฝ ([provide contact method if available]) +2. **GitHub Issues**: ๋น„๊ณต๊ฐœ ์‹ ๊ณ  ๊ธฐ๋Šฅ ์‚ฌ์šฉ (์„ค์ •๋œ ๊ฒฝ์šฐ) +3. **๋‹ค์ด๋ ‰ํŠธ ๋ฉ”์‹œ์ง€**: ํ”„๋กœ์ ํŠธ ๊ด€๋ฆฌ์ž์—๊ฒŒ ์ง์ ‘ ์—ฐ๋ฝ + +๋‹ค์Œ ์ •๋ณด๋ฅผ ์ œ๊ณตํ•ด ์ฃผ์„ธ์š”. +- ์—ฐ๋ฝ์ฒ˜ ์ •๋ณด +- ๊ด€๋ จ๋œ ์‚ฌ๋žŒ๋“ค์˜ ์ด๋ฆ„(๊ณต์œ ๊ฐ€ ํŽธํ•œ ๊ฒฝ์šฐ) +- ์‚ฌ๊ฑด์— ๋Œ€ํ•œ ์„ค๋ช… +- ๊ด€๋ จ ๋งฅ๋ฝ ๋ฐ ์ฐธ๊ณ  ๋งํฌ +- ํ•ด๋‹น ์‚ฌ๊ฑด์ด ๋ณธ์ธ์—๊ฒŒ ๋ฏธ์นœ ์˜ํ–ฅ + +**๋ชจ๋“  ์‹ ๊ณ  ๋‚ด์šฉ์€ ๊ธฐ๋ฐ€๋กœ ์œ ์ง€๋ฉ๋‹ˆ๋‹ค.** + +### ์กฐ์‚ฌ ๋ฐ ๋Œ€์‘ + +์ปค๋ฎค๋‹ˆํ‹ฐ ๋ฆฌ๋”๋Š” ๋‹ค์Œ์„ ์ˆ˜ํ–‰ํ•ฉ๋‹ˆ๋‹ค. +- ๋ชจ๋“  ์‹ ๊ณ ๋ฅผ ์‹ ์†ํ•˜๊ณ  ๊ณต์ •ํ•˜๊ฒŒ ๊ฒ€ํ†  ๋ฐ ์กฐ์‚ฌ +- ์‹ ๊ณ ์ž์˜ ๊ฐœ์ธ์ •๋ณด ๋ณดํ˜ธ ๋ฐ ๊ธฐ๋ฐ€ ์œ ์ง€ +- ์‹ ๊ณ  ์ง„ํ–‰ ์ƒํ™ฉ์— ๋Œ€ํ•ด ์‹ ๊ณ ์ž์—๊ฒŒ ์•ˆ๋‚ด +- ์กฐ์‚ฌ ๊ฒฐ๊ณผ์— ๋”ฐ๋ผ ์ ์ ˆํ•œ ์กฐ์น˜ ์‹œํ–‰ + +๊ฐ€๋Šฅํ•œ ์กฐ์น˜๋Š” ๋‹ค์Œ๊ณผ ๊ฐ™์Šต๋‹ˆ๋‹ค. +- ๋น„๊ณต๊ฐœ ๊ฒฝ๊ณ  ๋˜๋Š” ์ง€๋„ +- ๊ณต๊ฐœ ์‚ฌ๊ณผ(์œ„๋ฐ˜์ž๊ฐ€ ๋™์˜ํ•œ ๊ฒฝ์šฐ) +- ์ปค๋ฎค๋‹ˆํ‹ฐ ๊ณต๊ฐ„์—์„œ์˜ ์ผ์‹œ์  ๋˜๋Š” ์˜๊ตฌ์  ํ‡ด์ถœ +- ๊ธฐ์—ฌ ๊ถŒํ•œ ๋ฐ•ํƒˆ +- ํ•„์š” ์‹œ GitHub ๋˜๋Š” ๊ด€๋ จ ํ”Œ๋žซํผ์— ์—์Šค์ปฌ๋ ˆ์ด์…˜ + +### ์ด์˜ ์ œ๊ธฐ ์ ˆ์ฐจ + +๊ฒฐ์ •์— ์˜ค๋ฅ˜๊ฐ€ ์žˆ๋‹ค๊ณ  ์ƒ๊ฐํ•˜๋Š” ๊ฒฝ์šฐ ๋‹ค์Œ๊ณผ ๊ฐ™์ด ์ด์˜๋ฅผ ์ œ๊ธฐํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. +1. ์ƒˆ๋กœ์šด ์ •๋ณด ๋˜๋Š” ์ถ”๊ฐ€ ๋งฅ๋ฝ ์ œ๊ณต +2. ์—ฌ๋Ÿฌ ๊ด€๋ฆฌ์ž์— ์˜ํ•œ ์žฌ๊ฒ€ํ†  ์š”์ฒญ +3. ์ตœ์ดˆ ๊ฒฐ์ • ํ›„ 30์ผ ์ด๋‚ด์— ์žฌ์š”์ฒญ + +## ์กด์ค‘ํ•˜๋Š” ์˜๊ฒฌ ์ฐจ์ด๋ฅผ ์œ„ํ•œ ๊ฐ€์ด๋“œ๋ผ์ธ + +๊ธฐ์ˆ  ์ปค๋ฎค๋‹ˆํ‹ฐ์—์„œ ์˜๊ฒฌ ์ฐจ์ด๋Š” ์ž์—ฐ์Šค๋Ÿฌ์šด ์ผ์ž…๋‹ˆ๋‹ค. ๋‹ค์Œ๊ณผ ๊ฐ™์€ ๋ฐฉ์‹์œผ๋กœ ์กด์ค‘ํ•˜๋ฉฐ ์˜๊ฒฌ์„ ๋‚˜๋ˆ„์–ด ์ฃผ์„ธ์š”. + +### ํ•ด์•ผ ํ•  ๊ฒƒ +- โœ… ์‚ฌ๋žŒ๋ณด๋‹ค ์•„์ด๋””์–ด์— ์ง‘์ค‘ํ•˜๊ธฐ +- โœ… ๋ช…ํ™•ํ•œ ์ดํ•ด๋ฅผ ์œ„ํ•œ ์งˆ๋ฌธํ•˜๊ธฐ +- โœ… ๋ฐ˜๋Œ€ ์˜๊ฒฌ์˜ ํƒ€๋‹นํ•œ ๋ถ€๋ถ„ ์ธ์ •ํ•˜๊ธฐ +- โœ… "๋‚˜๋Š” ~๋ผ๊ณ  ์ƒ๊ฐํ•ฉ๋‹ˆ๋‹ค"์™€ ๊ฐ™์€ ํ‘œํ˜„ ์‚ฌ์šฉํ•˜๊ธฐ +- โœ… ๊ทผ๊ฑฐ์™€ ์ž๋ฃŒ๋ฅผ ์ œ์‹œํ•˜๊ธฐ +- โœ… ์ƒ๋Œ€๋ฐฉ์˜ ๊ด€์ ์— ๊ฐ์‚ฌ ํ‘œํ˜„ํ•˜๊ธฐ + +### ํ•˜์ง€ ๋ง์•„์•ผ ํ•  ๊ฒƒ +- โŒ ๊ฐœ์ธ ๊ณต๊ฒฉํ•˜๊ธฐ +- โŒ ๋ฌด์‹œํ•˜๊ฑฐ๋‚˜ ๋น„ํ•˜ํ•˜๋Š” ํ‘œํ˜„ ์‚ฌ์šฉํ•˜๊ธฐ ("๊ทธ๊ฑด ๋ฐ”๋ณด ๊ฐ™์€ ์ƒ๊ฐ์ด์•ผ") +- โŒ ์ƒ๋Œ€๋ฐฉ์˜ ์˜๋„๋ฅผ ์•…์˜์ ์œผ๋กœ ์ถ”์ •ํ•˜๊ธฐ +- โŒ ๊ด€๋ จ ์—†๋Š” ๊ณผ๊ฑฐ ๊ฐˆ๋“ฑ ๊บผ๋‚ด๊ธฐ +- โŒ ๊ณต๊ฒฉ์ ์ธ ํƒœ๋„๋กœ ๋ถ„์œ„๊ธฐ ์•…ํ™”์‹œํ‚ค๊ธฐ +- โŒ ์ƒ๋Œ€๋ฐฉ์˜ ์˜๊ฒฌ์„ ์˜๋„์ ์œผ๋กœ ์™œ๊ณกํ•˜๊ธฐ + +### ์กด์ค‘ํ•˜๋Š” ์˜๊ฒฌ ์ฐจ์ด์˜ ์˜ˆ +``` +โŒ Bad: "That's a dumb idea and you clearly don't understand the project." + +โœ… Good: "I see your point, but I'm concerned this approach might +not scale well with larger projects. Have you considered the +performance implications shown in this benchmark? I'd love to +hear your thoughts on this." +``` + +## ๊ด€๊ณ„๋ฅผ ์ž‡๋Š” ๋ฌธํ™” ๋งŒ๋“ค๊ธฐ + +์šฐ๋ฆฌ๋Š” ๋Œ€ํ™”์™€ ํ™”ํ•ด์˜ ํž˜์„ ๋ฏฟ์Šต๋‹ˆ๋‹ค. + +- ๋ˆ„๊ตฐ๊ฐ€๊ฐ€ ์ž์‹ ์˜ ํ–‰๋™์„ ์ง€์ ํ•˜๋ฉด ๊ฒฝ์ฒญํ•˜๊ณ  ๋Œ์•„๋ณด์„ธ์š”. +- ๋ˆ„๊ตฐ๊ฐ€์—๊ฒŒ ํ”ผํ•ด๋ฅผ ์ฃผ์—ˆ๋‹ค๋ฉด ์‚ฌ๊ณผํ•  ์ค€๋น„๋ฅผ ํ•˜์„ธ์š”. +- ๋‹ค๋ฅธ ์‚ฌ๋žŒ์˜ ํ•™์Šต๊ณผ ์„ฑ์žฅ์„ ์ง€์›ํ•˜์„ธ์š”. +- ๋ˆ„๊ตฌ๋‚˜ ์‹ค์ˆ˜ํ•  ์ˆ˜ ์žˆ๋‹ค๋Š” ์ ์„ ์ธ์ •ํ•˜์„ธ์š”. +- ๋น„๋‚œ๋ณด๋‹ค ํ•ด๊ฒฐ์ฑ…์— ์ง‘์ค‘ํ•˜์„ธ์š”. +- ์„ ์˜๋ฅผ ๊ฐ€์ •ํ•˜๋˜ ์ฑ…์ž„์€ ๋ถ„๋ช…ํžˆ ํ•˜์„ธ์š”. + +## ์ด ํ–‰๋™ ๊ฐ•๋ น์„ ๋”ฐ๋ฅผ ๋•Œ์˜ ์žฅ์  + +์กด์ค‘๊ณผ ํฌ์šฉ์˜ ๋ฌธํ™”๋ฅผ ์œ ์ง€ํ•จ์œผ๋กœ์จ ์šฐ๋ฆฌ๋Š” ๋‹ค์Œ๊ณผ ๊ฐ™์€ ์ด์ ์„ ์–ป์„ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. +- ๋‹ค์–‘ํ•œ ๊ด€์ ์„ ๊ฐ€์ง„ ๊ธฐ์—ฌ์ž๋ฅผ ์œ ์น˜ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. +- ํ˜‘์—…์„ ํ†ตํ•ด ๋” ๋‚˜์€ ํ•ด๊ฒฐ์ฑ…์„ ๋งŒ๋“ค ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. +- ๋” ๊ฐ•ํ•œ ๊ด€๊ณ„๋ฅผ ๊ตฌ์ถ•ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. +- ์‹ ๊ทœ ์ฐธ์—ฌ์ž์—๊ฒŒ ๋”์šฑ ํ™˜์˜๋ฐ›๋Š” ํ”„๋กœ์ ํŠธ๊ฐ€ ๋ฉ๋‹ˆ๋‹ค. +- ๋” ๋†’์€ ํ’ˆ์งˆ์˜ ๋ฌธ์„œ์™€ ์˜ˆ์ œ๋ฅผ ๋งŒ๋“ค ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. +- ํ•™์Šต๊ณผ ์„ฑ์žฅ์˜ ๋ฌธํ™”๋ฅผ ์กฐ์„ฑํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +## ํŠน๋ณ„ ๊ณ ๋ ค ์‚ฌํ•ญ + +### ๊ด€๋ฆฌ์ž(Maintainer)๋ฅผ ์œ„ํ•œ ์•ˆ๋‚ด +- ํ–‰๋™ ๊ฐ•๋ น์„ ์Šค์Šค๋กœ ๋ชจ๋ฒ”์ ์œผ๋กœ ์‹ค์ฒœํ•˜์„ธ์š”. +- ์‹ ๊ณ ์— ์‹ ์†ํ•˜๊ฒŒ ๋Œ€์‘ํ•˜์„ธ์š”. +- ์˜์‚ฌ๊ฒฐ์ • ๊ณผ์ •์„ ํˆฌ๋ช…ํ•˜๊ฒŒ ์šด์˜ํ•˜์„ธ์š”. +- ๊ฐˆ๋“ฑ์„ ๊ณต์ •ํ•˜๊ฒŒ ํ•ด๊ฒฐํ•˜์„ธ์š”. +- ๋ชจ๋‘๋ฅผ ์œ„ํ•œ ์•ˆ์ „ํ•œ ํ™˜๊ฒฝ์„ ์กฐ์„ฑํ•˜์„ธ์š”. + + +### ๊ธฐ์—ฌ์ž๋ฅผ ์œ„ํ•œ ์•ˆ๋‚ด +- ๊ด€๋ฆฌ์ž์™€ ๋‹ค๋ฅธ ๊ธฐ์—ฌ์ž์˜ ์„ ์˜๋ฅผ ๊ฐ€์ •ํ•˜์„ธ์š”. +- ๊ฑด์„ค์ ์ธ ํ”ผ๋“œ๋ฐฑ์„ ์ œ๊ณตํ•˜์„ธ์š”. +- ์‹ ๊ทœ ์ฐธ์—ฌ์ž๋ฅผ ์ง€์›ํ•˜์„ธ์š”. +- ์ปค๋ฎค๋‹ˆํ‹ฐ ๊ธฐ์ค€ ์ค€์ˆ˜๋ฅผ ๋•์Šต๋‹ˆ๋‹ค. +- ์ปค๋ฎค๋‹ˆํ‹ฐ ๋ฌธํ™” ํ˜•์„ฑ์— ์ฑ…์ž„๊ฐ์„ ๊ฐ€์ง€์„ธ์š”. + +### ๋ชจ๋‘๋ฅผ ์œ„ํ•œ ์•ˆ๋‚ด +- ๋ชจ๋“  ๋ฉ”์‹œ์ง€ ๋’ค์—๋Š” ์‚ฌ๋žŒ์ด ์žˆ๋‹ค๋Š” ์ ์„ ๊ธฐ์–ตํ•˜์„ธ์š”. +- ๋‹ต๋‹ตํ•จ์„ ๋Š๋‚„ ๋•Œ๋Š” ์ž ์‹œ ์‰ฌ์–ด๊ฐ€์„ธ์š”. +- ๋„์›€์ด ํ•„์š”ํ•˜๋ฉด ์ปค๋ฎค๋‹ˆํ‹ฐ ๋ฆฌ๋”์—๊ฒŒ ์—ฐ๋ฝํ•˜์„ธ์š”. +- ์ž์‹ ์ด ์ฐธ์—ฌํ•˜๊ณ  ์‹ถ์€ ์ปค๋ฎค๋‹ˆํ‹ฐ๋ฅผ ํ•จ๊ป˜ ๋งŒ๋“ค์–ด ๊ฐ€์„ธ์š”. + + +## ์ถœ์ฒ˜ + +์ด ํ–‰๋™ ๊ฐ•๋ น์€ ๋‹ค์Œ ์ž๋ฃŒ๋ฅผ ๊ธฐ๋ฐ˜์œผ๋กœ ์ž‘์„ฑ๋˜์—ˆ์Šต๋‹ˆ๋‹ค. +- The [Contributor Covenant](https://www.contributor-covenant.org/) +- The [Mozilla Community Participation Guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/) +- The [Python Community Code of Conduct](https://www.python.org/psf/conduct/) + +## ๋ฌธ์˜ + +์ด ํ–‰๋™ ๊ฐ•๋ น์— ๋Œ€ํ•œ ์งˆ๋ฌธ์ด ์žˆ๋‹ค๋ฉด ํ”„๋กœ์ ํŠธ ๊ด€๋ฆฌ์ž์—๊ฒŒ ๋ฌธ์˜ํ•ด ์ฃผ์„ธ์š”. + +## ๋ฒ„์ „ ์ด๋ ฅ + +- **Version 1.0** (2026๋…„ 1์›”) - ์ตœ์ดˆ ํ–‰๋™ ๊ฐ•๋ น ์ž‘์„ฑ + +--- + +**ํ™˜์˜๋ฐ›๊ณ , ํฌ์šฉ์ ์ด๋ฉฐ, ์„œ๋กœ๋ฅผ ์กด์ค‘ํ•˜๋Š” ์ปค๋ฎค๋‹ˆํ‹ฐ๋ฅผ ๋งŒ๋“œ๋Š” ๋ฐ ํ•จ๊ป˜ํ•ด ์ฃผ์…”์„œ ๊ฐ์‚ฌํ•ฉ๋‹ˆ๋‹ค!** ๐ŸŒŸ + +--- +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: 2026๋…„ 4์›” 9์ผ diff --git a/ko/CONTRIBUTING.md b/ko/CONTRIBUTING.md new file mode 100644 index 00000000..0ab15d26 --- /dev/null +++ b/ko/CONTRIBUTING.md @@ -0,0 +1,387 @@ + + + Claude How To + + +# Claude How To ๊ธฐ์—ฌ ๊ฐ€์ด๋“œ + +์ด ํ”„๋กœ์ ํŠธ์— ๊ด€์‹ฌ์„ ๊ฐ€์ ธ์ฃผ์…”์„œ ๊ฐ์‚ฌํ•ฉ๋‹ˆ๋‹ค! ์ด ๊ฐ€์ด๋“œ๋Š” ํšจ๊ณผ์ ์œผ๋กœ ๊ธฐ์—ฌํ•˜๋Š” ๋ฐฉ๋ฒ•์„ ์•ˆ๋‚ดํ•ฉ๋‹ˆ๋‹ค. + +## ์ด ํ”„๋กœ์ ํŠธ ์†Œ๊ฐœ + +Claude How To๋Š” Claude Code๋ฅผ ์œ„ํ•œ ์‹œ๊ฐ์ ์ด๊ณ  ์˜ˆ์ œ ์ค‘์‹ฌ์˜ ๊ฐ€์ด๋“œ์ž…๋‹ˆ๋‹ค. ๋‹ค์Œ๊ณผ ๊ฐ™์€ ์ฝ˜ํ…์ธ ๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. + +- **๊ธฐ๋Šฅ์˜ ๋™์ž‘ ๋ฐฉ์‹์„ ์„ค๋ช…ํ•˜๋Š” Mermaid ๋‹ค์ด์–ด๊ทธ๋žจ** +- **์ฆ‰์‹œ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ๋Š” ์‹ค์ „์šฉ ํ…œํ”Œ๋ฆฟ** +- **๋งฅ๋ฝ๊ณผ ๋ชจ๋ฒ” ์‚ฌ๋ก€๋ฅผ ํฌํ•จํ•œ ์‹ค์ œ ์˜ˆ์ œ** +- **์ดˆ๊ธ‰๋ถ€ํ„ฐ ๊ณ ๊ธ‰๊นŒ์ง€ ์ด์–ด์ง€๋Š” ๋‹จ๊ณ„๋ณ„ ํ•™์Šต ๊ฒฝ๋กœ** + +## ๊ธฐ์—ฌ ์œ ํ˜• + +### 1. ์ƒˆ๋กœ์šด ์˜ˆ์ œ ๋˜๋Š” ํ…œํ”Œ๋ฆฟ + +๊ธฐ์กด ๊ธฐ๋Šฅ(Slash Commands, Skills, Hooks ๋“ฑ)์— ๋Œ€ํ•œ ์˜ˆ์ œ๋ฅผ ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค. + +- ๋ฐ”๋กœ ๋ณต์‚ฌํ•ด์„œ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ๋Š” ์ฝ”๋“œ +- ๋™์ž‘ ๋ฐฉ์‹์„ ๋ช…ํ™•ํ•˜๊ฒŒ ์„ค๋ช… +- ํ™œ์šฉ ์‚ฌ๋ก€ ๋ฐ ์žฅ์  +- ๋ฌธ์ œ ํ•ด๊ฒฐ ํŒ + +### 2. ๋ฌธ์„œ ๊ฐœ์„  + +- ์ดํ•ดํ•˜๊ธฐ ์–ด๋ ค์šด ๋ถ€๋ถ„ ๋ช…ํ™•ํ•˜๊ฒŒ ์ˆ˜์ • +- ์˜คํƒˆ์ž ๋ฐ ๋ฌธ๋ฒ• ์ˆ˜์ • +- ๋ˆ„๋ฝ๋œ ์ •๋ณด ์ถ”๊ฐ€ +- ์ฝ”๋“œ ์˜ˆ์ œ ๊ฐœ์„  + +### 3. ๊ธฐ๋Šฅ ๊ฐ€์ด๋“œ +์ƒˆ๋กœ์šด Claude Code ๊ธฐ๋Šฅ์— ๋Œ€ํ•œ ๊ฐ€์ด๋“œ๋ฅผ ์ž‘์„ฑํ•ฉ๋‹ˆ๋‹ค. +- ๋‹จ๊ณ„๋ณ„ ํŠœํ† ๋ฆฌ์–ผ +- ์•„ํ‚คํ…์ฒ˜ ๋‹ค์ด์–ด๊ทธ๋žจ +- ์ผ๋ฐ˜์ ์ธ ํŒจํ„ด๊ณผ ์•ˆํ‹ฐํŒจํ„ด +- ์‹ค์ œ ์›Œํฌํ”Œ๋กœ ์˜ˆ์ œ + +### 4. ๋ฒ„๊ทธ ์ œ๋ณด +๋ฐœ๊ฒฌํ•œ ๋ฌธ์ œ๋ฅผ ์ œ๋ณดํ•ฉ๋‹ˆ๋‹ค. +- ๊ธฐ๋Œ€ํ–ˆ๋˜ ๋™์ž‘ ์„ค๋ช… +- ์‹ค์ œ ๋ฐœ์ƒํ•œ ๋™์ž‘ ์„ค๋ช… +- ์žฌํ˜„ ์ ˆ์ฐจ ํฌํ•จ +- ์‚ฌ์šฉํ•œ Claude Code ๋ฒ„์ „ ๋ฐ ์šด์˜์ฒด์ œ ์ •๋ณด ์ œ๊ณต + +### 5. ํ”ผ๋“œ๋ฐฑ ๋ฐ ์ œ์•ˆ +๊ฐ€์ด๋“œ๋ฅผ ๊ฐœ์„ ํ•  ์ˆ˜ ์žˆ๋„๋ก ์˜๊ฒฌ์„ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. +- ๋” ๋‚˜์€ ์„ค๋ช… ์ œ์•ˆ +- ๋น ์ง„ ๋‚ด์šฉ ์ง€์  +- ์ƒˆ๋กœ์šด ์„น์…˜ ๋˜๋Š” ๋ฌธ์„œ ๊ตฌ์กฐ ๊ฐœ์„  ์ œ์•ˆ + +## ์‹œ์ž‘ํ•˜๊ธฐ + +### 1. Fork ๋ฐ Clone +```bash +git clone https://github.com/luongnv89/claude-howto.git +cd claude-howto +``` + +### 2. ๋ธŒ๋žœ์น˜ ์ƒ์„ฑ +์˜๋ฏธ๋ฅผ ์•Œ ์ˆ˜ ์žˆ๋Š” ๋ธŒ๋žœ์น˜ ์ด๋ฆ„์„ ์‚ฌ์šฉํ•˜์„ธ์š”. +```bash +git checkout -b add/feature-name +git checkout -b fix/issue-description +git checkout -b docs/improvement-area +``` + +### 3. ๊ฐœ๋ฐœ ํ™˜๊ฒฝ ์„ค์ • + +Pre-commit Hook์€ ๋ชจ๋“  ์ปค๋ฐ‹ ์ „์— CI์™€ ๋™์ผํ•œ ๊ฒ€์‚ฌ๋ฅผ ๋กœ์ปฌ์—์„œ ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค. PR์ด ์Šน์ธ๋˜๋ ค๋ฉด ๋„ค ๊ฐ€์ง€ ๊ฒ€์‚ฌ๋ฅผ ๋ชจ๋‘ ํ†ต๊ณผํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. + +**ํ•„์ˆ˜ ์˜์กด์„ฑ:** + +```bash +# Python ๋„๊ตฌ (์ด ํ”„๋กœ์ ํŠธ์—์„œ๋Š” uv๋ฅผ ํŒจํ‚ค์ง€ ๊ด€๋ฆฌ์ž๋กœ ์‚ฌ์šฉ) +pip install uv +uv venv +source .venv/bin/activate +uv pip install -r scripts/requirements-dev.txt + +# Markdown ๋ฆฐํ„ฐ (Node.js) +npm install -g markdownlint-cli + +# Mermaid ๋‹ค์ด์–ด๊ทธ๋žจ ๊ฒ€์ฆ ๋„๊ตฌ (Node.js) +npm install -g @mermaid-js/mermaid-cli + +# pre-commit ์„ค์น˜ ๋ฐ Hook ํ™œ์„ฑํ™” +uv pip install pre-commit +pre-commit install +``` + +**์„ค์ • ํ™•์ธ:** + +```bash +pre-commit run --all-files +``` + +๋ชจ๋“  ์ปค๋ฐ‹์—์„œ ์‹คํ–‰๋˜๋Š” Hook์€ ๋‹ค์Œ๊ณผ ๊ฐ™์Šต๋‹ˆ๋‹ค. + +| Hook | ๊ฒ€์‚ฌ ๋‚ด์šฉ | +|------|----------| +| `markdown-lint` | Markdown ํ˜•์‹ ๋ฐ ๊ตฌ์กฐ ๊ฒ€์‚ฌ | +| `cross-references` | ์ƒ๋Œ€ ๋งํฌ, ์•ต์ปค, ์ฝ”๋“œ ํŽœ์Šค ๊ฒ€์‚ฌ | +| `mermaid-syntax` | ๋ชจ๋“  ` ```mermaid ` ๋ธ”๋ก์˜ ๋ฌธ๋ฒ• ๊ฒ€์‚ฌ | +| `link-check` | ์™ธ๋ถ€ URL ์ ‘๊ทผ ๊ฐ€๋Šฅ ์—ฌ๋ถ€ ํ™•์ธ | +| `build-epub` | `.md` ๋ณ€๊ฒฝ ์‹œ EPUB ์ƒ์„ฑ ์˜ค๋ฅ˜ ํ™•์ธ | + +## ๋””๋ ‰ํ„ฐ๋ฆฌ ๊ตฌ์กฐ + +``` +โ”œโ”€โ”€ 01-slash-commands/ # ์‚ฌ์šฉ์ž ์‹คํ–‰ ๋‹จ์ถ• ๋ช…๋ น +โ”œโ”€โ”€ 02-memory/ # ์˜๊ตฌ ์ปจํ…์ŠคํŠธ ์˜ˆ์ œ +โ”œโ”€โ”€ 03-skills/ # ์žฌ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ๊ธฐ๋Šฅ +โ”œโ”€โ”€ 04-subagents/ # ์ „๋ฌธ AI ๋ณด์กฐ ์—์ด์ „ํŠธ +โ”œโ”€โ”€ 05-mcp/ # Model Context Protocol ์˜ˆ์ œ +โ”œโ”€โ”€ 06-hooks/ # ์ด๋ฒคํŠธ ๊ธฐ๋ฐ˜ ์ž๋™ํ™” +โ”œโ”€โ”€ 07-plugins/ # ๊ธฐ๋Šฅ ๋ฒˆ๋“ค +โ”œโ”€โ”€ 08-checkpoints/ # ์„ธ์…˜ ์Šค๋ƒ…์ƒท +โ”œโ”€โ”€ 09-advanced-features/ # ๊ณ„ํš, ์‚ฌ๊ณ  ๊ณผ์ •, ๋ฐฑ๊ทธ๋ผ์šด๋“œ ๊ธฐ๋Šฅ +โ”œโ”€โ”€ 10-cli/ # CLI ์ฐธ์กฐ +โ”œโ”€โ”€ scripts/ # ๋นŒ๋“œ ๋ฐ ์œ ํ‹ธ๋ฆฌํ‹ฐ ์Šคํฌ๋ฆฝํŠธ +โ””โ”€โ”€ README.md # ๋ฉ”์ธ ๊ฐ€์ด๋“œ +``` + +## ์˜ˆ์ œ ๊ธฐ์—ฌ ๋ฐฉ๋ฒ• + +### Slash Command ์ถ”๊ฐ€ +1. `01-slash-commands/`์— `.md` ํŒŒ์ผ์„ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. +2. ๋‹ค์Œ ๋‚ด์šฉ์„ ํฌํ•จํ•ฉ๋‹ˆ๋‹ค. + - ๊ธฐ๋Šฅ ์„ค๋ช… + - ์‚ฌ์šฉ ์‚ฌ๋ก€ + - ์„ค์น˜ ๋ฐฉ๋ฒ• + - ์‚ฌ์šฉ ์˜ˆ์ œ + - ์‚ฌ์šฉ์ž ์ง€์ • ํŒ +3. `01-slash-commands/README.md`๋ฅผ ์—…๋ฐ์ดํŠธํ•ฉ๋‹ˆ๋‹ค. + +### Skill ์ถ”๊ฐ€ +1. `03-skills/`์— ๋””๋ ‰ํ„ฐ๋ฆฌ๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. +2. ๋‹ค์Œ ๋‚ด์šฉ์„ ํฌํ•จํ•ฉ๋‹ˆ๋‹ค. + - `SKILL.md` - ๋ฉ”์ธ ๋ฌธ์„œ + - `scripts/` - ํ•„์š”ํ•œ ๊ฒฝ์šฐ ๋ณด์กฐ ์Šคํฌ๋ฆฝํŠธ + - `templates/` - ํ”„๋กฌํ”„ํŠธ ํ…œํ”Œ๋ฆฟ + - README์˜ ์‚ฌ์šฉ ์˜ˆ์ œ +3. `03-skills/README.md`๋ฅผ ์—…๋ฐ์ดํŠธํ•ฉ๋‹ˆ๋‹ค. + +### Subagent ์ถ”๊ฐ€ +1. `04-subagents/`์— `.md` ํŒŒ์ผ์„ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. +2. ๋‹ค์Œ ๋‚ด์šฉ์„ ํฌํ•จํ•ฉ๋‹ˆ๋‹ค. + - ์—์ด์ „ํŠธ์˜ ๋ชฉ์ ๊ณผ ๊ธฐ๋Šฅ + - ์‹œ์Šคํ…œ ํ”„๋กฌํ”„ํŠธ ๊ตฌ์กฐ + - ์‚ฌ์šฉ ์˜ˆ์ œ + - ํ†ตํ•ฉ ์˜ˆ์ œ +3. `04-subagents/README.md`๋ฅผ ์—…๋ฐ์ดํŠธํ•ฉ๋‹ˆ๋‹ค. + +### MCP ์„ค์ • ์ถ”๊ฐ€ +1. `05-mcp/`์— `.json` ํŒŒ์ผ์„ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. +2. ๋‹ค์Œ ๋‚ด์šฉ์„ ํฌํ•จํ•ฉ๋‹ˆ๋‹ค. + - ์„ค์ • ์„ค๋ช… + - ํ•„์š”ํ•œ ํ™˜๊ฒฝ ๋ณ€์ˆ˜ + - ์„ค์ • ๋ฐฉ๋ฒ• + - ์‚ฌ์šฉ ์˜ˆ์ œ +3. `05-mcp/README.md`๋ฅผ ์—…๋ฐ์ดํŠธํ•ฉ๋‹ˆ๋‹ค. + +### Hook ์ถ”๊ฐ€ +1. `06-hooks/`์— `.sh` ํŒŒ์ผ์„ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. +2. ๋‹ค์Œ ๋‚ด์šฉ์„ ํฌํ•จํ•ฉ๋‹ˆ๋‹ค. + - Shebang ๋ฐ ์„ค๋ช… + - ๋™์ž‘์„ ์„ค๋ช…ํ•˜๋Š” ๋ช…ํ™•ํ•œ ์ฃผ์„ + - ์˜ค๋ฅ˜ ์ฒ˜๋ฆฌ + - ๋ณด์•ˆ ๊ณ ๋ ค ์‚ฌํ•ญ +3. `06-hooks/README.md`๋ฅผ ์—…๋ฐ์ดํŠธํ•ฉ๋‹ˆ๋‹ค. + +## ์ž‘์„ฑ ๊ฐ€์ด๋“œ๋ผ์ธ + +### Markdown ์Šคํƒ€์ผ +- ๋ช…ํ™•ํ•œ ์ œ๋ชฉ ์‚ฌ์šฉ(H2๋Š” ์„น์…˜, H3๋Š” ํ•˜์œ„ ์„น์…˜) +- ๋ฌธ๋‹จ์€ ์งง๊ณ  ํ•ต์‹ฌ์ ์œผ๋กœ ์ž‘์„ฑ +- ๋ชฉ๋ก์€ ๊ธ€๋จธ๋ฆฌํ‘œ ์‚ฌ์šฉ +- ์–ธ์–ด๋ฅผ ์ง€์ •ํ•œ ์ฝ”๋“œ ๋ธ”๋ก ํฌํ•จ +- ์„น์…˜ ์‚ฌ์ด์— ๋นˆ ์ค„ ์ถ”๊ฐ€ + +### ์ฝ”๋“œ ์˜ˆ์ œ +- ๋ฐ”๋กœ ๋ณต์‚ฌํ•ด์„œ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ๋„๋ก ์ž‘์„ฑ +- ์ดํ•ดํ•˜๊ธฐ ์–ด๋ ค์šด ๋กœ์ง์—๋Š” ์ฃผ์„ ์ถ”๊ฐ€ +- ๊ฐ„๋‹จํ•œ ๋ฒ„์ „๊ณผ ๊ณ ๊ธ‰ ๋ฒ„์ „ ๋ชจ๋‘ ์ œ๊ณต +- ์‹ค์ œ ํ™œ์šฉ ์‚ฌ๋ก€ ์ œ์‹œ +- ๋ฐœ์ƒ ๊ฐ€๋Šฅํ•œ ๋ฌธ์ œ์  ๊ฐ•์กฐ + +### ๋ฌธ์„œ ์ž‘์„ฑ +- "๋ฌด์—‡"๋ฟ ์•„๋‹ˆ๋ผ "์™œ"๋„ ์„ค๋ช… +- ์‚ฌ์ „ ์š”๊ตฌ ์‚ฌํ•ญ ํฌํ•จ +- ๋ฌธ์ œ ํ•ด๊ฒฐ ์„น์…˜ ์ถ”๊ฐ€ +- ๊ด€๋ จ ์ฃผ์ œ ๋งํฌ ์ œ๊ณต +- ์ดˆ๋ณด์ž๋„ ์ดํ•ดํ•˜๊ธฐ ์‰ฝ๊ฒŒ ์ž‘์„ฑ + +### JSON/YAML +- ์˜ฌ๋ฐ”๋ฅธ ๋“ค์—ฌ์“ฐ๊ธฐ ์‚ฌ์šฉ(2์นธ ๋˜๋Š” 4์นธ์„ ์ผ๊ด€๋˜๊ฒŒ ์œ ์ง€) +- ์„ค์ •์„ ์„ค๋ช…ํ•˜๋Š” ์ฃผ์„ ์ถ”๊ฐ€ +- ๊ฒ€์ฆ ์˜ˆ์ œ ํฌํ•จ + +### ๋‹ค์ด์–ด๊ทธ๋žจ +- ๊ฐ€๋Šฅํ•˜๋ฉด Mermaid ์‚ฌ์šฉ +- ๋‹ค์ด์–ด๊ทธ๋žจ์€ ๋‹จ์ˆœํ•˜๊ณ  ์ฝ๊ธฐ ์‰ฝ๊ฒŒ ์œ ์ง€ +- ๋‹ค์ด์–ด๊ทธ๋žจ ์•„๋ž˜์— ์„ค๋ช… ์ถ”๊ฐ€ +- ๊ด€๋ จ ์„น์…˜์œผ๋กœ ์—ฐ๊ฒฐ๋˜๋Š” ๋งํฌ ์ œ๊ณต + +## ์ปค๋ฐ‹ ๊ฐ€์ด๋“œ๋ผ์ธ + +Conventional Commit ํ˜•์‹์„ ๋”ฐ๋ฅด์„ธ์š”. +``` +type(scope): description + +[optional body] +``` + +Types: +- `feat`: ์ƒˆ๋กœ์šด ๊ธฐ๋Šฅ ๋˜๋Š” ์˜ˆ์ œ +- `fix`: ๋ฒ„๊ทธ ์ˆ˜์ • ๋˜๋Š” ์˜ค๋ฅ˜ ์ˆ˜์ • +- `docs`: ๋ฌธ์„œ ๋ณ€๊ฒฝ +- `refactor`: ์ฝ”๋“œ ๊ตฌ์กฐ ๊ฐœ์„  +- `style`: ์„œ์‹ ๋ณ€๊ฒฝ +- `test`: ํ…Œ์ŠคํŠธ ์ถ”๊ฐ€ ๋˜๋Š” ๋ณ€๊ฒฝ +- `chore`: ๋นŒ๋“œ, ์˜์กด์„ฑ ๋“ฑ + +์˜ˆ์‹œ: +``` +feat(slash-commands): Add API documentation generator +docs(memory): Improve personal preferences example +fix(README): Correct table of contents link +docs(skills): Add comprehensive code review skill +``` + +## ์ œ์ถœ ์ „ ํ™•์ธ + +### ์ฒดํฌ๋ฆฌ์ŠคํŠธ +- [ ] ์ฝ”๋“œ๊ฐ€ ํ”„๋กœ์ ํŠธ ์Šคํƒ€์ผ๊ณผ ๊ทœ์น™์„ ๋”ฐ๋ฅด๋Š”๊ฐ€ +- [ ] ์ƒˆ๋กœ์šด ์˜ˆ์ œ์— ๋ช…ํ™•ํ•œ ๋ฌธ์„œ๊ฐ€ ํฌํ•จ๋˜์–ด ์žˆ๋Š”๊ฐ€ +- [ ] README ํŒŒ์ผ(๋กœ์ปฌ ๋ฐ ๋ฃจํŠธ)์ด ๋ชจ๋‘ ์—…๋ฐ์ดํŠธ๋˜์—ˆ๋Š”๊ฐ€ +- [ ] ๋ฏผ๊ฐํ•œ ์ •๋ณด(API ํ‚ค, ์ž๊ฒฉ ์ฆ๋ช… ๋“ฑ)๊ฐ€ ํฌํ•จ๋˜์ง€ ์•Š์•˜๋Š”๊ฐ€ +- [ ] ์˜ˆ์ œ๊ฐ€ ํ…Œ์ŠคํŠธ๋˜์—ˆ์œผ๋ฉฐ ์ •์ƒ ๋™์ž‘ํ•˜๋Š”๊ฐ€ +- [ ] ๋ชจ๋“  ๋งํฌ๊ฐ€ ์˜ฌ๋ฐ”๋ฅด๊ฒŒ ์—ฐ๊ฒฐ๋˜์–ด ์žˆ๋Š”๊ฐ€ +- [ ] ํŒŒ์ผ ๊ถŒํ•œ์ด ์˜ฌ๋ฐ”๋ฅด๊ฒŒ ์„ค์ •๋˜์–ด ์žˆ๋Š”๊ฐ€(์Šคํฌ๋ฆฝํŠธ ์‹คํ–‰ ๊ถŒํ•œ ํฌํ•จ) +- [ ] ์ปค๋ฐ‹ ๋ฉ”์‹œ์ง€๊ฐ€ ๋ช…ํ™•ํ•˜๊ณ  ์ดํ•ดํ•˜๊ธฐ ์‰ฌ์šด๊ฐ€ + +### ๋กœ์ปฌ ํ…Œ์ŠคํŠธ +```bash +# ๋ชจ๋“  pre-commit ๊ฒ€์‚ฌ ์‹คํ–‰(CI์™€ ๋™์ผํ•œ ๊ฒ€์‚ฌ) +pre-commit run --all-files + +# ๋ณ€๊ฒฝ ์‚ฌํ•ญ ๊ฒ€ํ†  +git diff +``` + +## Pull Request ์ ˆ์ฐจ + +1. **๋ช…ํ™•ํ•œ ์„ค๋ช…๊ณผ ํ•จ๊ป˜ PR ์ƒ์„ฑ** + - ๋ฌด์—‡์„ ์ถ”๊ฐ€ํ•˜๊ฑฐ๋‚˜ ์ˆ˜์ •ํ–ˆ๋Š”๊ฐ€? + - ์™œ ํ•„์š”ํ•œ๊ฐ€? + - ๊ด€๋ จ ์ด์Šˆ(์žˆ๋Š” ๊ฒฝ์šฐ) + +2. **๊ด€๋ จ ์„ธ๋ถ€ ์ •๋ณด ํฌํ•จ** + - ์ƒˆ๋กœ์šด ๊ธฐ๋Šฅ์ธ๊ฐ€? ์‚ฌ์šฉ ์‚ฌ๋ก€ ํฌํ•จ + - ๋ฌธ์„œ ๋ณ€๊ฒฝ์ธ๊ฐ€? ๊ฐœ์„  ์‚ฌํ•ญ ์„ค๋ช… + - ์˜ˆ์ œ์ธ๊ฐ€? ๋ณ€๊ฒฝ ์ „/ํ›„ ๋น„๊ต ์ œ๊ณต + +3. **์ด์Šˆ ์—ฐ๊ฒฐ** + - ๊ด€๋ จ ์ด์Šˆ๋ฅผ ์ž๋™์œผ๋กœ ๋‹ซ์œผ๋ ค๋ฉด `Closes #123` ์‚ฌ์šฉ + +4. **๋ฆฌ๋ทฐ๋ฅผ ๊ธฐ๋‹ค๋ ค ์ฃผ์„ธ์š”** + - ์œ ์ง€ ๊ด€๋ฆฌ์ž๊ฐ€ ๊ฐœ์„  ์‚ฌํ•ญ์„ ์ œ์•ˆํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + - ํ”ผ๋“œ๋ฐฑ์„ ๋ฐ˜์˜ํ•˜์—ฌ ์ˆ˜์ •ํ•ด ์ฃผ์„ธ์š”. + - ์ตœ์ข… ๊ฒฐ์ •์€ ์œ ์ง€ ๊ด€๋ฆฌ์ž๊ฐ€ ๋‚ด๋ฆฝ๋‹ˆ๋‹ค. + +## ์ฝ”๋“œ ๋ฆฌ๋ทฐ ์ ˆ์ฐจ + +๋ฆฌ๋ทฐ์–ด๋Š” ๋‹ค์Œ ์‚ฌํ•ญ์„ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. +- **์ •ํ™•์„ฑ**: ์„ค๋ช…ํ•œ ๋Œ€๋กœ ๋™์ž‘ํ•˜๋Š”๊ฐ€? +- **ํ’ˆ์งˆ**: ์‹ค์ œ ์šด์˜ ํ™˜๊ฒฝ์—์„œ๋„ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ๋Š” ์ˆ˜์ค€์ธ๊ฐ€? +- **์ผ๊ด€์„ฑ**: ํ”„๋กœ์ ํŠธ์˜ ๊ธฐ์กด ํŒจํ„ด์„ ๋”ฐ๋ฅด๋Š”๊ฐ€? +- **๋ฌธ์„œํ™”**: ๋ช…ํ™•ํ•˜๊ณ  ์ถฉ๋ถ„ํ•˜๊ฒŒ ์ž‘์„ฑ๋˜์—ˆ๋Š”๊ฐ€? +- **๋ณด์•ˆ**: ์ทจ์•ฝ์ ์€ ์—†๋Š”๊ฐ€? + +## ์ด์Šˆ ์ œ๋ณด + +### ๋ฒ„๊ทธ ์ œ๋ณด +๋‹ค์Œ ์ •๋ณด๋ฅผ ํฌํ•จํ•ด ์ฃผ์„ธ์š”. +- Claude Code ๋ฒ„์ „ +- ์šด์˜์ฒด์ œ +- ์žฌํ˜„ ๋ฐฉ๋ฒ• +- ๊ธฐ๋Œ€ํ•œ ๋™์ž‘ +- ์‹ค์ œ ๋™์ž‘ +- ํ•„์š”ํ•œ ๊ฒฝ์šฐ ์Šคํฌ๋ฆฐ์ƒท + + +### ๊ธฐ๋Šฅ ์š”์ฒญ +๋‹ค์Œ ์ •๋ณด๋ฅผ ํฌํ•จํ•ด ์ฃผ์„ธ์š”. +- ํ•ด๊ฒฐํ•˜๋ ค๋Š” ์‚ฌ์šฉ ์‚ฌ๋ก€ ๋˜๋Š” ๋ฌธ์ œ +- ์ œ์•ˆํ•˜๋Š” ํ•ด๊ฒฐ ๋ฐฉ๋ฒ• +- ๊ณ ๋ คํ–ˆ๋˜ ๋Œ€์•ˆ +- ์ถ”๊ฐ€ ์„ค๋ช… + +### ๋ฌธ์„œ ๊ด€๋ จ ๋ฌธ์ œ +๋‹ค์Œ ์ •๋ณด๋ฅผ ํฌํ•จํ•ด ์ฃผ์„ธ์š”. +- ์ดํ•ดํ•˜๊ธฐ ์–ด๋ ต๊ฑฐ๋‚˜ ๋ˆ„๋ฝ๋œ ๋ถ€๋ถ„ +- ๊ฐœ์„  ์ œ์•ˆ +- ์˜ˆ์ œ ๋˜๋Š” ์ฐธ๊ณ  ์ž๋ฃŒ + +## ํ”„๋กœ์ ํŠธ ์ •์ฑ… + +### ๋ฏผ๊ฐํ•œ ์ •๋ณด +- API ํ‚ค, ํ† ํฐ ๋˜๋Š” ์ž๊ฒฉ ์ฆ๋ช…์„ ์ ˆ๋Œ€ ์ปค๋ฐ‹ํ•˜์ง€ ๋งˆ์„ธ์š”. +- ์˜ˆ์ œ์—์„œ๋Š” ํ”Œ๋ ˆ์ด์Šคํ™€๋” ๊ฐ’์„ ์‚ฌ์šฉํ•˜์„ธ์š”. +- ์„ค์ • ํŒŒ์ผ์—๋Š” `.env.example`์„ ํฌํ•จํ•˜์„ธ์š”. +- ํ•„์š”ํ•œ ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋ฅผ ๋ฌธ์„œํ™”ํ•˜์„ธ์š”. + +### ์ฝ”๋“œ ํ’ˆ์งˆ +- ์˜ˆ์ œ๋Š” ํ•ต์‹ฌ์— ์ง‘์ค‘ํ•˜๊ณ  ์ฝ๊ธฐ ์‰ฝ๊ฒŒ ์ž‘์„ฑํ•˜์„ธ์š”. +- ๊ณผ๋„ํ•˜๊ฒŒ ๋ณต์žกํ•œ ๊ตฌํ˜„์€ ํ”ผํ•˜์„ธ์š”. +- ์ดํ•ดํ•˜๊ธฐ ์–ด๋ ค์šด ๋กœ์ง์—๋Š” ์ฃผ์„์„ ์ถ”๊ฐ€ํ•˜์„ธ์š”. +- ์ œ์ถœ ์ „์— ์ถฉ๋ถ„ํžˆ ํ…Œ์ŠคํŠธํ•˜์„ธ์š”. +- +### ์ง€์  ์žฌ์‚ฐ๊ถŒ +- ์›๋ณธ ์ฝ˜ํ…์ธ ์˜ ์ €์ž‘๊ถŒ์€ ์ž‘์„ฑ์ž์—๊ฒŒ ์žˆ์Šต๋‹ˆ๋‹ค. +- ํ”„๋กœ์ ํŠธ๋Š” ๊ต์œก ๋ชฉ์ ์˜ ๋ผ์ด์„ ์Šค๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +- ๊ธฐ์กด ์ €์ž‘๊ถŒ์„ ์กด์ค‘ํ•˜์„ธ์š”. +- ํ•„์š”ํ•œ ๊ฒฝ์šฐ ์ถœ์ฒ˜๋ฅผ ๋ช…์‹œํ•˜์„ธ์š”. + +## ๋„์›€๋ฐ›๊ธฐ + +- **์งˆ๋ฌธ**: GitHub Issues์—์„œ Discussion์„ ์ƒ์„ฑํ•˜์„ธ์š”. +- **์ผ๋ฐ˜์ ์ธ ๋„์›€**: ๊ธฐ์กด ๋ฌธ์„œ๋ฅผ ๋จผ์ € ํ™•์ธํ•˜์„ธ์š”. +- **๊ฐœ๋ฐœ ๊ด€๋ จ ๋„์›€**: ๋น„์Šทํ•œ ์˜ˆ์ œ๋ฅผ ์ฐธ๊ณ ํ•˜์„ธ์š”. +- **์ฝ”๋“œ ๋ฆฌ๋ทฐ**: PR์—์„œ ์œ ์ง€ ๊ด€๋ฆฌ์ž๋ฅผ ๋ฉ˜์…˜ํ•˜์„ธ์š”. + +## ๊ธฐ์—ฌ์ž ์ธ์ • + +๊ธฐ์—ฌ์ž๋Š” ๋‹ค์Œ ์œ„์น˜์—์„œ ์ธ์ •๋ฐ›์Šต๋‹ˆ๋‹ค. + +- README.md์˜ Contributors ์„น์…˜ +- GitHub Contributors ํŽ˜์ด์ง€ +- ์ปค๋ฐ‹ ๊ธฐ๋ก + +## ๋ณด์•ˆ + +์˜ˆ์ œ์™€ ๋ฌธ์„œ๋ฅผ ์ž‘์„ฑํ•  ๋•Œ๋Š” ์•ˆ์ „ํ•œ ์ฝ”๋”ฉ ์›์น™์„ ๋”ฐ๋ผ ์ฃผ์„ธ์š”. + +- **๋น„๋ฐ€ ์ •๋ณด๋‚˜ API ํ‚ค๋ฅผ ํ•˜๋“œ์ฝ”๋”ฉํ•˜์ง€ ๋งˆ์„ธ์š”.** ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋ฅผ ์‚ฌ์šฉํ•˜์„ธ์š”. +- **๋ณด์•ˆ์ƒ์˜ ์˜ํ–ฅ์„ ์•ˆ๋‚ดํ•˜์„ธ์š”.** ์ž ์žฌ์ ์ธ ์œ„ํ—˜์„ ๋ช…ํ™•ํžˆ ์„ค๋ช…ํ•˜์„ธ์š”. +- **์•ˆ์ „ํ•œ ๊ธฐ๋ณธ๊ฐ’์„ ์‚ฌ์šฉํ•˜์„ธ์š”.** ๊ธฐ๋ณธ์ ์œผ๋กœ ๋ณด์•ˆ ๊ธฐ๋Šฅ์„ ํ™œ์„ฑํ™”ํ•˜์„ธ์š”. +- **์ž…๋ ฅ์„ ๊ฒ€์ฆํ•˜์„ธ์š”.** ์ ์ ˆํ•œ ์ž…๋ ฅ ๊ฒ€์ฆ๊ณผ ๋ฐ์ดํ„ฐ ์ •์ œ(Sanitization) ์˜ˆ์ œ๋ฅผ ์ œ๊ณตํ•˜์„ธ์š”. +- **๋ณด์•ˆ ๊ด€๋ จ ์ฐธ๊ณ  ์‚ฌํ•ญ์„ ํฌํ•จํ•˜์„ธ์š”.** ๋ณด์•ˆ ๊ณ ๋ ค ์‚ฌํ•ญ์„ ๋ฌธ์„œํ™”ํ•˜์„ธ์š”. + +๋ณด์•ˆ ๋ฌธ์ œ๋Š” ์ทจ์•ฝ์  ์ œ๋ณด ์ ˆ์ฐจ๋ฅผ ์„ค๋ช…ํ•œ [SECURITY.md](SECURITY.md)๋ฅผ ์ฐธ๊ณ ํ•˜์„ธ์š”. + +## ํ–‰๋™ ๊ฐ•๋ น + +๋ชจ๋“  ์‚ฌ๋žŒ์ด ํ™˜์˜๋ฐ›๊ณ  ํฌ์šฉ๋˜๋Š” ์ปค๋ฎค๋‹ˆํ‹ฐ๋ฅผ ๋งŒ๋“ค๊ธฐ ์œ„ํ•ด ๋…ธ๋ ฅํ•˜๊ณ  ์žˆ์Šต๋‹ˆ๋‹ค. ์ž์„ธํ•œ ์ปค๋ฎค๋‹ˆํ‹ฐ ๊ธฐ์ค€์€ [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)๋ฅผ ์ฐธ๊ณ ํ•˜์„ธ์š”. + +์š”์•ฝํ•˜๋ฉด ๋‹ค์Œ๊ณผ ๊ฐ™์Šต๋‹ˆ๋‹ค. +- ์„œ๋กœ๋ฅผ ์กด์ค‘ํ•˜๊ณ  ํฌ์šฉํ•˜์„ธ์š”. +- ํ”ผ๋“œ๋ฐฑ์„ ์—ด๋ฆฐ ์ž์„ธ๋กœ ๋ฐ›์•„๋“ค์ด์„ธ์š”. +- ๋‹ค๋ฅธ ์‚ฌ๋žŒ์˜ ํ•™์Šต๊ณผ ์„ฑ์žฅ์„ ๋„์™€์ฃผ์„ธ์š”. +- ๊ดด๋กญํž˜์ด๋‚˜ ์ฐจ๋ณ„์„ ํ•˜์ง€ ๋งˆ์„ธ์š”. +- ๋ฌธ์ œ๊ฐ€ ๋ฐœ์ƒํ•˜๋ฉด ์œ ์ง€ ๊ด€๋ฆฌ์ž์—๊ฒŒ ์•Œ๋ ค ์ฃผ์„ธ์š”. + +๋ชจ๋“  ๊ธฐ์—ฌ์ž๋Š” ์ด ํ–‰๋™ ๊ฐ•๋ น์„ ์ค€์ˆ˜ํ•˜๋ฉฐ ์„œ๋กœ๋ฅผ ์นœ์ ˆํ•˜๊ณ  ์กด์ค‘ํ•˜๋Š” ํƒœ๋„๋กœ ๋Œ€ํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. + +## ๋ผ์ด์„ ์Šค + +์ด ํ”„๋กœ์ ํŠธ์— ๊ธฐ์—ฌํ•˜๋ฉด ๊ธฐ์—ฌํ•œ ๋‚ด์šฉ์ด MIT ๋ผ์ด์„ ์Šค๋กœ ๋ฐฐํฌ๋˜๋Š” ๊ฒƒ์— ๋™์˜ํ•˜๋Š” ๊ฒƒ์œผ๋กœ ๊ฐ„์ฃผ๋ฉ๋‹ˆ๋‹ค. ์ž์„ธํ•œ ๋‚ด์šฉ์€ [LICENSE](LICENSE)๋ฅผ ์ฐธ๊ณ ํ•˜์„ธ์š”. + +## ์งˆ๋ฌธ์ด ์žˆ์œผ์‹ ๊ฐ€์š”? + +- [README](README.md)๋ฅผ ํ™•์ธํ•˜์„ธ์š”. +- [LEARNING-ROADMAP.md](LEARNING-ROADMAP.md)๋ฅผ ์ฐธ๊ณ ํ•˜์„ธ์š”. +- ๊ธฐ์กด ์˜ˆ์ œ๋ฅผ ์‚ดํŽด๋ณด์„ธ์š”. +- ํ† ๋ก ์ด ํ•„์š”ํ•˜๋ฉด ์ด์Šˆ๋ฅผ ์ƒ์„ฑํ•˜์„ธ์š”. + +๊ธฐ์—ฌํ•ด ์ฃผ์…”์„œ ๊ฐ์‚ฌํ•ฉ๋‹ˆ๋‹ค! ๐Ÿ™ + +--- +**๋งˆ์ง€๋ง‰ ์—…๋ฐ์ดํŠธ**: 2026๋…„ 4์›” 9์ผ diff --git a/ko/INDEX.md b/ko/INDEX.md new file mode 100644 index 00000000..2102f24e --- /dev/null +++ b/ko/INDEX.md @@ -0,0 +1,896 @@ + + + Claude How To + + +# ํด๋กœ๋“œ ์ฝ”๋“œ ์˜ˆ์‹œ - ์ „์ฒด ์ƒ‰์ธ + +์ด ๋ฌธ์„œ๋Š” ๊ธฐ๋Šฅ ์œ ํ˜•๋ณ„๋กœ ์ •๋ฆฌ๋œ ๋ชจ๋“  ์˜ˆ์‹œ ํŒŒ์ผ์˜ ์ „์ฒด ์ƒ‰์ธ์„ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. + +## ์š”์•ฝ ํ†ต๊ณ„ + +- **์ด ํŒŒ์ผ ์ˆ˜**: 100๊ฐœ ์ด์ƒ +- **์นดํ…Œ๊ณ ๋ฆฌ**: 10๊ฐ€์ง€ ๊ธฐ๋Šฅ ์นดํ…Œ๊ณ ๋ฆฌ +- **ํ”Œ๋Ÿฌ๊ทธ์ธ**: 3๊ฐœ์˜ ์™„๋ฒฝํ•œ ํ”Œ๋Ÿฌ๊ทธ์ธ +- **์Šคํ‚ฌ**: 6๊ฐœ์˜ ์™„๋ฒฝํ•œ ์Šคํ‚ฌ +- **ํ›…**: 8๊ฐ€์ง€ ์˜ˆ์‹œ ํ›… +- **์ฆ‰์‹œ ์‚ฌ์šฉ ๊ฐ€๋Šฅ**: ๋ชจ๋“  ์˜ˆ์‹œ + +--- + +## 01. ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด (10๊ฐœ ํŒŒ์ผ) + +์ผ๋ฐ˜์ ์ธ ์›Œํฌํ”Œ๋กœ์šฐ๋ฅผ ์œ„ํ•œ ์‚ฌ์šฉ์ž ํ˜ธ์ถœ ๋‹จ์ถ• ๋ช…๋ น์–ด์ž…๋‹ˆ๋‹ค. + +| ํŒŒ์ผ | ์„ค๋ช… | ์‚ฌ์šฉ ์‚ฌ๋ก€ | +|------|-------------|----------| +| `optimize.md` | ์ฝ”๋“œ ์ตœ์ ํ™” ๋ถ„์„๊ธฐ | ์„ฑ๋Šฅ ๋ฌธ์ œ ์ฐพ๊ธฐ | +| `pr.md` | ํ’€ ๋ฆฌํ€˜์ŠคํŠธ ์ค€๋น„ | PR ์›Œํฌํ”Œ๋กœ์šฐ ์ž๋™ํ™” | +| `generate-api-docs.md` | API ๋ฌธ์„œ ์ƒ์„ฑ๊ธฐ | API ๋ฌธ์„œ ์ƒ์„ฑ | +| `commit.md` | ์ปค๋ฐ‹ ๋ฉ”์‹œ์ง€ ๋„์šฐ๋ฏธ | ํ‘œ์ค€ํ™”๋œ ์ปค๋ฐ‹ | +| `setup-ci-cd.md` | CI/CD ํŒŒ์ดํ”„๋ผ์ธ ์„ค์ • | ๋ฐ๋ธŒ์˜ต์Šค ์ž๋™ํ™” | +| `push-all.md` | ๋ชจ๋“  ๋ณ€๊ฒฝ์‚ฌํ•ญ ํ‘ธ์‹œ | ๋น ๋ฅธ ํ‘ธ์‹œ ์›Œํฌํ”Œ๋กœ์šฐ | +| `unit-test-expand.md` | ๋‹จ์œ„ ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€ ํ™•์žฅ | ํ…Œ์ŠคํŠธ ์ž๋™ํ™” | +| `doc-refactor.md` | ๋ฌธ์„œ ๋ฆฌํŒฉํ† ๋ง | ๋ฌธ์„œ ๊ฐœ์„  | +| `pr-slash-command.png` | ์Šคํฌ๋ฆฐ์ƒท ์˜ˆ์‹œ | ์‹œ๊ฐ์  ์ฐธ๊ณ  ์ž๋ฃŒ | +| `README.md` | ๋ฌธ์„œ | ์„ค์ • ๋ฐ ์‚ฌ์šฉ ๊ฐ€์ด๋“œ | + +**์„ค์น˜ ๊ฒฝ๋กœ**: `.claude/commands/` + +**์‚ฌ์šฉ๋ฒ•**: `/optimize`, `/pr`, `/generate-api-docs`, `/commit`, `/setup-ci-cd`, `/push-all`, `/unit-test-expand`, `/doc-refactor` + +--- + +## 02. ๋ฉ”๋ชจ๋ฆฌ (6๊ฐœ ํŒŒ์ผ) + +์˜๊ตฌ์ ์ธ ์ปจํ…์ŠคํŠธ์™€ ํ”„๋กœ์ ํŠธ ํ‘œ์ค€์ž…๋‹ˆ๋‹ค. + +| ํŒŒ์ผ | ์„ค๋ช… | ๋ฒ”์œ„ | ์œ„์น˜ | +|------|-------------|-------|----------| +| `project-CLAUDE.md` | ํŒ€ ํ”„๋กœ์ ํŠธ ํ‘œ์ค€ | ํ”„๋กœ์ ํŠธ ์ „์ฒด | `./CLAUDE.md` | +| `directory-api-CLAUDE.md` | API๋ณ„ ๊ทœ์น™ | ๋””๋ ‰ํ† ๋ฆฌ | `./src/api/CLAUDE.md` | +| `personal-CLAUDE.md` | ๊ฐœ์ธ ์„ค์ • | ์‚ฌ์šฉ์ž | `~/.claude/CLAUDE.md` | +| `memory-saved.png` | ์Šคํฌ๋ฆฐ์ƒท: ๋ฉ”๋ชจ๋ฆฌ ์ €์žฅ๋จ | - | ์‹œ๊ฐ์  ์ฐธ๊ณ  ์ž๋ฃŒ | +| `memory-ask-claude.png` | ์Šคํฌ๋ฆฐ์ƒท: ํด๋กœ๋“œ์—๊ฒŒ ์งˆ๋ฌธ | - | ์‹œ๊ฐ์  ์ฐธ๊ณ  ์ž๋ฃŒ | +| `README.md` | ๋ฌธ์„œ | - | ์ฐธ์กฐ | + +**์„ค์น˜**: ์ ์ ˆํ•œ ์œ„์น˜์— ๋ณต์‚ฌ + +**์‚ฌ์šฉ๋ฒ•**: ํด๋กœ๋“œ์— ์˜ํ•ด ์ž๋™์œผ๋กœ ๋กœ๋“œ๋ฉ๋‹ˆ๋‹ค. + +--- + +## 03. ์Šคํ‚ฌ (16๊ฐœ ํŒŒ์ผ) + +์Šคํฌ๋ฆฝํŠธ ๋ฐ ํ…œํ”Œ๋ฆฟ๊ณผ ํ•จ๊ป˜ ์ž๋™์œผ๋กœ ํ˜ธ์ถœ๋˜๋Š” ๊ธฐ๋Šฅ์ž…๋‹ˆ๋‹ค. + +### ์ฝ”๋“œ ๊ฒ€ํ†  ์Šคํ‚ฌ (5๊ฐœ ํŒŒ์ผ) +``` +code-review-specialist/ +โ”œโ”€โ”€ SKILL.md # ์Šคํ‚ฌ ์ •์˜ +โ”œโ”€โ”€ scripts/ +โ”‚ โ”œโ”€โ”€ analyze-metrics.py # ์ฝ”๋“œ ๋ฉ”ํŠธ๋ฆญ ๋ถ„์„๊ธฐ +โ”‚ โ””โ”€โ”€ compare-complexity.py # ๋ณต์žก๋„ ๋น„๊ต +โ””โ”€โ”€ templates/ + โ”œโ”€โ”€ review-checklist.md # ๊ฒ€ํ†  ์ฒดํฌ๋ฆฌ์ŠคํŠธ + โ””โ”€โ”€ finding-template.md # ๋ฐœ๊ฒฌ ์‚ฌํ•ญ ๋ฌธ์„œ +``` + +**๋ชฉ์ **: ๋ณด์•ˆ, ์„ฑ๋Šฅ ๋ฐ ํ’ˆ์งˆ ๋ถ„์„์„ ํฌํ•จํ•œ ์ข…ํ•ฉ์ ์ธ ์ฝ”๋“œ ๊ฒ€ํ† ์ž…๋‹ˆ๋‹ค. + +**์ž๋™ ํ˜ธ์ถœ**: ์ฝ”๋“œ๋ฅผ ๊ฒ€ํ† ํ•  ๋•Œ + +--- + +### ๋ธŒ๋žœ๋“œ ๋ณด์ด์Šค ์Šคํ‚ฌ (4๊ฐœ ํŒŒ์ผ) +``` +brand-voice/ +โ”œโ”€โ”€ SKILL.md # ์Šคํ‚ฌ ์ •์˜ +โ”œโ”€โ”€ templates/ +โ”‚ โ”œโ”€โ”€ email-template.txt # ์ด๋ฉ”์ผ ํ˜•์‹ +โ”‚ โ””โ”€โ”€ social-post-template.txt # ์†Œ์…œ ๋ฏธ๋””์–ด ํ˜•์‹ +โ””โ”€โ”€ tone-examples.md # ์˜ˆ์‹œ ๋ฉ”์‹œ์ง€ +``` + +**๋ชฉ์ **: ์ปค๋ฎค๋‹ˆ์ผ€์ด์…˜์—์„œ ์ผ๊ด€๋œ ๋ธŒ๋žœ๋“œ ๋ณด์ด์Šค๋ฅผ ๋ณด์žฅํ•ฉ๋‹ˆ๋‹ค. + +**์ž๋™ ํ˜ธ์ถœ**: ๋งˆ์ผ€ํŒ… ๋ฌธ๊ตฌ๋ฅผ ์ž‘์„ฑํ•  ๋•Œ + +--- + +### ๋ฌธ์„œ ์ƒ์„ฑ๊ธฐ ์Šคํ‚ฌ (2๊ฐœ ํŒŒ์ผ) +``` +doc-generator/ +โ”œโ”€โ”€ SKILL.md # ์Šคํ‚ฌ ์ •์˜ +โ””โ”€โ”€ generate-docs.py # ํŒŒ์ด์ฌ ๋ฌธ์„œ ์ถ”์ถœ๊ธฐ +``` + +**๋ชฉ์ **: ์†Œ์Šค ์ฝ”๋“œ๋กœ๋ถ€ํ„ฐ ํฌ๊ด„์ ์ธ API ๋ฌธ์„œ๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. + +**์ž๋™ ํ˜ธ์ถœ**: API ๋ฌธ์„œ๋ฅผ ์ƒ์„ฑ/์—…๋ฐ์ดํŠธํ•  ๋•Œ + +--- + +### ๋ฆฌํŒฉํ„ฐ ์Šคํ‚ฌ (5๊ฐœ ํŒŒ์ผ) +``` +refactor/ +โ”œโ”€โ”€ SKILL.md # ์Šคํ‚ฌ ์ •์˜ +โ”œโ”€โ”€ scripts/ +โ”‚ โ”œโ”€โ”€ analyze-complexity.py # ๋ณต์žก๋„ ๋ถ„์„๊ธฐ +โ”‚ โ””โ”€โ”€ detect-smells.py # ์ฝ”๋“œ ์Šค๋ฉœ ๊ฐ์ง€๊ธฐ +โ”œโ”€โ”€ references/ +โ”‚ โ”œโ”€โ”€ code-smells.md # ์ฝ”๋“œ ์Šค๋ฉœ ์นดํƒˆ๋กœ๊ทธ +โ”‚ โ””โ”€โ”€ refactoring-catalog.md # ๋ฆฌํŒฉํ† ๋ง ํŒจํ„ด +โ””โ”€โ”€ templates/ + โ””โ”€โ”€ refactoring-plan.md # ๋ฆฌํŒฉํ† ๋ง ๊ณ„ํš ํ…œํ”Œ๋ฆฟ +``` + +**๋ชฉ์ **: ๋ณต์žก๋„ ๋ถ„์„์„ ํ†ตํ•œ ์ฒด๊ณ„์ ์ธ ์ฝ”๋“œ ๋ฆฌํŒฉํ† ๋ง์ž…๋‹ˆ๋‹ค. + +**์ž๋™ ํ˜ธ์ถœ**: ์ฝ”๋“œ๋ฅผ ๋ฆฌํŒฉํ† ๋งํ•  ๋•Œ + +--- + +### ํด๋กœ๋“œ MD ์Šคํ‚ฌ (1๊ฐœ ํŒŒ์ผ) +``` +claude-md/ +โ””โ”€โ”€ SKILL.md # ์Šคํ‚ฌ ์ •์˜ +``` + +**๋ชฉ์ **: CLAUDE.md ํŒŒ์ผ์„ ๊ด€๋ฆฌํ•˜๊ณ  ์ตœ์ ํ™”ํ•ฉ๋‹ˆ๋‹ค. + +--- + +### ๋ธ”๋กœ๊ทธ ์ดˆ์•ˆ ์Šคํ‚ฌ (3๊ฐœ ํŒŒ์ผ) +``` +blog-draft/ +โ”œโ”€โ”€ SKILL.md # ์Šคํ‚ฌ ์ •์˜ +โ””โ”€โ”€ templates/ + โ”œโ”€โ”€ draft-template.md # ๋ธ”๋กœ๊ทธ ์ดˆ์•ˆ ํ…œํ”Œ๋ฆฟ + โ””โ”€โ”€ outline-template.md # ๋ธ”๋กœ๊ทธ ๊ฐœ์š” ํ…œํ”Œ๋ฆฟ +``` + +**๋ชฉ์ **: ์ผ๊ด€๋œ ๊ตฌ์กฐ๋กœ ๋ธ”๋กœ๊ทธ ๊ฒŒ์‹œ๋ฌผ ์ดˆ์•ˆ์„ ์ž‘์„ฑํ•ฉ๋‹ˆ๋‹ค. + +**์ถ”๊ฐ€**: `README.md` - ์Šคํ‚ฌ ๊ฐœ์š” ๋ฐ ์‚ฌ์šฉ ๊ฐ€์ด๋“œ + +**์„ค์น˜ ๊ฒฝ๋กœ**: `~/.claude/skills/` ๋˜๋Š” `.claude/skills/` + +--- + +## 04. ์„œ๋ธŒ ์—์ด์ „ํŠธ (9๊ฐœ ํŒŒ์ผ) + +์‚ฌ์šฉ์ž ์ง€์ • ๊ธฐ๋Šฅ์„ ๊ฐ–์ถ˜ ํŠนํ™”๋œ AI ์–ด์‹œ์Šคํ„ดํŠธ์ž…๋‹ˆ๋‹ค. + +| ํŒŒ์ผ | ์„ค๋ช… | ๋„๊ตฌ | ์‚ฌ์šฉ ์‚ฌ๋ก€ | +|------|-------------|-------|----------| +| `code-reviewer.md` | ์ฝ”๋“œ ํ’ˆ์งˆ ๋ถ„์„ | read, grep, diff, lint_runner | ์ข…ํ•ฉ์ ์ธ ๊ฒ€ํ†  | +| `test-engineer.md` | ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€ ๋ถ„์„ | read, write, bash, grep | ํ…Œ์ŠคํŠธ ์ž๋™ํ™” | +| `documentation-writer.md` | ๋ฌธ์„œ ์ž‘์„ฑ | read, write, grep | ๋ฌธ์„œ ์ƒ์„ฑ | +| `secure-reviewer.md` | ๋ณด์•ˆ ๊ฒ€ํ†  (์ฝ๊ธฐ ์ „์šฉ) | read, grep | ๋ณด์•ˆ ๊ฐ์‚ฌ | +| `implementation-agent.md` | ์ „์ฒด ๊ตฌํ˜„ | read, write, bash, grep, edit, glob | ๊ธฐ๋Šฅ ๊ฐœ๋ฐœ | +| `debugger.md` | ๋””๋ฒ„๊น… ์ „๋ฌธ๊ฐ€ | read, bash, grep | ๋ฒ„๊ทธ ์กฐ์‚ฌ | +| `data-scientist.md` | ๋ฐ์ดํ„ฐ ๋ถ„์„ ์ „๋ฌธ๊ฐ€ | read, write, bash | ๋ฐ์ดํ„ฐ ์›Œํฌํ”Œ๋กœ์šฐ | +| `clean-code-reviewer.md` | ํด๋ฆฐ ์ฝ”๋“œ ํ‘œ์ค€ | read, grep | ์ฝ”๋“œ ํ’ˆ์งˆ | +| `README.md` | ๋ฌธ์„œ | - | ์„ค์ • ๋ฐ ์‚ฌ์šฉ ๊ฐ€์ด๋“œ | + +**์„ค์น˜ ๊ฒฝ๋กœ**: `.claude/agents/` + +**์‚ฌ์šฉ๋ฒ•**: ๋ฉ”์ธ ์—์ด์ „ํŠธ์— ์˜ํ•ด ์ž๋™์œผ๋กœ ์œ„์ž„๋ฉ๋‹ˆ๋‹ค. + +--- + +## 05. MCP ํ”„๋กœํ† ์ฝœ (5๊ฐœ ํŒŒ์ผ) + +์™ธ๋ถ€ ๋„๊ตฌ ๋ฐ API ํ†ตํ•ฉ์ž…๋‹ˆ๋‹ค. + +| ํŒŒ์ผ | ์„ค๋ช… | ํ†ตํ•ฉ ๋Œ€์ƒ | ์‚ฌ์šฉ ์‚ฌ๋ก€ | +|------|-------------|-----------------|----------| +| `github-mcp.json` | GitHub ํ†ตํ•ฉ | GitHub API | PR/์ด์Šˆ ๊ด€๋ฆฌ | +| `database-mcp.json` | ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ์ฟผ๋ฆฌ | PostgreSQL/MySQL | ์‹ค์‹œ๊ฐ„ ๋ฐ์ดํ„ฐ ์ฟผ๋ฆฌ | +| `filesystem-mcp.json` | ํŒŒ์ผ ์ž‘์—… | ๋กœ์ปฌ ํŒŒ์ผ ์‹œ์Šคํ…œ | ํŒŒ์ผ ๊ด€๋ฆฌ | +| `multi-mcp.json` | ๋‹ค์ค‘ ์„œ๋ฒ„ | GitHub + DB + Slack | ์™„์ „ํ•œ ํ†ตํ•ฉ | +| `README.md` | ๋ฌธ์„œ | - | ์„ค์ • ๋ฐ ์‚ฌ์šฉ ๊ฐ€์ด๋“œ | + +**์„ค์น˜ ๊ฒฝ๋กœ**: `.mcp.json` (ํ”„๋กœ์ ํŠธ ๋ฒ”์œ„) ๋˜๋Š” `~/.claude.json` (์‚ฌ์šฉ์ž ๋ฒ”์œ„) + +**์‚ฌ์šฉ๋ฒ•**: `/mcp__github__list_prs`, ๋“ฑ. + +--- + +## 06. ํ›… (9๊ฐœ ํŒŒ์ผ) + +์ž๋™์œผ๋กœ ์‹คํ–‰๋˜๋Š” ์ด๋ฒคํŠธ ๊ธฐ๋ฐ˜ ์ž๋™ํ™” ์Šคํฌ๋ฆฝํŠธ์ž…๋‹ˆ๋‹ค. + +| ํŒŒ์ผ | ์„ค๋ช… | ์ด๋ฒคํŠธ | ์‚ฌ์šฉ ์‚ฌ๋ก€ | +|------|-------------|-------|----------| +| `format-code.sh` | ์ฝ”๋“œ ์ž๋™ ํฌ๋งท | PreToolUse:Write | ์ฝ”๋“œ ํฌ๋งทํŒ… | +| `pre-commit.sh` | ์ปค๋ฐ‹ ์ „ ํ…Œ์ŠคํŠธ ์‹คํ–‰ | PreToolUse:Bash | ํ…Œ์ŠคํŠธ ์ž๋™ํ™” | +| `security-scan.sh` | ๋ณด์•ˆ ์Šค์บ๋‹ | PostToolUse:Write | ๋ณด์•ˆ ๊ฒ€์‚ฌ | +| `log-bash.sh` | Bash ๋ช…๋ น์–ด ๋กœ๊น… | PostToolUse:Bash | ๋ช…๋ น์–ด ๋กœ๊น… | +| `validate-prompt.sh` | ํ”„๋กฌํ”„ํŠธ ์œ ํšจ์„ฑ ๊ฒ€์‚ฌ | PreToolUse | ์ž…๋ ฅ ์œ ํšจ์„ฑ ๊ฒ€์‚ฌ | +| `notify-team.sh` | ์•Œ๋ฆผ ๋ณด๋‚ด๊ธฐ | Notification | ํŒ€ ์•Œ๋ฆผ | +| `context-tracker.py` | ์ปจํ…์ŠคํŠธ ์ฐฝ ์‚ฌ์šฉ๋Ÿ‰ ์ถ”์  | PostToolUse | ์ปจํ…์ŠคํŠธ ๋ชจ๋‹ˆํ„ฐ๋ง | +| `context-tracker-tiktoken.py` | ํ† ํฐ ๊ธฐ๋ฐ˜ ์ปจํ…์ŠคํŠธ ์ถ”์  | PostToolUse | ์ •ํ™•ํ•œ ํ† ํฐ ๊ณ„์‚ฐ | +| `README.md` | ๋ฌธ์„œ | - | ์„ค์ • ๋ฐ ์‚ฌ์šฉ ๊ฐ€์ด๋“œ | + +**์„ค์น˜ ๊ฒฝ๋กœ**: `~/.claude/settings.json`์—์„œ ๊ตฌ์„ฑ + +**์‚ฌ์šฉ๋ฒ•**: ์„ค์ •์—์„œ ๊ตฌ์„ฑ๋˜๋ฉฐ ์ž๋™์œผ๋กœ ์‹คํ–‰๋ฉ๋‹ˆ๋‹ค. + +**ํ›… ์œ ํ˜•** (5๊ฐ€์ง€ ์œ ํ˜•, 29๊ฐ€์ง€ ์ด๋ฒคํŠธ): +- ๋„๊ตฌ ํ›…: PreToolUse, PostToolUse, PostToolUseFailure, PostToolBatch, PermissionRequest, PermissionDenied +- ์„ธ์…˜ ํ›…: SessionStart, Setup, SessionEnd, Stop, StopFailure, SubagentStart, SubagentStop +- ํƒœ์Šคํฌ ํ›…: UserPromptSubmit, UserPromptExpansion, TaskCompleted, TaskCreated, TeammateIdle +- ์ˆ˜๋ช… ์ฃผ๊ธฐ ํ›…: ConfigChange, CwdChanged, FileChanged, PreCompact, PostCompact, WorktreeCreate, WorktreeRemove, Notification, InstructionsLoaded, Elicitation, ElicitationResult + +--- + +## 07. ํ”Œ๋Ÿฌ๊ทธ์ธ (3๊ฐœ์˜ ์™„๋ฒฝํ•œ ํ”Œ๋Ÿฌ๊ทธ์ธ, 27๊ฐœ ํŒŒ์ผ) + +๊ธฐ๋Šฅ๋“ค์„ ๋ฌถ์–ด ๋†“์€ ๋ชจ์Œ์ง‘์ž…๋‹ˆ๋‹ค. + +### PR ๊ฒ€ํ†  ํ”Œ๋Ÿฌ๊ทธ์ธ (10๊ฐœ ํŒŒ์ผ) +``` +pr-review/ +โ”œโ”€โ”€ .claude-plugin/ +โ”‚ โ””โ”€โ”€ plugin.json # ํ”Œ๋Ÿฌ๊ทธ์ธ ๋งค๋‹ˆํŽ˜์ŠคํŠธ +โ”œโ”€โ”€ commands/ +โ”‚ โ”œโ”€โ”€ review-pr.md # ์ข…ํ•ฉ ๊ฒ€ํ†  +โ”‚ โ”œโ”€โ”€ check-security.md # ๋ณด์•ˆ ๊ฒ€์‚ฌ +โ”‚ โ””โ”€โ”€ check-tests.md # ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€ ๊ฒ€์‚ฌ +โ”œโ”€โ”€ agents/ +โ”‚ โ”œโ”€โ”€ security-reviewer.md # ๋ณด์•ˆ ์ „๋ฌธ๊ฐ€ +โ”‚ โ”œโ”€โ”€ test-checker.md # ํ…Œ์ŠคํŠธ ์ „๋ฌธ๊ฐ€ +โ”‚ โ””โ”€โ”€ performance-analyzer.md # ์„ฑ๋Šฅ ์ „๋ฌธ๊ฐ€ +โ”œโ”€โ”€ mcp/ +โ”‚ โ””โ”€โ”€ github-config.json # GitHub ํ†ตํ•ฉ +โ”œโ”€โ”€ hooks/ +โ”‚ โ””โ”€โ”€ pre-review.js # ์‚ฌ์ „ ๊ฒ€ํ†  ์œ ํšจ์„ฑ ๊ฒ€์‚ฌ +โ””โ”€โ”€ README.md # ํ”Œ๋Ÿฌ๊ทธ์ธ ๋ฌธ์„œ +``` + +**๊ธฐ๋Šฅ**: ๋ณด์•ˆ ๋ถ„์„, ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€, ์„ฑ๋Šฅ ์˜ํ–ฅ + +**๋ช…๋ น์–ด**: `/review-pr`, `/check-security`, `/check-tests` + +**์„ค์น˜**: `/plugin install pr-review` + +--- + +### ๋ฐ๋ธŒ์˜ต์Šค ์ž๋™ํ™” ํ”Œ๋Ÿฌ๊ทธ์ธ (15๊ฐœ ํŒŒ์ผ) +``` +devops-automation/ +โ”œโ”€โ”€ .claude-plugin/ +โ”‚ โ””โ”€โ”€ plugin.json # ํ”Œ๋Ÿฌ๊ทธ์ธ ๋งค๋‹ˆํŽ˜์ŠคํŠธ +โ”œโ”€โ”€ commands/ +โ”‚ โ”œโ”€โ”€ deploy.md # ๋ฐฐํฌ +โ”‚ โ”œโ”€โ”€ rollback.md # ๋กค๋ฐฑ +โ”‚ โ”œโ”€โ”€ status.md # ์‹œ์Šคํ…œ ์ƒํƒœ +โ”‚ โ””โ”€โ”€ incident.md # ์ธ์‹œ๋˜ํŠธ ๋Œ€์‘ +โ”œโ”€โ”€ agents/ +โ”‚ โ”œโ”€โ”€ deployment-specialist.md # ๋ฐฐํฌ ์ „๋ฌธ๊ฐ€ +โ”‚ โ”œโ”€โ”€ incident-commander.md # ์ธ์‹œ๋˜ํŠธ ์ฝ”๋””๋„ค์ดํ„ฐ +โ”‚ โ””โ”€โ”€ alert-analyzer.md # ๊ฒฝ๊ณ  ๋ถ„์„๊ธฐ +โ”œโ”€โ”€ mcp/ +โ”‚ โ””โ”€โ”€ kubernetes-config.json # Kubernetes ํ†ตํ•ฉ +โ”œโ”€โ”€ hooks/ +โ”‚ โ”œโ”€โ”€ pre-deploy.js # ๋ฐฐํฌ ์ „ ๊ฒ€์‚ฌ +โ”‚ โ””โ”€โ”€ post-deploy.js # ๋ฐฐํฌ ํ›„ ์ž‘์—… +โ”œโ”€โ”€ scripts/ +โ”‚ โ”œโ”€โ”€ deploy.sh # ๋ฐฐํฌ ์ž๋™ํ™” +โ”‚ โ”œโ”€โ”€ rollback.sh # ๋กค๋ฐฑ ์ž๋™ํ™” +โ”‚ โ””โ”€โ”€ health-check.sh # ์ƒํƒœ ๊ฒ€์‚ฌ +โ””โ”€โ”€ README.md # ํ”Œ๋Ÿฌ๊ทธ์ธ ๋ฌธ์„œ +``` + +**๊ธฐ๋Šฅ**: Kubernetes ๋ฐฐํฌ, ๋กค๋ฐฑ, ๋ชจ๋‹ˆํ„ฐ๋ง, ์ธ์‹œ๋˜ํŠธ ๋Œ€์‘ + +**๋ช…๋ น์–ด**: `/deploy`, `/rollback`, `/status`, `/incident` + +**์„ค์น˜**: `/plugin install devops-automation` + +--- + +### ๋ฌธ์„œํ™” ํ”Œ๋Ÿฌ๊ทธ์ธ (14๊ฐœ ํŒŒ์ผ) +``` +documentation/ +โ”œโ”€โ”€ .claude-plugin/ +โ”‚ โ””โ”€โ”€ plugin.json # ํ”Œ๋Ÿฌ๊ทธ์ธ ๋งค๋‹ˆํŽ˜์ŠคํŠธ +โ”œโ”€โ”€ commands/ +โ”‚ โ”œโ”€โ”€ generate-api-docs.md # API ๋ฌธ์„œ ์ƒ์„ฑ +โ”‚ โ”œโ”€โ”€ generate-readme.md # README ์ƒ์„ฑ +โ”‚ โ”œโ”€โ”€ sync-docs.md # ๋ฌธ์„œ ๋™๊ธฐํ™” +โ”‚ โ””โ”€โ”€ validate-docs.md # ๋ฌธ์„œ ์œ ํšจ์„ฑ ๊ฒ€์‚ฌ +โ”œโ”€โ”€ agents/ +โ”‚ โ”œโ”€โ”€ api-documenter.md # API ๋ฌธ์„œ ์ „๋ฌธ๊ฐ€ +โ”‚ โ”œโ”€โ”€ code-commentator.md # ์ฝ”๋“œ ์ฃผ์„ ์ „๋ฌธ๊ฐ€ +โ”‚ โ””โ”€โ”€ example-generator.md # ์˜ˆ์‹œ ์ƒ์„ฑ๊ธฐ +โ”œโ”€โ”€ mcp/ +โ”‚ โ””โ”€โ”€ github-docs-config.json # GitHub ํ†ตํ•ฉ +โ”œโ”€โ”€ templates/ +โ”‚ โ”œโ”€โ”€ api-endpoint.md # API ์—”๋“œํฌ์ธํŠธ ํ…œํ”Œ๋ฆฟ +โ”‚ โ”œโ”€โ”€ function-docs.md # ํ•จ์ˆ˜ ๋ฌธ์„œ ํ…œํ”Œ๋ฆฟ +โ”‚ โ””โ”€โ”€ adr-template.md # ADR ํ…œํ”Œ๋ฆฟ +โ””โ”€โ”€ README.md # ํ”Œ๋Ÿฌ๊ทธ์ธ ๋ฌธ์„œ +``` + +**๊ธฐ๋Šฅ**: API ๋ฌธ์„œ, README ์ƒ์„ฑ, ๋ฌธ์„œ ๋™๊ธฐํ™”, ์œ ํšจ์„ฑ ๊ฒ€์‚ฌ + +**๋ช…๋ น์–ด**: `/generate-api-docs`, `/generate-readme`, `/sync-docs`, `/validate-docs` + +**์„ค์น˜**: `/plugin install documentation` + +**์ถ”๊ฐ€**: `README.md` - ํ”Œ๋Ÿฌ๊ทธ์ธ ๊ฐœ์š” ๋ฐ ์‚ฌ์šฉ ๊ฐ€์ด๋“œ + +--- + +## 08. ์ฒดํฌํฌ์ธํŠธ ๋ฐ ๋˜๊ฐ๊ธฐ (2๊ฐœ ํŒŒ์ผ) + +๋Œ€ํ™” ์ƒํƒœ๋ฅผ ์ €์žฅํ•˜๊ณ  ๋Œ€์•ˆ์ ์ธ ์ ‘๊ทผ ๋ฐฉ์‹์„ ํƒ์ƒ‰ํ•ฉ๋‹ˆ๋‹ค. + +| ํŒŒ์ผ | ์„ค๋ช… | ๋‚ด์šฉ | +|------|-------------|---------| +| `README.md` | ๋ฌธ์„œ | ํฌ๊ด„์ ์ธ ์ฒดํฌํฌ์ธํŠธ ๊ฐ€์ด๋“œ | +| `checkpoint-examples.md` | ์‹ค์ œ ์˜ˆ์‹œ | ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜, ์„ฑ๋Šฅ ์ตœ์ ํ™”, UI ๋ฐ˜๋ณต, ๋””๋ฒ„๊น… | +| | | | + +**์ฃผ์š” ๊ฐœ๋…**: +- **์ฒดํฌํฌ์ธํŠธ**: ๋Œ€ํ™” ์ƒํƒœ์˜ ์Šค๋ƒ…์ƒท +- **๋˜๊ฐ๊ธฐ**: ์ด์ „ ์ฒดํฌํฌ์ธํŠธ๋กœ ๋Œ์•„๊ฐ€๊ธฐ +- **๋ถ„๊ธฐ์ **: ์—ฌ๋Ÿฌ ์ ‘๊ทผ ๋ฐฉ์‹ ํƒ์ƒ‰ + +**์‚ฌ์šฉ๋ฒ•**: +``` +# ์ฒดํฌํฌ์ธํŠธ๋Š” ์‚ฌ์šฉ์ž ํ”„๋กฌํ”„ํŠธ๋งˆ๋‹ค ์ž๋™์œผ๋กœ ์ƒ์„ฑ๋ฉ๋‹ˆ๋‹ค. +# ๋˜๊ฐ์œผ๋ ค๋ฉด Esc๋ฅผ ๋‘ ๋ฒˆ ๋ˆ„๋ฅด๊ฑฐ๋‚˜ ๋‹ค์Œ์„ ์‚ฌ์šฉํ•˜์‹ญ์‹œ์˜ค: +/rewind +# ๊ทธ๋Ÿฐ ๋‹ค์Œ ์„ ํƒํ•˜์‹ญ์‹œ์˜ค: ์ฝ”๋“œ ๋ฐ ๋Œ€ํ™” ๋ณต์›, ๋Œ€ํ™” ๋ณต์›, +# ์ฝ”๋“œ ๋ณต์›, ์—ฌ๊ธฐ๋ถ€ํ„ฐ ์š”์•ฝ ๋˜๋Š” ์ทจ์†Œ +``` + +**์‚ฌ์šฉ ์‚ฌ๋ก€**: +- ๋‹ค์–‘ํ•œ ๊ตฌํ˜„ ์‹œ๋„ +- ์‹ค์ˆ˜์—์„œ ๋ณต๊ตฌ +- ์•ˆ์ „ํ•œ ์‹คํ—˜ +- ์†”๋ฃจ์…˜ ๋น„๊ต +- A/B ํ…Œ์ŠคํŠธ + +--- + +## 09. ๊ณ ๊ธ‰ ๊ธฐ๋Šฅ (3๊ฐœ ํŒŒ์ผ) + +๋ณต์žกํ•œ ์›Œํฌํ”Œ๋กœ์šฐ๋ฅผ ์œ„ํ•œ ๊ณ ๊ธ‰ ๊ธฐ๋Šฅ์ž…๋‹ˆ๋‹ค. + +| ํŒŒ์ผ | ์„ค๋ช… | ๊ธฐ๋Šฅ | +|------|-------------|----------| +| `README.md` | ์™„๋ฒฝ ๊ฐ€์ด๋“œ | ๋ชจ๋“  ๊ณ ๊ธ‰ ๊ธฐ๋Šฅ ๋ฌธ์„œ | +| `config-examples.json` | ๊ตฌ์„ฑ ์˜ˆ์‹œ | 10๊ฐ€์ง€ ์ด์ƒ์˜ ์‚ฌ์šฉ ์‚ฌ๋ก€๋ณ„ ๊ตฌ์„ฑ | +| `planning-mode-examples.md` | ๊ธฐํš ์˜ˆ์‹œ | REST API, ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜, ๋ฆฌํŒฉํ† ๋ง | +| ๋™์  ์›Œํฌํ”Œ๋กœ์šฐ | `/workflows` (v2.1.154)๋ฅผ ํ†ตํ•œ ํ™•์ •์  ๋‹ค์ค‘ ์—์ด์ „ํŠธ ์˜ค์ผ€์ŠคํŠธ๋ ˆ์ด์…˜ | ํฌ๊ด„์ ์ธ ๊ฐ์‚ฌ, ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜, ์Šค์ผ€์ผ ์•„์›ƒ | +| ์˜ˆ์ •๋œ ์ž‘์—… | `/loop` ๋ฐ cron ๋„๊ตฌ๋ฅผ ์‚ฌ์šฉํ•œ ๋ฐ˜๋ณต ์ž‘์—… | ์ž๋™ํ™”๋œ ๋ฐ˜๋ณต ์›Œํฌํ”Œ๋กœ์šฐ | +| Chrome ํ†ตํ•ฉ | ํ—ค๋“œ๋ฆฌ์Šค Chromium์„ ํ†ตํ•œ ๋ธŒ๋ผ์šฐ์ € ์ž๋™ํ™” | ์›น ํ…Œ์ŠคํŠธ ๋ฐ ์Šคํฌ๋ž˜ํ•‘ | +| ์›๊ฒฉ ์ œ์–ด (ํ™•์žฅ๋จ) | ์—ฐ๊ฒฐ ๋ฐฉ๋ฒ•, ๋ณด์•ˆ, ๋น„๊ต ํ‘œ | ์›๊ฒฉ ์„ธ์…˜ ๊ด€๋ฆฌ | +| ํ‚ค๋ณด๋“œ ์‚ฌ์šฉ์ž ์ง€์ • | ์‚ฌ์šฉ์ž ์ง€์ • ํ‚ค ๋ฐ”์ธ๋”ฉ, ์ฝ”๋“œ ์ง€์›, ์ปจํ…์ŠคํŠธ | ๊ฐœ์ธํ™”๋œ ๋‹จ์ถ•ํ‚ค | +| ๋ฐ์Šคํฌํ†ฑ ์•ฑ (ํ™•์žฅ๋จ) | ์ปค๋„ฅํ„ฐ, launch.json, ์—”ํ„ฐํ”„๋ผ์ด์ฆˆ ๊ธฐ๋Šฅ | ๋ฐ์Šคํฌํ†ฑ ํ†ตํ•ฉ | +| | | | + +**๋‹ค๋ฃจ๋Š” ๊ณ ๊ธ‰ ๊ธฐ๋Šฅ**: + +### ๊ธฐํš ๋ชจ๋“œ +- ์ƒ์„ธ ๊ตฌํ˜„ ๊ณ„ํš ์ƒ์„ฑ +- ์‹œ๊ฐ„ ์ถ”์ • ๋ฐ ์œ„ํ—˜ ํ‰๊ฐ€ +- ์ฒด๊ณ„์ ์ธ ์ž‘์—… ๋ถ„ํ•  + +### ํ™•์žฅ ์‚ฌ๊ณ  +- ๋ณต์žกํ•œ ๋ฌธ์ œ์— ๋Œ€ํ•œ ์‹ฌ์ธต ์ถ”๋ก  +- ์•„ํ‚คํ…์ฒ˜ ์˜์‚ฌ ๊ฒฐ์ • ๋ถ„์„ +- ํŠธ๋ ˆ์ด๋“œ์˜คํ”„ ํ‰๊ฐ€ + +### ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž‘์—… +- ๋ธ”๋กœํ‚น ์—†์ด ์žฅ๊ธฐ ์‹คํ–‰ ์ž‘์—… +- ๋ณ‘๋ ฌ ๊ฐœ๋ฐœ ์›Œํฌํ”Œ๋กœ์šฐ +- ์ž‘์—… ๊ด€๋ฆฌ ๋ฐ ๋ชจ๋‹ˆํ„ฐ๋ง + +### ๋™์  ์›Œํฌํ”Œ๋กœ์šฐ (v2.1.154) +- ์ˆ˜์‹ญ์—์„œ ์ˆ˜๋ฐฑ ๊ฐœ์˜ ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์„œ๋ธŒ ์—์ด์ „ํŠธ์˜ ํ™•์ •์  ์˜ค์ผ€์ŠคํŠธ๋ ˆ์ด์…˜ +- ํฌ๊ด„์ ์ธ ์ปค๋ฒ„๋ฆฌ์ง€๋ฅผ ์œ„ํ•œ ํŒฌ์•„์›ƒ / ํŒŒ์ดํ”„๋ผ์ธ / ๋ณ‘๋ ฌ ๋‹จ๊ณ„ +- `/workflows`๋กœ ์‹คํ–‰ ๋ณด๊ธฐ; `ultracode` `/effort`๋Š” ์„ธ์…˜์— ๋Œ€ํ•ด ์ด๋ฅผ ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค. + +### ๊ถŒํ•œ ๋ชจ๋“œ +- **default**: ์œ„ํ—˜ํ•œ ์ž‘์—…์— ๋Œ€ํ•ด ์Šน์ธ ์š”์ฒญ +- **acceptEdits**: ํŒŒ์ผ ํŽธ์ง‘ ์ž๋™ ์Šน์ธ, ๋‹ค๋ฅธ ์ž‘์—…์€ ์š”์ฒญ +- **plan**: ์ฝ๊ธฐ ์ „์šฉ ๋ถ„์„, ์ˆ˜์ • ์—†์Œ +- **auto**: ์•ˆ์ „ํ•œ ์ž‘์—… ์ž๋™ ์Šน์ธ, ์œ„ํ—˜ํ•œ ์ž‘์—…์€ ํ”„๋กฌํ”„ํŠธ +- **dontAsk**: ์œ„ํ—˜ํ•œ ์ž‘์—…์„ ์ œ์™ธํ•œ ๋ชจ๋“  ์ž‘์—… ์Šน์ธ +- **bypassPermissions**: ๋ชจ๋“  ์ž‘์—… ์Šน์ธ (`--dangerously-skip-permissions` ํ•„์š”) + +### ํ—ค๋“œ๋ฆฌ์Šค ๋ชจ๋“œ (`claude -p`) +- CI/CD ํ†ตํ•ฉ +- ์ž๋™ํ™”๋œ ์ž‘์—… ์‹คํ–‰ +- ๋ฐฐ์น˜ ์ฒ˜๋ฆฌ + +### ์„ธ์…˜ ๊ด€๋ฆฌ +- ๋‹ค์ค‘ ์ž‘์—… ์„ธ์…˜ +- ์„ธ์…˜ ์ „ํ™˜ ๋ฐ ์ €์žฅ +- ์„ธ์…˜ ์ง€์†์„ฑ + +### ๋Œ€ํ™”ํ˜• ๊ธฐ๋Šฅ +- ํ‚ค๋ณด๋“œ ๋‹จ์ถ•ํ‚ค +- ๋ช…๋ น์–ด ๊ธฐ๋ก +- ํƒญ ์ž๋™ ์™„์„ฑ +- ๋‹ค์ค‘ ๋ผ์ธ ์ž…๋ ฅ + +### ๊ตฌ์„ฑ +- ํฌ๊ด„์ ์ธ ์„ค์ • ๊ด€๋ฆฌ +- ํ™˜๊ฒฝ๋ณ„ ๊ตฌ์„ฑ +- ํ”„๋กœ์ ํŠธ๋ณ„ ์‚ฌ์šฉ์ž ์ง€์ • + +### ์˜ˆ์ •๋œ ์ž‘์—… +- `/loop` ๋ช…๋ น์„ ์‚ฌ์šฉํ•œ ๋ฐ˜๋ณต ์ž‘์—… +- Cron ๋„๊ตฌ: CronCreate, CronList, CronDelete +- ์ž๋™ํ™”๋œ ๋ฐ˜๋ณต ์›Œํฌํ”Œ๋กœ์šฐ + +### Chrome ํ†ตํ•ฉ +- ํ—ค๋“œ๋ฆฌ์Šค Chromium์„ ํ†ตํ•œ ๋ธŒ๋ผ์šฐ์ € ์ž๋™ํ™” +- ์›น ํ…Œ์ŠคํŠธ ๋ฐ ์Šคํฌ๋ž˜ํ•‘ ๊ธฐ๋Šฅ +- ํŽ˜์ด์ง€ ์ƒํ˜ธ ์ž‘์šฉ ๋ฐ ๋ฐ์ดํ„ฐ ์ถ”์ถœ + +### ์›๊ฒฉ ์ œ์–ด (ํ™•์žฅ๋จ) +- ์—ฐ๊ฒฐ ๋ฐฉ๋ฒ• ๋ฐ ํ”„๋กœํ† ์ฝœ +- ๋ณด์•ˆ ๊ณ ๋ ค ์‚ฌํ•ญ ๋ฐ ๋ชจ๋ฒ” ์‚ฌ๋ก€ +- ์›๊ฒฉ ์•ก์„ธ์Šค ์˜ต์…˜ ๋น„๊ต ํ‘œ + +### ํ‚ค๋ณด๋“œ ์‚ฌ์šฉ์ž ์ง€์ • +- ์‚ฌ์šฉ์ž ์ง€์ • ํ‚ค ๋ฐ”์ธ๋”ฉ ๊ตฌ์„ฑ +- ๋‹ค์ค‘ ํ‚ค ๋‹จ์ถ•ํ‚ค๋ฅผ ์œ„ํ•œ ์ฝ”๋“œ ์ง€์› +- ์ปจํ…์ŠคํŠธ ์ธ์‹ ํ‚ค ๋ฐ”์ธ๋”ฉ ํ™œ์„ฑํ™” + +### ๋ฐ์Šคํฌํ†ฑ ์•ฑ (ํ™•์žฅ๋จ) +- IDE ํ†ตํ•ฉ์„ ์œ„ํ•œ ์ปค๋„ฅํ„ฐ +- launch.json ๊ตฌ์„ฑ +- ์—”ํ„ฐํ”„๋ผ์ด์ฆˆ ๊ธฐ๋Šฅ ๋ฐ ๋ฐฐํฌ + +--- + +## 10. CLI ์‚ฌ์šฉ๋ฒ• (1๊ฐœ ํŒŒ์ผ) + +๋ช…๋ น์ค„ ์ธํ„ฐํŽ˜์ด์Šค ์‚ฌ์šฉ ํŒจํ„ด ๋ฐ ์ฐธ์กฐ. + +| ํŒŒ์ผ | ์„ค๋ช… | ๋‚ด์šฉ | +|------|-------------|----------| +| `README.md` | CLI ๋ฌธ์„œ | ํ”Œ๋ž˜๊ทธ, ์˜ต์…˜ ๋ฐ ์‚ฌ์šฉ ํŒจํ„ด | + +**์ฃผ์š” CLI ๊ธฐ๋Šฅ**: +- `claude` - ๋Œ€ํ™”ํ˜• ์„ธ์…˜ ์‹œ์ž‘ +- `claude -p "prompt"` - ํ—ค๋“œ๋ฆฌ์Šค/๋น„๋Œ€ํ™”ํ˜• ๋ชจ๋“œ +- `claude web` - ์›น ์„ธ์…˜ ์‹œ์ž‘ +- `claude --model` - ๋ชจ๋ธ ์„ ํƒ (Sonnet 4.6, Opus 4.8, Haiku 4.5) +- `claude --permission-mode` - ๊ถŒํ•œ ๋ชจ๋“œ ์„ค์ • +- `claude --remote` - WebSocket์„ ํ†ตํ•œ ์›๊ฒฉ ์ œ์–ด ํ™œ์„ฑํ™” + +--- + +## ๋ฌธ์„œ ํŒŒ์ผ (13๊ฐœ ํŒŒ์ผ) + +| ํŒŒ์ผ | ์œ„์น˜ | ์„ค๋ช… | +|------|----------|-------------| +| `README.md` | `/` | ์ฃผ์š” ์˜ˆ์‹œ ๊ฐœ์š” | +| `INDEX.md` | `/` | ์ด ์ „์ฒด ์ƒ‰์ธ | +| `QUICK_REFERENCE.md` | `/` | ๋น ๋ฅธ ์ฐธ์กฐ ์นด๋“œ | +| `README.md` | `/01-slash-commands/` | ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด ๊ฐ€์ด๋“œ | +| `README.md` | `/02-memory/` | ๋ฉ”๋ชจ๋ฆฌ ๊ฐ€์ด๋“œ | +| `README.md` | `/03-skills/` | ์Šคํ‚ฌ ๊ฐ€์ด๋“œ | +| `README.md` | `/04-subagents/` | ์„œ๋ธŒ ์—์ด์ „ํŠธ ๊ฐ€์ด๋“œ | +| `README.md` | `/05-mcp/` | MCP ๊ฐ€์ด๋“œ | +| `README.md` | `/06-hooks/` | ํ›… ๊ฐ€์ด๋“œ | +| `README.md` | `/07-plugins/` | ํ”Œ๋Ÿฌ๊ทธ์ธ ๊ฐ€์ด๋“œ | +| `README.md` | `/08-checkpoints/` | ์ฒดํฌํฌ์ธํŠธ ๊ฐ€์ด๋“œ | +| `README.md` | `/09-advanced-features/` | ๊ณ ๊ธ‰ ๊ธฐ๋Šฅ ๊ฐ€์ด๋“œ | +| `README.md` | `/10-cli/` | CLI ๊ฐ€์ด๋“œ | + +--- + +## ์ „์ฒด ํŒŒ์ผ ํŠธ๋ฆฌ + +``` +claude-howto/ +โ”œโ”€โ”€ README.md # ์ฃผ์š” ๊ฐœ์š” +โ”œโ”€โ”€ INDEX.md # ์ด ํŒŒ์ผ +โ”œโ”€โ”€ QUICK_REFERENCE.md # ๋น ๋ฅธ ์ฐธ์กฐ ์นด๋“œ +โ”œโ”€โ”€ claude_concepts_guide.md # ์›๋ณธ ๊ฐ€์ด๋“œ +โ”‚ +โ”œโ”€โ”€ 01-slash-commands/ # ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด +โ”‚ โ”œโ”€โ”€ optimize.md +โ”‚ โ”œโ”€โ”€ pr.md +โ”‚ โ”œโ”€โ”€ generate-api-docs.md +โ”‚ โ”œโ”€โ”€ commit.md +โ”‚ โ”œโ”€โ”€ setup-ci-cd.md +โ”‚ โ”œโ”€โ”€ push-all.md +โ”‚ โ”œโ”€โ”€ unit-test-expand.md +โ”‚ โ”œโ”€โ”€ doc-refactor.md +โ”‚ โ”œโ”€โ”€ pr-slash-command.png +โ”‚ โ””โ”€โ”€ README.md +โ”‚ +โ”œโ”€โ”€ 02-memory/ # ๋ฉ”๋ชจ๋ฆฌ +โ”‚ โ”œโ”€โ”€ project-CLAUDE.md +โ”‚ โ”œโ”€โ”€ directory-api-CLAUDE.md +โ”‚ โ”œโ”€โ”€ personal-CLAUDE.md +โ”‚ โ”œโ”€โ”€ memory-saved.png +โ”‚ โ”œโ”€โ”€ memory-ask-claude.png +โ”‚ โ””โ”€โ”€ README.md +โ”‚ +โ”œโ”€โ”€ 03-skills/ # ์Šคํ‚ฌ +โ”‚ โ”œโ”€โ”€ code-review-specialist/ +โ”‚ โ”‚ โ”œโ”€โ”€ SKILL.md +โ”‚ โ”‚ โ”œโ”€โ”€ scripts/ +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ analyze-metrics.py +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ compare-complexity.py +โ”‚ โ”‚ โ””โ”€โ”€ templates/ +โ”‚ โ”‚ โ”œโ”€โ”€ review-checklist.md +โ”‚ โ”‚ โ””โ”€โ”€ finding-template.md +โ”‚ โ”œโ”€โ”€ brand-voice/ +โ”‚ โ”‚ โ”œโ”€โ”€ SKILL.md +โ”‚ โ”‚ โ”œโ”€โ”€ templates/ +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ email-template.txt +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ social-post-template.txt +โ”‚ โ”‚ โ””โ”€โ”€ tone-examples.md +โ”‚ โ”œโ”€โ”€ doc-generator/ +โ”‚ โ”‚ โ”œโ”€โ”€ SKILL.md +โ”‚ โ”‚ โ””โ”€โ”€ generate-docs.py +โ”‚ โ”œโ”€โ”€ refactor/ +โ”‚ โ”‚ โ”œโ”€โ”€ SKILL.md +โ”‚ โ”‚ โ”œโ”€โ”€ scripts/ +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ analyze-complexity.py +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ detect-smells.py +โ”‚ โ”‚ โ”œโ”€โ”€ references/ +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ code-smells.md +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ refactoring-catalog.md +โ”‚ โ”‚ โ””โ”€โ”€ templates/ +โ”‚ โ”‚ โ””โ”€โ”€ refactoring-plan.md +โ”‚ โ”œโ”€โ”€ claude-md/ +โ”‚ โ”‚ โ””โ”€โ”€ SKILL.md +โ”‚ โ”œโ”€โ”€ blog-draft/ +โ”‚ โ”‚ โ”œโ”€โ”€ SKILL.md +โ”‚ โ”‚ โ””โ”€โ”€ templates/ +โ”‚ โ”‚ โ”œโ”€โ”€ draft-template.md +โ”‚ โ”‚ โ””โ”€โ”€ outline-template.md +โ”‚ โ””โ”€โ”€ README.md +โ”‚ +โ”œโ”€โ”€ 04-subagents/ # ์„œ๋ธŒ ์—์ด์ „ํŠธ +โ”‚ โ”œโ”€โ”€ code-reviewer.md +โ”‚ โ”œโ”€โ”€ test-engineer.md +โ”‚ โ”œโ”€โ”€ documentation-writer.md +โ”‚ โ”œโ”€โ”€ secure-reviewer.md +โ”‚ โ”œโ”€โ”€ implementation-agent.md +โ”‚ โ”œโ”€โ”€ debugger.md +โ”‚ โ”œโ”€โ”€ data-scientist.md +โ”‚ โ”œโ”€โ”€ clean-code-reviewer.md +โ”‚ โ””โ”€โ”€ README.md +โ”‚ +โ”œโ”€โ”€ 05-mcp/ # MCP ํ”„๋กœํ† ์ฝœ +โ”‚ โ”œโ”€โ”€ github-mcp.json +โ”‚ โ”œโ”€โ”€ database-mcp.json +โ”‚ โ”œโ”€โ”€ filesystem-mcp.json +โ”‚ โ”œโ”€โ”€ multi-mcp.json +โ”‚ โ””โ”€โ”€ README.md +โ”‚ +โ”œโ”€โ”€ 06-hooks/ # ํ›… +โ”‚ โ”œโ”€โ”€ format-code.sh +โ”‚ โ”œโ”€โ”€ pre-commit.sh +โ”‚ โ”œโ”€โ”€ security-scan.sh +โ”‚ โ”œโ”€โ”€ log-bash.sh +โ”‚ โ”œโ”€โ”€ validate-prompt.sh +โ”‚ โ”œโ”€โ”€ notify-team.sh +โ”‚ โ”œโ”€โ”€ context-tracker.py +โ”‚ โ”œโ”€โ”€ context-tracker-tiktoken.py +โ”‚ โ””โ”€โ”€ README.md +โ”‚ +โ”œโ”€โ”€ 07-plugins/ # ํ”Œ๋Ÿฌ๊ทธ์ธ +โ”‚ โ”œโ”€โ”€ pr-review/ +โ”‚ โ”‚ โ”œโ”€โ”€ .claude-plugin/ +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ plugin.json +โ”‚ โ”‚ โ”œโ”€โ”€ commands/ +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ review-pr.md +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ check-security.md +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ check-tests.md +โ”‚ โ”‚ โ”œโ”€โ”€ agents/ +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ security-reviewer.md +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ test-checker.md +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ performance-analyzer.md +โ”‚ โ”‚ โ”œโ”€โ”€ mcp/ +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ github-config.json +โ”‚ โ”‚ โ”œโ”€โ”€ hooks/ +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ pre-review.js +โ”‚ โ”‚ โ””โ”€โ”€ README.md +โ”‚ โ”œโ”€โ”€ devops-automation/ +โ”‚ โ”‚ โ”œโ”€โ”€ .claude-plugin/ +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ plugin.json +โ”‚ โ”‚ โ”œโ”€โ”€ commands/ +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ deploy.md +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ rollback.md +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ status.md +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ incident.md +โ”‚ โ”‚ โ”œโ”€โ”€ agents/ +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ deployment-specialist.md +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ incident-commander.md +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ alert-analyzer.md +โ”‚ โ”‚ โ”œโ”€โ”€ mcp/ +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ kubernetes-config.json +โ”‚ โ”‚ โ”œโ”€โ”€ hooks/ +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ pre-deploy.js +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ post-deploy.js +โ”‚ โ”‚ โ”œโ”€โ”€ scripts/ +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ deploy.sh +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ rollback.sh +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ health-check.sh +โ”‚ โ”‚ โ””โ”€โ”€ README.md +โ”‚ โ”œโ”€โ”€ documentation/ +โ”‚ โ”‚ โ”œโ”€โ”€ .claude-plugin/ +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ plugin.json +โ”‚ โ”‚ โ”œโ”€โ”€ commands/ +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ generate-api-docs.md +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ generate-readme.md +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ sync-docs.md +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ validate-docs.md +โ”‚ โ”‚ โ”œโ”€โ”€ agents/ +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ api-documenter.md +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ code-commentator.md +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ example-generator.md +โ”‚ โ”‚ โ”œโ”€โ”€ mcp/ +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ github-docs-config.json +โ”‚ โ”‚ โ”œโ”€โ”€ templates/ +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ api-endpoint.md +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ function-docs.md +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ adr-template.md +โ”‚ โ”‚ โ””โ”€โ”€ README.md +โ”‚ โ””โ”€โ”€ README.md +โ”‚ +โ”œโ”€โ”€ 08-checkpoints/ # ์ฒดํฌํฌ์ธํŠธ +โ”‚ โ”œโ”€โ”€ checkpoint-examples.md +โ”‚ โ””โ”€โ”€ README.md +โ”‚ +โ”œโ”€โ”€ 09-advanced-features/ # ๊ณ ๊ธ‰ ๊ธฐ๋Šฅ +โ”‚ โ”œโ”€โ”€ config-examples.json +โ”‚ โ”œโ”€โ”€ planning-mode-examples.md +โ”‚ โ””โ”€โ”€ README.md +โ”‚ +โ””โ”€โ”€ 10-cli/ # CLI ์‚ฌ์šฉ๋ฒ• + โ””โ”€โ”€ README.md +``` + +--- + +## ์‚ฌ์šฉ ์‚ฌ๋ก€๋ณ„ ๋น ๋ฅธ ์‹œ์ž‘ + +### ์ฝ”๋“œ ํ’ˆ์งˆ ๋ฐ ๊ฒ€ํ†  +```bash +# ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด ์„ค์น˜ +cp 01-slash-commands/optimize.md .claude/commands/ + +# ์„œ๋ธŒ ์—์ด์ „ํŠธ ์„ค์น˜ +cp 04-subagents/code-reviewer.md .claude/agents/ + +# ์Šคํ‚ฌ ์„ค์น˜ +cp -r 03-skills/code-review-specialist ~/.claude/skills/ + +# ๋˜๋Š” ์ „์ฒด ํ”Œ๋Ÿฌ๊ทธ์ธ ์„ค์น˜ +/plugin install pr-review +``` + +### ๋ฐ๋ธŒ์˜ต์Šค ๋ฐ ๋ฐฐํฌ +```bash +# ํ”Œ๋Ÿฌ๊ทธ์ธ ์„ค์น˜ (๋ชจ๋“  ๊ฒƒ ํฌํ•จ) +/plugin install devops-automation +``` + +### ๋ฌธ์„œํ™” +```bash +# ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด ์„ค์น˜ +cp 01-slash-commands/generate-api-docs.md .claude/commands/ + +# ์„œ๋ธŒ ์—์ด์ „ํŠธ ์„ค์น˜ +cp 04-subagents/documentation-writer.md .claude/agents/ + +# ์Šคํ‚ฌ ์„ค์น˜ +cp -r 03-skills/doc-generator ~/.claude/skills/ + +# ๋˜๋Š” ์ „์ฒด ํ”Œ๋Ÿฌ๊ทธ์ธ ์„ค์น˜ +/plugin install documentation +``` + +### ํŒ€ ํ‘œ์ค€ +```bash +# ํ”„๋กœ์ ํŠธ ๋ฉ”๋ชจ๋ฆฌ ์„ค์ • +cp 02-memory/project-CLAUDE.md ./CLAUDE.md + +# ํŒ€์˜ ํ‘œ์ค€์— ๋งž๊ฒŒ ํŽธ์ง‘ +``` + +### ์™ธ๋ถ€ ํ†ตํ•ฉ +```bash +# ํ™˜๊ฒฝ ๋ณ€์ˆ˜ ์„ค์ • +export GITHUB_TOKEN="your_token" +export DATABASE_URL="postgresql://..." + +# MCP ๊ตฌ์„ฑ ์„ค์น˜ (ํ”„๋กœ์ ํŠธ ๋ฒ”์œ„) +cp 05-mcp/multi-mcp.json .mcp.json +``` + +### ์ž๋™ํ™” ๋ฐ ์œ ํšจ์„ฑ ๊ฒ€์‚ฌ +```bash +# ํ›… ์„ค์น˜ +mkdir -p ~/.claude/hooks +cp 06-hooks/*.sh ~/.claude/hooks/ +chmod +x ~/.claude/hooks/*.sh + +# ์„ค์ •์—์„œ ํ›… ๊ตฌ์„ฑ (~/.claude/settings.json) +# 06-hooks/README.md ์ฐธ์กฐ +``` + +### ์•ˆ์ „ํ•œ ์‹คํ—˜ +```bash +# ์ฒดํฌํฌ์ธํŠธ๋Š” ์‚ฌ์šฉ์ž ํ”„๋กฌํ”„ํŠธ๋งˆ๋‹ค ์ž๋™์œผ๋กœ ์ƒ์„ฑ๋ฉ๋‹ˆ๋‹ค. +# ๋˜๊ฐ๊ธฐ: Esc+Esc๋ฅผ ๋ˆ„๋ฅด๊ฑฐ๋‚˜ /rewind ์‚ฌ์šฉ +# ๊ทธ๋Ÿฐ ๋‹ค์Œ ๋˜๊ฐ๊ธฐ ๋ฉ”๋‰ด์—์„œ ๋ณต์›ํ•  ํ•ญ๋ชฉ์„ ์„ ํƒํ•˜์‹ญ์‹œ์˜ค. + +# ์˜ˆ์‹œ๋Š” 08-checkpoints/README.md ์ฐธ์กฐ +``` + +### ๊ณ ๊ธ‰ ์›Œํฌํ”Œ๋กœ์šฐ +```bash +# ๊ณ ๊ธ‰ ๊ธฐ๋Šฅ ๊ตฌ์„ฑ +# 09-advanced-features/config-examples.json ์ฐธ์กฐ + +# ๊ธฐํš ๋ชจ๋“œ ์‚ฌ์šฉ +/plan Implement feature X + +# ๊ถŒํ•œ ๋ชจ๋“œ ์‚ฌ์šฉ +claude --permission-mode plan # ์ฝ”๋“œ ๊ฒ€ํ† ์šฉ (์ฝ๊ธฐ ์ „์šฉ) +claude --permission-mode acceptEdits # ํŽธ์ง‘ ์ž๋™ ์Šน์ธ +claude --permission-mode auto # ์•ˆ์ „ํ•œ ์ž‘์—… ์ž๋™ ์Šน์ธ + +# CI/CD๋ฅผ ์œ„ํ•ด ํ—ค๋“œ๋ฆฌ์Šค ๋ชจ๋“œ๋กœ ์‹คํ–‰ +claude -p "Run tests and report results" + +# ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž‘์—… ์‹คํ–‰ +Run tests in background + +# ์™„์ „ํ•œ ๊ฐ€์ด๋“œ๋Š” 09-advanced-features/README.md ์ฐธ์กฐ +``` + +--- + +## ๊ธฐ๋Šฅ ์ปค๋ฒ„๋ฆฌ์ง€ ๋งคํŠธ๋ฆญ์Šค + +| ์นดํ…Œ๊ณ ๋ฆฌ | ๋ช…๋ น์–ด | ์—์ด์ „ํŠธ | MCP | ํ›… | ์Šคํฌ๋ฆฝํŠธ | ํ…œํ”Œ๋ฆฟ | ๋ฌธ์„œ | ์ด๋ฏธ์ง€ | ํ•ฉ๊ณ„ | +|----------|----------|--------|-----|-------|---------|-----------|------|--------|-------| +| **01 ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด** | 8 | - | - | - | - | - | 1 | 1 | **10** | +| **02 ๋ฉ”๋ชจ๋ฆฌ** | - | - | - | - | - | 3 | 1 | 2 | **6** | +| **03 ์Šคํ‚ฌ** | - | - | - | - | 5 | 9 | 1 | - | **28** | +| **04 ์„œ๋ธŒ ์—์ด์ „ํŠธ** | - | 8 | - | - | - | - | 1 | - | **9** | +| **05 MCP** | - | - | 4 | - | - | - | 1 | - | **5** | +| **06 ํ›…** | - | - | - | 8 | - | - | 1 | - | **9** | +| **07 ํ”Œ๋Ÿฌ๊ทธ์ธ** | 11 | 9 | 3 | 3 | 3 | 3 | 4 | - | **40** | +| **08 ์ฒดํฌํฌ์ธํŠธ** | - | - | - | - | - | - | 1 | 1 | **2** | +| **09 ๊ณ ๊ธ‰** | - | - | - | - | - | - | 1 | 2 | **3** | +| **10 CLI** | - | - | - | - | - | - | 1 | - | **1** | + +--- + +## ํ•™์Šต ๊ฒฝ๋กœ + +### ์ดˆ๊ธ‰ (1์ฃผ์ฐจ) +1. โœ… `README.md` ์ฝ๊ธฐ +2. โœ… ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด 1-2๊ฐœ ์„ค์น˜ +3. โœ… ํ”„๋กœ์ ํŠธ ๋ฉ”๋ชจ๋ฆฌ ํŒŒ์ผ ์ƒ์„ฑ +4. โœ… ๊ธฐ๋ณธ ๋ช…๋ น์–ด ์‹œ๋„ + +### ์ค‘๊ธ‰ (2-3์ฃผ์ฐจ) +1. โœ… GitHub MCP ์„ค์ • +2. โœ… ์„œ๋ธŒ ์—์ด์ „ํŠธ ์„ค์น˜ +3. โœ… ์ž‘์—… ์œ„์ž„ ์‹œ๋„ +4. โœ… ์Šคํ‚ฌ ์„ค์น˜ + +### ๊ณ ๊ธ‰ (4์ฃผ์ฐจ ์ด์ƒ) +1. โœ… ์™„๋ฒฝํ•œ ํ”Œ๋Ÿฌ๊ทธ์ธ ์„ค์น˜ +2. โœ… ์‚ฌ์šฉ์ž ์ง€์ • ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด ์ƒ์„ฑ +3. โœ… ์‚ฌ์šฉ์ž ์ง€์ • ์„œ๋ธŒ ์—์ด์ „ํŠธ ์ƒ์„ฑ +4. โœ… ์‚ฌ์šฉ์ž ์ง€์ • ์Šคํ‚ฌ ์ƒ์„ฑ +5. โœ… ์ž์‹ ๋งŒ์˜ ํ”Œ๋Ÿฌ๊ทธ์ธ ๊ตฌ์ถ• + +### ์ „๋ฌธ๊ฐ€ (5์ฃผ์ฐจ ์ด์ƒ) +1. โœ… ์ž๋™ํ™”๋ฅผ ์œ„ํ•œ ํ›… ์„ค์ • +2. โœ… ์‹คํ—˜์„ ์œ„ํ•œ ์ฒดํฌํฌ์ธํŠธ ์‚ฌ์šฉ +3. โœ… ๊ธฐํš ๋ชจ๋“œ ๊ตฌ์„ฑ +4. โœ… ๊ถŒํ•œ ๋ชจ๋“œ๋ฅผ ํšจ๊ณผ์ ์œผ๋กœ ์‚ฌ์šฉ +5. โœ… CI/CD๋ฅผ ์œ„ํ•œ ํ—ค๋“œ๋ฆฌ์Šค ๋ชจ๋“œ ์„ค์ • +6. โœ… ์„ธ์…˜ ๊ด€๋ฆฌ ๋งˆ์Šคํ„ฐ + +--- + +## ํ‚ค์›Œ๋“œ๋กœ ๊ฒ€์ƒ‰ + +### ์„ฑ๋Šฅ +- `01-slash-commands/optimize.md` - ์„ฑ๋Šฅ ๋ถ„์„ +- `04-subagents/code-reviewer.md` - ์„ฑ๋Šฅ ๊ฒ€ํ†  +- `03-skills/code-review-specialist/` - ์„ฑ๋Šฅ ์ง€ํ‘œ +- `07-plugins/pr-review/agents/performance-analyzer.md` - ์„ฑ๋Šฅ ์ „๋ฌธ๊ฐ€ + +### ๋ณด์•ˆ +- `04-subagents/secure-reviewer.md` - ๋ณด์•ˆ ๊ฒ€ํ†  +- `03-skills/code-review-specialist/` - ๋ณด์•ˆ ๋ถ„์„ +- `07-plugins/pr-review/` - ๋ณด์•ˆ ๊ฒ€์‚ฌ + +### ํ…Œ์ŠคํŠธ +- `04-subagents/test-engineer.md` - ํ…Œ์ŠคํŠธ ์—”์ง€๋‹ˆ์–ด +- `07-plugins/pr-review/commands/check-tests.md` - ํ…Œ์ŠคํŠธ ์ปค๋ฒ„๋ฆฌ์ง€ + +### ๋ฌธ์„œํ™” +- `01-slash-commands/generate-api-docs.md` - API ๋ฌธ์„œ ๋ช…๋ น์–ด +- `04-subagents/documentation-writer.md` - ๋ฌธ์„œ ์ž‘์„ฑ ์—์ด์ „ํŠธ +- `03-skills/doc-generator/` - ๋ฌธ์„œ ์ƒ์„ฑ๊ธฐ ์Šคํ‚ฌ +- `07-plugins/documentation/` - ์™„๋ฒฝํ•œ ๋ฌธ์„œ ํ”Œ๋Ÿฌ๊ทธ์ธ + +### ๋ฐฐํฌ +- `07-plugins/devops-automation/` - ์™„๋ฒฝํ•œ ๋ฐ๋ธŒ์˜ต์Šค ์†”๋ฃจ์…˜ + +### ์ž๋™ํ™” +- `06-hooks/` - ์ด๋ฒคํŠธ ๊ธฐ๋ฐ˜ ์ž๋™ํ™” +- `06-hooks/pre-commit.sh` - ์‚ฌ์ „ ์ปค๋ฐ‹ ์ž๋™ํ™” +- `06-hooks/format-code.sh` - ์ž๋™ ํฌ๋งทํŒ… +- `09-advanced-features/` - CI/CD๋ฅผ ์œ„ํ•œ ํ—ค๋“œ๋ฆฌ์Šค ๋ชจ๋“œ + +### ์œ ํšจ์„ฑ ๊ฒ€์‚ฌ +- `06-hooks/security-scan.sh` - ๋ณด์•ˆ ์œ ํšจ์„ฑ ๊ฒ€์‚ฌ +- `06-hooks/validate-prompt.sh` - ํ”„๋กฌํ”„ํŠธ ์œ ํšจ์„ฑ ๊ฒ€์‚ฌ + +### ์‹คํ—˜ +- `08-checkpoints/` - ๋˜๊ฐ๊ธฐ๋ฅผ ํ†ตํ•œ ์•ˆ์ „ํ•œ ์‹คํ—˜ +- `08-checkpoints/checkpoint-examples.md` - ์‹ค์ œ ์˜ˆ์‹œ + +### ๊ธฐํš +- `09-advanced-features/planning-mode-examples.md` - ๊ธฐํš ๋ชจ๋“œ ์˜ˆ์‹œ +- `09-advanced-features/README.md` - ํ™•์žฅ ์‚ฌ๊ณ  + +### ๊ตฌ์„ฑ +- `09-advanced-features/config-examples.json` - ๊ตฌ์„ฑ ์˜ˆ์‹œ + +--- + +## ์ฐธ๊ณ  ์‚ฌํ•ญ + +- ๋ชจ๋“  ์˜ˆ์‹œ๋Š” ์ฆ‰์‹œ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. +- ํŠน์ • ์š”๊ตฌ์‚ฌํ•ญ์— ๋งž๊ฒŒ ์ˆ˜์ •ํ•˜์‹ญ์‹œ์˜ค. +- ์˜ˆ์‹œ๋Š” ํด๋กœ๋“œ ์ฝ”๋“œ ๋ชจ๋ฒ” ์‚ฌ๋ก€๋ฅผ ๋”ฐ๋ฆ…๋‹ˆ๋‹ค. +- ๊ฐ ์นดํ…Œ๊ณ ๋ฆฌ์—๋Š” ์ƒ์„ธ ์ง€์นจ์ด ํฌํ•จ๋œ ์ž์ฒด README๊ฐ€ ์žˆ์Šต๋‹ˆ๋‹ค. +- ์Šคํฌ๋ฆฝํŠธ์—๋Š” ์ ์ ˆํ•œ ์˜ค๋ฅ˜ ์ฒ˜๋ฆฌ๊ฐ€ ํฌํ•จ๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. +- ํ…œํ”Œ๋ฆฟ์€ ์‚ฌ์šฉ์ž ์ง€์ • ๊ฐ€๋Šฅํ•ฉ๋‹ˆ๋‹ค. + +--- + +## ๊ธฐ์—ฌ + +๋” ๋งŽ์€ ์˜ˆ์‹œ๋ฅผ ์ถ”๊ฐ€ํ•˜๊ณ  ์‹ถ์œผ์‹ญ๋‹ˆ๊นŒ? ๋‹ค์Œ ๊ตฌ์กฐ๋ฅผ ๋”ฐ๋ฅด์‹ญ์‹œ์˜ค: +1. ์ ์ ˆํ•œ ํ•˜์œ„ ๋””๋ ‰ํ† ๋ฆฌ ์ƒ์„ฑ +2. ์‚ฌ์šฉ๋ฒ•์ด ํฌํ•จ๋œ README.md ์ถ”๊ฐ€ +3. ๋ช…๋ช… ๊ทœ์น™ ์ค€์ˆ˜ +4. ์ฒ ์ €ํžˆ ํ…Œ์ŠคํŠธ +5. ์ด ์ƒ‰์ธ ์—…๋ฐ์ดํŠธ + +--- + +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: 2026๋…„ 6์›” 2์ผ +**ํด๋กœ๋“œ ์ฝ”๋“œ ๋ฒ„์ „**: 2.1.160 +**์ถœ์ฒ˜**: +- https://code.claude.com/docs/en/overview +- https://code.claude.com/docs/en/hooks +- https://code.claude.com/docs/en/commands +- https://github.com/anthropics/claude-code/releases/tag/v2.1.153 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.154 +**ํ˜ธํ™˜ ๋ชจ๋ธ**: Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5 +**์ด ์˜ˆ์‹œ ์ˆ˜**: 100๊ฐœ ์ด์ƒ ํŒŒ์ผ +**์นดํ…Œ๊ณ ๋ฆฌ**: 10๊ฐ€์ง€ ๊ธฐ๋Šฅ +**ํ›…**: 9๊ฐ€์ง€ ์ž๋™ํ™” ์Šคํฌ๋ฆฝํŠธ +**๊ตฌ์„ฑ ์˜ˆ์‹œ**: 10๊ฐ€์ง€ ์ด์ƒ ์‹œ๋‚˜๋ฆฌ์˜ค +**์ฆ‰์‹œ ์‚ฌ์šฉ ๊ฐ€๋Šฅ**: ๋ชจ๋“  ์˜ˆ์‹œ diff --git a/ko/LEARNING-ROADMAP.md b/ko/LEARNING-ROADMAP.md new file mode 100644 index 00000000..cd2f4aa2 --- /dev/null +++ b/ko/LEARNING-ROADMAP.md @@ -0,0 +1,754 @@ + + + Claude How To + + +# ๐Ÿ“š Claude Code ํ•™์Šต ๋กœ๋“œ๋งต + +**Claude Code๊ฐ€ ์ฒ˜์Œ์ด์‹ ๊ฐ€์š”?** ์ด ๊ฐ€์ด๋“œ๋Š” ์ž์‹ ์—๊ฒŒ ๋งž๋Š” ์†๋„๋กœ Claude Code์˜ ๊ธฐ๋Šฅ์„ ๋งˆ์Šคํ„ฐํ•˜๋Š” ๋ฐ ๋„์›€์„ ์ค๋‹ˆ๋‹ค. ์™„์ „ํžˆ ์ดˆ๋ณด์ž๋“  ์ˆ™๋ จ๋œ ๊ฐœ๋ฐœ์ž๋“ , ์•„๋ž˜ ์ž๊ธฐ ํ‰๊ฐ€ ํ€ด์ฆˆ๋ฅผ ํ†ตํ•ด ์ž์‹ ์—๊ฒŒ ์ ํ•ฉํ•œ ๊ฒฝ๋กœ๋ฅผ ์ฐพ์•„๋ณด์„ธ์š”. + +--- + +## ๐Ÿงญ ์ˆ˜์ค€ ํ™•์ธํ•˜๊ธฐ + +๋ชจ๋“  ์‚ฌ๋žŒ์ด ๊ฐ™์€ ์ถœ๋ฐœ์ ์—์„œ ์‹œ์ž‘ํ•˜๋Š” ๊ฒƒ์€ ์•„๋‹™๋‹ˆ๋‹ค. ์ด ๊ฐ„๋‹จํ•œ ์ž๊ธฐ ํ‰๊ฐ€๋ฅผ ํ†ตํ•ด ์ ์ ˆํ•œ ์‹œ์ž‘ ์ง€์ ์„ ์ฐพ์•„๋ณด์„ธ์š”. + +**๋‹ค์Œ ์งˆ๋ฌธ์— ์†”์งํ•˜๊ฒŒ ๋‹ตํ•˜์‹ญ์‹œ์˜ค:** + +- [ ] `claude`๋ฅผ ์‹คํ–‰ํ•˜์—ฌ Claude Code์™€ ๋Œ€ํ™”๋ฅผ ์‹œ์ž‘ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. +- [ ] `CLAUDE.md` ํŒŒ์ผ์„ ์ƒ์„ฑํ•˜๊ฑฐ๋‚˜ ์ˆ˜์ •ํ–ˆ์Šต๋‹ˆ๋‹ค. +- [ ] ๊ธฐ๋ณธ ์ œ๊ณต ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด๋ฅผ 3๊ฐœ ์ด์ƒ ์‚ฌ์šฉํ–ˆ์Šต๋‹ˆ๋‹ค(์˜ˆ: `/help`, `/compact`, `/model`). +- [ ] ์‚ฌ์šฉ์ž ์ •์˜ ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด ๋˜๋Š” Skill(`SKILL.md`)์„ ๋งŒ๋“ค์—ˆ์Šต๋‹ˆ๋‹ค. +- [ ] MCP ์„œ๋ฒ„(์˜ˆ: GitHub, ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค)๋ฅผ ๊ตฌ์„ฑํ–ˆ์Šต๋‹ˆ๋‹ค. +- [ ] `~/.claude/settings.json`์— Hook์„ ์„ค์ •ํ–ˆ์Šต๋‹ˆ๋‹ค. +- [ ] ์‚ฌ์šฉ์ž ์ •์˜ Subagent(`.claude/agents/`)๋ฅผ ๋งŒ๋“ค๊ฑฐ๋‚˜ ์‚ฌ์šฉํ–ˆ์Šต๋‹ˆ๋‹ค. +- [ ] ์Šคํฌ๋ฆฝํŒ… ๋˜๋Š” CI/CD๋ฅผ ์œ„ํ•ด ์ถœ๋ ฅ ๋ชจ๋“œ(`claude -p`)๋ฅผ ์‚ฌ์šฉํ–ˆ์Šต๋‹ˆ๋‹ค. + +**๋‹น์‹ ์˜ ๋ ˆ๋ฒจ:** + +| Checks | Level | Start At | Time to Complete | +|--------|-------|----------|------------------| +| 0-2 | **๋ ˆ๋ฒจ 1: ์ดˆ๊ธ‰** โ€” ์‹œ์ž‘ํ•˜๊ธฐ | [๋งˆ์ผ์Šคํ†ค 1A: ์ฒซ ๋ช…๋ น์–ด ๋ฐ ๋ฉ”๋ชจ๋ฆฌ](#๋งˆ์ผ์Šคํ†ค-1a-์ฒซ-๋ช…๋ น์–ด-๋ฐ-๋ฉ”๋ชจ๋ฆฌ) | ~3 hours | +| 3-5 | **๋ ˆ๋ฒจ 2: ์ค‘๊ธ‰** โ€” ์›Œํฌํ”Œ๋กœ์šฐ ๊ตฌ์ถ• | [๋งˆ์ผ์Šคํ†ค 2A: ์ž๋™ํ™” (๊ธฐ์ˆ  + ํ›…)](#๋งˆ์ผ์Šคํ†ค-2a-์ž๋™ํ™”-๊ธฐ์ˆ --ํ›…) | ~5 hours | +| 6-8 | **๋ ˆ๋ฒจ 3: ๊ณ ๊ธ‰** โ€” ํŒŒ์›Œ ์œ ์ € ๋ฐ ํŒ€ ๋ฆฌ๋” | [๋งˆ์ผ์Šคํ†ค 3A: ๊ณ ๊ธ‰ ๊ธฐ๋Šฅ](#๋งˆ์ผ์Šคํ†ค-3a-๊ณ ๊ธ‰-๊ธฐ๋Šฅ) | ~5 hours | + +> **ํŒ**: ํ™•์‹คํ•˜์ง€ ์•Š๋‹ค๋ฉด ํ•œ ๋‹จ๊ณ„ ๋‚ฎ๊ฒŒ ์‹œ์ž‘ํ•˜์„ธ์š”. ๊ธฐ์ดˆ ๊ฐœ๋…์„ ๋†“์น˜๋Š” ๊ฒƒ๋ณด๋‹ค ์ต์ˆ™ํ•œ ๋‚ด์šฉ์„ ๋น ๋ฅด๊ฒŒ ๋ณต์Šตํ•˜๋Š” ๊ฒƒ์ด ๋‚ซ์Šต๋‹ˆ๋‹ค. + +> **๋Œ€ํ™”ํ˜• ๋ฒ„์ „**: Claude Code์—์„œ `/self-assessment`๋ฅผ ์‹คํ–‰ํ•˜๋ฉด 10๊ฐ€์ง€ ๊ธฐ๋Šฅ ์˜์—ญ ์ „๋ฐ˜์— ๊ฑธ์ณ ์ˆ™๋ จ๋„๋ฅผ ์ธก์ •ํ•˜๊ณ  ๊ฐœ์ธํ™”๋œ ํ•™์Šต ๊ฒฝ๋กœ๋ฅผ ์ƒ์„ฑํ•˜๋Š” ์•ˆ๋‚ดํ˜• ๋Œ€ํ™”์‹ ํ€ด์ฆˆ๋ฅผ ํ’€ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +--- + +## ๐ŸŽฏ ํ•™์Šต ์ฒ ํ•™ + +์ด ์ €์žฅ์†Œ์˜ ํด๋”๋Š” ์„ธ ๊ฐ€์ง€ ํ•ต์‹ฌ ์›์น™์— ๋”ฐ๋ผ **๊ถŒ์žฅ ํ•™์Šต ์ˆœ์„œ**๋กœ ๋ฒˆํ˜ธ๊ฐ€ ์ง€์ •๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. + +1. **์ข…์†์„ฑ** - ๊ธฐ์ดˆ ๊ฐœ๋…์ด ๋จผ์ € ๋‚˜์˜ต๋‹ˆ๋‹ค. +2. **๋ณต์žก์„ฑ** - ๊ณ ๊ธ‰ ๊ธฐ๋Šฅ๋ณด๋‹ค ์‰ฌ์šด ๊ธฐ๋Šฅ์ด ๋จผ์ € ๋‚˜์˜ต๋‹ˆ๋‹ค. +3. **์‚ฌ์šฉ ๋นˆ๋„** - ๊ฐ€์žฅ ์ผ๋ฐ˜์ ์ธ ๊ธฐ๋Šฅ์€ ์ดˆ๊ธฐ์— ํ•™์Šตํ•ฉ๋‹ˆ๋‹ค. + +์ด ์ ‘๊ทผ ๋ฐฉ์‹์€ ์ฆ‰๊ฐ์ ์ธ ์ƒ์‚ฐ์„ฑ ํ–ฅ์ƒ์„ ์–ป์œผ๋ฉด์„œ ๊ฒฌ๊ณ ํ•œ ๊ธฐ๋ฐ˜์„ ๊ตฌ์ถ•ํ•˜๋„๋ก ๋ณด์žฅํ•ฉ๋‹ˆ๋‹ค. + +--- + +## ๐Ÿ—บ๏ธ ํ•™์Šต ๊ฒฝ๋กœ + +```mermaid +graph TD + Q["๐Ÿงญ Self-Assessment Quiz
Find Your Level"] --> L1 + Q --> L2 + Q --> L3 + + subgraph L1["๐ŸŸข Level 1: Beginner โ€” Getting Started"] + direction LR + A["1A: First Commands & Memory
Slash Commands + Memory"] --> B["1B: Safe Exploration
Checkpoints + CLI Basics"] + end + + subgraph L2["๐Ÿ”ต Level 2: Intermediate โ€” Building Workflows"] + direction LR + C["2A: Automation
Skills + Hooks"] --> D["2B: Integration
MCP + Subagents"] + end + + subgraph L3["๐Ÿ”ด Level 3: Advanced โ€” Power User"] + direction LR + E["3A: Advanced Features
Planning + Permissions"] --> F["3B: Team & Distribution
Plugins + CLI Mastery"] + end + + L1 --> L2 + L2 --> L3 + + style Q fill:#6A1B9A,color:#fff,stroke:#9C27B0,stroke-width:2px + style A fill:#2E7D32,color:#fff + style B fill:#2E7D32,color:#fff + style C fill:#1565C0,color:#fff + style D fill:#F57C00,color:#fff + style E fill:#C62828,color:#fff + style F fill:#B71C1C,color:#fff +``` + +**์ƒ‰์ƒ ๋ฒ”๋ก€:** +- ๐Ÿ’œ ๋ณด๋ผ์ƒ‰: ์ž๊ธฐ ํ‰๊ฐ€ ํ€ด์ฆˆ +- ๐ŸŸข ๋…น์ƒ‰: ๋ ˆ๋ฒจ 1 โ€” ์ดˆ๊ธ‰ ๊ฒฝ๋กœ +- ๐Ÿ”ต ํŒŒ๋ž€์ƒ‰ / ๐ŸŸก ๊ธˆ์ƒ‰: ๋ ˆ๋ฒจ 2 โ€” ์ค‘๊ธ‰ ๊ฒฝ๋กœ +- ๐Ÿ”ด ๋นจ๊ฐ„์ƒ‰: ๋ ˆ๋ฒจ 3 โ€” ๊ณ ๊ธ‰ ๊ฒฝ๋กœ + +--- + +## ๐Ÿ“Š ์ „์ฒด ๋กœ๋“œ๋งต ํ‘œ + +| Step | Feature | Complexity | Time | Level | Dependencies | Why Learn This | Key Benefits | +|------|---------|-----------|------|-------|--------------|----------------|--------------| +| **1** | [์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด](01-slash-commands/) | โญ ์ดˆ๊ธ‰ | 30 min | ๋ ˆ๋ฒจ 1 | None | ๋น ๋ฅธ ์ƒ์‚ฐ์„ฑ ํ–ฅ์ƒ (60๊ฐœ ์ด์ƒ์˜ ๋‚ด์žฅ ๋ช…๋ น์–ด + 5๊ฐœ ๋ฒˆ๋“ค ๊ธฐ์ˆ ) | ์ฆ‰๊ฐ์ ์ธ ์ž๋™ํ™”, ํŒ€ ํ‘œ์ค€ | +| **2** | [๋ฉ”๋ชจ๋ฆฌ](02-memory/) | โญโญ ์ดˆ๊ธ‰+ | 45 min | ๋ ˆ๋ฒจ 1 | None | ๋ชจ๋“  ๊ธฐ๋Šฅ์— ํ•„์ˆ˜์  | ์ง€์†์ ์ธ ์ปจํ…์ŠคํŠธ, ํ™˜๊ฒฝ ์„ค์ • | +| **3** | [์ฒดํฌํฌ์ธํŠธ](08-checkpoints/) | โญโญ ์ค‘๊ธ‰ | 45 min | ๋ ˆ๋ฒจ 1 | ์„ธ์…˜ ๊ด€๋ฆฌ | ์•ˆ์ „ํ•œ ํƒ์ƒ‰ | ์‹คํ—˜, ๋ณต๊ตฌ | +| **4** | [CLI ๊ธฐ๋ณธ ์‚ฌํ•ญ](10-cli/) | โญโญ ์ดˆ๊ธ‰+ | 30 min | ๋ ˆ๋ฒจ 1 | None | ํ•ต์‹ฌ CLI ์‚ฌ์šฉ๋ฒ• | ๋Œ€ํ™”ํ˜• ๋ฐ ์ธ์‡„ ๋ชจ๋“œ | +| **5** | [๊ธฐ์ˆ ](03-skills/) | โญโญ ์ค‘๊ธ‰ | 1 hour | ๋ ˆ๋ฒจ 2 | ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด | ์ž๋™ํ™”๋œ ์ „๋ฌธ์„ฑ | ์žฌ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ๊ธฐ๋Šฅ, ์ผ๊ด€์„ฑ | +| **6** | [ํ›…](06-hooks/) | โญโญ ์ค‘๊ธ‰ | 1 hour | ๋ ˆ๋ฒจ 2 | ๋„๊ตฌ, ๋ช…๋ น์–ด | ์›Œํฌํ”Œ๋กœ์šฐ ์ž๋™ํ™” (29๊ฐœ ์ด๋ฒคํŠธ, 5๊ฐ€์ง€ ์œ ํ˜•) | ์œ ํšจ์„ฑ ๊ฒ€์‚ฌ, ํ’ˆ์งˆ ๊ฒŒ์ดํŠธ | +| **7** | [MCP](05-mcp/) | โญโญโญ ์ค‘๊ธ‰+ | 1 hour | ๋ ˆ๋ฒจ 2 | ๊ตฌ์„ฑ | ์‹ค์‹œ๊ฐ„ ๋ฐ์ดํ„ฐ ์ ‘๊ทผ | ์‹ค์‹œ๊ฐ„ ํ†ตํ•ฉ, API | +| **8** | [์„œ๋ธŒ ์—์ด์ „ํŠธ](04-subagents/) | โญโญโญ ์ค‘๊ธ‰+ | 1.5 hours | ๋ ˆ๋ฒจ 2 | ๋ฉ”๋ชจ๋ฆฌ, ๋ช…๋ น์–ด | ๋ณต์žกํ•œ ์ž‘์—… ์ฒ˜๋ฆฌ (Bash ํฌํ•จ 6๊ฐœ ๋‚ด์žฅ) | ์œ„์ž„, ์ „๋ฌธํ™”๋œ ์ „๋ฌธ์„ฑ | +| **9** | [๊ณ ๊ธ‰ ๊ธฐ๋Šฅ](09-advanced-features/) | โญโญโญโญโญ ๊ณ ๊ธ‰ | 2-3 hours | ๋ ˆ๋ฒจ 3 | ๋ชจ๋“  ์ด์ „ ๋‚ด์šฉ | ํŒŒ์›Œ ์œ ์ € ๋„๊ตฌ | ๊ณ„ํš, ์ž๋™ ๋ชจ๋“œ, ์ฑ„๋„, ์Œ์„ฑ ๋ฐ›์•„์“ฐ๊ธฐ, ๊ถŒํ•œ | +| **10** | [ํ”Œ๋Ÿฌ๊ทธ์ธ](07-plugins/) | โญโญโญโญ ๊ณ ๊ธ‰ | 2 hours | ๋ ˆ๋ฒจ 3 | ๋ชจ๋“  ์ด์ „ ๋‚ด์šฉ | ์™„๋ฒฝํ•œ ์†”๋ฃจ์…˜ | ํŒ€ ์˜จ๋ณด๋”ฉ, ๋ฐฐํฌ | +| **11** | [CLI ๋งˆ์Šคํ„ฐ๋ฆฌ](10-cli/) | โญโญโญ ๊ณ ๊ธ‰ | 1 hour | ๋ ˆ๋ฒจ 3 | ๊ถŒ์žฅ: ๋ชจ๋“  ๋‚ด์šฉ | ๋ช…๋ น์ค„ ์‚ฌ์šฉ ๋งˆ์Šคํ„ฐ | ์Šคํฌ๋ฆฝํŒ…, CI/CD, ์ž๋™ํ™” | + +**์ด ํ•™์Šต ์‹œ๊ฐ„**: ~11-13์‹œ๊ฐ„ (๋˜๋Š” ์ž์‹ ์˜ ๋ ˆ๋ฒจ๋กœ ๊ฑด๋„ˆ๋›ฐ์–ด ์‹œ๊ฐ„์„ ์ ˆ์•ฝํ•˜์„ธ์š”) + +--- + +## ๐ŸŸข ๋ ˆ๋ฒจ 1: ์ดˆ๊ธ‰ โ€” ์‹œ์ž‘ํ•˜๊ธฐ + +**๋Œ€์ƒ**: ํ€ด์ฆˆ ์ฒดํฌ 0-2๊ฐœ์ธ ์‚ฌ์šฉ์ž +**์‹œ๊ฐ„**: ~3์‹œ๊ฐ„ +**์ดˆ์ **: ์ฆ‰๊ฐ์ ์ธ ์ƒ์‚ฐ์„ฑ, ๊ธฐ๋ณธ ์ดํ•ด +**๊ฒฐ๊ณผ**: ๋งค์ผ ํŽธ์•ˆํ•˜๊ฒŒ ์‚ฌ์šฉํ•˜๋Š” ์‚ฌ์šฉ์ž, ๋ ˆ๋ฒจ 2 ์ค€๋น„ ์™„๋ฃŒ + +### ๋งˆ์ผ์Šคํ†ค 1A: ์ฒซ ๋ช…๋ น์–ด ๋ฐ ๋ฉ”๋ชจ๋ฆฌ + +**์ฃผ์ œ**: ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด + ๋ฉ”๋ชจ๋ฆฌ +**์‹œ๊ฐ„**: 1-2์‹œ๊ฐ„ +**๋ณต์žก์„ฑ**: โญ ์ดˆ๊ธ‰ +**๋ชฉํ‘œ**: ์‚ฌ์šฉ์ž ์ง€์ • ๋ช…๋ น์–ด ๋ฐ ์˜๊ตฌ ์ปจํ…์ŠคํŠธ๋ฅผ ํ†ตํ•œ ์ฆ‰๊ฐ์ ์ธ ์ƒ์‚ฐ์„ฑ ํ–ฅ์ƒ + +#### ๋‹ฌ์„ฑํ•  ๋‚ด์šฉ +โœ… ๋ฐ˜๋ณต ์ž‘์—…์„ ์œ„ํ•œ ์‚ฌ์šฉ์ž ์ง€์ • ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด ์ƒ์„ฑ +โœ… ํŒ€ ํ‘œ์ค€์„ ์œ„ํ•œ ํ”„๋กœ์ ํŠธ ๋ฉ”๋ชจ๋ฆฌ ์„ค์ • +โœ… ๊ฐœ์ธ ํ™˜๊ฒฝ ์„ค์ • ๊ตฌ์„ฑ +โœ… Claude๊ฐ€ ์ปจํ…์ŠคํŠธ๋ฅผ ์ž๋™์œผ๋กœ ๋กœ๋“œํ•˜๋Š” ๋ฐฉ๋ฒ• ์ดํ•ด + +#### ์‹ค์Šต ๊ณผ์ œ + +```bash +# Exercise 1: Install your first slash command +mkdir -p .claude/commands +cp 01-slash-commands/optimize.md .claude/commands/ + +# Exercise 2: Create project memory +cp 02-memory/project-CLAUDE.md ./CLAUDE.md + +# Exercise 3: Try it out +# In Claude Code, type: /optimize +``` + +#### ์„ฑ๊ณต ๊ธฐ์ค€ +- [ ] `/optimize` ๋ช…๋ น์–ด๋ฅผ ์„ฑ๊ณต์ ์œผ๋กœ ํ˜ธ์ถœํ•จ +- [ ] Claude๊ฐ€ CLAUDE.md์—์„œ ํ”„๋กœ์ ํŠธ ํ‘œ์ค€์„ ๊ธฐ์–ตํ•จ +- [ ] ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด์™€ ๋ฉ”๋ชจ๋ฆฌ๋ฅผ ์–ธ์ œ ์‚ฌ์šฉํ•ด์•ผ ํ•˜๋Š”์ง€ ์ดํ•ดํ•จ + +#### ๋‹ค์Œ ๋‹จ๊ณ„ +ํŽธ์•ˆํ•ด์ง€๋ฉด ๋‹ค์Œ์„ ์ฝ์–ด๋ณด์„ธ์š”: +- [01-slash-commands/README.md](01-slash-commands/README.md) +- [02-memory/README.md](02-memory/README.md) + +> **์ดํ•ด ํ™•์ธ**: Claude Code์—์„œ `/lesson-quiz slash-commands` ๋˜๋Š” `/lesson-quiz memory`๋ฅผ ์‹คํ–‰ํ•˜์—ฌ ํ•™์Šตํ•œ ๋‚ด์šฉ์„ ํ…Œ์ŠคํŠธํ•˜์„ธ์š”. + +--- + +### ๋งˆ์ผ์Šคํ†ค 1B: ์•ˆ์ „ํ•œ ํƒ์ƒ‰ + +**์ฃผ์ œ**: ์ฒดํฌํฌ์ธํŠธ + CLI ๊ธฐ๋ณธ ์‚ฌํ•ญ +**์‹œ๊ฐ„**: 1์‹œ๊ฐ„ +**๋ณต์žก์„ฑ**: โญโญ ์ดˆ๊ธ‰+ +**๋ชฉํ‘œ**: ์•ˆ์ „ํ•˜๊ฒŒ ์‹คํ—˜ํ•˜๊ณ  ํ•ต์‹ฌ CLI ๋ช…๋ น์–ด๋ฅผ ์‚ฌ์šฉํ•˜๋Š” ๋ฐฉ๋ฒ• ํ•™์Šต + +#### ๋‹ฌ์„ฑํ•  ๋‚ด์šฉ +โœ… ์•ˆ์ „ํ•œ ์‹คํ—˜์„ ์œ„ํ•œ ์ฒดํฌํฌ์ธํŠธ ์ƒ์„ฑ ๋ฐ ๋ณต์› +โœ… ๋Œ€ํ™”ํ˜• ๋ชจ๋“œ์™€ ์ธ์‡„ ๋ชจ๋“œ ์ดํ•ด +โœ… ๊ธฐ๋ณธ CLI ํ”Œ๋ž˜๊ทธ ๋ฐ ์˜ต์…˜ ์‚ฌ์šฉ +โœ… ํŒŒ์ดํ•‘์„ ํ†ตํ•œ ํŒŒ์ผ ์ฒ˜๋ฆฌ + +#### ์‹ค์Šต ๊ณผ์ œ + +```bash +# Exercise 1: Try checkpoint workflow +# In Claude Code: +# Make some experimental changes, then press Esc+Esc or use /rewind +# Select the checkpoint before your experiment +# Choose "Restore code and conversation" to go back + +# Exercise 2: Interactive vs Print mode +claude "explain this project" # Interactive mode +claude -p "explain this function" # Print mode (non-interactive) + +# Exercise 3: Process file content via piping +cat error.log | claude -p "explain this error" +``` + +#### ์„ฑ๊ณต ๊ธฐ์ค€ +- [ ] ์ฒดํฌํฌ์ธํŠธ๋ฅผ ์ƒ์„ฑํ•˜๊ณ  ์ด์ „ ์ƒํƒœ๋กœ ๋˜๋Œ๋ฆผ +- [ ] ๋Œ€ํ™”ํ˜• ๋ฐ ์ธ์‡„ ๋ชจ๋“œ๋ฅผ ๋ชจ๋‘ ์‚ฌ์šฉํ•จ +- [ ] ๋ถ„์„์„ ์œ„ํ•ด ํŒŒ์ผ์„ Claude๋กœ ํŒŒ์ดํ”„ํ•จ +- [ ] ์•ˆ์ „ํ•œ ์‹คํ—˜์„ ์œ„ํ•ด ์ฒดํฌํฌ์ธํŠธ๋ฅผ ์–ธ์ œ ์‚ฌ์šฉํ•ด์•ผ ํ•˜๋Š”์ง€ ์ดํ•ดํ•จ + +#### ๋‹ค์Œ ๋‹จ๊ณ„ +- ์ฝ๊ธฐ: [08-checkpoints/README.md](08-checkpoints/README.md) +- ์ฝ๊ธฐ: [10-cli/README.md](10-cli/README.md) +- **๋ ˆ๋ฒจ 2 ์ค€๋น„ ์™„๋ฃŒ!** [๋งˆ์ผ์Šคํ†ค 2A: ์ž๋™ํ™” (๊ธฐ์ˆ  + ํ›…)](#๋งˆ์ผ์Šคํ†ค-2a-์ž๋™ํ™”-๊ธฐ์ˆ --ํ›…)๋กœ ์ง„ํ–‰ํ•˜์„ธ์š”. + +> **์ดํ•ด ํ™•์ธ**: `/lesson-quiz checkpoints` ๋˜๋Š” `/lesson-quiz cli`๋ฅผ ์‹คํ–‰ํ•˜์—ฌ ๋ ˆ๋ฒจ 2 ์ค€๋น„๊ฐ€ ๋˜์—ˆ๋Š”์ง€ ํ™•์ธํ•˜์„ธ์š”. + +--- + +## ๐Ÿ”ต ๋ ˆ๋ฒจ 2: ์ค‘๊ธ‰ โ€” ์›Œํฌํ”Œ๋กœ์šฐ ๊ตฌ์ถ• + +**๋Œ€์ƒ**: ํ€ด์ฆˆ ์ฒดํฌ 3-5๊ฐœ์ธ ์‚ฌ์šฉ์ž +**์‹œ๊ฐ„**: ~5์‹œ๊ฐ„ +**์ดˆ์ **: ์ž๋™ํ™”, ํ†ตํ•ฉ, ์ž‘์—… ์œ„์ž„ +**๊ฒฐ๊ณผ**: ์ž๋™ํ™”๋œ ์›Œํฌํ”Œ๋กœ์šฐ, ์™ธ๋ถ€ ํ†ตํ•ฉ, ๋ ˆ๋ฒจ 3 ์ค€๋น„ ์™„๋ฃŒ + +### ํ•„์ˆ˜ ์ „์ œ ์กฐ๊ฑด ํ™•์ธ + +๋ ˆ๋ฒจ 2๋ฅผ ์‹œ์ž‘ํ•˜๊ธฐ ์ „์— ๋‹ค์Œ ๋ ˆ๋ฒจ 1 ๊ฐœ๋…์— ์ต์ˆ™ํ•œ์ง€ ํ™•์ธํ•˜์„ธ์š”: + +- [ ] ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด๋ฅผ ์ƒ์„ฑํ•˜๊ณ  ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์Œ ([01-slash-commands/](01-slash-commands/)) +- [ ] CLAUDE.md๋ฅผ ํ†ตํ•ด ํ”„๋กœ์ ํŠธ ๋ฉ”๋ชจ๋ฆฌ๋ฅผ ์„ค์ •ํ–ˆ์Œ ([02-memory/](02-memory/)) +- [ ] ์ฒดํฌํฌ์ธํŠธ๋ฅผ ์ƒ์„ฑํ•˜๊ณ  ๋ณต์›ํ•˜๋Š” ๋ฐฉ๋ฒ•์„ ์•Œ๊ณ  ์žˆ์Œ ([08-checkpoints/](08-checkpoints/)) +- [ ] ๋ช…๋ น์ค„์—์„œ `claude` ๋ฐ `claude -p`๋ฅผ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์Œ ([10-cli/](10-cli/)) + +> **๋ˆ„๋ฝ๋œ ๋ถ€๋ถ„?** ๊ณ„์†ํ•˜๊ธฐ ์ „์— ์œ„์— ์—ฐ๊ฒฐ๋œ ํŠœํ† ๋ฆฌ์–ผ์„ ๊ฒ€ํ† ํ•˜์„ธ์š”. + +--- + +### ๋งˆ์ผ์Šคํ†ค 2A: ์ž๋™ํ™” (๊ธฐ์ˆ  + ํ›…) + +**์ฃผ์ œ**: ๊ธฐ์ˆ  + ํ›… +**์‹œ๊ฐ„**: 2-3์‹œ๊ฐ„ +**๋ณต์žก์„ฑ**: โญโญ ์ค‘๊ธ‰ +**๋ชฉํ‘œ**: ์ผ๋ฐ˜์ ์ธ ์›Œํฌํ”Œ๋กœ์šฐ ๋ฐ ํ’ˆ์งˆ ๊ฒ€์‚ฌ ์ž๋™ํ™” + +#### ๋‹ฌ์„ฑํ•  ๋‚ด์šฉ +โœ… YAML ํ”„๋ŸฐํŠธ๋งคํ„ฐ( `effort` ๋ฐ `shell` ํ•„๋“œ ํฌํ•จ)๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ํŠน์ˆ˜ ๊ธฐ๋Šฅ ์ž๋™ ํ˜ธ์ถœ +โœ… 29๊ฐœ ํ›… ์ด๋ฒคํŠธ ์ „๋ฐ˜์— ๊ฑธ์ณ ์ด๋ฒคํŠธ ๊ธฐ๋ฐ˜ ์ž๋™ํ™” ์„ค์ • +โœ… 5๊ฐ€์ง€ ํ›… ์œ ํ˜•(command, http, mcp_tool, prompt, agent) ๋ชจ๋‘ ์‚ฌ์šฉ +โœ… ์ฝ”๋“œ ํ’ˆ์งˆ ํ‘œ์ค€ ์‹œํ–‰ +โœ… ์›Œํฌํ”Œ๋กœ์šฐ๋ฅผ ์œ„ํ•œ ์‚ฌ์šฉ์ž ์ง€์ • ํ›… ์ƒ์„ฑ + +#### ์‹ค์Šต ๊ณผ์ œ + +```bash +# Exercise 1: Install a skill +cp -r 03-skills/code-review-specialist ~/.claude/skills/ + +# Exercise 2: Set up hooks +mkdir -p ~/.claude/hooks +cp 06-hooks/pre-tool-check.sh ~/.claude/hooks/ +chmod +x ~/.claude/hooks/pre-tool-check.sh + +# Exercise 3: Configure hooks in settings +# Add to ~/.claude/settings.json: +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "~/.claude/hooks/pre-tool-check.sh" + } + ] + } + ] + } +} +``` + +#### ์„ฑ๊ณต ๊ธฐ์ค€ +- [ ] ๊ด€๋ จ์„ฑ์ด ์žˆ์„ ๋•Œ ์ฝ”๋“œ ๊ฒ€ํ†  ๊ธฐ์ˆ ์ด ์ž๋™์œผ๋กœ ํ˜ธ์ถœ๋จ +- [ ] PreToolUse ํ›…์ด ๋„๊ตฌ ์‹คํ–‰ ์ „์— ์‹คํ–‰๋จ +- [ ] ๊ธฐ์ˆ  ์ž๋™ ํ˜ธ์ถœ๊ณผ ํ›… ์ด๋ฒคํŠธ ํŠธ๋ฆฌ๊ฑฐ์˜ ์ฐจ์ด๋ฅผ ์ดํ•ดํ•จ + +#### ๋‹ค์Œ ๋‹จ๊ณ„ +- ์ž์‹ ๋งŒ์˜ ์‚ฌ์šฉ์ž ์ง€์ • ๊ธฐ์ˆ  ์ƒ์„ฑ +- ์›Œํฌํ”Œ๋กœ์šฐ๋ฅผ ์œ„ํ•œ ์ถ”๊ฐ€ ํ›… ์„ค์ • +- ์ฝ๊ธฐ: [03-skills/README.md](03-skills/README.md) +- ์ฝ๊ธฐ: [06-hooks/README.md](06-hooks/README.md) + +> **์ดํ•ด ํ™•์ธ**: `/lesson-quiz skills` ๋˜๋Š” `/lesson-quiz hooks`๋ฅผ ์‹คํ–‰ํ•˜์—ฌ ๋‹ค์Œ ๋‹จ๊ณ„๋กœ ๋„˜์–ด๊ฐ€๊ธฐ ์ „์— ์ง€์‹์„ ํ…Œ์ŠคํŠธํ•˜์„ธ์š”. + +--- + +### ๋งˆ์ผ์Šคํ†ค 2B: ํ†ตํ•ฉ (MCP + ์„œ๋ธŒ ์—์ด์ „ํŠธ) + +**์ฃผ์ œ**: MCP + ์„œ๋ธŒ ์—์ด์ „ํŠธ +**์‹œ๊ฐ„**: 2-3์‹œ๊ฐ„ +**๋ณต์žก์„ฑ**: โญโญโญ ์ค‘๊ธ‰+ +**๋ชฉํ‘œ**: ์™ธ๋ถ€ ์„œ๋น„์Šค ํ†ตํ•ฉ ๋ฐ ๋ณต์žกํ•œ ์ž‘์—… ์œ„์ž„ + +#### ๋‹ฌ์„ฑํ•  ๋‚ด์šฉ +โœ… GitHub, ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ๋“ฑ์—์„œ ์‹ค์‹œ๊ฐ„ ๋ฐ์ดํ„ฐ์— ์•ก์„ธ์Šค +โœ… ํŠน์ˆ˜ AI ์—์ด์ „ํŠธ์—๊ฒŒ ์ž‘์—… ์œ„์ž„ +โœ… MCP์™€ ์„œ๋ธŒ ์—์ด์ „ํŠธ๋ฅผ ์–ธ์ œ ์‚ฌ์šฉํ•ด์•ผ ํ•˜๋Š”์ง€ ์ดํ•ด +โœ… ํ†ตํ•ฉ ์›Œํฌํ”Œ๋กœ์šฐ ๊ตฌ์ถ• + +#### ์‹ค์Šต ๊ณผ์ œ + +```bash +# Exercise 1: Set up GitHub MCP +export GITHUB_TOKEN="your_github_token" +claude mcp add github -- npx -y @modelcontextprotocol/server-github + +# Exercise 2: Test MCP integration +# In Claude Code: /mcp__github__list_prs + +# Exercise 3: Install subagents +mkdir -p .claude/agents +cp 04-subagents/*.md .claude/agents/ +``` + +#### ํ†ตํ•ฉ ๊ณผ์ œ +์ด ์™„์ „ํ•œ ์›Œํฌํ”Œ๋กœ์šฐ๋ฅผ ์‹œ๋„ํ•ด ๋ณด์„ธ์š”: +1. MCP๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ GitHub PR ๊ฐ€์ ธ์˜ค๊ธฐ +2. Claude๊ฐ€ ์ฝ”๋“œ ๊ฒ€ํ†  ์„œ๋ธŒ ์—์ด์ „ํŠธ์— ๊ฒ€ํ† ๋ฅผ ์œ„์ž„ํ•˜๋„๋ก ํ•˜๊ธฐ +3. ํ›…์„ ์‚ฌ์šฉํ•˜์—ฌ ์ž๋™์œผ๋กœ ํ…Œ์ŠคํŠธ ์‹คํ–‰ + +#### ์„ฑ๊ณต ๊ธฐ์ค€ +- [ ] MCP๋ฅผ ํ†ตํ•ด GitHub ๋ฐ์ดํ„ฐ๋ฅผ ์„ฑ๊ณต์ ์œผ๋กœ ์ฟผ๋ฆฌํ•จ +- [ ] Claude๊ฐ€ ๋ณต์žกํ•œ ์ž‘์—…์„ ์„œ๋ธŒ ์—์ด์ „ํŠธ์— ์œ„์ž„ํ•จ +- [ ] MCP์™€ ์„œ๋ธŒ ์—์ด์ „ํŠธ์˜ ์ฐจ์ด๋ฅผ ์ดํ•ดํ•จ +- [ ] ์›Œํฌํ”Œ๋กœ์šฐ์—์„œ MCP + ์„œ๋ธŒ ์—์ด์ „ํŠธ + ํ›…์„ ๊ฒฐํ•ฉํ•จ + +#### ๋‹ค์Œ ๋‹จ๊ณ„ +- ์ถ”๊ฐ€ MCP ์„œ๋ฒ„ ์„ค์ • (๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค, Slack ๋“ฑ) +- ๋„๋ฉ”์ธ์— ๋งž๋Š” ์‚ฌ์šฉ์ž ์ง€์ • ์„œ๋ธŒ ์—์ด์ „ํŠธ ์ƒ์„ฑ +- ์ฝ๊ธฐ: [05-mcp/README.md](05-mcp/README.md) +- ์ฝ๊ธฐ: [04-subagents/README.md](04-subagents/README.md) +- **๋ ˆ๋ฒจ 3 ์ค€๋น„ ์™„๋ฃŒ!** [๋งˆ์ผ์Šคํ†ค 3A: ๊ณ ๊ธ‰ ๊ธฐ๋Šฅ](#๋งˆ์ผ์Šคํ†ค-3a-๊ณ ๊ธ‰-๊ธฐ๋Šฅ)๋กœ ์ง„ํ–‰ํ•˜์„ธ์š”. + +> **์ดํ•ด ํ™•์ธ**: `/lesson-quiz mcp` ๋˜๋Š” `/lesson-quiz subagents`๋ฅผ ์‹คํ–‰ํ•˜์—ฌ ๋ ˆ๋ฒจ 3 ์ค€๋น„๊ฐ€ ๋˜์—ˆ๋Š”์ง€ ํ™•์ธํ•˜์„ธ์š”. + +--- + +## ๐Ÿ”ด ๋ ˆ๋ฒจ 3: ๊ณ ๊ธ‰ โ€” ํŒŒ์›Œ ์œ ์ € ๋ฐ ํŒ€ ๋ฆฌ๋” + +**๋Œ€์ƒ**: ํ€ด์ฆˆ ์ฒดํฌ 6-8๊ฐœ์ธ ์‚ฌ์šฉ์ž +**์‹œ๊ฐ„**: ~5์‹œ๊ฐ„ +**์ดˆ์ **: ํŒ€ ๋„๊ตฌ, CI/CD, ์—”ํ„ฐํ”„๋ผ์ด์ฆˆ ๊ธฐ๋Šฅ, ํ”Œ๋Ÿฌ๊ทธ์ธ ๊ฐœ๋ฐœ +**๊ฒฐ๊ณผ**: ํŒŒ์›Œ ์œ ์ €, ํŒ€ ์›Œํฌํ”Œ๋กœ์šฐ ๋ฐ CI/CD ์„ค์ • ๊ฐ€๋Šฅ + +### ํ•„์ˆ˜ ์ „์ œ ์กฐ๊ฑด ํ™•์ธ + +๋ ˆ๋ฒจ 3์„ ์‹œ์ž‘ํ•˜๊ธฐ ์ „์— ๋‹ค์Œ ๋ ˆ๋ฒจ 2 ๊ฐœ๋…์— ์ต์ˆ™ํ•œ์ง€ ํ™•์ธํ•˜์„ธ์š”: + +- [ ] ์ž๋™ ํ˜ธ์ถœ์„ ์‚ฌ์šฉํ•˜์—ฌ ๊ธฐ์ˆ ์„ ์ƒ์„ฑํ•˜๊ณ  ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์Œ ([03-skills/](03-skills/)) +- [ ] ์ด๋ฒคํŠธ ๊ธฐ๋ฐ˜ ์ž๋™ํ™”๋ฅผ ์œ„ํ•œ ํ›…์„ ์„ค์ •ํ–ˆ์Œ ([06-hooks/](06-hooks/)) +- [ ] ์™ธ๋ถ€ ๋ฐ์ดํ„ฐ๋ฅผ ์œ„ํ•œ MCP ์„œ๋ฒ„๋ฅผ ๊ตฌ์„ฑํ•  ์ˆ˜ ์žˆ์Œ ([05-mcp/](05-mcp/)) +- [ ] ์ž‘์—… ์œ„์ž„์„ ์œ„ํ•ด ์„œ๋ธŒ ์—์ด์ „ํŠธ๋ฅผ ์‚ฌ์šฉํ•˜๋Š” ๋ฐฉ๋ฒ•์„ ์•Œ๊ณ  ์žˆ์Œ ([04-subagents/](04-subagents/)) + +> **๋ˆ„๋ฝ๋œ ๋ถ€๋ถ„?** ๊ณ„์†ํ•˜๊ธฐ ์ „์— ์œ„์— ์—ฐ๊ฒฐ๋œ ํŠœํ† ๋ฆฌ์–ผ์„ ๊ฒ€ํ† ํ•˜์„ธ์š”. + +--- + +### ๋งˆ์ผ์Šคํ†ค 3A: ๊ณ ๊ธ‰ ๊ธฐ๋Šฅ + +**์ฃผ์ œ**: ๊ณ ๊ธ‰ ๊ธฐ๋Šฅ (๊ณ„ํš, ๊ถŒํ•œ, ํ™•์žฅ๋œ ์‚ฌ๊ณ , ์ž๋™ ๋ชจ๋“œ, ์ฑ„๋„, ์Œ์„ฑ ๋ฐ›์•„์“ฐ๊ธฐ, ์›๊ฒฉ/๋ฐ์Šคํฌํ†ฑ/์›น) +**์‹œ๊ฐ„**: 2-3์‹œ๊ฐ„ +**๋ณต์žก์„ฑ**: โญโญโญโญโญ ๊ณ ๊ธ‰ +**๋ชฉํ‘œ**: ๊ณ ๊ธ‰ ์›Œํฌํ”Œ๋กœ์šฐ ๋ฐ ํŒŒ์›Œ ์œ ์ € ๋„๊ตฌ ๋งˆ์Šคํ„ฐ + +#### ๋‹ฌ์„ฑํ•  ๋‚ด์šฉ +โœ… ๋ณต์žกํ•œ ๊ธฐ๋Šฅ์„ ์œ„ํ•œ ๊ณ„ํš ๋ชจ๋“œ +โœ… 6๊ฐ€์ง€ ๋ชจ๋“œ(default, acceptEdits, plan, auto, dontAsk, bypassPermissions)๋ฅผ ํ†ตํ•œ ์„ธ๋ถ„ํ™”๋œ ๊ถŒํ•œ ์ œ์–ด +โœ… Alt+T / Option+T ํ† ๊ธ€์„ ํ†ตํ•œ ํ™•์žฅ๋œ ์‚ฌ๊ณ  +โœ… ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž‘์—… ๊ด€๋ฆฌ +โœ… ํ•™์Šต๋œ ํ™˜๊ฒฝ ์„ค์ •์„ ์œ„ํ•œ ์ž๋™ ๋ฉ”๋ชจ๋ฆฌ +โœ… ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์•ˆ์ „ ๋ถ„๋ฅ˜๊ธฐ๊ฐ€ ์žˆ๋Š” ์ž๋™ ๋ชจ๋“œ +โœ… ๊ตฌ์กฐํ™”๋œ ๋‹ค์ค‘ ์„ธ์…˜ ์›Œํฌํ”Œ๋กœ์šฐ๋ฅผ ์œ„ํ•œ ์ฑ„๋„ +โœ… ํ•ธ์ฆˆํ”„๋ฆฌ ์ƒํ˜ธ ์ž‘์šฉ์„ ์œ„ํ•œ ์Œ์„ฑ ๋ฐ›์•„์“ฐ๊ธฐ +โœ… ์›๊ฒฉ ์ œ์–ด, ๋ฐ์Šคํฌํ†ฑ ์•ฑ ๋ฐ ์›น ์„ธ์…˜ +โœ… ๋‹ค์ค‘ ์—์ด์ „ํŠธ ํ˜‘์—…์„ ์œ„ํ•œ ์—์ด์ „ํŠธ ํŒ€ + +#### ์‹ค์Šต ๊ณผ์ œ + +```bash +# Exercise 1: Use planning mode +/plan Implement user authentication system + +# Exercise 2: Try permission modes (6 available: default, acceptEdits, plan, auto, dontAsk, bypassPermissions) +claude --permission-mode plan "analyze this codebase" +claude --permission-mode acceptEdits "refactor the auth module" +claude --permission-mode auto "implement the feature" + +# Exercise 3: Enable extended thinking +# Press Alt+T (Option+T on macOS) during a session to toggle + +# Exercise 4: Advanced checkpoint workflow +# 1. Create checkpoint "Clean state" +# 2. Use planning mode to design a feature +# 3. Implement with subagent delegation +# 4. Run tests in background +# 5. If tests fail, rewind to checkpoint +# 6. Try alternative approach + +# Exercise 5: Try auto mode (background safety classifier) +claude --permission-mode auto "implement user settings page" + +# Exercise 6: Enable agent teams +export CLAUDE_AGENT_TEAMS=1 +# Ask Claude: "Implement feature X using a team approach" + +# Exercise 7: Scheduled tasks +/loop 5m /check-status +# Or use CronCreate for persistent scheduled tasks + +# Exercise 8: Channels for multi-session workflows +# Use channels to organize work across sessions + +# Exercise 9: Voice Dictation +# Use voice input for hands-free interaction with Claude Code +``` + +#### ์„ฑ๊ณต ๊ธฐ์ค€ +- [ ] ๋ณต์žกํ•œ ๊ธฐ๋Šฅ์„ ์œ„ํ•ด ๊ณ„ํš ๋ชจ๋“œ๋ฅผ ์‚ฌ์šฉํ•จ +- [ ] ๊ถŒํ•œ ๋ชจ๋“œ(plan, acceptEdits, auto, dontAsk)๋ฅผ ๊ตฌ์„ฑํ•จ +- [ ] Alt+T / Option+T๋กœ ํ™•์žฅ๋œ ์‚ฌ๊ณ ๋ฅผ ํ† ๊ธ€ํ•จ +- [ ] ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์•ˆ์ „ ๋ถ„๋ฅ˜๊ธฐ๊ฐ€ ์žˆ๋Š” ์ž๋™ ๋ชจ๋“œ๋ฅผ ์‚ฌ์šฉํ•จ +- [ ] ๊ธด ์ž‘์—…์„ ์œ„ํ•ด ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž‘์—…์„ ์‚ฌ์šฉํ•จ +- [ ] ๋‹ค์ค‘ ์„ธ์…˜ ์›Œํฌํ”Œ๋กœ์šฐ๋ฅผ ์œ„ํ•ด ์ฑ„๋„์„ ํƒ์ƒ‰ํ•จ +- [ ] ํ•ธ์ฆˆํ”„๋ฆฌ ์ž…๋ ฅ์„ ์œ„ํ•ด ์Œ์„ฑ ๋ฐ›์•„์“ฐ๊ธฐ๋ฅผ ์‹œ๋„ํ•จ +- [ ] ์›๊ฒฉ ์ œ์–ด, ๋ฐ์Šคํฌํ†ฑ ์•ฑ ๋ฐ ์›น ์„ธ์…˜์„ ์ดํ•ดํ•จ +- [ ] ํ˜‘์—… ์ž‘์—…์„ ์œ„ํ•ด ์—์ด์ „ํŠธ ํŒ€์„ ํ™œ์„ฑํ™”ํ•˜๊ณ  ์‚ฌ์šฉํ•จ +- [ ] ๋ฐ˜๋ณต ์ž‘์—… ๋˜๋Š” ์˜ˆ์•ฝ๋œ ๋ชจ๋‹ˆํ„ฐ๋ง์„ ์œ„ํ•ด `/loop`๋ฅผ ์‚ฌ์šฉํ•จ + +#### ๋‹ค์Œ ๋‹จ๊ณ„ +- ์ฝ๊ธฐ: [09-advanced-features/README.md](09-advanced-features/README.md) + +> **์ดํ•ด ํ™•์ธ**: `/lesson-quiz advanced`๋ฅผ ์‹คํ–‰ํ•˜์—ฌ ํŒŒ์›Œ ์œ ์ € ๊ธฐ๋Šฅ ์ˆ™๋ จ๋„๋ฅผ ํ…Œ์ŠคํŠธํ•˜์„ธ์š”. + +--- + +### ๋งˆ์ผ์Šคํ†ค 3B: ํŒ€ ๋ฐ ๋ฐฐํฌ (ํ”Œ๋Ÿฌ๊ทธ์ธ + CLI ๋งˆ์Šคํ„ฐ๋ฆฌ) + +**์ฃผ์ œ**: ํ”Œ๋Ÿฌ๊ทธ์ธ + CLI ๋งˆ์Šคํ„ฐ๋ฆฌ + CI/CD +**์‹œ๊ฐ„**: 2-3์‹œ๊ฐ„ +**๋ณต์žก์„ฑ**: โญโญโญโญ ๊ณ ๊ธ‰ +**๋ชฉํ‘œ**: ํŒ€ ๋„๊ตฌ ๊ตฌ์ถ•, ํ”Œ๋Ÿฌ๊ทธ์ธ ์ƒ์„ฑ, CI/CD ํ†ตํ•ฉ ๋งˆ์Šคํ„ฐ + +#### ๋‹ฌ์„ฑํ•  ๋‚ด์šฉ +โœ… ์™„์ „ํ•œ ๋ฒˆ๋“ค ํ”Œ๋Ÿฌ๊ทธ์ธ ์„ค์น˜ ๋ฐ ์ƒ์„ฑ +โœ… ์Šคํฌ๋ฆฝํŒ… ๋ฐ ์ž๋™ํ™”๋ฅผ ์œ„ํ•œ CLI ๋งˆ์Šคํ„ฐ +โœ… `claude -p`๋ฅผ ํ†ตํ•œ CI/CD ํ†ตํ•ฉ ์„ค์ • +โœ… ์ž๋™ํ™”๋œ ํŒŒ์ดํ”„๋ผ์ธ์„ ์œ„ํ•œ JSON ์ถœ๋ ฅ +โœ… ์„ธ์…˜ ๊ด€๋ฆฌ ๋ฐ ์ผ๊ด„ ์ฒ˜๋ฆฌ + +#### ์‹ค์Šต ๊ณผ์ œ + +```bash +# Exercise 1: Install a complete plugin +# In Claude Code: /plugin install pr-review + +# Exercise 2: Print mode for CI/CD +claude -p "Run all tests and generate report" + +# Exercise 3: JSON output for scripts +claude -p --output-format json "list all functions" + +# Exercise 4: Session management and resumption +claude -r "feature-auth" "continue implementation" + +# Exercise 5: CI/CD integration with constraints +claude -p --max-turns 3 --output-format json "review code" + +# Exercise 6: Batch processing +for file in *.md; do + claude -p --output-format json "summarize this: $(cat $file)" > ${file%.md}.summary.json +done +``` + +#### CI/CD ํ†ตํ•ฉ ๊ณผ์ œ +๊ฐ„๋‹จํ•œ CI/CD ์Šคํฌ๋ฆฝํŠธ๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค: +1. `claude -p`๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ๋ณ€๊ฒฝ๋œ ํŒŒ์ผ ๊ฒ€ํ†  +2. ๊ฒฐ๊ณผ๋ฅผ JSON์œผ๋กœ ์ถœ๋ ฅ +3. `jq`๋กœ ํŠน์ • ๋ฌธ์ œ ์ฒ˜๋ฆฌ +4. GitHub Actions ์›Œํฌํ”Œ๋กœ์šฐ์— ํ†ตํ•ฉ + +#### ์„ฑ๊ณต ๊ธฐ์ค€ +- [ ] ํ”Œ๋Ÿฌ๊ทธ์ธ์„ ์„ค์น˜ํ•˜๊ณ  ์‚ฌ์šฉํ•จ +- [ ] ํŒ€์„ ์œ„ํ•œ ํ”Œ๋Ÿฌ๊ทธ์ธ์„ ๊ตฌ์ถ•ํ•˜๊ฑฐ๋‚˜ ์ˆ˜์ •ํ•จ +- [ ] CI/CD์—์„œ ์ธ์‡„ ๋ชจ๋“œ (`claude -p`)๋ฅผ ์‚ฌ์šฉํ•จ +- [ ] ์Šคํฌ๋ฆฝํŒ…์„ ์œ„ํ•ด JSON ์ถœ๋ ฅ์„ ์ƒ์„ฑํ•จ +- [ ] ์ด์ „ ์„ธ์…˜์„ ์„ฑ๊ณต์ ์œผ๋กœ ์žฌ๊ฐœํ•จ +- [ ] ์ผ๊ด„ ์ฒ˜๋ฆฌ ์Šคํฌ๋ฆฝํŠธ๋ฅผ ์ƒ์„ฑํ•จ +- [ ] Claude๋ฅผ CI/CD ์›Œํฌํ”Œ๋กœ์šฐ์— ํ†ตํ•ฉํ•จ + +#### CLI์˜ ์‹ค์ œ ์‚ฌ์šฉ ์‚ฌ๋ก€ +- **์ฝ”๋“œ ๊ฒ€ํ†  ์ž๋™ํ™”**: CI/CD ํŒŒ์ดํ”„๋ผ์ธ์—์„œ ์ฝ”๋“œ ๊ฒ€ํ†  ์‹คํ–‰ +- **๋กœ๊ทธ ๋ถ„์„**: ์˜ค๋ฅ˜ ๋กœ๊ทธ ๋ฐ ์‹œ์Šคํ…œ ์ถœ๋ ฅ ๋ถ„์„ +- **๋ฌธ์„œ ์ƒ์„ฑ**: ๋ฌธ์„œ ์ผ๊ด„ ์ƒ์„ฑ +- **ํ…Œ์ŠคํŠธ ์ธ์‚ฌ์ดํŠธ**: ํ…Œ์ŠคํŠธ ์‹คํŒจ ๋ถ„์„ +- **์„ฑ๋Šฅ ๋ถ„์„**: ์„ฑ๋Šฅ ์ง€ํ‘œ ๊ฒ€ํ†  +- **๋ฐ์ดํ„ฐ ์ฒ˜๋ฆฌ**: ๋ฐ์ดํ„ฐ ํŒŒ์ผ ๋ณ€ํ™˜ ๋ฐ ๋ถ„์„ + +#### ๋‹ค์Œ ๋‹จ๊ณ„ +- ์ฝ๊ธฐ: [07-plugins/README.md](07-plugins/README.md) +- ์ฝ๊ธฐ: [10-cli/README.md](10-cli/README.md) +- ํŒ€ ์ „์ฒด CLI ๋‹จ์ถ•ํ‚ค ๋ฐ ํ”Œ๋Ÿฌ๊ทธ์ธ ์ƒ์„ฑ +- ์ผ๊ด„ ์ฒ˜๋ฆฌ ์Šคํฌ๋ฆฝํŠธ ์„ค์ • + +> **์ดํ•ด ํ™•์ธ**: `/lesson-quiz plugins` ๋˜๋Š” `/lesson-quiz cli`๋ฅผ ์‹คํ–‰ํ•˜์—ฌ ์ˆ™๋ จ๋„๋ฅผ ํ™•์ธํ•˜์„ธ์š”. + +--- + +## ๐Ÿงช ์ง€์‹ ํ…Œ์ŠคํŠธํ•˜๊ธฐ + +์ด ์ €์žฅ์†Œ์—๋Š” Claude Code์—์„œ ์–ธ์ œ๋“ ์ง€ ์‚ฌ์šฉํ•˜์—ฌ ์ดํ•ด๋„๋ฅผ ํ‰๊ฐ€ํ•  ์ˆ˜ ์žˆ๋Š” ๋‘ ๊ฐ€์ง€ ๋Œ€ํ™”ํ˜• ๊ธฐ์ˆ ์ด ํฌํ•จ๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. + +| Skill | Command | Purpose | +|-------|---------|---------| +| **์ž๊ธฐ ํ‰๊ฐ€** | `/self-assessment` | 10๊ฐ€์ง€ ๊ธฐ๋Šฅ ์ „๋ฐ˜์— ๊ฑธ์นœ ์ „๋ฐ˜์ ์ธ ์ˆ™๋ จ๋„๋ฅผ ํ‰๊ฐ€ํ•ฉ๋‹ˆ๋‹ค. Quick (2๋ถ„) ๋˜๋Š” Deep (5๋ถ„) ๋ชจ๋“œ๋ฅผ ์„ ํƒํ•˜์—ฌ ๊ฐœ์ธํ™”๋œ ๊ธฐ์ˆ  ํ”„๋กœํ•„ ๋ฐ ํ•™์Šต ๊ฒฝ๋กœ๋ฅผ ์–ป์œผ์„ธ์š”. | +| **๋ ˆ์Šจ ํ€ด์ฆˆ** | `/lesson-quiz [lesson]` | 10๊ฐ€์ง€ ์งˆ๋ฌธ์œผ๋กœ ํŠน์ • ๋ ˆ์Šจ์— ๋Œ€ํ•œ ์ดํ•ด๋„๋ฅผ ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. ๋ ˆ์Šจ ์ „(์‚ฌ์ „ ํ…Œ์ŠคํŠธ), ๋„์ค‘(์ง„ํ–‰ ์ƒํ™ฉ ํ™•์ธ) ๋˜๋Š” ํ›„(์ˆ™๋ จ๋„ ํ™•์ธ)์— ์‚ฌ์šฉํ•˜์„ธ์š”. | + +**์˜ˆ์‹œ:** +``` +/self-assessment # Find your overall level +/lesson-quiz hooks # Quiz on Lesson 06: Hooks +/lesson-quiz 03 # Quiz on Lesson 03: Skills +/lesson-quiz advanced-features # Quiz on Lesson 09 +``` + +--- + +## โšก ๋น ๋ฅธ ์‹œ์ž‘ ๊ฒฝ๋กœ + +### 15๋ถ„๋งŒ ์žˆ๋‹ค๋ฉด +**๋ชฉํ‘œ**: ์ฒซ ๋ฒˆ์งธ ์„ฑ๊ณต ๊ฒฝํ—˜ ์–ป๊ธฐ + +1. ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด ํ•˜๋‚˜ ๋ณต์‚ฌ: `cp 01-slash-commands/optimize.md .claude/commands/` +2. Claude Code์—์„œ ์‹œ๋„: `/optimize` +3. ์ฝ๊ธฐ: [01-slash-commands/README.md](01-slash-commands/README.md) + +**๊ฒฐ๊ณผ**: ์ž‘๋™ํ•˜๋Š” ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด๋ฅผ ๊ฐ€์ง€๊ณ  ๊ธฐ๋ณธ ์‚ฌํ•ญ์„ ์ดํ•ดํ•˜๊ฒŒ ๋ฉ๋‹ˆ๋‹ค. + +--- + +### 1์‹œ๊ฐ„์ด ์žˆ๋‹ค๋ฉด +**๋ชฉํ‘œ**: ํ•„์ˆ˜ ์ƒ์‚ฐ์„ฑ ๋„๊ตฌ ์„ค์ • + +1. **์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด** (15๋ถ„): `/optimize` ๋ฐ `/pr` ๋ณต์‚ฌ ๋ฐ ํ…Œ์ŠคํŠธ +2. **ํ”„๋กœ์ ํŠธ ๋ฉ”๋ชจ๋ฆฌ** (15๋ถ„): ํ”„๋กœ์ ํŠธ ํ‘œ์ค€์œผ๋กœ CLAUDE.md ์ƒ์„ฑ +3. **๊ธฐ์ˆ  ์„ค์น˜** (15๋ถ„): ์ฝ”๋“œ ๊ฒ€ํ†  ์ „๋ฌธ๊ฐ€ ๊ธฐ์ˆ  ์„ค์ • +4. **ํ•จ๊ป˜ ์‹œ๋„** (15๋ถ„): ์ด๋“ค์ด ์–ด๋–ป๊ฒŒ ์กฐํ™”๋กญ๊ฒŒ ์ž‘๋™ํ•˜๋Š”์ง€ ํ™•์ธ + +**๊ฒฐ๊ณผ**: ๋ช…๋ น์–ด, ๋ฉ”๋ชจ๋ฆฌ ๋ฐ ์ž๋™ ๊ธฐ์ˆ ์„ ํ†ตํ•œ ๊ธฐ๋ณธ ์ƒ์‚ฐ์„ฑ ํ–ฅ์ƒ + +--- + +### ์ฃผ๋ง์ด ์žˆ๋‹ค๋ฉด +**๋ชฉํ‘œ**: ๋Œ€๋ถ€๋ถ„์˜ ๊ธฐ๋Šฅ์— ๋Šฅ์ˆ™ํ•ด์ง€๊ธฐ + +**ํ† ์š”์ผ ์˜ค์ „** (3์‹œ๊ฐ„): +- ๋งˆ์ผ์Šคํ†ค 1A ์™„๋ฃŒ: ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด + ๋ฉ”๋ชจ๋ฆฌ +- ๋งˆ์ผ์Šคํ†ค 1B ์™„๋ฃŒ: ์ฒดํฌํฌ์ธํŠธ + CLI ๊ธฐ๋ณธ ์‚ฌํ•ญ + +**ํ† ์š”์ผ ์˜คํ›„** (3์‹œ๊ฐ„): +- ๋งˆ์ผ์Šคํ†ค 2A ์™„๋ฃŒ: ๊ธฐ์ˆ  + ํ›… +- ๋งˆ์ผ์Šคํ†ค 2B ์™„๋ฃŒ: MCP + ์„œ๋ธŒ ์—์ด์ „ํŠธ + +**์ผ์š”์ผ** (4์‹œ๊ฐ„): +- ๋งˆ์ผ์Šคํ†ค 3A ์™„๋ฃŒ: ๊ณ ๊ธ‰ ๊ธฐ๋Šฅ +- ๋งˆ์ผ์Šคํ†ค 3B ์™„๋ฃŒ: ํ”Œ๋Ÿฌ๊ทธ์ธ + CLI ๋งˆ์Šคํ„ฐ๋ฆฌ + CI/CD +- ํŒ€์„ ์œ„ํ•œ ์‚ฌ์šฉ์ž ์ง€์ • ํ”Œ๋Ÿฌ๊ทธ์ธ ๊ตฌ์ถ• + +**๊ฒฐ๊ณผ**: Claude Code ํŒŒ์›Œ ์œ ์ €๊ฐ€ ๋˜์–ด ๋‹ค๋ฅธ ์‚ฌ๋žŒ์„ ๊ต์œกํ•˜๊ณ  ๋ณต์žกํ•œ ์›Œํฌํ”Œ๋กœ์šฐ๋ฅผ ์ž๋™ํ™”ํ•  ์ค€๋น„๊ฐ€ ๋ฉ๋‹ˆ๋‹ค. + +--- + +## ๐Ÿ’ก ํ•™์Šต ํŒ + +### โœ… ํ•ด์•ผ ํ•  ์ผ + +- ์‹œ์ž‘ ์ง€์ ์„ ์ฐพ๊ธฐ ์œ„ํ•ด **๋จผ์ € ํ€ด์ฆˆ๋ฅผ ํ‘ธ์„ธ์š”** +- ๊ฐ ๋งˆ์ผ์Šคํ†ค์— ๋Œ€ํ•œ **์‹ค์Šต ๊ณผ์ œ๋ฅผ ์™„๋ฃŒํ•˜์„ธ์š”** +- **๊ฐ„๋‹จํ•˜๊ฒŒ ์‹œ์ž‘**ํ•˜๊ณ  ์ ์ง„์ ์œผ๋กœ ๋ณต์žก์„ฑ์„ ์ถ”๊ฐ€ํ•˜์„ธ์š” +- ๋‹ค์Œ์œผ๋กœ ๋„˜์–ด๊ฐ€๊ธฐ ์ „์— **๊ฐ ๊ธฐ๋Šฅ์„ ํ…Œ์ŠคํŠธํ•˜์„ธ์š”** +- ์›Œํฌํ”Œ๋กœ์šฐ์— ์ž‘๋™ํ•˜๋Š” ๋‚ด์šฉ์— ๋Œ€ํ•ด **๋ฉ”๋ชจ๋ฅผ ์ž‘์„ฑํ•˜์„ธ์š”** +- ๊ณ ๊ธ‰ ์ฃผ์ œ๋ฅผ ํ•™์Šตํ•  ๋•Œ **์ด์ „ ๊ฐœ๋…์„ ๋‹ค์‹œ ์ฐธ์กฐํ•˜์„ธ์š”** +- ์ฒดํฌํฌ์ธํŠธ๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ **์•ˆ์ „ํ•˜๊ฒŒ ์‹คํ—˜ํ•˜์„ธ์š”** +- ํŒ€๊ณผ **์ง€์‹์„ ๊ณต์œ ํ•˜์„ธ์š”** + +### โŒ ํ•˜์ง€ ๋ง์•„์•ผ ํ•  ์ผ + +- ๋” ๋†’์€ ๋ ˆ๋ฒจ๋กœ ๊ฑด๋„ˆ๋›ธ ๋•Œ **์ „์ œ ์กฐ๊ฑด ํ™•์ธ์„ ๊ฑด๋„ˆ๋›ฐ์ง€ ๋งˆ์„ธ์š”** +- **๋ชจ๋“  ๊ฒƒ์„ ํ•œ ๋ฒˆ์— ๋ฐฐ์šฐ๋ ค ํ•˜์ง€ ๋งˆ์„ธ์š”** - ์••๋„์ ์ผ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. +- **์ดํ•ด ์—†์ด ๊ตฌ์„ฑ์„ ๋ณต์‚ฌํ•˜์ง€ ๋งˆ์„ธ์š”** - ๋””๋ฒ„๊ทธ ๋ฐฉ๋ฒ•์„ ์•Œ ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค. +- **ํ…Œ์ŠคํŠธํ•˜๋Š” ๊ฒƒ์„ ์žŠ์ง€ ๋งˆ์„ธ์š”** - ํ•ญ์ƒ ๊ธฐ๋Šฅ์ด ์ž‘๋™ํ•˜๋Š”์ง€ ํ™•์ธํ•˜์„ธ์š”. +- **๋งˆ์ผ์Šคํ†ค์„ ์„œ๋‘๋ฅด์ง€ ๋งˆ์„ธ์š”** - ์ดํ•ดํ•˜๋Š” ๋ฐ ์‹œ๊ฐ„์„ ๋“ค์ด์„ธ์š”. +- **๋ฌธ์„œ๋ฅผ ๋ฌด์‹œํ•˜์ง€ ๋งˆ์„ธ์š”** - ๊ฐ README์—๋Š” ๊ท€์ค‘ํ•œ ์„ธ๋ถ€ ์ •๋ณด๊ฐ€ ์žˆ์Šต๋‹ˆ๋‹ค. +- **ํ˜ผ์ž ์ž‘์—…ํ•˜์ง€ ๋งˆ์„ธ์š”** - ํŒ€์›๋“ค๊ณผ ๋…ผ์˜ํ•˜์„ธ์š”. + +--- + +## ๐ŸŽ“ ํ•™์Šต ์Šคํƒ€์ผ + +### ์‹œ๊ฐ ํ•™์Šต์ž +- ๊ฐ README์˜ ๋จธ๋ฉ”์ด๋“œ ๋‹ค์ด์–ด๊ทธ๋žจ์„ ์—ฐ๊ตฌํ•˜์„ธ์š” +- ๋ช…๋ น์–ด ์‹คํ–‰ ํ๋ฆ„์„ ๊ด€์ฐฐํ•˜์„ธ์š” +- ์ž์‹ ๋งŒ์˜ ์›Œํฌํ”Œ๋กœ์šฐ ๋‹ค์ด์–ด๊ทธ๋žจ์„ ๊ทธ๋ฆฌ์„ธ์š” +- ์œ„ ์‹œ๊ฐ ํ•™์Šต ๊ฒฝ๋กœ๋ฅผ ์‚ฌ์šฉํ•˜์„ธ์š” + +### ์‹ค์Šต ํ•™์Šต์ž +- ๋ชจ๋“  ์‹ค์Šต ๊ณผ์ œ๋ฅผ ์™„๋ฃŒํ•˜์„ธ์š” +- ๋‹ค์–‘ํ•œ ๋ณ€ํ˜•์œผ๋กœ ์‹คํ—˜ํ•˜์„ธ์š” +- ๊ณ ์žฅ ๋‚ด๊ณ  ๊ณ ์ณ๋ณด์„ธ์š” (์ฒดํฌํฌ์ธํŠธ๋ฅผ ์‚ฌ์šฉํ•˜์„ธ์š”!) +- ์ž์‹ ๋งŒ์˜ ์˜ˆ์‹œ๋ฅผ ๋งŒ๋“œ์„ธ์š” + +### ๋…์„œ ํ•™์Šต์ž +- ๊ฐ README๋ฅผ ์ฒ ์ €ํžˆ ์ฝ์œผ์„ธ์š” +- ์ฝ”๋“œ ์˜ˆ์ œ๋ฅผ ์—ฐ๊ตฌํ•˜์„ธ์š” +- ๋น„๊ต ํ‘œ๋ฅผ ๊ฒ€ํ† ํ•˜์„ธ์š” +- ์ž๋ฃŒ์— ์—ฐ๊ฒฐ๋œ ๋ธ”๋กœ๊ทธ ๊ฒŒ์‹œ๋ฌผ์„ ์ฝ์œผ์„ธ์š” + +### ์‚ฌํšŒ์  ํ•™์Šต์ž +- ํŽ˜์–ด ํ”„๋กœ๊ทธ๋ž˜๋ฐ ์„ธ์…˜์„ ์„ค์ •ํ•˜์„ธ์š” +- ํŒ€์›๋“ค์—๊ฒŒ ๊ฐœ๋…์„ ๊ฐ€๋ฅด์น˜์„ธ์š” +- Claude Code ์ปค๋ฎค๋‹ˆํ‹ฐ ํ† ๋ก ์— ์ฐธ์—ฌํ•˜์„ธ์š” +- ์ž์‹ ๋งŒ์˜ ์‚ฌ์šฉ์ž ์ง€์ • ๊ตฌ์„ฑ์„ ๊ณต์œ ํ•˜์„ธ์š” + +--- + +## ๐Ÿ“ˆ ์ง„ํ–‰ ์ƒํ™ฉ ์ถ”์  + +์ด ์ฒดํฌ๋ฆฌ์ŠคํŠธ๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ๋ ˆ๋ฒจ๋ณ„ ์ง„ํ–‰ ์ƒํ™ฉ์„ ์ถ”์ ํ•˜์„ธ์š”. ์–ธ์ œ๋“ ์ง€ `/self-assessment`๋ฅผ ์‹คํ–‰ํ•˜์—ฌ ์—…๋ฐ์ดํŠธ๋œ ๊ธฐ์ˆ  ํ”„๋กœํ•„์„ ์–ป๊ฑฐ๋‚˜, ๊ฐ ํŠœํ† ๋ฆฌ์–ผ ํ›„์— `/lesson-quiz [lesson]`์„ ์‹คํ–‰ํ•˜์—ฌ ์ดํ•ด๋„๋ฅผ ํ™•์ธํ•˜์„ธ์š”. + +### ๐ŸŸข ๋ ˆ๋ฒจ 1: ์ดˆ๊ธ‰ +- [ ] [01-slash-commands](01-slash-commands/) ์™„๋ฃŒ +- [ ] [02-memory](02-memory/) ์™„๋ฃŒ +- [ ] ์ฒซ ๋ฒˆ์งธ ์‚ฌ์šฉ์ž ์ง€์ • ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด ์ƒ์„ฑ +- [ ] ํ”„๋กœ์ ํŠธ ๋ฉ”๋ชจ๋ฆฌ ์„ค์ • +- [ ] **๋งˆ์ผ์Šคํ†ค 1A ๋‹ฌ์„ฑ** +- [ ] [08-checkpoints](08-checkpoints/) ์™„๋ฃŒ +- [ ] [10-cli](10-cli/) ๊ธฐ๋ณธ ์‚ฌํ•ญ ์™„๋ฃŒ +- [ ] ์ฒดํฌํฌ์ธํŠธ๋ฅผ ์ƒ์„ฑํ•˜๊ณ  ์ด์ „ ์ƒํƒœ๋กœ ๋˜๋Œ๋ฆผ +- [ ] ๋Œ€ํ™”ํ˜• ๋ฐ ์ธ์‡„ ๋ชจ๋“œ๋ฅผ ์‚ฌ์šฉํ•จ +- [ ] **๋งˆ์ผ์Šคํ†ค 1B ๋‹ฌ์„ฑ** + +### ๐Ÿ”ต ๋ ˆ๋ฒจ 2: ์ค‘๊ธ‰ +- [ ] [03-skills](03-skills/) ์™„๋ฃŒ +- [ ] [06-hooks](06-hooks/) ์™„๋ฃŒ +- [ ] ์ฒซ ๋ฒˆ์งธ ๊ธฐ์ˆ  ์„ค์น˜ +- [ ] PreToolUse ํ›… ์„ค์ • +- [ ] **๋งˆ์ผ์Šคํ†ค 2A ๋‹ฌ์„ฑ** +- [ ] [05-mcp](05-mcp/) ์™„๋ฃŒ +- [ ] [04-subagents](04-subagents/) ์™„๋ฃŒ +- [ ] GitHub MCP ์—ฐ๊ฒฐ +- [ ] ์‚ฌ์šฉ์ž ์ง€์ • ์„œ๋ธŒ ์—์ด์ „ํŠธ ์ƒ์„ฑ +- [ ] ์›Œํฌํ”Œ๋กœ์šฐ์— ํ†ตํ•ฉ์„ ๊ฒฐํ•ฉํ•จ +- [ ] **๋งˆ์ผ์Šคํ†ค 2B ๋‹ฌ์„ฑ** + +### ๐Ÿ”ด ๋ ˆ๋ฒจ 3: ๊ณ ๊ธ‰ +- [ ] [09-advanced-features](09-advanced-features/) ์™„๋ฃŒ +- [ ] ๊ณ„ํš ๋ชจ๋“œ๋ฅผ ์„ฑ๊ณต์ ์œผ๋กœ ์‚ฌ์šฉํ•จ +- [ ] ๊ถŒํ•œ ๋ชจ๋“œ(์ž๋™ ํฌํ•จ 6๊ฐ€์ง€ ๋ชจ๋“œ)๋ฅผ ๊ตฌ์„ฑํ•จ +- [ ] ์•ˆ์ „ ๋ถ„๋ฅ˜๊ธฐ๊ฐ€ ์žˆ๋Š” ์ž๋™ ๋ชจ๋“œ๋ฅผ ์‚ฌ์šฉํ•จ +- [ ] ํ™•์žฅ๋œ ์‚ฌ๊ณ  ํ† ๊ธ€์„ ์‚ฌ์šฉํ•จ +- [ ] ์ฑ„๋„ ๋ฐ ์Œ์„ฑ ๋ฐ›์•„์“ฐ๊ธฐ๋ฅผ ํƒ์ƒ‰ํ•จ +- [ ] **๋งˆ์ผ์Šคํ†ค 3A ๋‹ฌ์„ฑ** +- [ ] [07-plugins](07-plugins/) ์™„๋ฃŒ +- [ ] [10-cli](10-cli/) ๊ณ ๊ธ‰ ์‚ฌ์šฉ๋ฒ• ์™„๋ฃŒ +- [ ] ์ธ์‡„ ๋ชจ๋“œ (`claude -p`) CI/CD ์„ค์ • +- [ ] ์ž๋™ํ™”๋ฅผ ์œ„ํ•œ JSON ์ถœ๋ ฅ ์ƒ์„ฑ +- [ ] Claude๋ฅผ CI/CD ํŒŒ์ดํ”„๋ผ์ธ์— ํ†ตํ•ฉํ•จ +- [ ] ํŒ€ ํ”Œ๋Ÿฌ๊ทธ์ธ ์ƒ์„ฑ +- [ ] **๋งˆ์ผ์Šคํ†ค 3B ๋‹ฌ์„ฑ** + +--- + +## ๐Ÿ†˜ ์ผ๋ฐ˜์ ์ธ ํ•™์Šต ๊ณผ์ œ + +### ๊ณผ์ œ 1: "๋™์‹œ์— ๋„ˆ๋ฌด ๋งŽ์€ ๊ฐœ๋…" +**ํ•ด๊ฒฐ์ฑ…**: ํ•œ ๋ฒˆ์— ํ•˜๋‚˜์˜ ๋งˆ์ผ์Šคํ†ค์— ์ง‘์ค‘ํ•˜์„ธ์š”. ๋‹ค์Œ์œผ๋กœ ๋„˜์–ด๊ฐ€๊ธฐ ์ „์— ๋ชจ๋“  ๊ณผ์ œ๋ฅผ ์™„๋ฃŒํ•˜์„ธ์š”. + +### ๊ณผ์ œ 2: "์–ธ์ œ ์–ด๋–ค ๊ธฐ๋Šฅ์„ ์‚ฌ์šฉํ•ด์•ผ ํ• ์ง€ ๋ชจ๋ฅด๊ฒ ์Œ" +**ํ•ด๊ฒฐ์ฑ…**: ๋ฉ”์ธ README์˜ [์‚ฌ์šฉ ์‚ฌ๋ก€ ๋งคํŠธ๋ฆญ์Šค](README.md#use-case-matrix)๋ฅผ ์ฐธ์กฐํ•˜์„ธ์š”. + +### ๊ณผ์ œ 3: "๊ตฌ์„ฑ ์ž‘๋™ ๋ถˆ๋Šฅ" +**ํ•ด๊ฒฐ์ฑ…**: [๋ฌธ์ œ ํ•ด๊ฒฐ](README.md#troubleshooting) ์„น์…˜์„ ํ™•์ธํ•˜๊ณ  ํŒŒ์ผ ์œ„์น˜๋ฅผ ํ™•์ธํ•˜์„ธ์š”. + +### ๊ณผ์ œ 4: "๊ฐœ๋…์ด ์ค‘๋ณต๋˜๋Š” ๊ฒƒ ๊ฐ™์Œ" +**ํ•ด๊ฒฐ์ฑ…**: [๊ธฐ๋Šฅ ๋น„๊ต](README.md#feature-comparison) ํ‘œ๋ฅผ ๊ฒ€ํ† ํ•˜์—ฌ ์ฐจ์ด์ ์„ ์ดํ•ดํ•˜์„ธ์š”. + +### ๊ณผ์ œ 5: "๋ชจ๋“  ๊ฒƒ์„ ๊ธฐ์–ตํ•˜๊ธฐ ์–ด๋ ค์›€" +**ํ•ด๊ฒฐ์ฑ…**: ์ž์‹ ๋งŒ์˜ ์š”์•ฝ๋ณธ์„ ๋งŒ๋“œ์„ธ์š”. ์ฒดํฌํฌ์ธํŠธ๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ์•ˆ์ „ํ•˜๊ฒŒ ์‹คํ—˜ํ•˜์„ธ์š”. + +### ๊ณผ์ œ 6: "๊ฒฝํ—˜์ด ์žˆ์ง€๋งŒ ์–ด๋””์„œ๋ถ€ํ„ฐ ์‹œ์ž‘ํ•ด์•ผ ํ• ์ง€ ๋ชจ๋ฅด๊ฒ ์Œ" +**ํ•ด๊ฒฐ์ฑ…**: ์œ„์— ์žˆ๋Š” [์ˆ˜์ค€ ํ™•์ธํ•˜๊ธฐ](#-์ˆ˜์ค€-ํ™•์ธํ•˜๊ธฐ)๋ฅผ ํ’€์–ด๋ณด์„ธ์š”. ์ž์‹ ์˜ ๋ ˆ๋ฒจ๋กœ ๊ฑด๋„ˆ๋›ฐ๊ณ  ์ „์ œ ์กฐ๊ฑด ํ™•์ธ์„ ์‚ฌ์šฉํ•˜์—ฌ ๋ˆ„๋ฝ๋œ ๋ถ€๋ถ„์„ ํŒŒ์•…ํ•˜์„ธ์š”. + +--- + +## ๐ŸŽฏ ์™„๋ฃŒ ํ›„ ๋‹ค์Œ ๋‹จ๊ณ„๋Š”? + +๋ชจ๋“  ๋งˆ์ผ์Šคํ†ค์„ ์™„๋ฃŒํ•œ ํ›„: + +1. **ํŒ€ ๋ฌธ์„œ ์ƒ์„ฑ** - ํŒ€์˜ Claude Code ์„ค์ • ๋ฌธ์„œํ™” +2. **์‚ฌ์šฉ์ž ์ง€์ • ํ”Œ๋Ÿฌ๊ทธ์ธ ๊ตฌ์ถ•** - ํŒ€์˜ ์›Œํฌํ”Œ๋กœ์šฐ ํŒจํ‚ค์ง• +3. **์›๊ฒฉ ์ œ์–ด ํƒ์ƒ‰** - ์™ธ๋ถ€ ๋„๊ตฌ์—์„œ Claude Code ์„ธ์…˜์„ ํ”„๋กœ๊ทธ๋ž˜๋ฐ ๋ฐฉ์‹์œผ๋กœ ์ œ์–ด +4. **์›น ์„ธ์…˜ ์‹œ๋„** - ๋ธŒ๋ผ์šฐ์ € ๊ธฐ๋ฐ˜ ์ธํ„ฐํŽ˜์ด์Šค๋ฅผ ํ†ตํ•ด Claude Code๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ์›๊ฒฉ ๊ฐœ๋ฐœ +5. **๋ฐ์Šคํฌํ†ฑ ์•ฑ ์‚ฌ์šฉ** - ๋„ค์ดํ‹ฐ๋ธŒ ๋ฐ์Šคํฌํ†ฑ ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜์„ ํ†ตํ•ด Claude Code ๊ธฐ๋Šฅ์— ์•ก์„ธ์Šค +6. **์ž๋™ ๋ชจ๋“œ ์‚ฌ์šฉ** - ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์•ˆ์ „ ๋ถ„๋ฅ˜๊ธฐ๋กœ Claude๊ฐ€ ์ž์œจ์ ์œผ๋กœ ์ž‘์—…ํ•˜๋„๋ก ํ—ˆ์šฉ +7. **์ž๋™ ๋ฉ”๋ชจ๋ฆฌ ํ™œ์šฉ** - Claude๊ฐ€ ์‹œ๊ฐ„์ด ์ง€๋‚จ์— ๋”ฐ๋ผ ํ™˜๊ฒฝ ์„ค์ •์„ ์ž๋™์œผ๋กœ ํ•™์Šตํ•˜๋„๋ก ํ—ˆ์šฉ +8. **์—์ด์ „ํŠธ ํŒ€ ์„ค์ •** - ๋ณต์žกํ•˜๊ณ  ๋‹ค๋ฉด์ ์ธ ์ž‘์—…์—์„œ ์—ฌ๋Ÿฌ ์—์ด์ „ํŠธ ์กฐ์ • +9. **์ฑ„๋„ ์‚ฌ์šฉ** - ๊ตฌ์กฐํ™”๋œ ๋‹ค์ค‘ ์„ธ์…˜ ์›Œํฌํ”Œ๋กœ์šฐ ์ „๋ฐ˜์— ๊ฑธ์ณ ์ž‘์—… ๊ตฌ์„ฑ +10. **์Œ์„ฑ ๋ฐ›์•„์“ฐ๊ธฐ ์‹œ๋„** - Claude Code์™€ ํ•ธ์ฆˆํ”„๋ฆฌ ์ƒํ˜ธ ์ž‘์šฉ์„ ์œ„ํ•ด ์Œ์„ฑ ์ž…๋ ฅ ์‚ฌ์šฉ +11. **์˜ˆ์•ฝ๋œ ์ž‘์—… ์‚ฌ์šฉ** - `/loop` ๋ฐ cron ๋„๊ตฌ๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ๋ฐ˜๋ณต ํ™•์ธ ์ž๋™ํ™” +12. **์˜ˆ์‹œ ๊ธฐ์—ฌ** - ์ปค๋ฎค๋‹ˆํ‹ฐ์™€ ๊ณต์œ  +13. **๋‹ค๋ฅธ ์‚ฌ๋žŒ ๋ฉ˜ํ† ๋ง** - ํŒ€์›์˜ ํ•™์Šต ์ง€์› +14. **์›Œํฌํ”Œ๋กœ์šฐ ์ตœ์ ํ™”** - ์‚ฌ์šฉ๋Ÿ‰์— ๋”ฐ๋ผ ์ง€์†์ ์œผ๋กœ ๊ฐœ์„  +15. **์ตœ์‹  ์ •๋ณด ์œ ์ง€** - Claude Code ๋ฆด๋ฆฌ์Šค ๋ฐ ์ƒˆ๋กœ์šด ๊ธฐ๋Šฅ ํŒ”๋กœ์šฐ + +--- + +## ๐Ÿ“š ์ถ”๊ฐ€ ์ž๋ฃŒ + +### ๊ณต์‹ ๋ฌธ์„œ +- [Claude Code ๋ฌธ์„œ](https://code.claude.com/docs/en/overview) +- [Anthropic ๋ฌธ์„œ](https://docs.anthropic.com) +- [MCP ํ”„๋กœํ† ์ฝœ ์‚ฌ์–‘](https://modelcontextprotocol.io) + +### ๋ธ”๋กœ๊ทธ ๊ฒŒ์‹œ๋ฌผ +- [Claude Code ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด ๋ฐœ๊ฒฌํ•˜๊ธฐ](https://medium.com/@luongnv89/discovering-claude-code-slash-commands-cdc17f0dfb29) + +### ์ปค๋ฎค๋‹ˆํ‹ฐ +- [Anthropic ์ฟก๋ถ](https://github.com/anthropics/anthropic-cookbook) +- [MCP ์„œ๋ฒ„ ์ €์žฅ์†Œ](https://github.com/modelcontextprotocol/servers) + +--- + +## ๐Ÿ’ฌ ํ”ผ๋“œ๋ฐฑ ๋ฐ ์ง€์› + +- **๋ฌธ์ œ ๋ฐœ๊ฒฌ?** ์ €์žฅ์†Œ์— ์ด์Šˆ ์ƒ์„ฑ +- **์ œ์•ˆ ์‚ฌํ•ญ?** ํ’€ ๋ฆฌํ€˜์ŠคํŠธ ์ œ์ถœ +- **๋„์›€์ด ํ•„์š”ํ•˜์„ธ์š”?** ๋ฌธ์„œ๋ฅผ ํ™•์ธํ•˜๊ฑฐ๋‚˜ ์ปค๋ฎค๋‹ˆํ‹ฐ์— ๋ฌธ์˜ + +--- + +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: 2026๋…„ 6์›” 2์ผ +**Claude Code ๋ฒ„์ „**: 2.1.160 +**์ถœ์ฒ˜**: +- https://code.claude.com/docs/en/overview +- https://code.claude.com/docs/en/hooks +- https://github.com/anthropics/claude-code/releases/tag/v2.1.144 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.145 +**ํ˜ธํ™˜ ๋ชจ๋ธ**: Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5 +**์œ ์ง€๋ณด์ˆ˜**: Claude How-To ๊ธฐ์—ฌ์ž +**๋ผ์ด์„ ์Šค**: ๊ต์œก ๋ชฉ์ , ์ž์œ ๋กญ๊ฒŒ ์‚ฌ์šฉ ๋ฐ ๊ฐœ์ž‘ ๊ฐ€๋Šฅ + +--- + +[โ† ๋ฉ”์ธ README๋กœ ๋Œ์•„๊ฐ€๊ธฐ](README.md) diff --git a/ko/QUICK_REFERENCE.md b/ko/QUICK_REFERENCE.md new file mode 100644 index 00000000..5914067b --- /dev/null +++ b/ko/QUICK_REFERENCE.md @@ -0,0 +1,522 @@ + + + Claude How To + + +# Claude Code ์˜ˆ์ œ - ๋น ๋ฅธ ์ฐธ์กฐ ์นด๋“œ + +## ๐Ÿš€ ๋น ๋ฅธ ์„ค์น˜ ๋ช…๋ น + +### Slash Commands +```bash +# ๋ชจ๋‘ ์„ค์น˜ +cp 01-slash-commands/*.md .claude/commands/ + +# ํŠน์ • ๋ช…๋ น๋งŒ ์„ค์น˜ +cp 01-slash-commands/optimize.md .claude/commands/ +``` + +### Memory +```bash +# ํ”„๋กœ์ ํŠธ ๋ฉ”๋ชจ๋ฆฌ +cp 02-memory/project-CLAUDE.md ./CLAUDE.md + +# ๊ฐœ์ธ ๋ฉ”๋ชจ๋ฆฌ +cp 02-memory/personal-CLAUDE.md ~/.claude/CLAUDE.md +``` + +### Skills +```bash +# ๊ฐœ์ธ Skills +cp -r 03-skills/code-review-specialist ~/.claude/skills/ + +# ํ”„๋กœ์ ํŠธ Skills +cp -r 03-skills/code-review-specialist .claude/skills/ +``` + +### Subagents +```bash +# ๋ชจ๋‘ ์„ค์น˜ +cp 04-subagents/*.md .claude/agents/ + +# ํŠน์ • Subagent ์„ค์น˜ +cp 04-subagents/code-reviewer.md .claude/agents/ +``` + +### MCP +```bash +# ์ž๊ฒฉ ์ฆ๋ช… ์„ค์ • +export GITHUB_TOKEN="your_token" +export DATABASE_URL="postgresql://..." + +# ์„ค์ • ์„ค์น˜(ํ”„๋กœ์ ํŠธ ๋ฒ”์œ„) +cp 05-mcp/github-mcp.json .mcp.json + +# ๋˜๋Š” ์‚ฌ์šฉ์ž ๋ฒ”์œ„: ~/.claude.json์— ์ถ”๊ฐ€ +``` + +### Hooks +```bash +# Hook ์„ค์น˜ +mkdir -p ~/.claude/hooks +cp 06-hooks/*.sh ~/.claude/hooks/ +chmod +x ~/.claude/hooks/*.sh + +# ์„ค์ • ํŒŒ์ผ(~/.claude/settings.json)์—์„œ ๊ตฌ์„ฑ +``` + +### Plugins +```bash +# ์˜ˆ์ œ์—์„œ ์„ค์น˜(๊ฒŒ์‹œ๋œ ๊ฒฝ์šฐ) +/plugin install pr-review +/plugin install devops-automation +/plugin install documentation +``` + +### Checkpoints +```bash +# ๋ชจ๋“  ์‚ฌ์šฉ์ž ํ”„๋กฌํ”„ํŠธ๋งˆ๋‹ค Checkpoint๊ฐ€ ์ž๋™ ์ƒ์„ฑ๋ฉ๋‹ˆ๋‹ค. +# ์ด์ „ ์ƒํƒœ๋กœ ๋˜๋Œ๋ฆฌ๋ ค๋ฉด Esc๋ฅผ ๋‘ ๋ฒˆ ๋ˆ„๋ฅด๊ฑฐ๋‚˜ ๋‹ค์Œ์„ ์‚ฌ์šฉํ•˜์„ธ์š”. +/rewind + +# ๊ทธ๋Ÿฐ ๋‹ค์Œ, ์ด ์ค‘์— ํ•˜๋‚˜๋ฅผ ์„ ํƒํ•˜์„ธ์š”: Restore code and conversation, Restore conversation, +# Restore code, Summarize from here, or Never mind +``` + +### ๊ณ ๊ธ‰ ๊ธฐ๋Šฅ +```bash +# ์„ค์ • ํŒŒ์ผ(.claude/settings.json)์—์„œ ๊ตฌ์„ฑ +# 09-advanced-features/config-examples.json ์ฐธ๊ณ  + +# ๊ณ„ํš ๋ชจ๋“œ +/plan Task description + +# ๊ถŒํ•œ ๋ชจ๋“œ(--permission-mode ํ”Œ๋ž˜๊ทธ ์‚ฌ์šฉ) +# default - ์œ„ํ—˜ํ•œ ์ž‘์—…์€ ์Šน์ธ ์š”์ฒญ +# acceptEdits - ํŒŒ์ผ ํŽธ์ง‘์€ ์ž๋™ ์Šน์ธ, ๊ทธ ์™ธ๋Š” ์Šน์ธ ์š”์ฒญ +# plan - ์ฝ๊ธฐ ์ „์šฉ ๋ถ„์„, ์ˆ˜์ • ์—†์Œ +# dontAsk - ์œ„ํ—˜ํ•œ ์ž‘์—…์„ ์ œ์™ธํ•œ ๋ชจ๋“  ์ž‘์—… ์ž๋™ ์Šน์ธ +# auto - ๋ฐฑ๊ทธ๋ผ์šด๋“œ ๋ถ„๋ฅ˜๊ธฐ๊ฐ€ ๊ถŒํ•œ์„ ์ž๋™ ๊ฒฐ์ • +# bypassPermissions - ๋ชจ๋“  ์ž‘์—… ์ž๋™ ์Šน์ธ(--dangerously-skip-permissions ํ•„์š”) + +# ์„ธ์…˜ ๊ด€๋ฆฌ +/resume # ์ด์ „ ๋Œ€ํ™” ์ด์–ด์„œ ์ง„ํ–‰ +/rename "name" # ํ˜„์žฌ ์„ธ์…˜ ์ด๋ฆ„ ๋ณ€๊ฒฝ +/fork # ํ˜„์žฌ ์„ธ์…˜ ๋ถ„๊ธฐ +claude -c # ๊ฐ€์žฅ ์ตœ๊ทผ ๋Œ€ํ™” ์ด์–ด์„œ ์ง„ํ–‰ +claude -r "session" # ์ด๋ฆ„ ๋˜๋Š” ID๋กœ ์„ธ์…˜ ์žฌ๊ฐœ +``` + +--- + +## ๐Ÿ“‹ ๊ธฐ๋Šฅ ์š”์•ฝํ‘œ + +| ๊ธฐ๋Šฅ | ์„ค์น˜ ์œ„์น˜ | ์‚ฌ์šฉ ๋ฐฉ๋ฒ• | +|---------|-------------|-------| +| **Slash Commands (60+)** | `.claude/commands/*.md` | `/command-name` | +| **Memory** | `./CLAUDE.md` | ์ž๋™ ๋กœ๋“œ | +| **Skills** | `.claude/skills/*/SKILL.md` | ์ž๋™ ํ˜ธ์ถœ | +| **Subagents** | `.claude/agents/*.md` | ์ž๋™ ์œ„์ž„ | +| **MCP** | `.mcp.json`(ํ”„๋กœ์ ํŠธ) ๋˜๋Š” `~/.claude.json`(์‚ฌ์šฉ์ž) | `/mcp__server__action` | +| **Hooks (29๊ฐœ ์ด๋ฒคํŠธ)** | `~/.claude/hooks/*.sh` | ์ด๋ฒคํŠธ ๊ธฐ๋ฐ˜ ์‹คํ–‰(5๊ฐ€์ง€ ์œ ํ˜•) | +| **Plugins** | `/plugin install` ์‚ฌ์šฉ | ๋ชจ๋“  ๊ธฐ๋Šฅ์„ ๋ฒˆ๋“ค๋กœ ์ œ๊ณต | +| **Checkpoints** | ๋‚ด์žฅ | `Esc+Esc` ๋˜๋Š” `/rewind` | +| **Planning Mode** | ๋‚ด์žฅ | `/plan ` | +| **Permission Modes (6)** | ๋‚ด์žฅ | `--allowedTools`, `--permission-mode` | +| **Sessions** | ๋‚ด์žฅ | `/session ` | +| **Background Tasks** | ๋‚ด์žฅ | ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์‹คํ–‰ | +| **Remote Control** | ๋‚ด์žฅ | WebSocket API | +| **Web Sessions** | ๋‚ด์žฅ | `claude web` | +| **Git Worktrees** | ๋‚ด์žฅ | `/worktree` | +| **Auto Memory** | ๋‚ด์žฅ | `CLAUDE.md`์— ์ž๋™ ์ €์žฅ | +| **Task List** | ๋‚ด์žฅ | `/task list` | +| **Bundled Skills (10)** | ๋‚ด์žฅ | `/batch`, `/claude-api`, `/code-review`, `/simplify` *(์ •๋ฆฌ ์ „์šฉ ๋ฆฌ๋ทฐ, ๋ฒ„๊ทธ ํƒ์ƒ‰ ์—†์Œ. v2.1.154๋ถ€ํ„ฐ ๋‹ค์‹œ `/code-review`์™€ ๋ณ„๋„ ๊ธฐ๋Šฅ)*, `/debug`, `/fewer-permission-prompts`, `/loop`, `/run` *(v2.1.145+)*, `/run-skill-generator` *(v2.1.145+)*, `/verify` *(v2.1.145+)* | + +--- + +## ๐ŸŽฏ ์ผ๋ฐ˜์ ์ธ ์‚ฌ์šฉ ์‚ฌ๋ก€ + +### ์ฝ”๋“œ ๋ฆฌ๋ทฐ +```bash +# ๋ฐฉ๋ฒ• 1: Slash Command +cp 01-slash-commands/optimize.md .claude/commands/ +# ์‚ฌ์šฉ: /optimize + +# ๋ฐฉ๋ฒ• 2: Subagent +cp 04-subagents/code-reviewer.md .claude/agents/ +# ์‚ฌ์šฉ: ์ž๋™ ์œ„์ž„ + +# ๋ฐฉ๋ฒ• 3: Skill +cp -r 03-skills/code-review-specialist ~/.claude/skills/ +# ์‚ฌ์šฉ: ์ž๋™ ํ˜ธ์ถœ + +# ๋ฐฉ๋ฒ• 4: Plugin (๊ถŒ์žฅ) +/plugin install pr-review +# ์‚ฌ์šฉ: /review-pr +``` + +### ๋ฌธ์„œ ์ž‘์„ฑ +```bash +# Slash Command +cp 01-slash-commands/generate-api-docs.md .claude/commands/ + +# Subagent +cp 04-subagents/documentation-writer.md .claude/agents/ + +# Skill +cp -r 03-skills/doc-generator ~/.claude/skills/ + +# Plugin (์™„์ „ํ•œ ์†”๋ฃจ์…˜) +/plugin install documentation +``` + +### DevOps +```bash +# ์ „์ฒด Plugin ์„ค์น˜ +/plugin install devops-automation + +# ๋ช…๋ น์–ด: /deploy, /rollback, /status, /incident +``` + +### ํŒ€ ํ‘œ์ค€ ๊ด€๋ฆฌ +```bash +# ํ”„๋กœ์ ํŠธ Memory +cp 02-memory/project-CLAUDE.md ./CLAUDE.md + +# ํŒ€์— ๋งž๊ฒŒ ์ˆ˜์ • +vim CLAUDE.md +``` + +### ์ž๋™ํ™” ๋ฐ Hooks +```bash +# Hook ์„ค์น˜(29๊ฐœ ์ด๋ฒคํŠธ, 5๊ฐ€์ง€ ์œ ํ˜•: command, http, mcp_tool, prompt, agent) +mkdir -p ~/.claude/hooks +cp 06-hooks/*.sh ~/.claude/hooks/ +chmod +x ~/.claude/hooks/*.sh + +# ์˜ˆ์‹œ: +# - ์ปค๋ฐ‹ ์ „ ํ…Œ์ŠคํŠธ: pre-commit.sh +# - ์ฝ”๋“œ ์ž๋™ ํฌ๋งท: format-code.sh +# - ๋ณด์•ˆ ๊ฒ€์‚ฌ: security-scan.sh + +# ์™„์ „ ์ž์œจ ์›Œํฌํ”Œ๋กœ๋ฅผ ์œ„ํ•œ Auto Mode +claude --enable-auto-mode -p "Refactor and test the auth module" +# ๋˜๋Š” Shift+Tab์œผ๋กœ ๋ชจ๋“œ๋ฅผ ์ˆœํ™˜ ์ „ํ™˜ +``` + +### ์•ˆ์ „ํ•œ ๋ฆฌํŒฉํ„ฐ๋ง +```bash +# ๋ชจ๋“  ํ”„๋กฌํ”„ํŠธ ์ „์— Checkpoint๊ฐ€ ์ž๋™ ์ƒ์„ฑ๋ฉ๋‹ˆ๋‹ค. +# ๋ฆฌํŒฉํ„ฐ๋ง์„ ์‹œ๋„ํ•ฉ๋‹ˆ๋‹ค. +# ์„ฑ๊ณตํ•˜๋ฉด ๊ณ„์† ์ง„ํ–‰ํ•ฉ๋‹ˆ๋‹ค. +# ์‹คํŒจํ•˜๋ฉด Esc๋ฅผ ๋‘ ๋ฒˆ ๋ˆ„๋ฅด๊ฑฐ๋‚˜ /rewind๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ์ด์ „ ์ƒํƒœ๋กœ ๋˜๋Œ๋ฆฝ๋‹ˆ๋‹ค. +``` + +### ๋ณต์žกํ•œ ๊ตฌํ˜„ +```bash +# ๊ณ„ํš ๋ชจ๋“œ ์‚ฌ์šฉ +/plan Implement user authentication system + +# Claude๊ฐ€ ์ƒ์„ธํ•œ ๊ณ„ํš์„ ์ƒ์„ฑ +# ๊ฒ€ํ†  ํ›„ ์Šน์ธ +# Claude๊ฐ€ ์ฒด๊ณ„์ ์œผ๋กœ ๊ตฌํ˜„ ์ง„ํ–‰ +``` + +### CI/CD ํ†ตํ•ฉ +```bash +# ํ—ค๋“œ๋ฆฌ์Šค ๋ชจ๋“œ์—์„œ ์‹คํ–‰(๋น„๋Œ€ํ™”ํ˜•) +claude -p "Run all tests and generate report" + +# CI์šฉ ๊ถŒํ•œ ๋ชจ๋“œ ์‚ฌ์šฉ +claude -p "Run tests" --permission-mode dontAsk + +# ์™„์ „ ์ž์œจ CI ์ž‘์—…์„ ์œ„ํ•œ Auto Mode ์‚ฌ์šฉ +claude --enable-auto-mode -p "Run tests and fix failures" + +# Hook๋ฅผ ์ด์šฉํ•œ ์ž๋™ํ™” +# 09-advanced-features/README.md ์ฐธ๊ณ  +``` + +### ํ•™์Šต ๋ฐ ์‹คํ—˜ +```bash +# ์•ˆ์ „ํ•œ ๋ถ„์„์„ ์œ„ํ•ด ๊ณ„ํš ๋ชจ๋“œ ์‚ฌ์šฉ +claude --permission-mode plan + +# ์•ˆ์ „ํ•˜๊ฒŒ ์‹คํ—˜ - Checkpoint๋Š” ์ž๋™์œผ๋กœ ์ƒ์„ฑ๋ฉ๋‹ˆ๋‹ค. +# ์ด์ „ ์ƒํƒœ๋กœ ๋˜๋Œ๋ฆฌ๋ ค๋ฉด Esc๋ฅผ ๋‘ ๋ฒˆ ๋ˆ„๋ฅด๊ฑฐ๋‚˜ /rewind๋ฅผ ์‚ฌ์šฉํ•˜์„ธ์š”. +``` + +### Agent Teams +```bash +# Agent Teams ํ™œ์„ฑํ™” +export CLAUDE_AGENT_TEAMS=1 + +# ๋˜๋Š” settings.json์—์„œ ์„ค์ • +{ "agentTeams": { "enabled": true } } + +# ๋‹ค์Œ๊ณผ ๊ฐ™์ด ์‹œ์ž‘: +# "Implement feature X using a team approach" +``` + +### ์˜ˆ์•ฝ ์ž‘์—… +```bash +# 5๋ถ„๋งˆ๋‹ค ๋ช…๋ น ์‹คํ–‰ +/loop 5m /check-status + +# ์ผํšŒ์„ฑ ์•Œ๋ฆผ +/loop 30m "remind me to check the deploy" +``` + +--- + +## ๐Ÿ“ ํŒŒ์ผ ์œ„์น˜ ์ฐธ์กฐ + +``` +ํ”„๋กœ์ ํŠธ/ +โ”œโ”€โ”€ .claude/ +โ”‚ โ”œโ”€โ”€ commands/ # Slash Command ์ €์žฅ ์œ„์น˜ +โ”‚ โ”œโ”€โ”€ agents/ # Subagent ์ €์žฅ ์œ„์น˜ +โ”‚ โ”œโ”€โ”€ skills/ # ํ”„๋กœ์ ํŠธ Skill ์ €์žฅ ์œ„์น˜ +โ”‚ โ””โ”€โ”€ settings.json # ํ”„๋กœ์ ํŠธ ์„ค์ •(Hook ๋“ฑ) +โ”œโ”€โ”€ .mcp.json # MCP ์„ค์ •(ํ”„๋กœ์ ํŠธ ๋ฒ”์œ„) +โ”œโ”€โ”€ CLAUDE.md # ํ”„๋กœ์ ํŠธ Memory +โ””โ”€โ”€ src/ + โ””โ”€โ”€ api/ + โ””โ”€โ”€ CLAUDE.md # ๋””๋ ‰ํ„ฐ๋ฆฌ๋ณ„ Memory + +์‚ฌ์šฉ์ž ํ™ˆ/ +โ”œโ”€โ”€ .claude/ +โ”‚ โ”œโ”€โ”€ commands/ # ๊ฐœ์ธ ๋ช…๋ น์–ด +โ”‚ โ”œโ”€โ”€ agents/ # ๊ฐœ์ธ Agent +โ”‚ โ”œโ”€โ”€ skills/ # ๊ฐœ์ธ Skill +โ”‚ โ”œโ”€โ”€ hooks/ # Hook ์Šคํฌ๋ฆฝํŠธ +โ”‚ โ”œโ”€โ”€ settings.json # ์‚ฌ์šฉ์ž ์„ค์ • +โ”‚ โ”œโ”€โ”€ managed-settings.d/ # ๊ด€๋ฆฌ๋˜๋Š” ์„ค์ •(Enterprise/Organization) +โ”‚ โ””โ”€โ”€ CLAUDE.md # ๊ฐœ์ธ Memory +โ””โ”€โ”€ .claude.json # ๊ฐœ์ธ MCP ์„ค์ •(์‚ฌ์šฉ์ž ๋ฒ”์œ„) +``` + +--- + +## ๐Ÿ” ์˜ˆ์ œ ์ฐพ๊ธฐ + +### ์นดํ…Œ๊ณ ๋ฆฌ๋ณ„ +- **Slash Commands**: `01-slash-commands/` +- **Memory**: `02-memory/` +- **Skills**: `03-skills/` +- **Subagents**: `04-subagents/` +- **MCP**: `05-mcp/` +- **Hooks**: `06-hooks/` +- **Plugins**: `07-plugins/` +- **Checkpoints**: `08-checkpoints/` +- **Advanced Features**: `09-advanced-features/` +- **CLI**: `10-cli/` + +### ์‚ฌ์šฉ ์‚ฌ๋ก€๋ณ„ +- **์„ฑ๋Šฅ ์ตœ์ ํ™”**: `01-slash-commands/optimize.md` +- **๋ณด์•ˆ**: `04-subagents/secure-reviewer.md` +- **ํ…Œ์ŠคํŠธ**: `04-subagents/test-engineer.md` +- **๋ฌธ์„œํ™”**: `03-skills/doc-generator/` +- **DevOps**: `07-plugins/devops-automation/` + +### ๋‚œ์ด๋„๋ณ„ +- **์‰ฌ์›€**: Slash Commands +- **์ค‘๊ฐ„**: Subagents, Memory +- **๊ณ ๊ธ‰**: Skills, Hooks +- **์™„์„ฑํ˜•**: Plugins + +--- + +## ๐ŸŽ“ ํ•™์Šต ๋กœ๋“œ๋งต + +### Day 1 +```bash +# ๊ฐœ์š” ์ฝ๊ธฐ +cat README.md + +# ๋ช…๋ น์–ด ์„ค์น˜ +cp 01-slash-commands/optimize.md .claude/commands/ + +# ์‹คํ–‰ +/optimize +``` + +### Day 2-3 +```bash +# Memory ์„ค์ • +cp 02-memory/project-CLAUDE.md ./CLAUDE.md +vim CLAUDE.md + +# Subagent ์„ค์น˜ +cp 04-subagents/code-reviewer.md .claude/agents/ +``` + +### Day 4-5 +```bash +# MCP ์„ค์ • +export GITHUB_TOKEN="your_token" +cp 05-mcp/github-mcp.json .mcp.json + +# MCP ๋ช…๋ น ์‹คํ–‰ +/mcp__github__list_prs +``` + +### Week 2 +```bash +# Skill ์„ค์น˜ +cp -r 03-skills/code-review-specialist ~/.claude/skills/ + +# ์ž๋™ ํ˜ธ์ถœ ์‚ฌ์šฉ +# ๋‹ค์Œ๊ณผ ๊ฐ™์ด ์ž…๋ ฅํ•˜๊ธฐ๋งŒ ํ•˜๋ฉด ๋ฉ๋‹ˆ๋‹ค: "Review this code for issues" +``` + +### Week 3+ +```bash +# ์ „์ฒด Plugin ์„ค์น˜ +/plugin install pr-review + +# ๋ฒˆ๋“ค ๊ธฐ๋Šฅ ์‚ฌ์šฉ +/review-pr +/check-security +/check-tests +``` + +--- + +## 2026๋…„ 5์›” ์‹ ๊ทœ ๊ธฐ๋Šฅ + +| ๊ธฐ๋Šฅ | ์„ค๋ช… | ์‚ฌ์šฉ ๋ฐฉ๋ฒ• | +|---------|-------------|-------| +| **Auto Mode** | ๋ฐฑ๊ทธ๋ผ์šด๋“œ ๋ถ„๋ฅ˜๊ธฐ๋ฅผ ์ด์šฉํ•œ ์™„์ „ ์ž์œจ ์‹คํ–‰ | `--enable-auto-mode` ํ”Œ๋ž˜๊ทธ, `Shift+Tab`์œผ๋กœ ๋ชจ๋“œ ์ „ํ™˜ | +| **Channels** | Discord ๋ฐ Telegram ํ†ตํ•ฉ | `--channels` ํ”Œ๋ž˜๊ทธ, Discord/Telegram ๋ด‡ | +| **Voice Dictation** | ์Œ์„ฑ์œผ๋กœ ๋ช…๋ น๊ณผ ์ปจํ…์ŠคํŠธ ์ž…๋ ฅ | `/voice` ๋ช…๋ น | +| **Hooks (29๊ฐœ ์ด๋ฒคํŠธ)** | 5๊ฐ€์ง€ ์œ ํ˜•์œผ๋กœ ํ™•์žฅ๋œ Hook ์‹œ์Šคํ…œ | command, http, mcp_tool, prompt, agent Hook ์œ ํ˜• | +| **MCP Elicitation** | MCP ์„œ๋ฒ„๊ฐ€ ์‹คํ–‰ ์ค‘ ์‚ฌ์šฉ์ž ์ž…๋ ฅ์„ ์š”์ฒญ ๊ฐ€๋Šฅ | ์„œ๋ฒ„๊ฐ€ ์ถ”๊ฐ€ ์ •๋ณด๊ฐ€ ํ•„์š”ํ•˜๋ฉด ์ž๋™์œผ๋กœ ํ”„๋กฌํ”„ํŠธ ํ‘œ์‹œ | +| **Plugin LSP** | Plugin์šฉ Language Server Protocol ์ง€์› | `userConfig`, `${CLAUDE_PLUGIN_DATA}` ๋ณ€์ˆ˜ | +| **Remote Control** | WebSocket API๋ฅผ ํ†ตํ•œ Claude Code ์ œ์–ด | ์™ธ๋ถ€ ์—ฐ๋™์„ ์œ„ํ•ด `claude --remote` ์‚ฌ์šฉ | +| **Web Sessions** | ๋ธŒ๋ผ์šฐ์ € ๊ธฐ๋ฐ˜ Claude Code ์ธํ„ฐํŽ˜์ด์Šค | `claude web` ์‹คํ–‰ | +| **Desktop App** | ๋„ค์ดํ‹ฐ๋ธŒ ๋ฐ์Šคํฌํ†ฑ ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜ | `claude.ai/download`์—์„œ ๋‹ค์šด๋กœ๋“œ | +| **Task List** | ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž‘์—… ๊ด€๋ฆฌ | `/task list`, `/task status ` | +| **Auto Memory** | ๋Œ€ํ™” ๋‚ด์šฉ์„ ์ž๋™์œผ๋กœ Memory์— ์ €์žฅ | Claude๊ฐ€ ํ•ต์‹ฌ ์ปจํ…์ŠคํŠธ๋ฅผ `CLAUDE.md`์— ์ž๋™ ์ €์žฅ | +| **Git Worktrees** | ๋ณ‘๋ ฌ ๊ฐœ๋ฐœ์„ ์œ„ํ•œ ๊ฒฉ๋ฆฌ๋œ ์ž‘์—… ๊ณต๊ฐ„ | `/worktree`๋กœ ์ž‘์—… ๊ณต๊ฐ„ ์ƒ์„ฑ | +| **Model Selection** | Sonnet 4.6, Opus 4.8, Haiku 4.5 ๊ฐ„ ๋ชจ๋ธ ์ „ํ™˜ | `/model` โ€” v2.1.153๋ถ€ํ„ฐ ์„ ํƒํ•œ ๋ชจ๋ธ์ด ์ƒˆ ์„ธ์…˜์˜ ๊ธฐ๋ณธ๊ฐ’์œผ๋กœ ์ €์žฅ๋˜๋ฉฐ, `s`๋ฅผ ๋ˆ„๋ฅด๋ฉด ํ˜„์žฌ ์„ธ์…˜์—๋งŒ ์ ์šฉ | +| **Agent Teams** | ์—ฌ๋Ÿฌ Agent๊ฐ€ ํ˜‘์—…ํ•˜์—ฌ ์ž‘์—… ์ˆ˜ํ–‰ | `CLAUDE_AGENT_TEAMS=1` ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋กœ ํ™œ์„ฑํ™” | +| **Dynamic Workflows** *(v2.1.154)* | ๊ฒฐ์ •๋ก ์  ๋ฉ€ํ‹ฐ Agent ์˜ค์ผ€์ŠคํŠธ๋ ˆ์ด์…˜ | `/workflows`๋กœ ์‹คํ–‰ ๋‚ด์—ญ ํ™•์ธ ๋˜๋Š” Claude์—๊ฒŒ ์ƒ์„ฑ ์š”์ฒญ | +| **Scheduled Tasks** | `/loop`๋ฅผ ์ด์šฉํ•œ ๋ฐ˜๋ณต ์ž‘์—… | `/loop 5m /command` ๋˜๋Š” CronCreate ๋„๊ตฌ | +| **Chrome Integration** | ๋ธŒ๋ผ์šฐ์ € ์ž๋™ํ™” | `--chrome` ํ”Œ๋ž˜๊ทธ ๋˜๋Š” `/chrome` ๋ช…๋ น | +| **Keyboard Customization** | ์‚ฌ์šฉ์ž ์ง€์ • ํ‚ค ๋ฐ”์ธ๋”ฉ | `/keybindings` ๋ช…๋ น | +| **/usage-credits** | ์ถ”๊ฐ€ ์‚ฌ์šฉ๋Ÿ‰ ํ•œ๋„ ์„ค์ •(v2.1.144์—์„œ `/extra-usage`์—์„œ ์ด๋ฆ„ ๋ณ€๊ฒฝ, ๊ธฐ์กด ์ด๋ฆ„๋„ ๋ณ„์นญ์œผ๋กœ ์‚ฌ์šฉ ๊ฐ€๋Šฅ) | `/usage-credits` | +| **/run** *(v2.1.145+)* | ๋ณ€๊ฒฝ ์‚ฌํ•ญ์ด ์ ์šฉ๋œ ํ”„๋กœ์ ํŠธ ์•ฑ ์‹คํ–‰ | `/run` | +| **/verify** *(v2.1.145+)* | ๋นŒ๋“œ, ์‹คํ–‰ ๋ฐ ๋™์ž‘ ํ™•์ธ์„ ํ†ตํ•ด ์ˆ˜์ • ์‚ฌํ•ญ ๊ฒ€์ฆ | `/verify` | +| **/run-skill-generator** *(v2.1.145+)* | ํŠน์ • ํ”„๋กœ์ ํŠธ์—์„œ `/run`๊ณผ `/verify`๋ฅผ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ๋„๋ก ์„ค์ • | `/run-skill-generator` | + +--- + +## Tips & Tricks + +### ์‚ฌ์šฉ์ž ์ง€์ • +- ๋จผ์ € ์˜ˆ์ œ๋ฅผ ๊ทธ๋Œ€๋กœ ์‚ฌ์šฉํ•ด ๋ณด์„ธ์š”. +- ํ•„์š”์— ๋งž๊ฒŒ ์ˆ˜์ •ํ•˜์„ธ์š”. +- ํŒ€๊ณผ ๊ณต์œ ํ•˜๊ธฐ ์ „์— ํ…Œ์ŠคํŠธํ•˜์„ธ์š”. +- ์„ค์ • ํŒŒ์ผ์„ ๋ฒ„์ „ ๊ด€๋ฆฌํ•˜์„ธ์š”. + +### ๋ชจ๋ฒ” ์‚ฌ๋ก€ +- ํŒ€ ํ‘œ์ค€์€ Memory๋ฅผ ์‚ฌ์šฉํ•˜์„ธ์š”. +- ์™„์ „ํ•œ ์›Œํฌํ”Œ๋กœ์—๋Š” Plugin์„ ์‚ฌ์šฉํ•˜์„ธ์š”. +- ๋ณต์žกํ•œ ์ž‘์—…์—๋Š” Subagent๋ฅผ ์‚ฌ์šฉํ•˜์„ธ์š”. +- ๋น ๋ฅธ ์ž‘์—…์—๋Š” Slash Command๋ฅผ ์‚ฌ์šฉํ•˜์„ธ์š”. + + +### ๋ฌธ์ œ ํ•ด๊ฒฐ +```bash +# ํŒŒ์ผ ์œ„์น˜ ํ™•์ธ +ls -la .claude/commands/ +ls -la .claude/agents/ + +# YAML ๋ฌธ๋ฒ• ํ™•์ธ +head -20 .claude/agents/code-reviewer.md + +# MCP ์—ฐ๊ฒฐ ํ™•์ธ +echo $GITHUB_TOKEN +``` + +--- + +## ๐Ÿ“Š ๊ธฐ๋Šฅ ๋งคํŠธ๋ฆญ์Šค + +| ํ•„์š” ์‚ฌํ•ญ | ์‚ฌ์šฉํ•  ๊ธฐ๋Šฅ | ์˜ˆ์ œ | +|------|----------|---------| +| ๋น ๋ฅธ ๋‹จ์ถ• ๋ช…๋ น | Slash Command (60+) | `01-slash-commands/optimize.md` | +| ํŒ€ ํ‘œ์ค€ | Memory | `02-memory/project-CLAUDE.md` | +| ์ž๋™ ์›Œํฌํ”Œ๋กœ | Skill | `03-skills/code-review-specialist/` | +| ์ „๋ฌธ ์ž‘์—… | Subagent | `04-subagents/code-reviewer.md` | +| ์™ธ๋ถ€ ๋ฐ์ดํ„ฐ | MCP (+ Elicitation) | `05-mcp/github-mcp.json` | +| ์ด๋ฒคํŠธ ์ž๋™ํ™” | Hook (29๊ฐœ ์ด๋ฒคํŠธ, 5๊ฐ€์ง€ ์œ ํ˜•) | `06-hooks/pre-commit.sh` | +| ์™„์ „ํ•œ ์†”๋ฃจ์…˜ | Plugin (+ LSP ์ง€์›) | `07-plugins/pr-review/` | +| ์•ˆ์ „ํ•œ ์‹คํ—˜ | Checkpoint | `08-checkpoints/checkpoint-examples.md` | +| ์™„์ „ ์ž์œจ ์‹คํ–‰ | Auto Mode | `--enable-auto-mode` ๋˜๋Š” `Shift+Tab` | +| ์ฑ„ํŒ… ํ”Œ๋žซํผ ์—ฐ๋™ | Channels | `--channels` (Discord, Telegram) | +| CI/CD ํŒŒ์ดํ”„๋ผ์ธ | CLI | `10-cli/README.md` | + +--- + +## ๐Ÿ”— ๋น ๋ฅธ ๋งํฌ + +- **๋ฉ”์ธ ๊ฐ€์ด๋“œ**: `README.md` +- **์ „์ฒด ์ƒ‰์ธ**: `INDEX.md` +- **์›๋ณธ ๊ฐ€์ด๋“œ**: `claude_concepts_guide.md` + +--- + +## ๐Ÿ“ž ์ž์ฃผ ๋ฌป๋Š” ์งˆ๋ฌธ + +**Q: ์–ด๋–ค ๊ธฐ๋Šฅ๋ถ€ํ„ฐ ์‚ฌ์šฉํ•ด์•ผ ํ•˜๋‚˜์š”?** +A: ๋จผ์ € Slash Command๋ถ€ํ„ฐ ์‹œ์ž‘ํ•˜๊ณ , ํ•„์š”์— ๋”ฐ๋ผ ๊ธฐ๋Šฅ์„ ์ถ”๊ฐ€ํ•˜์„ธ์š”. + +**Q: ์—ฌ๋Ÿฌ ๊ธฐ๋Šฅ์„ ํ•จ๊ป˜ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ๋‚˜์š”?** +A: ๋„ค! ์„œ๋กœ ํ•จ๊ป˜ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. Memory + Commands + MCP๋ฅผ ์กฐํ•ฉํ•˜๋ฉด ๋”์šฑ ๊ฐ•๋ ฅํ•˜๊ฒŒ ํ™œ์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +**Q: ํŒ€๊ณผ ๊ณต์œ ํ•˜๋ ค๋ฉด ์–ด๋–ป๊ฒŒ ํ•˜๋‚˜์š”?** +A: `.claude/` ๋””๋ ‰ํ„ฐ๋ฆฌ๋ฅผ Git์— ์ปค๋ฐ‹ํ•˜์„ธ์š”. + +**Q: ๋น„๋ฐ€ ์ •๋ณด๋Š” ์–ด๋–ป๊ฒŒ ๊ด€๋ฆฌํ•˜๋‚˜์š”?** +A: ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋ฅผ ์‚ฌ์šฉํ•˜๊ณ , ์ ˆ๋Œ€๋กœ ํ•˜๋“œ์ฝ”๋”ฉํ•˜์ง€ ๋งˆ์„ธ์š”. + +**Q: ์˜ˆ์ œ๋ฅผ ์ˆ˜์ •ํ•ด๋„ ๋˜๋‚˜์š”?** +A: ๋ฌผ๋ก ์ž…๋‹ˆ๋‹ค! ์˜ˆ์ œ๋Š” ์ž์œ ๋กญ๊ฒŒ ์‚ฌ์šฉ์ž ํ™˜๊ฒฝ์— ๋งž๊ฒŒ ์ˆ˜์ •ํ•  ์ˆ˜ ์žˆ๋Š” ํ…œํ”Œ๋ฆฟ์ž…๋‹ˆ๋‹ค. + +--- + +## โœ… ์ฒดํฌ๋ฆฌ์ŠคํŠธ + +์‹œ์ž‘ํ•˜๊ธฐ ์ฒดํฌ๋ฆฌ์ŠคํŠธ: + +- [ ] `README.md` ์ฝ๊ธฐ +- [ ] Slash Command 1๊ฐœ ์„ค์น˜ +- [ ] ๋ช…๋ น ์‹คํ–‰ํ•ด ๋ณด๊ธฐ +- [ ] ํ”„๋กœ์ ํŠธ `CLAUDE.md` ์ƒ์„ฑ +- [ ] Subagent 1๊ฐœ ์„ค์น˜ +- [ ] MCP ์—ฐ๋™ 1๊ฐœ ์„ค์ • +- [ ] Skill 1๊ฐœ ์„ค์น˜ +- [ ] ์™„์ „ํ•œ Plugin ์‚ฌ์šฉํ•ด ๋ณด๊ธฐ +- [ ] ํ•„์š”์— ๋งž๊ฒŒ ์‚ฌ์šฉ์ž ์ง€์ • +- [ ] ํŒ€๊ณผ ๊ณต์œ ํ•˜๊ธฐ + +--- + +**๋น ๋ฅธ ์‹œ์ž‘**: `cat README.md` + +**์ „์ฒด ์ƒ‰์ธ**: `cat INDEX.md` + +**์ด ์ฐธ์กฐ ์นด๋“œ**: ๋น ๋ฅด๊ฒŒ ์ฐธ๊ณ ํ•  ์ˆ˜ ์žˆ๋„๋ก ๊ฐ€๊นŒ์ด์— ๋ณด๊ด€ํ•˜์„ธ์š”! + +--- +**๋งˆ์ง€๋ง‰ ์—…๋ฐ์ดํŠธ**: 2026๋…„ 6์›” 2์ผ +**Claude Code ๋ฒ„์ „**: 2.1.160 +**์ถœ์ฒ˜**: +- https://code.claude.com/docs/en/overview +- https://code.claude.com/docs/en/hooks +- https://code.claude.com/docs/en/commands +- https://github.com/anthropics/claude-code/releases/tag/v2.1.153 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.154 +**ํ˜ธํ™˜ ๋ชจ๋ธ**: Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5 diff --git a/ko/README.md b/ko/README.md new file mode 100644 index 00000000..7970d34f --- /dev/null +++ b/ko/README.md @@ -0,0 +1,889 @@ + + + Claude How To + + +

+ + + +

+ +[![GitHub Stars](https://img.shields.io/github/stars/luongnv89/claude-howto?style=flat&color=gold)](https://github.com/luongnv89/claude-howto/stargazers) +[![GitHub Forks](https://img.shields.io/github/forks/luongnv89/claude-howto?style=flat)](https://github.com/luongnv89/claude-howto/network/members) +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) +[![Version](https://img.shields.io/badge/version-2.1.160-brightgreen)](CHANGELOG.md) +[![Claude Code](https://img.shields.io/badge/Claude_Code-2.1+-purple)](https://code.claude.com) + +# ์ฃผ๋ง ๋™์•ˆ Claude Code ๋งˆ์Šคํ„ฐํ•˜๊ธฐ + +`claude` ๋ช…๋ น์–ด๋ฅผ ์ž…๋ ฅํ•˜๋Š” ๊ฒƒ๋ถ€ํ„ฐ ์—์ด์ „ํŠธ, ํ›…, ์Šคํ‚ฌ ๋ฐ MCP ์„œ๋ฒ„๋ฅผ ๊ตฌ์„ฑํ•˜๋Š” ๋ฐฉ๋ฒ•๊นŒ์ง€ ์‹œ๊ฐ์  ํŠœํ† ๋ฆฌ์–ผ, ์ง์ ‘ ๋ณต์‚ฌํ•˜์—ฌ ๋ถ™์—ฌ๋„ฃ์„ ์ˆ˜ ์žˆ๋Š” ํ…œํ”Œ๋ฆฟ ๋ฐ ๋‹จ๊ณ„๋ณ„ ํ•™์Šต ๊ฒฝ๋กœ๋ฅผ ํ†ตํ•ด ์•Œ์•„๋ณด์„ธ์š”. + +**[15๋ถ„ ์•ˆ์— ์‹œ์ž‘ํ•˜๊ธฐ](#15๋ถ„-์•ˆ์—-์‹œ์ž‘ํ•˜๊ธฐ)** | **[๋‚ด ๋ ˆ๋ฒจ ์ฐพ๊ธฐ](#์–ด๋””์„œ-์‹œ์ž‘ํ•ด์•ผ-ํ• ์ง€-๋ชจ๋ฅด๊ฒ ๋‚˜์š”)** | **[๊ธฐ๋Šฅ ์นดํƒˆ๋กœ๊ทธ ๋ณด๊ธฐ](CATALOG.md)** + +--- + +## ๋ชฉ์ฐจ + +- [๋ฌธ์ œ์ ](#๋ฌธ์ œ์ ) +- [Claude How To๊ฐ€ ํ•ด๊ฒฐํ•˜๋Š” ๋ฐฉ๋ฒ•](#claude-how-to๊ฐ€-ํ•ด๊ฒฐํ•˜๋Š”-๋ฐฉ๋ฒ•) +- [์ž‘๋™ ๋ฐฉ์‹](#์ž‘๋™-๋ฐฉ์‹) +- [์–ด๋””์„œ ์‹œ์ž‘ํ•ด์•ผ ํ• ์ง€ ๋ชจ๋ฅด๊ฒ ๋‚˜์š”?](#์–ด๋””์„œ-์‹œ์ž‘ํ•ด์•ผ-ํ• ์ง€-๋ชจ๋ฅด๊ฒ ๋‚˜์š”) +- [15๋ถ„ ์•ˆ์— ์‹œ์ž‘ํ•˜๊ธฐ](#15๋ถ„-์•ˆ์—-์‹œ์ž‘ํ•˜๊ธฐ) +- [๋ฌด์—‡์„ ๋งŒ๋“ค ์ˆ˜ ์žˆ์„๊นŒ์š”?](#๋ฌด์—‡์„-๋งŒ๋“ค-์ˆ˜-์žˆ์„๊นŒ์š”) +- [์ž์ฃผ ๋ฌป๋Š” ์งˆ๋ฌธ](#faq) +- [๊ธฐ์—ฌํ•˜๊ธฐ](#๊ธฐ์—ฌํ•˜๊ธฐ) +- [๋ผ์ด์„ ์Šค](#๋ผ์ด์„ ์Šค) + +--- + +## ๋ฌธ์ œ์  + +Claude Code๋ฅผ ์„ค์น˜ํ–ˆ์Šต๋‹ˆ๋‹ค. ๋ช‡ ๊ฐœ์˜ ํ”„๋กฌํ”„ํŠธ๋„ ์‹คํ–‰ํ•ด ๋ณด์•˜์Šต๋‹ˆ๋‹ค. ์ด์ œ ๋ฌด์—‡์„ ํ•ด์•ผ ํ• ๊นŒ์š”? + +- **๊ณต์‹ ๋ฌธ์„œ๋Š” ๊ธฐ๋Šฅ์„ ์„ค๋ช…ํ•˜์ง€๋งŒ, ๊ธฐ๋Šฅ๋“ค์„ ์–ด๋–ป๊ฒŒ ์กฐํ•ฉํ•ด์•ผ ํ•˜๋Š”์ง€๋Š” ์•Œ๋ ค์ฃผ์ง€ ์•Š์Šต๋‹ˆ๋‹ค.** ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด๊ฐ€ ์žˆ๋‹ค๋Š” ๊ฒƒ์€ ์•Œ์ง€๋งŒ, ์ด๋ฅผ ํ›…, ๋ฉ”๋ชจ๋ฆฌ, ์„œ๋ธŒ์—์ด์ „ํŠธ์™€ ์—ฐ๊ฒฐํ•˜์—ฌ ์‹ค์ œ๋กœ ์‹œ๊ฐ„์„ ์ ˆ์•ฝํ•ด ์ฃผ๋Š” ์›Œํฌํ”Œ๋กœ๋ฅผ ๋งŒ๋“œ๋Š” ๋ฐฉ๋ฒ•์€ ์•Œ๊ธฐ ์–ด๋ ต์Šต๋‹ˆ๋‹ค. +- **๋ช…ํ™•ํ•œ ํ•™์Šต ๊ฒฝ๋กœ๊ฐ€ ์—†์Šต๋‹ˆ๋‹ค.** MCP๋ฅผ ๋จผ์ € ๋ฐฐ์›Œ์•ผ ํ• ๊นŒ์š”? ํ›…์„ ๋จผ์ € ๋ฐฐ์›Œ์•ผ ํ• ๊นŒ์š”? ์Šคํ‚ฌ์„ ๋จผ์ € ๋ฐฐ์›Œ์•ผ ํ• ๊นŒ์š”, ์„œ๋ธŒ์—์ด์ „ํŠธ๋ฅผ ๋จผ์ € ๋ฐฐ์›Œ์•ผ ํ• ๊นŒ์š”? ๊ฒฐ๊ตญ ๋ชจ๋“  ๋‚ด์šฉ์„ ํ›‘์–ด๋ณด๊ธฐ๋งŒ ํ•˜๊ณ  ์–ด๋Š ๊ฒƒ๋„ ์ œ๋Œ€๋กœ ์ตํžˆ์ง€ ๋ชปํ•˜๊ฒŒ ๋ฉ๋‹ˆ๋‹ค. +- **์˜ˆ์ œ๊ฐ€ ๋„ˆ๋ฌด ๊ธฐ์ดˆ์ ์ž…๋‹ˆ๋‹ค.** "Hello World" ์ˆ˜์ค€์˜ ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด ์˜ˆ์ œ๋Š” ๋ฉ”๋ชจ๋ฆฌ๋ฅผ ํ™œ์šฉํ•˜๊ณ , ์ „๋ฌธ ์—์ด์ „ํŠธ์—๊ฒŒ ์ž‘์—…์„ ์œ„์ž„ํ•˜๋ฉฐ, ๋ณด์•ˆ ์Šค์บ”์„ ์ž๋™์œผ๋กœ ์‹คํ–‰ํ•˜๋Š” ์‹ค์ „ ์ฝ”๋“œ ๋ฆฌ๋ทฐ ํŒŒ์ดํ”„๋ผ์ธ์„ ๊ตฌ์ถ•ํ•˜๋Š” ๋ฐ ๋„์›€์ด ๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. + +Claude Code์˜ ๊ฐ•๋ ฅํ•œ ๊ธฐ๋Šฅ ์ค‘ 90%๋ฅผ ํ™œ์šฉํ•˜์ง€ ๋ชปํ•˜๊ณ  ์žˆ์œผ๋ฉฐ, ๋ฌด์—‡์„ ๋ชจ๋ฅด๋Š”์ง€์กฐ์ฐจ ์•Œ์ง€ ๋ชปํ•˜๋Š” ์ƒํƒœ์ž…๋‹ˆ๋‹ค. + +--- + +## Claude How To๊ฐ€ ํ•ด๊ฒฐํ•˜๋Š” ๋ฐฉ๋ฒ• + +์ด๊ฒƒ์€ ๋‹จ์ˆœํ•œ ๊ธฐ๋Šฅ ๋ ˆํผ๋Ÿฐ์Šค๊ฐ€ ์•„๋‹™๋‹ˆ๋‹ค. ์˜ค๋Š˜ ๋ฐ”๋กœ ํ”„๋กœ์ ํŠธ์— ์ ์šฉํ•  ์ˆ˜ ์žˆ๋Š” ์‹ค์ „ ํ…œํ”Œ๋ฆฟ์„ ํ†ตํ•ด Claude Code์˜ ๋ชจ๋“  ๊ธฐ๋Šฅ์„ ๋ฐฐ์šธ ์ˆ˜ ์žˆ๋„๋ก ์„ค๊ณ„๋œ **๊ตฌ์กฐํ™”๋œ ์‹œ๊ฐ ์ค‘์‹ฌ์˜ ์‹ค์Šต ๊ฐ€์ด๋“œ**์ž…๋‹ˆ๋‹ค. + +| | Official Docs | This Guide | +|--|---------------|------------| +| **Format** | ๊ธฐ๋Šฅ ์ฐธ์กฐ ๋ฌธ์„œ | Mermaid ๋‹ค์ด์–ด๊ทธ๋žจ ๊ธฐ๋ฐ˜ ์‹œ๊ฐ์  ํŠœํ† ๋ฆฌ์–ผ | +| **Depth** | ๊ธฐ๋Šฅ ์„ค๋ช… | ๋‚ด๋ถ€ ๋™์ž‘ ์›๋ฆฌ๊นŒ์ง€ ์„ค๋ช… | +| **Examples** | ๊ธฐ๋ณธ ์˜ˆ์ œ | ์ฆ‰์‹œ ํ™œ์šฉ ๊ฐ€๋Šฅํ•œ ์‹ค์ „ ํ…œํ”Œ๋ฆฟ | +| **Structure** | ๊ธฐ๋Šฅ ์ค‘์‹ฌ ๊ตฌ์„ฑ | ์ดˆ๊ธ‰ โ†’ ๊ณ ๊ธ‰ ๋‹จ๊ณ„๋ณ„ ํ•™์Šต ๊ฒฝ๋กœ | +| **Onboarding** | ์ž์œจ ํ•™์Šต | ์˜ˆ์ƒ ์†Œ์š” ์‹œ๊ฐ„์ด ํฌํ•จ๋œ ๊ฐ€์ด๋“œํ˜• ๋กœ๋“œ๋งต | +| **Self-Assessment** | ์—†์Œ | ํ•™์Šต ๊ณต๋ฐฑ์„ ์ฐพ๊ณ  ๋งž์ถคํ˜• ๊ฒฝ๋กœ๋ฅผ ์ œ์•ˆํ•˜๋Š” ํ€ด์ฆˆ ์ œ๊ณต | + +### ์ œ๊ณต๋˜๋Š” ๋‚ด์šฉ + +- ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด๋ถ€ํ„ฐ ์‚ฌ์šฉ์ž ์ •์˜ ์—์ด์ „ํŠธ ํŒ€๊นŒ์ง€ Claude Code์˜ ๋ชจ๋“  ๊ธฐ๋Šฅ์„ ๋‹ค๋ฃจ๋Š” **10๊ฐœ์˜ ํŠœํ† ๋ฆฌ์–ผ ๋ชจ๋“ˆ** +- ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด, CLAUDE.md ํ…œํ”Œ๋ฆฟ, ํ›… ์Šคํฌ๋ฆฝํŠธ, MCP ์„ค์ •, ์„œ๋ธŒ์—์ด์ „ํŠธ ์ •์˜, ํ”Œ๋Ÿฌ๊ทธ์ธ ๋ฒˆ๋“ค์„ ํฌํ•จํ•œ **์ฆ‰์‹œ ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ๋ณต์‚ฌยท๋ถ™์—ฌ๋„ฃ๊ธฐ ํ…œํ”Œ๋ฆฟ** +- ๊ฐ ๊ธฐ๋Šฅ์˜ ๋‚ด๋ถ€ ๋™์ž‘ ์›๋ฆฌ๋ฅผ ๋ณด์—ฌ์ฃผ๋Š” **Mermaid ๋‹ค์ด์–ด๊ทธ๋žจ** +- ์ดˆ๋ณด์ž์—์„œ ๊ณ ๊ธ‰ ์‚ฌ์šฉ์ž๊นŒ์ง€ ์„ฑ์žฅํ•  ์ˆ˜ ์žˆ๋Š” **11~13์‹œ๊ฐ„ ๋ถ„๋Ÿ‰์˜ ๋‹จ๊ณ„๋ณ„ ํ•™์Šต ๊ฒฝ๋กœ** +- `/self-assessment` ๋˜๋Š” `/lesson-quiz hooks`๋ฅผ ํ†ตํ•ด ํ•™์Šต ๊ณต๋ฐฑ์„ ํŒŒ์•…ํ•  ์ˆ˜ ์žˆ๋Š” **๋‚ด์žฅ ์ž๊ธฐ ํ‰๊ฐ€ ๊ธฐ๋Šฅ** + +**[ํ•™์Šต ๋กœ๋“œ๋งต ์‹œ์ž‘ํ•˜๊ธฐ ->](LEARNING-ROADMAP.md)** + +--- + +## ์ž‘๋™ ๋ฐฉ์‹ + +### 1. ๋‚ด ์ˆ˜์ค€ ์ฐพ๊ธฐ + +[์ž๊ธฐ ํ‰๊ฐ€ ํ€ด์ฆˆ](LEARNING-ROADMAP.md#-find-your-level)๋ฅผ ์ง„ํ–‰ํ•˜๊ฑฐ๋‚˜ Claude Code์—์„œ `/self-assessment`๋ฅผ ์‹คํ–‰ํ•˜์„ธ์š”. ํ˜„์žฌ ์ˆ˜์ค€์— ๋งž๋Š” ๊ฐœ์ธํ™”๋œ ํ•™์Šต ๋กœ๋“œ๋งต์„ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. + +### 2. ๊ฐ€์ด๋“œ ํ•™์Šต ๊ฒฝ๋กœ ๋”ฐ๋ผ๊ฐ€๊ธฐ + +10๊ฐœ์˜ ๋ชจ๋“ˆ์„ ์ˆœ์„œ๋Œ€๋กœ ํ•™์Šตํ•˜์„ธ์š”. ๊ฐ ๋ชจ๋“ˆ์€ ์ด์ „ ๋‚ด์šฉ์„ ๊ธฐ๋ฐ˜์œผ๋กœ ๊ตฌ์„ฑ๋˜์–ด ์žˆ์œผ๋ฉฐ, ํ•™์Šตํ•˜๋ฉด์„œ ํ…œํ”Œ๋ฆฟ์„ ํ”„๋กœ์ ํŠธ์— ๋ฐ”๋กœ ์ ์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +### 3. ๊ธฐ๋Šฅ์„ ์กฐํ•ฉํ•˜์—ฌ ์›Œํฌํ”Œ๋กœ ๋งŒ๋“ค๊ธฐ + +Claude Code์˜ ์ง„์ •ํ•œ ๊ฐ•์ ์€ ๊ธฐ๋Šฅ ์กฐํ•ฉ์— ์žˆ์Šต๋‹ˆ๋‹ค. ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด, ๋ฉ”๋ชจ๋ฆฌ, ์„œ๋ธŒ์—์ด์ „ํŠธ, ํ›…์„ ์—ฐ๊ฒฐํ•˜์—ฌ ์ฝ”๋“œ ๋ฆฌ๋ทฐ, ๋ฐฐํฌ, ๋ฌธ์„œ ์ƒ์„ฑ ๋“ฑ์„ ์ž๋™ํ™”ํ•˜๋Š” ํŒŒ์ดํ”„๋ผ์ธ์„ ๊ตฌ์ถ•ํ•˜๋Š” ๋ฐฉ๋ฒ•์„ ๋ฐฐ์›๋‹ˆ๋‹ค. + +### 4. ์ดํ•ด๋„ ํ™•์ธํ•˜๊ธฐ + +๊ฐ ๋ชจ๋“ˆ์„ ํ•™์Šตํ•œ ํ›„ `/lesson-quiz [topic]`์„ ์‹คํ–‰ํ•˜์„ธ์š”. ๋†“์นœ ๋‚ด์šฉ์„ ์ •ํ™•ํžˆ ์ฐพ์•„๋‚ด์–ด ๋น ๋ฅด๊ฒŒ ๋ณด์™„ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +**[15๋ถ„ ์•ˆ์— ์‹œ์ž‘ํ•˜๊ธฐ](#15๋ถ„-์•ˆ์—-์‹œ์ž‘ํ•˜๊ธฐ)** + +--- + +## ๊ฐœ๋ฐœ์ž๋“ค์ด ์‹ ๋ขฐํ•˜๋Š” ๊ฐ€์ด๋“œ + +- Claude Code๋ฅผ ๋งค์ผ ์‚ฌ์šฉํ•˜๋Š” ๊ฐœ๋ฐœ์ž๋“ค์˜ **GitHub Star** +- ํŒ€ ์›Œํฌํ”Œ๋กœ์— ๋งž๊ฒŒ ๊ฐ€์ด๋“œ๋ฅผ ํ™•์žฅํ•˜๊ธฐ ์œ„ํ•œ **Fork** +- **์ง€์†์ ์ธ ์œ ์ง€๋ณด์ˆ˜** โ€” Claude Code์˜ ๋ชจ๋“  ๋ฆด๋ฆฌ์Šค์— ๋งž์ถฐ ์—…๋ฐ์ดํŠธ (์ตœ์‹  ๋ฒ„์ „: v2.1.160, 2026๋…„ 6์›”) +- **์ปค๋ฎค๋‹ˆํ‹ฐ ์ค‘์‹ฌ ์šด์˜** โ€” ์‹ค์ „ ์„ค์ •์„ ๊ณต์œ ํ•˜๋Š” ๊ฐœ๋ฐœ์ž๋“ค์˜ ๊ธฐ์—ฌ + +[![Star History Chart](https://api.star-history.com/svg?repos=luongnv89/claude-howto&type=Date)](https://star-history.com/#luongnv89/claude-howto&Date) + +--- + +## ์–ด๋””์„œ ์‹œ์ž‘ํ•ด์•ผ ํ• ์ง€ ๋ชจ๋ฅด๊ฒ ๋‚˜์š”? + +์ž๊ธฐ ํ‰๊ฐ€๋ฅผ ์ง„ํ–‰ํ•˜๊ฑฐ๋‚˜ ์ž์‹ ์˜ ์ˆ˜์ค€์— ๋งž๋Š” ๊ฒฝ๋กœ๋ฅผ ์„ ํƒํ•˜์„ธ์š”. + +| Level | You can... | Start here | Time | +|-------|-----------|------------|------| +| **Beginner** | Claude Code๋ฅผ ์‹คํ–‰ํ•˜๊ณ  ๋Œ€ํ™”ํ•  ์ˆ˜ ์žˆ์Œ | [Slash Commands](01-slash-commands/) | ์•ฝ 2.5์‹œ๊ฐ„ | +| **Intermediate** | CLAUDE.md ๋ฐ ์‚ฌ์šฉ์ž ์ •์˜ ๋ช…๋ น์–ด ์‚ฌ์šฉ ๊ฐ€๋Šฅ | [Skills](03-skills/) | ์•ฝ 3.5์‹œ๊ฐ„ | +| **Advanced** | MCP ์„œ๋ฒ„ ๋ฐ ํ›… ๊ตฌ์„ฑ ๊ฐ€๋Šฅ | [Advanced Features](09-advanced-features/) | ์•ฝ 5์‹œ๊ฐ„ | + +**10๊ฐœ ๋ชจ๋“ˆ ์ „์ฒด ํ•™์Šต ๊ฒฝ๋กœ** + +| Order | Module | Level | Time | +|-------|--------|-------|------| +| 1 | [Slash Commands](01-slash-commands/) | Beginner | 30๋ถ„ | +| 2 | [Memory](02-memory/) | Beginner+ | 45๋ถ„ | +| 3 | [Checkpoints](08-checkpoints/) | Intermediate | 45๋ถ„ | +| 4 | [CLI Basics](10-cli/) | Beginner+ | 30๋ถ„ | +| 5 | [Skills](03-skills/) | Intermediate | 1์‹œ๊ฐ„ | +| 6 | [Hooks](06-hooks/) | Intermediate | 1์‹œ๊ฐ„ | +| 7 | [MCP](05-mcp/) | Intermediate+ | 1์‹œ๊ฐ„ | +| 8 | [Subagents](04-subagents/) | Intermediate+ | 1.5์‹œ๊ฐ„ | +| 9 | [Advanced Features](09-advanced-features/) | Advanced | 2~3์‹œ๊ฐ„ | +| 10 | [Plugins](07-plugins/) | Advanced | 2์‹œ๊ฐ„ | + +**[์ „์ฒด ํ•™์Šต ๋กœ๋“œ๋งต ->](LEARNING-ROADMAP.md)** + +--- + +## 15๋ถ„ ์•ˆ์— ์‹œ์ž‘ํ•˜๊ธฐ + +> **์„ค์น˜ ์ฐธ๊ณ  ์‚ฌํ•ญ**: v2.1.113๋ถ€ํ„ฐ Claude Code๋Š” macOS, Linux, Windows์šฉ ๋„ค์ดํ‹ฐ๋ธŒ ๋ฐ”์ด๋„ˆ๋ฆฌ๋กœ ์ œ๊ณต๋ฉ๋‹ˆ๋‹ค. `npm install -g @anthropic-ai/claude-code` ๋ช…๋ น๋„ ๊ณ„์† ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์œผ๋ฉฐ, ์ฒซ ์‹คํ–‰ ์‹œ ๋„ค์ดํ‹ฐ๋ธŒ ๋ฐ”์ด๋„ˆ๋ฆฌ๊ฐ€ ์„ ํƒ์  ์˜์กด์„ฑ์œผ๋กœ ๋‹ค์šด๋กœ๋“œ๋ฉ๋‹ˆ๋‹ค. v2.1.116๋ถ€ํ„ฐ๋Š” ๋‹ค์šด๋กœ๋“œ๊ฐ€ `https://downloads.claude.ai/claude-code-releases`์—์„œ ์ œ๊ณต๋˜๋ฏ€๋กœ, ๊ธฐ์—… ํ™˜๊ฒฝ์˜ ํ”„๋ก์‹œ์—์„œ๋Š” ํ•ด๋‹น ํ˜ธ์ŠคํŠธ๋ฅผ ํ—ˆ์šฉ ๋ชฉ๋ก์— ์ถ”๊ฐ€ํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. + +```bash +# 1. Clone the guide +git clone https://github.com/luongnv89/claude-howto.git +cd claude-howto + +# 2. Copy your first slash command +mkdir -p /path/to/your-project/.claude/commands +cp 01-slash-commands/optimize.md /path/to/your-project/.claude/commands/ + +# 3. Try it โ€” in Claude Code, type: +# /optimize + +# 4. Ready for more? Set up project memory: +cp 02-memory/project-CLAUDE.md /path/to/your-project/CLAUDE.md + +# 5. Install a skill: +cp -r 03-skills/code-review-specialist ~/.claude/skills/ +``` + +์ „์ฒด ์„ค์ •์„ ์›ํ•˜์‹œ๋‚˜์š”? ๋‹ค์Œ์€ **1์‹œ๊ฐ„ ํ•ต์‹ฌ ์„ค์ • ๊ฐ€์ด๋“œ**์ž…๋‹ˆ๋‹ค. + +```bash +# Slash commands (15 min) +cp 01-slash-commands/*.md .claude/commands/ + +# Project memory (15 min) +cp 02-memory/project-CLAUDE.md ./CLAUDE.md + +# Install a skill (15 min) +cp -r 03-skills/code-review-specialist ~/.claude/skills/ + +# Weekend goal: add hooks, subagents, MCP, and plugins +# Follow the learning path for guided setup +``` + +**[์ „์ฒด ์„ค์น˜ ๊ฐ€์ด๋“œ ๋ณด๊ธฐ](#15๋ถ„-์•ˆ์—-์‹œ์ž‘ํ•˜๊ธฐ)** + +--- + +## ๋ฌด์—‡์„ ๋งŒ๋“ค ์ˆ˜ ์žˆ์„๊นŒ์š”? + +| Use Case | Features You'll Combine | +|----------|------------------------| +| **์ž๋™ํ™”๋œ ์ฝ”๋“œ ๋ฆฌ๋ทฐ** | Slash Commands + Subagents + Memory + MCP | +| **ํŒ€ ์˜จ๋ณด๋”ฉ ์‹œ์Šคํ…œ** | Memory + Slash Commands + Plugins | +| **CI/CD ์ž๋™ํ™”** | CLI Reference + Hooks + Background Tasks | +| **๋ฌธ์„œ ์ž๋™ ์ƒ์„ฑ** | Skills + Subagents + Plugins | +| **๋ณด์•ˆ ๊ฐ์‚ฌ** | Subagents + Skills + Hooks (์ฝ๊ธฐ ์ „์šฉ ๋ชจ๋“œ) | +| **DevOps ํŒŒ์ดํ”„๋ผ์ธ** | Plugins + MCP + Hooks + Background Tasks | +| **๋Œ€๊ทœ๋ชจ ๋ฆฌํŒฉํ„ฐ๋ง** | Checkpoints + Planning Mode + Hooks | + +--- + +## FAQ + +**๋ฌด๋ฃŒ์ธ๊ฐ€์š”?** +๋„ค. MIT ๋ผ์ด์„ ์Šค๋กœ ์ œ๊ณต๋˜๋ฉฐ ์˜๊ตฌ์ ์œผ๋กœ ๋ฌด๋ฃŒ์ž…๋‹ˆ๋‹ค. ๋ผ์ด์„ ์Šค ๊ณ ์ง€๋งŒ ์œ ์ง€ํ•˜๋ฉด ๊ฐœ์ธ ํ”„๋กœ์ ํŠธ, ํšŒ์‚ฌ ์—…๋ฌด, ํŒ€ ํ”„๋กœ์ ํŠธ ๋“ฑ ์–ด๋””์—์„œ๋‚˜ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +**๊ณ„์† ์œ ์ง€๋ณด์ˆ˜๋˜๋‚˜์š”?** +๋„ค. Claude Code์˜ ๋ชจ๋“  ๋ฆด๋ฆฌ์Šค์— ๋งž์ถฐ ์ง€์†์ ์œผ๋กœ ์—…๋ฐ์ดํŠธ๋ฉ๋‹ˆ๋‹ค. ํ˜„์žฌ ๋ฒ„์ „์€ v2.1.160(2026๋…„ 6์›”)์ด๋ฉฐ Claude Code 2.1+์™€ ํ˜ธํ™˜๋ฉ๋‹ˆ๋‹ค. + +**๊ณต์‹ ๋ฌธ์„œ์™€ ์–ด๋–ค ์ฐจ์ด๊ฐ€ ์žˆ๋‚˜์š”?** +๊ณต์‹ ๋ฌธ์„œ๋Š” ๊ธฐ๋Šฅ ์ฐธ์กฐ์šฉ ๋ฌธ์„œ์ž…๋‹ˆ๋‹ค. ์ด ๊ฐ€์ด๋“œ๋Š” ๋‹ค์ด์–ด๊ทธ๋žจ, ์‹ค์ „ ํ…œํ”Œ๋ฆฟ, ๋‹จ๊ณ„๋ณ„ ํ•™์Šต ๊ฒฝ๋กœ๋ฅผ ์ œ๊ณตํ•˜๋Š” ํŠœํ† ๋ฆฌ์–ผ์ž…๋‹ˆ๋‹ค. ๋‘ ์ž๋ฃŒ๋Š” ์ƒํ˜ธ ๋ณด์™„์ ์ž…๋‹ˆ๋‹ค. ํ•™์Šต์€ ์ด ๊ฐ€์ด๋“œ๋กœ ์‹œ์ž‘ํ•˜๊ณ , ์„ธ๋ถ€ ์‚ฌํ•ญ์ด ํ•„์š”ํ•  ๋•Œ ๊ณต์‹ ๋ฌธ์„œ๋ฅผ ์ฐธ๊ณ ํ•˜์„ธ์š”. + +**์ „์ฒด ํ•™์Šต์—๋Š” ์–ผ๋งˆ๋‚˜ ๊ฑธ๋ฆฌ๋‚˜์š”?** +์ „์ฒด ๊ฒฝ๋กœ๋ฅผ ์™„๋ฃŒํ•˜๋Š” ๋ฐ ์•ฝ 11~13์‹œ๊ฐ„์ด ์†Œ์š”๋ฉ๋‹ˆ๋‹ค. ํ•˜์ง€๋งŒ ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด ํ…œํ”Œ๋ฆฟ ํ•˜๋‚˜๋ฅผ ๋ณต์‚ฌํ•ด ์‹คํ–‰ํ•˜๋Š” ๊ฒƒ๋งŒ์œผ๋กœ๋„ 15๋ถ„ ์•ˆ์— ์ฆ‰๊ฐ์ ์ธ ํšจ๊ณผ๋ฅผ ์–ป์„ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +**Claude Sonnet / Haiku / Opus์—์„œ๋„ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ๋‚˜์š”?** +๋„ค. ๋ชจ๋“  ํ…œํ”Œ๋ฆฟ์€ Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5์—์„œ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +**๊ธฐ์—ฌํ•  ์ˆ˜ ์žˆ๋‚˜์š”?** +๋ฌผ๋ก ์ž…๋‹ˆ๋‹ค. ์ž์„ธํ•œ ๋‚ด์šฉ์€ [CONTRIBUTING.md](CONTRIBUTING.md)๋ฅผ ์ฐธ๊ณ ํ•˜์„ธ์š”. ์ƒˆ๋กœ์šด ์˜ˆ์ œ, ๋ฒ„๊ทธ ์ˆ˜์ •, ๋ฌธ์„œ ๊ฐœ์„ , ์ปค๋ฎค๋‹ˆํ‹ฐ ํ…œํ”Œ๋ฆฟ ๊ธฐ์—ฌ๋ฅผ ํ™˜์˜ํ•ฉ๋‹ˆ๋‹ค. + +**์˜คํ”„๋ผ์ธ์—์„œ๋„ ์ฝ์„ ์ˆ˜ ์žˆ๋‚˜์š”?** +๋„ค. ๋ชจ๋“  ์ฝ˜ํ…์ธ ์™€ ๋ Œ๋”๋ง๋œ ๋‹ค์ด์–ด๊ทธ๋žจ์ด ํฌํ•จ๋œ EPUB ์ „์ž์ฑ…์„ ์ƒ์„ฑํ•˜๋ ค๋ฉด ๋‹ค์Œ ๋ช…๋ น์„ ์‹คํ–‰ํ•˜์„ธ์š”. + +--- + +## ์ง€๊ธˆ ๋ฐ”๋กœ Claude Code ๋งˆ์Šคํ„ฐํ•˜๊ธฐ + +์ด๋ฏธ Claude Code๋Š” ์„ค์น˜๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. ์ด์ œ ์ƒ์‚ฐ์„ฑ์„ 10๋ฐฐ ํ–ฅ์ƒ์‹œํ‚ค๋Š” ๋ฐ ํ•„์š”ํ•œ ๊ฒƒ์€ Claude Code๋ฅผ ์ œ๋Œ€๋กœ ํ™œ์šฉํ•˜๋Š” ๋ฐฉ๋ฒ•์„ ์ตํžˆ๋Š” ๊ฒƒ๋ฟ์ž…๋‹ˆ๋‹ค. ์ด ๊ฐ€์ด๋“œ๋Š” ๊ทธ ๋ชฉํ‘œ์— ๋„๋‹ฌํ•  ์ˆ˜ ์žˆ๋„๋ก ์ฒด๊ณ„์ ์ธ ํ•™์Šต ๊ฒฝ๋กœ, ์‹œ๊ฐ์  ์„ค๋ช…, ๊ทธ๋ฆฌ๊ณ  ๋ฐ”๋กœ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ๋Š” ํ…œํ”Œ๋ฆฟ์„ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. + +MIT ๋ผ์ด์„ ์Šค๋กœ ์ œ๊ณต๋ฉ๋‹ˆ๋‹ค. ์˜๊ตฌ์ ์œผ๋กœ ๋ฌด๋ฃŒ์ž…๋‹ˆ๋‹ค. ์ž์œ ๋กญ๊ฒŒ Cloneํ•˜๊ณ , Forkํ•˜๊ณ , ์›ํ•˜๋Š” ๋ฐฉ์‹์œผ๋กœ ํ™œ์šฉํ•˜์„ธ์š”. + +**[ํ•™์Šต ๋กœ๋“œ๋งต ์‹œ์ž‘ํ•˜๊ธฐ ->](LEARNING-ROADMAP.md)** | **[๊ธฐ๋Šฅ ์นดํƒˆ๋กœ๊ทธ ๋ณด๊ธฐ](CATALOG.md)** | **[15๋ถ„ ์•ˆ์— ์‹œ์ž‘ํ•˜๊ธฐ](#15๋ถ„-์•ˆ์—-์‹œ์ž‘ํ•˜๊ธฐ)** + +--- + +
+๋น ๋ฅธ ํƒ์ƒ‰ โ€” ์ „์ฒด ๊ธฐ๋Šฅ ๋ชฉ๋ก + +| ๊ธฐ๋Šฅ | ์„ค๋ช… | ํด๋” | +|---------|-------------|--------| +| **๊ธฐ๋Šฅ ์นดํƒˆ๋กœ๊ทธ** | ์„ค์น˜ ๋ช…๋ น์–ด๋ฅผ ํฌํ•จํ•œ ์ „์ฒด ์ฐธ์กฐ ๋ฌธ์„œ | [CATALOG.md](CATALOG.md) | +| **์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด** | ์‚ฌ์šฉ์ž๊ฐ€ ์ง์ ‘ ์‹คํ–‰ํ•˜๋Š” ๋‹จ์ถ• ๋ช…๋ น์–ด | [01-slash-commands/](01-slash-commands/) | +| **๋ฉ”๋ชจ๋ฆฌ** | ์ง€์†์ ์œผ๋กœ ์œ ์ง€๋˜๋Š” ์ปจํ…์ŠคํŠธ | [02-memory/](02-memory/) | +| **์Šคํ‚ฌ** | ์žฌ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ๊ธฐ๋Šฅ ๋ชจ์Œ | [03-skills/](03-skills/) | +| **์„œ๋ธŒ์—์ด์ „ํŠธ** | ํŠน์ • ์—ญํ• ์— ํŠนํ™”๋œ AI ๋„์šฐ๋ฏธ | [04-subagents/](04-subagents/) | +| **MCP ํ”„๋กœํ† ์ฝœ** | ์™ธ๋ถ€ ๋„๊ตฌ ์ ‘๊ทผ ๊ธฐ๋Šฅ | [05-mcp/](05-mcp/) | +| **ํ›…** | ์ด๋ฒคํŠธ ๊ธฐ๋ฐ˜ ์ž๋™ํ™” | [06-hooks/](06-hooks/) | +| **ํ”Œ๋Ÿฌ๊ทธ์ธ** | ๊ธฐ๋Šฅ ํŒจํ‚ค์ง€ ๋ฒˆ๋“ค | [07-plugins/](07-plugins/) | +| **์ฒดํฌํฌ์ธํŠธ** | ์„ธ์…˜ ์Šค๋ƒ…์ƒท ๋ฐ ๋˜๋Œ๋ฆฌ๊ธฐ | [08-checkpoints/](08-checkpoints/) | +| **๊ณ ๊ธ‰ ๊ธฐ๋Šฅ** | ๊ณ„ํš ๋ชจ๋“œ, ์‹ฌ์ธต ์‚ฌ๊ณ , ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž‘์—… | [09-advanced-features/](09-advanced-features/) | +| **CLI ์ฐธ์กฐ** | ๋ช…๋ น์–ด, ํ”Œ๋ž˜๊ทธ ๋ฐ ์˜ต์…˜ | [10-cli/](10-cli/) | +| **๋ธ”๋กœ๊ทธ ๊ฒŒ์‹œ๋ฌผ** | ์‹ค์ „ ํ™œ์šฉ ์‚ฌ๋ก€ | [Blog Posts](https://medium.com/@luongnv89) | + + +
+ +
+๊ธฐ๋Šฅ ๋น„๊ต + +| ๊ธฐ๋Šฅ | ์‹คํ–‰ ๋ฐฉ์‹ | ์ง€์†์„ฑ | ์ ํ•ฉํ•œ ์šฉ๋„ | +|---------|-----------|------------|----------| +| **์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด** | ์ˆ˜๋™ ์‹คํ–‰ (`/cmd`) | ํ˜„์žฌ ์„ธ์…˜๋งŒ | ๋น ๋ฅธ ๋‹จ์ถ• ์ž‘์—… | +| **๋ฉ”๋ชจ๋ฆฌ** | ์ž๋™ ๋กœ๋“œ | ์„ธ์…˜ ๊ฐ„ ์œ ์ง€ | ์žฅ๊ธฐ ํ•™์Šต ๋ฐ ์ปจํ…์ŠคํŠธ | +| **์Šคํ‚ฌ** | ์ž๋™ ํ˜ธ์ถœ | ํŒŒ์ผ ์‹œ์Šคํ…œ ๊ธฐ๋ฐ˜ | ์ž๋™ํ™”๋œ ์›Œํฌํ”Œ๋กœ | +| **์„œ๋ธŒ์—์ด์ „ํŠธ** | ์ž๋™ ์œ„์ž„ | ๊ฒฉ๋ฆฌ๋œ ์ปจํ…์ŠคํŠธ | ์ž‘์—… ๋ถ„์‚ฐ | +| **MCP ํ”„๋กœํ† ์ฝœ** | ์ž๋™ ์กฐํšŒ | ์‹ค์‹œ๊ฐ„ | ๋ผ์ด๋ธŒ ๋ฐ์ดํ„ฐ ์ ‘๊ทผ | +| **ํ›…** | ์ด๋ฒคํŠธ ๋ฐœ์ƒ ์‹œ ์‹คํ–‰ | ์„ค์ • ๊ธฐ๋ฐ˜ | ์ž๋™ํ™” ๋ฐ ๊ฒ€์ฆ | +| **ํ”Œ๋Ÿฌ๊ทธ์ธ** | ๋‹จ์ผ ๋ช…๋ น์–ด | ์ „์ฒด ๊ธฐ๋Šฅ ํฌํ•จ | ์™„์„ฑํ˜• ์†”๋ฃจ์…˜ | +| **์ฒดํฌํฌ์ธํŠธ** | ์ˆ˜๋™/์ž๋™ | ์„ธ์…˜ ๊ธฐ๋ฐ˜ | ์•ˆ์ „ํ•œ ์‹คํ—˜ | +| **๊ณ„ํš ๋ชจ๋“œ** | ์ˆ˜๋™/์ž๋™ | ๊ณ„ํš ๋‹จ๊ณ„ ์œ ์ง€ | ๋ณต์žกํ•œ ๊ตฌํ˜„ ์ž‘์—… | +| **๋ฐฑ๊ทธ๋ผ์šด๋“œ ์ž‘์—…** | ์ˆ˜๋™ ์‹คํ–‰ | ์ž‘์—… ์ˆ˜ํ–‰ ๊ธฐ๊ฐ„ | ์žฅ์‹œ๊ฐ„ ์‹คํ–‰ ์ž‘์—… | +| **CLI ์ฐธ์กฐ** | ํ„ฐ๋ฏธ๋„ ๋ช…๋ น์–ด | ์„ธ์…˜/์Šคํฌ๋ฆฝํŠธ | ์ž๋™ํ™” ๋ฐ ์Šคํฌ๋ฆฝํŒ… | + +
+ +
+์„ค์น˜ ๋น ๋ฅธ ์ฐธ์กฐ + +```bash +# Slash Commands +cp 01-slash-commands/*.md .claude/commands/ + +# Memory +cp 02-memory/project-CLAUDE.md ./CLAUDE.md + +# Skills +cp -r 03-skills/code-review-specialist ~/.claude/skills/ + +# Subagents +cp 04-subagents/*.md .claude/agents/ + +# MCP +export GITHUB_TOKEN="token" +claude mcp add github -- npx -y @modelcontextprotocol/server-github + +# Hooks +mkdir -p ~/.claude/hooks +cp 06-hooks/*.sh ~/.claude/hooks/ +chmod +x ~/.claude/hooks/*.sh + +# Plugins +/plugin install pr-review + +# Checkpoints (auto-enabled, configure in settings) +# See 08-checkpoints/README.md + +# Advanced Features (configure in settings) +# See 09-advanced-features/config-examples.json + +# CLI Reference (no installation needed) +# See 10-cli/README.md for usage examples +``` + +
+ +
+01. ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด + +**์œ„์น˜**: [01-slash-commands/](01-slash-commands/) + +**์„ค๋ช…**: Markdown ํŒŒ์ผ๋กœ ์ €์žฅ๋˜๋Š” ์‚ฌ์šฉ์ž ์‹คํ–‰ํ˜• ๋‹จ์ถ• ๋ช…๋ น์–ด + +**์˜ˆ์‹œ**: +- `optimize.md` - ์ฝ”๋“œ ์ตœ์ ํ™” ๋ถ„์„ +- `pr.md` - Pull Request ์ค€๋น„ +- `generate-api-docs.md` - API ๋ฌธ์„œ ์ƒ์„ฑ๊ธฐ + +**์„ค์น˜**: +```bash +cp 01-slash-commands/*.md /path/to/project/.claude/commands/ +``` + +**์‚ฌ์šฉ ๋ฐฉ๋ฒ•**: +``` +/optimize +/pr +/generate-api-docs +``` + +**์ž์„ธํžˆ ๋ณด๊ธฐ**: [Discovering Claude Code Slash Commands](https://medium.com/@luongnv89/discovering-claude-code-slash-commands-cdc17f0dfb29) + +
+ +
+02. ๋ฉ”๋ชจ๋ฆฌ + +**์œ„์น˜**: [02-memory/](02-memory/) + +**์„ค๋ช…**: ์„ธ์…˜ ๊ฐ„์—๋„ ์œ ์ง€๋˜๋Š” ์ง€์†ํ˜• ์ปจํ…์ŠคํŠธ + +**์˜ˆ์‹œ**: +- `project-CLAUDE.md` - ํŒ€ ๊ณตํ†ต ํ”„๋กœ์ ํŠธ ๊ทœ์น™ +- `directory-api-CLAUDE.md` - ๋””๋ ‰ํ„ฐ๋ฆฌ๋ณ„ ๊ทœ์น™ +- `personal-CLAUDE.md` - ๊ฐœ์ธ ์„ค์ • ๋ฐ ์„ ํ˜ธ๋„ + +**์„ค์น˜**: +```bash +# Project memory +cp 02-memory/project-CLAUDE.md /path/to/project/CLAUDE.md + +# Directory memory +cp 02-memory/directory-api-CLAUDE.md /path/to/project/src/api/CLAUDE.md + +# Personal memory +cp 02-memory/personal-CLAUDE.md ~/.claude/CLAUDE.md +``` + +**์‚ฌ์šฉ ๋ฐฉ๋ฒ•**: Claude๊ฐ€ ์ž๋™์œผ๋กœ ๋กœ๋“œํ•ฉ๋‹ˆ๋‹ค. + +
+ +
+03. ์Šคํ‚ฌ + +**์œ„์น˜**: [03-skills/](03-skills/) + +**์„ค๋ช…**: ์ง€์นจ๊ณผ ์Šคํฌ๋ฆฝํŠธ๋ฅผ ํฌํ•จํ•˜๋Š” ์žฌ์‚ฌ์šฉ ๊ฐ€๋Šฅํ•œ ์ž๋™ ์‹คํ–‰ ๊ธฐ๋Šฅ + +**์˜ˆ์‹œ**: +- `code-review-specialist/` - ์Šคํฌ๋ฆฝํŠธ๋ฅผ ํฌํ•จํ•œ ์ข…ํ•ฉ ์ฝ”๋“œ ๋ฆฌ๋ทฐ +- `brand-voice/` - ๋ธŒ๋žœ๋“œ ํ†ค์•ค๋งค๋„ˆ ์ผ๊ด€์„ฑ ๊ฒ€์‚ฌ๊ธฐ +- `doc-generator/` - API ๋ฌธ์„œ ์ƒ์„ฑ๊ธฐ + +**์„ค์น˜**: +```bash +# Personal skills +cp -r 03-skills/code-review-specialist ~/.claude/skills/ + +# Project skills +cp -r 03-skills/code-review-specialist /path/to/project/.claude/skills/ +``` + +**์‚ฌ์šฉ ๋ฐฉ๋ฒ•**: ๊ด€๋ จ ์ž‘์—… ์‹œ ์ž๋™์œผ๋กœ ํ˜ธ์ถœ๋ฉ๋‹ˆ๋‹ค. + +
+ +
+04. ์„œ๋ธŒ์—์ด์ „ํŠธ + +**์œ„์น˜**: [04-subagents/](04-subagents/) + +**์„ค๋ช…**: ๋…๋ฆฝ๋œ ์ปจํ…์ŠคํŠธ์™€ ์‚ฌ์šฉ์ž ์ •์˜ ํ”„๋กฌํ”„ํŠธ๋ฅผ ๊ฐ€์ง„ ์ „๋ฌธํ™”๋œ AI ๋„์šฐ๋ฏธ + +**์˜ˆ์‹œ**: +- `code-reviewer.md` - ์ข…ํ•ฉ ์ฝ”๋“œ ํ’ˆ์งˆ ๋ถ„์„ +- `test-engineer.md` - ํ…Œ์ŠคํŠธ ์ „๋žต ๋ฐ ์ปค๋ฒ„๋ฆฌ์ง€ ๋ถ„์„ +- `documentation-writer.md` - ๊ธฐ์ˆ  ๋ฌธ์„œ ์ž‘์„ฑ +- `secure-reviewer.md` - ๋ณด์•ˆ ์ค‘์‹ฌ ๋ฆฌ๋ทฐ (์ฝ๊ธฐ ์ „์šฉ) +- `implementation-agent.md` - ์ „์ฒด ๊ธฐ๋Šฅ ๊ตฌํ˜„ ๋‹ด๋‹น + +**์„ค์น˜**: +```bash +cp 04-subagents/*.md /path/to/project/.claude/agents/ +``` + +**์‚ฌ์šฉ ๋ฐฉ๋ฒ•**: ๋ฉ”์ธ ์—์ด์ „ํŠธ๊ฐ€ ํ•„์š”์— ๋”ฐ๋ผ ์ž๋™์œผ๋กœ ์ž‘์—…์„ ์œ„์ž„ํ•ฉ๋‹ˆ๋‹ค. + +
+ +
+05. MCP ํ”„๋กœํ† ์ฝœ + +**์œ„์น˜**: [05-mcp/](05-mcp/) + +**์„ค๋ช…**: ์™ธ๋ถ€ ๋„๊ตฌ์™€ API์— ์ ‘๊ทผํ•˜๊ธฐ ์œ„ํ•œ Model Context Protocol + +**์˜ˆ์‹œ**: +- `github-mcp.json` - GitHub ์—ฐ๋™ +- `database-mcp.json` - ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ์กฐํšŒ +- `filesystem-mcp.json` - ํŒŒ์ผ ์ž‘์—… +- `multi-mcp.json` - ๋‹ค์ค‘ MCP ์„œ๋ฒ„ ๊ตฌ์„ฑ + +**์„ค์น˜**: + +```bash +# Set environment variables +export GITHUB_TOKEN="your_token" +export DATABASE_URL="postgresql://..." + +# Add MCP server via CLI +claude mcp add github -- npx -y @modelcontextprotocol/server-github + +# Or add to project .mcp.json manually (see 05-mcp/ for examples) +``` + +**์‚ฌ์šฉ ๋ฐฉ๋ฒ•**: MCP ์„œ๋ฒ„ ์„ค์ •์ด ์™„๋ฃŒ๋˜๋ฉด Claude๊ฐ€ ํ•ด๋‹น ๋„๊ตฌ๋ฅผ ์ž๋™์œผ๋กœ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +
+ +
+06. ํ›…(Hooks) + +**์œ„์น˜**: [06-hooks/](06-hooks/) + +**์„ค๋ช…**: Claude Code ์ด๋ฒคํŠธ์— ๋ฐ˜์‘ํ•˜์—ฌ ์ž๋™ ์‹คํ–‰๋˜๋Š” ์ด๋ฒคํŠธ ๊ธฐ๋ฐ˜ ์…ธ ๋ช…๋ น์–ด + +**์˜ˆ์‹œ**: +- `format-code.sh` - ์ฝ”๋“œ ์ž‘์„ฑ ์ „ ์ž๋™ ํฌ๋งทํŒ… +- `pre-commit.sh` - ์ปค๋ฐ‹ ์ „ ํ…Œ์ŠคํŠธ ์‹คํ–‰ +- `security-scan.sh` - ๋ณด์•ˆ ์ทจ์•ฝ์  ๊ฒ€์‚ฌ +- `log-bash.sh` - ๋ชจ๋“  Bash ๋ช…๋ น ๊ธฐ๋ก +- `validate-prompt.sh` - ์‚ฌ์šฉ์ž ํ”„๋กฌํ”„ํŠธ ๊ฒ€์ฆ +- `notify-team.sh` - ์ด๋ฒคํŠธ ๋ฐœ์ƒ ์‹œ ์•Œ๋ฆผ ์ „์†ก + +**์„ค์น˜**: +```bash +mkdir -p ~/.claude/hooks +cp 06-hooks/*.sh ~/.claude/hooks/ +chmod +x ~/.claude/hooks/*.sh +``` + +`~/.claude/settings.json`์—์„œ ํ›…์„ ์„ค์ •ํ•ฉ๋‹ˆ๋‹ค. +```json +{ + "hooks": { + "PreToolUse": [{ + "matcher": "Write", + "hooks": ["~/.claude/hooks/format-code.sh"] + }], + "PostToolUse": [{ + "matcher": "Write", + "hooks": ["~/.claude/hooks/security-scan.sh"] + }] + } +} +``` + +**์‚ฌ์šฉ ๋ฐฉ๋ฒ•**: ์ด๋ฒคํŠธ๊ฐ€ ๋ฐœ์ƒํ•˜๋ฉด ํ›…์ด ์ž๋™์œผ๋กœ ์‹คํ–‰๋ฉ๋‹ˆ๋‹ค. + +**ํ›… ์ข…๋ฅ˜** (5๊ฐœ ์œ ํ˜•, ์ด 29๊ฐœ ์ด๋ฒคํŠธ) + +- **๋„๊ตฌ ํ›…(Tool Hooks)**: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` +- **์„ธ์…˜ ํ›…(Session Hooks)**: `SessionStart`, `SessionEnd`, `Stop`, `StopFailure`, `SubagentStart`, `SubagentStop` +- **์ž‘์—… ํ›…(Task Hooks)**: `UserPromptSubmit`, `TaskCompleted`, `TaskCreated`, `TeammateIdle` +- **๋ผ์ดํ”„์‚ฌ์ดํด ํ›…(Lifecycle Hooks)**: `ConfigChange`, `CwdChanged`, `FileChanged`, `PreCompact`, `PostCompact`, `WorktreeCreate`, `WorktreeRemove`, `Notification`, `InstructionsLoaded`, `Elicitation`, `ElicitationResult` + +
+ +
+07. ํ”Œ๋Ÿฌ๊ทธ์ธ + +**์œ„์น˜**: [07-plugins/](07-plugins/) + +**์„ค๋ช…**: ๋ช…๋ น์–ด, ์—์ด์ „ํŠธ, MCP, ํ›…์„ ํ•˜๋‚˜๋กœ ๋ฌถ์€ ๊ธฐ๋Šฅ ํŒจํ‚ค์ง€ + +**์˜ˆ์‹œ**: +- `pr-review/` - ์™„์ „ํ•œ PR ๋ฆฌ๋ทฐ ์›Œํฌํ”Œ๋กœ +- `devops-automation/` - ๋ฐฐํฌ ๋ฐ ๋ชจ๋‹ˆํ„ฐ๋ง ์ž๋™ํ™” +- `documentation/` - ๋ฌธ์„œ ์ƒ์„ฑ ์ž๋™ํ™” + +**์„ค์น˜**: +```bash +/plugin install pr-review +/plugin install devops-automation +/plugin install documentation +``` + +**์‚ฌ์šฉ ๋ฐฉ๋ฒ•**: ํ”Œ๋Ÿฌ๊ทธ์ธ์— ํฌํ•จ๋œ ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด์™€ ๊ธฐ๋Šฅ์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + +
+ +
+08. ์ฒดํฌํฌ์ธํŠธ์™€ ๋˜๋Œ๋ฆฌ๊ธฐ(Rewind) + +**์œ„์น˜**: [08-checkpoints/](08-checkpoints/) + +**์„ค๋ช…**: ๋Œ€ํ™” ์ƒํƒœ๋ฅผ ์ €์žฅํ•˜๊ณ  ์ด์ „ ์‹œ์ ์œผ๋กœ ๋˜๋Œ์•„๊ฐ€ ๋‹ค๋ฅธ ์ ‘๊ทผ ๋ฐฉ์‹์„ ์‹œ๋„ํ•  ์ˆ˜ ์žˆ๋Š” ๊ธฐ๋Šฅ + +**ํ•ต์‹ฌ ๊ฐœ๋…**: + +- **Checkpoint**: ๋Œ€ํ™” ์ƒํƒœ ์Šค๋ƒ…์ƒท +- **Rewind**: ์ด์ „ ์ฒดํฌํฌ์ธํŠธ๋กœ ๋ณต์› +- **Branch Point**: ๋™์ผํ•œ ์ฒดํฌํฌ์ธํŠธ์—์„œ ์—ฌ๋Ÿฌ ์ ‘๊ทผ ๋ฐฉ์‹ ํƒ์ƒ‰ + +**์‚ฌ์šฉ ๋ฐฉ๋ฒ•**: +``` +# Checkpoints are created automatically with every user prompt +# To rewind, press Esc twice or use: +/rewind + +# Then choose from five options: +# 1. Restore code and conversation +# 2. Restore conversation +# 3. Restore code +# 4. Summarize from here +# 5. Never mind +``` + +**ํ™œ์šฉ ์‚ฌ๋ก€**: +- ์—ฌ๋Ÿฌ ๊ตฌํ˜„ ๋ฐฉ์‹์„ ์‹œ๋„ํ•  ๋•Œ +- ์‹ค์ˆ˜๋ฅผ ๋ณต๊ตฌํ•  ๋•Œ +- ์•ˆ์ „ํ•˜๊ฒŒ ์‹คํ—˜ํ•  ๋•Œ +- ๋Œ€์•ˆ ์†”๋ฃจ์…˜์„ ๋น„๊ตํ•  ๋•Œ +- ๋‹ค์–‘ํ•œ ์„ค๊ณ„๋ฅผ A/B ํ…Œ์ŠคํŠธํ•  ๋•Œ + +
+ +
+09. ๊ณ ๊ธ‰ ๊ธฐ๋Šฅ + +**์œ„์น˜**: [09-advanced-features/](09-advanced-features/) + +**์„ค๋ช…**: ๋ณต์žกํ•œ ์›Œํฌํ”Œ๋กœ์™€ ์ž๋™ํ™”๋ฅผ ์œ„ํ•œ ๊ณ ๊ธ‰ ๊ธฐ๋Šฅ ๋ชจ์Œ + +**ํฌํ•จ ๊ธฐ๋Šฅ**: + +- **Planning Mode** โ€” ์ฝ”๋”ฉ ์ „์— ์ƒ์„ธํ•œ ๊ตฌํ˜„ ๊ณ„ํš ์ˆ˜๋ฆฝ +- **Extended Thinking** โ€” ๋ณต์žกํ•œ ๋ฌธ์ œ ํ•ด๊ฒฐ์„ ์œ„ํ•œ ์‹ฌ์ธต ์ถ”๋ก  (`Alt+T` / `Option+T`๋กœ ์ „ํ™˜) +- **Background Tasks** โ€” ์ž‘์—…์„ ์ฐจ๋‹จํ•˜์ง€ ์•Š๊ณ  ์žฅ์‹œ๊ฐ„ ์ž‘์—… ์‹คํ–‰ +- **Permission Modes** โ€” `default`, `acceptEdits`, `plan`, `dontAsk`, `bypassPermissions` +- **Headless Mode** โ€” CI/CD ํ™˜๊ฒฝ์—์„œ Claude Code ์‹คํ–‰: `claude -p "Run tests and generate report"` +- **Session Management** โ€” `/resume`, `/rename`, `/fork`, `claude -c`, `claude -r` +- **Configuration** โ€” `~/.claude/settings.json`์„ ํ†ตํ•œ ๋™์ž‘ ์‚ฌ์šฉ์ž ์ •์˜ + +์ „์ฒด ์„ค์ • ์˜ˆ์‹œ๋Š” [config-examples.json](09-advanced-features/config-examples.json)์„ ์ฐธ๊ณ ํ•˜์„ธ์š”. + +
+ +
+10. CLI ์ฐธ์กฐ + +**์œ„์น˜**: [10-cli/](10-cli/) + +**์„ค๋ช…**: Claude Code ๋ช…๋ น์ค„ ์ธํ„ฐํŽ˜์ด์Šค ์ „์ฒด ์ฐธ์กฐ ๋ฌธ์„œ + +**๋น ๋ฅธ ์˜ˆ์‹œ**: + +```bash +# Interactive mode +claude "explain this project" + +# Print mode (non-interactive) +claude -p "review this code" + +# Process file content +cat error.log | claude -p "explain this error" + +# JSON output for scripts +claude -p --output-format json "list functions" + +# Resume session +claude -r "feature-auth" "continue implementation" +``` + +**ํ™œ์šฉ ์‚ฌ๋ก€**: CI/CD ํŒŒ์ดํ”„๋ผ์ธ ์—ฐ๋™, ์Šคํฌ๋ฆฝํŠธ ์ž๋™ํ™”, ๋ฐฐ์น˜ ์ฒ˜๋ฆฌ, ๋‹ค์ค‘ ์„ธ์…˜ ์›Œํฌํ”Œ๋กœ, ์‚ฌ์šฉ์ž ์ •์˜ ์—์ด์ „ํŠธ ๊ตฌ์„ฑ + +
+ +
+์˜ˆ์ œ ์›Œํฌํ”Œ๋กœ + +### ์ „์ฒด ์ฝ”๋“œ ๋ฆฌ๋ทฐ ์›Œํฌํ”Œ๋กœ + +```markdown +# Uses: Slash Commands + Subagents + Memory + MCP + +User: /review-pr + +Claude: +1. Loads project memory (coding standards) +2. Fetches PR via GitHub MCP +3. Delegates to code-reviewer subagent +4. Delegates to test-engineer subagent +5. Synthesizes findings +6. Provides comprehensive review +``` + +### ์ž๋™ ๋ฌธ์„œ ์ƒ์„ฑ + +```markdown +# Uses: Skills + Subagents + Memory + +User: "Generate API documentation for the auth module" + +Claude: +1. Loads project memory (doc standards) +2. Detects doc generation request +3. Auto-invokes doc-generator skill +4. Delegates to api-documenter subagent +5. Creates comprehensive docs with examples +``` + +### DevOps ๋ฐฐํฌ + +```markdown +# Uses: Plugins + MCP + Hooks + +User: /deploy production + +Claude: +1. Runs pre-deploy hook (validates environment) +2. Delegates to deployment-specialist subagent +3. Executes deployment via Kubernetes MCP +4. Monitors progress +5. Runs post-deploy hook (health checks) +6. Reports status +``` + +
+ +
+๋””๋ ‰ํ„ฐ๋ฆฌ ๊ตฌ์กฐ + +``` +โ”œโ”€โ”€ 01-slash-commands/ +โ”‚ โ”œโ”€โ”€ optimize.md +โ”‚ โ”œโ”€โ”€ pr.md +โ”‚ โ”œโ”€โ”€ generate-api-docs.md +โ”‚ โ””โ”€โ”€ README.md +โ”œโ”€โ”€ 02-memory/ +โ”‚ โ”œโ”€โ”€ project-CLAUDE.md +โ”‚ โ”œโ”€โ”€ directory-api-CLAUDE.md +โ”‚ โ”œโ”€โ”€ personal-CLAUDE.md +โ”‚ โ””โ”€โ”€ README.md +โ”œโ”€โ”€ 03-skills/ +โ”‚ โ”œโ”€โ”€ code-review-specialist/ +โ”‚ โ”‚ โ”œโ”€โ”€ SKILL.md +โ”‚ โ”‚ โ”œโ”€โ”€ scripts/ +โ”‚ โ”‚ โ””โ”€โ”€ templates/ +โ”‚ โ”œโ”€โ”€ brand-voice/ +โ”‚ โ”‚ โ”œโ”€โ”€ SKILL.md +โ”‚ โ”‚ โ””โ”€โ”€ templates/ +โ”‚ โ”œโ”€โ”€ doc-generator/ +โ”‚ โ”‚ โ”œโ”€โ”€ SKILL.md +โ”‚ โ”‚ โ””โ”€โ”€ generate-docs.py +โ”‚ โ””โ”€โ”€ README.md +โ”œโ”€โ”€ 04-subagents/ +โ”‚ โ”œโ”€โ”€ code-reviewer.md +โ”‚ โ”œโ”€โ”€ test-engineer.md +โ”‚ โ”œโ”€โ”€ documentation-writer.md +โ”‚ โ”œโ”€โ”€ secure-reviewer.md +โ”‚ โ”œโ”€โ”€ implementation-agent.md +โ”‚ โ””โ”€โ”€ README.md +โ”œโ”€โ”€ 05-mcp/ +โ”‚ โ”œโ”€โ”€ github-mcp.json +โ”‚ โ”œโ”€โ”€ database-mcp.json +โ”‚ โ”œโ”€โ”€ filesystem-mcp.json +โ”‚ โ”œโ”€โ”€ multi-mcp.json +โ”‚ โ””โ”€โ”€ README.md +โ”œโ”€โ”€ 06-hooks/ +โ”‚ โ”œโ”€โ”€ format-code.sh +โ”‚ โ”œโ”€โ”€ pre-commit.sh +โ”‚ โ”œโ”€โ”€ security-scan.sh +โ”‚ โ”œโ”€โ”€ log-bash.sh +โ”‚ โ”œโ”€โ”€ validate-prompt.sh +โ”‚ โ”œโ”€โ”€ notify-team.sh +โ”‚ โ””โ”€โ”€ README.md +โ”œโ”€โ”€ 07-plugins/ +โ”‚ โ”œโ”€โ”€ pr-review/ +โ”‚ โ”œโ”€โ”€ devops-automation/ +โ”‚ โ”œโ”€โ”€ documentation/ +โ”‚ โ””โ”€โ”€ README.md +โ”œโ”€โ”€ 08-checkpoints/ +โ”‚ โ”œโ”€โ”€ checkpoint-examples.md +โ”‚ โ””โ”€โ”€ README.md +โ”œโ”€โ”€ 09-advanced-features/ +โ”‚ โ”œโ”€โ”€ config-examples.json +โ”‚ โ”œโ”€โ”€ planning-mode-examples.md +โ”‚ โ””โ”€โ”€ README.md +โ”œโ”€โ”€ 10-cli/ +โ”‚ โ””โ”€โ”€ README.md +โ””โ”€โ”€ README.md (this file) +``` + +
+ +
+๋ชจ๋ฒ” ์‚ฌ๋ก€ + +### ๊ถŒ์žฅ ์‚ฌํ•ญ +- ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด๋ถ€ํ„ฐ ๊ฐ„๋‹จํ•˜๊ฒŒ ์‹œ์ž‘ํ•˜์„ธ์š”. +- ๊ธฐ๋Šฅ์€ ์ ์ง„์ ์œผ๋กœ ์ถ”๊ฐ€ํ•˜์„ธ์š”. +- ํŒ€ ํ‘œ์ค€์€ ๋ฉ”๋ชจ๋ฆฌ๋ฅผ ํ™œ์šฉํ•ด ๊ด€๋ฆฌํ•˜์„ธ์š”. +- ์„ค์ •์€ ๋จผ์ € ๋กœ์ปฌ ํ™˜๊ฒฝ์—์„œ ํ…Œ์ŠคํŠธํ•˜์„ธ์š”. +- ์‚ฌ์šฉ์ž ์ •์˜ ๊ตฌํ˜„์€ ๋ฌธ์„œํ™”ํ•˜์„ธ์š”. +- ํ”„๋กœ์ ํŠธ ์„ค์ • ํŒŒ์ผ์€ ๋ฒ„์ „ ๊ด€๋ฆฌ์— ํฌํ•จํ•˜์„ธ์š”. +- ํ”Œ๋Ÿฌ๊ทธ์ธ์„ ํŒ€๊ณผ ๊ณต์œ ํ•˜์„ธ์š”. + +### ํ”ผํ•ด์•ผ ํ•  ์‚ฌํ•ญ +- ์ค‘๋ณต ๊ธฐ๋Šฅ์„ ๋งŒ๋“ค์ง€ ๋งˆ์„ธ์š”. +- ์ž๊ฒฉ ์ฆ๋ช…์„ ์ฝ”๋“œ์— ํ•˜๋“œ์ฝ”๋”ฉํ•˜์ง€ ๋งˆ์„ธ์š”. +- ๋ฌธ์„œ ์ž‘์„ฑ์„ ์ƒ๋žตํ•˜์ง€ ๋งˆ์„ธ์š”. +- ๋‹จ์ˆœํ•œ ์ž‘์—…์„ ์ง€๋‚˜์น˜๊ฒŒ ๋ณต์žกํ•˜๊ฒŒ ๋งŒ๋“ค์ง€ ๋งˆ์„ธ์š”. +- ๋ณด์•ˆ ๋ชจ๋ฒ” ์‚ฌ๋ก€๋ฅผ ๋ฌด์‹œํ•˜์ง€ ๋งˆ์„ธ์š”. +- ๋ฏผ๊ฐํ•œ ๋ฐ์ดํ„ฐ๋ฅผ ์ €์žฅ์†Œ์— ์ปค๋ฐ‹ํ•˜์ง€ ๋งˆ์„ธ์š”. + +
+ +
+๋ฌธ์ œ ํ•ด๊ฒฐ + +### ๊ธฐ๋Šฅ์ด ๋กœ๋“œ๋˜์ง€ ์•Š๋Š” ๊ฒฝ์šฐ +1. ํŒŒ์ผ ์œ„์น˜์™€ ์ด๋ฆ„์„ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. +2. YAML Frontmatter ๋ฌธ๋ฒ•์„ ๊ฒ€์ฆํ•ฉ๋‹ˆ๋‹ค. +3. ํŒŒ์ผ ๊ถŒํ•œ์„ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. +4. Claude Code ๋ฒ„์ „ ํ˜ธํ™˜์„ฑ์„ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. + +### MCP ์—ฐ๊ฒฐ ์‹คํŒจ +1. ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋ฅผ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. +2. MCP ์„œ๋ฒ„ ์„ค์น˜ ์ƒํƒœ๋ฅผ ์ ๊ฒ€ํ•ฉ๋‹ˆ๋‹ค. +3. ์ธ์ฆ ์ •๋ณด๋ฅผ ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. +4. ๋„คํŠธ์›Œํฌ ์—ฐ๊ฒฐ ์ƒํƒœ๋ฅผ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. + +### ์„œ๋ธŒ์—์ด์ „ํŠธ๊ฐ€ ์ž‘์—…์„ ์œ„์ž„๋ฐ›์ง€ ๋ชปํ•˜๋Š” ๊ฒฝ์šฐ +1. ๋„๊ตฌ ๊ถŒํ•œ์„ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. +2. ์—์ด์ „ํŠธ ์„ค๋ช…์ด ๋ช…ํ™•ํ•œ์ง€ ๊ฒ€ํ† ํ•ฉ๋‹ˆ๋‹ค. +3. ์ž‘์—… ๋ณต์žก๋„๋ฅผ ๊ฒ€ํ† ํ•ฉ๋‹ˆ๋‹ค. +4. ์—์ด์ „ํŠธ๋ฅผ ๋…๋ฆฝ์ ์œผ๋กœ ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. + +
+ +
+ํ…Œ์ŠคํŠธ + +์ด ํ”„๋กœ์ ํŠธ๋Š” ํฌ๊ด„์ ์ธ ์ž๋™ํ™” ํ…Œ์ŠคํŠธ๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. + +- **๋‹จ์œ„ ํ…Œ์ŠคํŠธ**: pytest ๊ธฐ๋ฐ˜ Python ํ…Œ์ŠคํŠธ (Python 3.10, 3.11, 3.12) +- **์ฝ”๋“œ ํ’ˆ์งˆ**: Ruff๋ฅผ ์ด์šฉํ•œ ๋ฆฐํŠธ ๋ฐ ํฌ๋งท ๊ฒ€์‚ฌ +- **๋ณด์•ˆ**: Bandit ๊ธฐ๋ฐ˜ ์ทจ์•ฝ์  ์Šค์บ” +- **ํƒ€์ž… ๊ฒ€์‚ฌ**: mypy๋ฅผ ํ™œ์šฉํ•œ ์ •์  ํƒ€์ž… ๋ถ„์„ +- **๋นŒ๋“œ ๊ฒ€์ฆ**: EPUB ์ƒ์„ฑ ํ…Œ์ŠคํŠธ +- **์ปค๋ฒ„๋ฆฌ์ง€ ์ถ”์ **: Codecov ์—ฐ๋™ + +```bash +# Install development dependencies +uv pip install -r requirements-dev.txt + +# Run all unit tests +pytest scripts/tests/ -v + +# Run tests with coverage report +pytest scripts/tests/ -v --cov=scripts --cov-report=html + +# Run code quality checks +ruff check scripts/ +ruff format --check scripts/ + +# Run security scan +bandit -c pyproject.toml -r scripts/ --exclude scripts/tests/ + +# Run type checking +mypy scripts/ --ignore-missing-imports +``` + +๋ชจ๋“  ํ…Œ์ŠคํŠธ๋Š” `main` ๋˜๋Š” `develop` ๋ธŒ๋žœ์น˜๋กœ์˜ Push, ๊ทธ๋ฆฌ๊ณ  `main` ๋ธŒ๋žœ์น˜ ๋Œ€์ƒ PR ์ƒ์„ฑ ์‹œ ์ž๋™ ์‹คํ–‰๋ฉ๋‹ˆ๋‹ค. ์ž์„ธํ•œ ๋‚ด์šฉ์€ [TESTING.md](.github/TESTING.md)๋ฅผ ์ฐธ๊ณ ํ•˜์„ธ์š”. + +
+ +
+EPUB ์ƒ์„ฑ + +์ด ๊ฐ€์ด๋“œ๋ฅผ ์˜คํ”„๋ผ์ธ์œผ๋กœ ์ฝ๊ณ  ์‹ถ์œผ์‹ ๊ฐ€์š”? EPUB ์ „์ž์ฑ…์„ ์ƒ์„ฑํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +```bash +uv run scripts/build_epub.py +``` + +์ด ๋ช…๋ น์€ ๋ Œ๋”๋ง๋œ Mermaid ๋‹ค์ด์–ด๊ทธ๋žจ์„ ํฌํ•จํ•œ ๋ชจ๋“  ์ฝ˜ํ…์ธ ๊ฐ€ ๋‹ด๊ธด `claude-howto-guide.epub` ํŒŒ์ผ์„ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. + +์ถ”๊ฐ€ ์˜ต์…˜์€ [scripts/README.md](scripts/README.md)๋ฅผ ์ฐธ๊ณ ํ•˜์„ธ์š”. + +
+ +
+๊ธฐ์—ฌํ•˜๊ธฐ + +๋ฌธ์ œ๋ฅผ ๋ฐœ๊ฒฌํ–ˆ๊ฑฐ๋‚˜ ์˜ˆ์ œ๋ฅผ ์ถ”๊ฐ€ํ•˜๊ณ  ์‹ถ์œผ์‹ ๊ฐ€์š”? ์—ฌ๋Ÿฌ๋ถ„์˜ ๊ธฐ์—ฌ๋ฅผ ํ™˜์˜ํ•ฉ๋‹ˆ๋‹ค. + +**๋‹ค์Œ ๋‚ด์šฉ์„ ํฌํ•จํ•œ ์ž์„ธํ•œ ๊ฐ€์ด๋“œ๋Š” [CONTRIBUTING.md](CONTRIBUTING.md)๋ฅผ ์ฐธ๊ณ ํ•˜์„ธ์š”.** +- ๊ธฐ์—ฌ ์œ ํ˜•(์˜ˆ์ œ, ๋ฌธ์„œ, ๊ธฐ๋Šฅ, ๋ฒ„๊ทธ ์ˆ˜์ •, ํ”ผ๋“œ๋ฐฑ) +- ๊ฐœ๋ฐœ ํ™˜๊ฒฝ ์„ค์ • ๋ฐฉ๋ฒ• +- ๋””๋ ‰ํ„ฐ๋ฆฌ ๊ตฌ์กฐ ๋ฐ ์ฝ˜ํ…์ธ  ์ถ”๊ฐ€ ๋ฐฉ๋ฒ• +- ์ž‘์„ฑ ๊ฐ€์ด๋“œ๋ผ์ธ ๋ฐ ๋ชจ๋ฒ” ์‚ฌ๋ก€ +- ์ปค๋ฐ‹ ๋ฐ PR ์ ˆ์ฐจ + +**์ปค๋ฎค๋‹ˆํ‹ฐ ๊ทœ์น™** +- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) - ์ปค๋ฎค๋‹ˆํ‹ฐ ๊ตฌ์„ฑ์› ๊ฐ„์˜ ํ–‰๋™ ๊ธฐ์ค€ +- [SECURITY.md](SECURITY.md) - ๋ณด์•ˆ ์ •์ฑ… ๋ฐ ์ทจ์•ฝ์  ์‹ ๊ณ  ์ ˆ์ฐจ + + +### ๋ณด์•ˆ ์ด์Šˆ ์‹ ๊ณ  + +๋ณด์•ˆ ์ทจ์•ฝ์ ์„ ๋ฐœ๊ฒฌํ•œ ๊ฒฝ์šฐ ์ฑ…์ž„๊ฐ ์žˆ๊ฒŒ ์‹ ๊ณ ํ•ด ์ฃผ์„ธ์š”. + +1. **GitHub Private Vulnerability Reporting ์‚ฌ์šฉ**: https://github.com/luongnv89/claude-howto/security/advisories +2. ๋˜๋Š” [.github/SECURITY_REPORTING.md](.github/SECURITY_REPORTING.md)๋ฅผ ์ฐธ๊ณ ํ•˜์—ฌ ์ƒ์„ธ ์ ˆ์ฐจ๋ฅผ ํ™•์ธํ•˜์„ธ์š”. +3. ๋ณด์•ˆ ์ทจ์•ฝ์ ์— ๋Œ€ํ•ด์„œ๋Š” **๊ณต๊ฐœ ์ด์Šˆ๋ฅผ ์ƒ์„ฑํ•˜์ง€ ๋งˆ์„ธ์š”.** + +๋น ๋ฅธ ์‹œ์ž‘ ์ ˆ์ฐจ: +1. ์ €์žฅ์†Œ๋ฅผ Fork ๋ฐ Cloneํ•ฉ๋‹ˆ๋‹ค. +2. ์„ค๋ช…์ด ๋ช…ํ™•ํ•œ ๋ธŒ๋žœ์น˜๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค (`add/feature-name`, `fix/bug`, `docs/improvement`) +3. ๊ฐ€์ด๋“œ๋ผ์ธ์— ๋”ฐ๋ผ ๋ณ€๊ฒฝ ์‚ฌํ•ญ์„ ์ ์šฉํ•ฉ๋‹ˆ๋‹ค. +4. ๋ณ€๊ฒฝ ๋‚ด์šฉ์„ ์„ค๋ช…ํ•˜๋Š” Pull Request๋ฅผ ์ œ์ถœํ•ฉ๋‹ˆ๋‹ค. + +**๋„์›€์ด ํ•„์š”ํ•˜์‹ ๊ฐ€์š”?** ์ด์Šˆ ๋˜๋Š” Discussion์„ ์ƒ์„ฑํ•ด ์ฃผ์„ธ์š”. ์ ˆ์ฐจ๋ฅผ ์•ˆ๋‚ดํ•ด ๋“œ๋ฆฌ๊ฒ ์Šต๋‹ˆ๋‹ค. + + +
+ +
+์ถ”๊ฐ€ ์ž๋ฃŒ + +- [Claude Code Documentation](https://code.claude.com/docs/en/overview) +- [MCP Protocol Specification](https://modelcontextprotocol.io) +- [Skills Repository](https://github.com/luongnv89/skills) - ๋ฐ”๋กœ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ๋Š” ์Šคํ‚ฌ ๋ชจ์Œ +- [Anthropic Cookbook](https://github.com/anthropics/anthropic-cookbook) +- [Boris Cherny's Claude Code Workflow](https://x.com/bcherny/status/2007179832300581177) - Claude Code ๊ฐœ๋ฐœ์ž๊ฐ€ ์ง์ ‘ ๊ณต์œ ํ•œ ์ฒด๊ณ„์ ์ธ ์›Œํฌํ”Œ๋กœ: ๋ณ‘๋ ฌ ์—์ด์ „ํŠธ, ๊ณต์œ  CLAUDE.md, Plan ๋ชจ๋“œ, ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด, ์„œ๋ธŒ์—์ด์ „ํŠธ, ๊ฒ€์ฆ ํ›…์„ ํ™œ์šฉํ•œ ์žฅ์‹œ๊ฐ„ ์ž์œจ ์„ธ์…˜ ์šด์˜ ๋ฐฉ์‹ + +
+ +--- + +## ๊ธฐ์—ฌํ•˜๊ธฐ + +๊ธฐ์—ฌ๋ฅผ ํ™˜์˜ํ•ฉ๋‹ˆ๋‹ค! ์‹œ์ž‘ ๋ฐฉ๋ฒ•์€ [CONTRIBUTING.md](CONTRIBUTING.md)๋ฅผ ์ฐธ๊ณ ํ•˜์„ธ์š”. + +--- + +## ๋ผ์ด์„ ์Šค + +MIT License - ์ž์„ธํ•œ ๋‚ด์šฉ์€ [LICENSE](LICENSE)๋ฅผ ์ฐธ๊ณ ํ•˜์„ธ์š”. ์ž์œ ๋กญ๊ฒŒ ์‚ฌ์šฉ, ์ˆ˜์ •, ๋ฐฐํฌํ•  ์ˆ˜ ์žˆ์œผ๋ฉฐ, ์œ ์ผํ•œ ์š”๊ตฌ ์‚ฌํ•ญ์€ ๋ผ์ด์„ ์Šค ๊ณ ์ง€๋ฅผ ํฌํ•จํ•˜๋Š” ๊ฒƒ์ž…๋‹ˆ๋‹ค. + + +--- + +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: 2026๋…„ 6์›” 2์ผ +**Claude Code ๋ฒ„์ „**: 2.1.160 +**์ถœ์ฒ˜**: +- https://code.claude.com/docs/en/overview +- https://code.claude.com/docs/en/changelog +- https://platform.claude.com/docs/en/about-claude/models/overview +- https://github.com/anthropics/claude-code/releases +- https://github.com/anthropics/claude-code/releases/tag/v2.1.154 +**ํ˜ธํ™˜ ๋ชจ๋ธ**: Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5 diff --git a/ko/SECURITY.md b/ko/SECURITY.md new file mode 100644 index 00000000..dec7ad6d --- /dev/null +++ b/ko/SECURITY.md @@ -0,0 +1,334 @@ +# ๋ณด์•ˆ ์ •์ฑ… + +## ๊ฐœ์š” +Claude How To ํ”„๋กœ์ ํŠธ์˜ ๋ณด์•ˆ์€ ๋งค์šฐ ์ค‘์š”ํ•ฉ๋‹ˆ๋‹ค. ์ด ๋ฌธ์„œ๋Š” ํ”„๋กœ์ ํŠธ์˜ ๋ณด์•ˆ ๊ด€ํ–‰์„ ์„ค๋ช…ํ•˜๊ณ , ๋ณด์•ˆ ์ทจ์•ฝ์ ์„ ์ฑ…์ž„๊ฐ ์žˆ๊ฒŒ ์‹ ๊ณ ํ•˜๋Š” ๋ฐฉ๋ฒ•์„ ์•ˆ๋‚ดํ•ฉ๋‹ˆ๋‹ค. + +## ์ง€์› ๋ฒ„์ „ +๋‹ค์Œ ๋ฒ„์ „์— ๋Œ€ํ•ด ๋ณด์•ˆ ์—…๋ฐ์ดํŠธ๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. + +| Version | Status | Support Until | +|---------|--------|---------------| +| Latest (main) | โœ… Active | Current + 6 months | +| 1.x releases | โœ… Active | Until next major version | + +**์ฐธ๊ณ **: ์ด ํ”„๋กœ์ ํŠธ๋Š” ๊ต์œก์šฉ ๊ฐ€์ด๋“œ ํ”„๋กœ์ ํŠธ์ด๋ฏ€๋กœ, ์ผ๋ฐ˜์ ์ธ ๋ฒ„์ „ ์ง€์›๋ณด๋‹ค๋Š” ์ตœ์‹  ๋ชจ๋ฒ” ์‚ฌ๋ก€์™€ ๋ฌธ์„œ ๋ณด์•ˆ์„ ์œ ์ง€ํ•˜๋Š” ๋ฐ ์ค‘์ ์„ ๋‘ก๋‹ˆ๋‹ค. ์—…๋ฐ์ดํŠธ๋Š” ๋ฉ”์ธ ๋ธŒ๋žœ์น˜์— ์ง์ ‘ ์ ์šฉ๋ฉ๋‹ˆ๋‹ค. + +## ๋ณด์•ˆ ๊ด€ํ–‰ + +### ์ฝ”๋“œ ๋ณด์•ˆ + +1. **์˜์กด์„ฑ ๊ด€๋ฆฌ** + - ๋ชจ๋“  Python ์˜์กด์„ฑ์€ `requirements.txt`์— ๊ณ ์ •๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. + - Dependabot ๋ฐ ์ˆ˜๋™ ๊ฒ€ํ† ๋ฅผ ํ†ตํ•ด ์ •๊ธฐ์ ์œผ๋กœ ์—…๋ฐ์ดํŠธํ•ฉ๋‹ˆ๋‹ค. + - ๋ชจ๋“  ์ปค๋ฐ‹์—์„œ Bandit์„ ์‚ฌ์šฉํ•ด ๋ณด์•ˆ ์Šค์บ”์„ ์ˆ˜ํ–‰ํ•ฉ๋‹ˆ๋‹ค. + - ๋ณด์•ˆ ๊ฒ€์‚ฌ๋ฅผ ์œ„ํ•œ pre-commit ํ›…์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + +2. **์ฝ”๋“œ ํ’ˆ์งˆ** + - Ruff๋ฅผ ์‚ฌ์šฉํ•œ ๋ฆฐํŠธ ๊ฒ€์‚ฌ๊ฐ€ ์ผ๋ฐ˜์ ์ธ ๋ฌธ์ œ๋ฅผ ํƒ์ง€ํ•ฉ๋‹ˆ๋‹ค. + - mypy๋ฅผ ํ†ตํ•œ ํƒ€์ž… ๊ฒ€์‚ฌ๋Š” ํƒ€์ž… ๊ด€๋ จ ์ทจ์•ฝ์ ์„ ๋ฐฉ์ง€ํ•ฉ๋‹ˆ๋‹ค. + - pre-commit ํ›…์ด ํ‘œ์ค€ ์ค€์ˆ˜๋ฅผ ๊ฐ•์ œํ•ฉ๋‹ˆ๋‹ค. + - ๋ชจ๋“  ๋ณ€๊ฒฝ ์‚ฌํ•ญ์€ ๋ณ‘ํ•ฉ ์ „์— ๊ฒ€ํ† ๋ฉ๋‹ˆ๋‹ค. + +3. **์ ‘๊ทผ ์ œ์–ด** + - `main` ๋ธŒ๋žœ์น˜์— ๋ธŒ๋žœ์น˜ ๋ณดํ˜ธ๊ฐ€ ์ ์šฉ๋ฉ๋‹ˆ๋‹ค. + - ๋ณ‘ํ•ฉ ์ „ ํ•„์ˆ˜ ๋ฆฌ๋ทฐ๊ฐ€ ํ•„์š”ํ•ฉ๋‹ˆ๋‹ค. + - ๋ณ‘ํ•ฉ ์ „์— ์ƒํƒœ ๊ฒ€์‚ฌ(Status Checks)๊ฐ€ ๋ชจ๋‘ ํ†ต๊ณผํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. + - ์ €์žฅ์†Œ ์“ฐ๊ธฐ ๊ถŒํ•œ์€ ์ œํ•œ์ ์œผ๋กœ ๋ถ€์—ฌ๋ฉ๋‹ˆ๋‹ค. + +### ๋ฌธ์„œ ๋ณด์•ˆ + +1. **์˜ˆ์ œ์— ๋น„๋ฐ€ ์ •๋ณด ํฌํ•จ ๊ธˆ์ง€** + - ์˜ˆ์ œ์— ํฌํ•จ๋œ ๋ชจ๋“  API ํ‚ค๋Š” ์ž๋ฆฌ ํ‘œ์‹œ์ž(placeholder)์ž…๋‹ˆ๋‹ค. + - ์ž๊ฒฉ ์ฆ๋ช…์€ ์ ˆ๋Œ€ ํ•˜๋“œ์ฝ”๋”ฉ๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. + - `.env.example` ํŒŒ์ผ์€ ํ•„์š”ํ•œ ๋ณ€์ˆ˜๋ฅผ ๋ณด์—ฌ์ค๋‹ˆ๋‹ค. + - ๋น„๋ฐ€ ์ •๋ณด ๊ด€๋ฆฌ์— ๋Œ€ํ•œ ๋ช…ํ™•ํ•œ ๊ฒฝ๊ณ ๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. + +2. **๋ณด์•ˆ ๋ชจ๋ฒ” ์‚ฌ๋ก€** + - ์˜ˆ์ œ๋Š” ์•ˆ์ „ํ•œ ๊ตฌํ˜„ ํŒจํ„ด์„ ๋ณด์—ฌ์ค๋‹ˆ๋‹ค. + - ๋ณด์•ˆ ๊ฒฝ๊ณ ๋ฅผ ๋ฌธ์„œ์—์„œ ๊ฐ•์กฐ ํ‘œ์‹œํ•ฉ๋‹ˆ๋‹ค. + - ๊ณต์‹ ๋ณด์•ˆ ๊ฐ€์ด๋“œ ๋งํฌ๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. + - ๊ด€๋ จ ์„น์…˜์—์„œ ์ž๊ฒฉ ์ฆ๋ช… ์ฒ˜๋ฆฌ ๋ฐฉ๋ฒ•์„ ์„ค๋ช…ํ•ฉ๋‹ˆ๋‹ค. + +3. **์ฝ˜ํ…์ธ  ๊ฒ€ํ† ** + - ๋ชจ๋“  ๋ฌธ์„œ๋Š” ๋ณด์•ˆ ๋ฌธ์ œ ์—ฌ๋ถ€๋ฅผ ๊ฒ€ํ† ํ•ฉ๋‹ˆ๋‹ค. + - ๊ธฐ์—ฌ ๊ฐ€์ด๋“œ๋ผ์ธ์— ๋ณด์•ˆ ๊ณ ๋ ค ์‚ฌํ•ญ์ด ํฌํ•จ๋ฉ๋‹ˆ๋‹ค. + - ์™ธ๋ถ€ ๋งํฌ์™€ ์ฐธ๊ณ  ์ž๋ฃŒ๋ฅผ ๊ฒ€์ฆํ•ฉ๋‹ˆ๋‹ค. + +### ์˜์กด์„ฑ ๋ณด์•ˆ + +1. **์Šค์บ”** + - Bandit์ด ๋ชจ๋“  Python ์ฝ”๋“œ์˜ ์ทจ์•ฝ์ ์„ ๊ฒ€์‚ฌํ•ฉ๋‹ˆ๋‹ค. + - GitHub ๋ณด์•ˆ ๊ฒฝ๊ณ ๋ฅผ ํ†ตํ•ด ์˜์กด์„ฑ ์ทจ์•ฝ์ ์„ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. + - ์ •๊ธฐ์ ์œผ๋กœ ์ˆ˜๋™ ๋ณด์•ˆ ๊ฐ์‚ฌ๋ฅผ ์ˆ˜ํ–‰ํ•ฉ๋‹ˆ๋‹ค. + +2. **์—…๋ฐ์ดํŠธ** + - ๋ณด์•ˆ ํŒจ์น˜๋Š” ์‹ ์†ํ•˜๊ฒŒ ์ ์šฉ๋ฉ๋‹ˆ๋‹ค. + - ๋ฉ”์ด์ € ๋ฒ„์ „์€ ์‹ ์ค‘ํ•˜๊ฒŒ ํ‰๊ฐ€ํ•ฉ๋‹ˆ๋‹ค. + - ๋ณ€๊ฒฝ ์ด๋ ฅ์—๋Š” ๋ณด์•ˆ ๊ด€๋ จ ์—…๋ฐ์ดํŠธ๊ฐ€ ํฌํ•จ๋ฉ๋‹ˆ๋‹ค. + +3. **ํˆฌ๋ช…์„ฑ** + - ๋ณด์•ˆ ์—…๋ฐ์ดํŠธ๋Š” ์ปค๋ฐ‹์— ๋ฌธ์„œํ™”๋ฉ๋‹ˆ๋‹ค. + - ์ทจ์•ฝ์  ๊ณต๊ฐœ๋Š” ์ฑ…์ž„๊ฐ ์žˆ๊ฒŒ ์ฒ˜๋ฆฌํ•ฉ๋‹ˆ๋‹ค. + - ํ•„์š” ์‹œ ๊ณต๊ฐœ ๋ณด์•ˆ ๊ถŒ๊ณ ๋ฌธ์„ ๋ฐœํ–‰ํ•ฉ๋‹ˆ๋‹ค. + +## ์ทจ์•ฝ์  ์‹ ๊ณ  + +### ์ค‘์š”ํ•˜๊ฒŒ ๋‹ค๋ฃจ๋Š” ๋ณด์•ˆ ์ด์Šˆ + +๋‹ค์Œ๊ณผ ๊ฐ™์€ ๋ณด๊ณ ๋ฅผ ํ™˜์˜ํ•ฉ๋‹ˆ๋‹ค. +- **์Šคํฌ๋ฆฝํŠธ ๋˜๋Š” ์˜ˆ์ œ ์ฝ”๋“œ์˜ ์ทจ์•ฝ์ ** +- **Python ํŒจํ‚ค์ง€์˜ ์˜์กด์„ฑ ์ทจ์•ฝ์ ** +- **์ฝ”๋“œ ์˜ˆ์ œ์˜ ์•”ํ˜ธํ™” ๊ด€๋ จ ๋ฌธ์ œ** +- **๋ฌธ์„œ ๋‚ด ์ธ์ฆ/์ธ๊ฐ€ ์ทจ์•ฝ์ ** +- **์„ค์ • ์˜ˆ์ œ์˜ ๋ฐ์ดํ„ฐ ๋…ธ์ถœ ์œ„ํ—˜** +- **์ธ์ ์…˜ ์ทจ์•ฝ์ ** (SQL, ๋ช…๋ น์–ด ๋“ฑ) +- **SSRF/XXE/๊ฒฝ๋กœ ์ˆœํšŒ(Path Traversal) ๋ฌธ์ œ** + +### ๋ฒ”์œ„์— ํฌํ•จ๋˜์ง€ ์•Š๋Š” ๋ณด์•ˆ ์ด์Šˆ + +๋‹ค์Œ ํ•ญ๋ชฉ์€ ์ด ํ”„๋กœ์ ํŠธ์˜ ๋ฒ”์œ„์— ํฌํ•จ๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. +- Claude Code ์ž์ฒด์˜ ์ทจ์•ฝ์ (Anthropic์— ์‹ ๊ณ ) +- ์™ธ๋ถ€ ์„œ๋น„์Šค ๋˜๋Š” ๋ผ์ด๋ธŒ๋Ÿฌ๋ฆฌ์˜ ๋ฌธ์ œ(์› ํ”„๋กœ์ ํŠธ์— ์‹ ๊ณ ) +- ์‚ฌํšŒ๊ณตํ•™ ๋˜๋Š” ์‚ฌ์šฉ์ž ๊ต์œก ๊ด€๋ จ ๋ฌธ์ œ(์ด ๊ฐ€์ด๋“œ์—๋Š” ํ•ด๋‹น ์—†์Œ) +- ๊ฐœ๋… ์ฆ๋ช…(PoC) ์—†์ด ์ œ์‹œ๋œ ์ด๋ก ์  ์ทจ์•ฝ์  +- ๊ณต์‹ ์ฑ„๋„์„ ํ†ตํ•ด ์ด๋ฏธ ๋ณด๊ณ ๋œ ์˜์กด์„ฑ ์ทจ์•ฝ์  + +## ์‹ ๊ณ  ๋ฐฉ๋ฒ• + +### ๋น„๊ณต๊ฐœ ์‹ ๊ณ  (๊ถŒ์žฅ) + +**๋ฏผ๊ฐํ•œ ๋ณด์•ˆ ์ด์Šˆ๋Š” GitHub์˜ ๋น„๊ณต๊ฐœ ์ทจ์•ฝ์  ์‹ ๊ณ  ๊ธฐ๋Šฅ์„ ์ด์šฉํ•ด ์ฃผ์„ธ์š”.** + +1. ๋ฐฉ๋ฌธ: https://github.com/luongnv89/claude-howto/security/advisories +2. "Report a vulnerability" ํด๋ฆญ +3. ์ทจ์•ฝ์  ์„ธ๋ถ€ ์ •๋ณด ์ž…๋ ฅ +4. ๋‹ค์Œ ์ •๋ณด๋ฅผ ํฌํ•จ: + - ์ทจ์•ฝ์ ์— ๋Œ€ํ•œ ๋ช…ํ™•ํ•œ ์„ค๋ช… + - ์˜ํ–ฅ์„ ๋ฐ›๋Š” ๊ตฌ์„ฑ ์š”์†Œ(ํŒŒ์ผ, ์„น์…˜, ์˜ˆ์ œ) + - ์ž ์žฌ์  ์˜ํ–ฅ + - ์žฌํ˜„ ๋ฐฉ๋ฒ•(ํ•ด๋‹นํ•˜๋Š” ๊ฒฝ์šฐ) + - ์ œ์•ˆํ•˜๋Š” ์ˆ˜์ • ๋ฐฉ๋ฒ•(์žˆ๋Š” ๊ฒฝ์šฐ) + +**์ดํ›„ ์ง„ํ–‰ ์ ˆ์ฐจ** +- 48์‹œ๊ฐ„ ์ด๋‚ด์— ์ ‘์ˆ˜ ์‚ฌ์‹ค์„ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. +- ์ทจ์•ฝ์ ์„ ์กฐ์‚ฌํ•˜๊ณ  ์‹ฌ๊ฐ๋„๋ฅผ ํ‰๊ฐ€ํ•ฉ๋‹ˆ๋‹ค. +- ์ˆ˜์ • ๋ฐฉ์•ˆ์„ ํ•จ๊ป˜ ๋งˆ๋ จํ•ฉ๋‹ˆ๋‹ค. +- ๊ณต๊ฐœ ์ผ์ •์„ ์กฐ์œจํ•ฉ๋‹ˆ๋‹ค. +- ์›ํ•˜์‹ค ๊ฒฝ์šฐ ๋ณด์•ˆ ๊ถŒ๊ณ ๋ฌธ์— ๊ธฐ์—ฌ์ž๋กœ ์ด๋ฆ„์„ ํ‘œ๊ธฐํ•ฉ๋‹ˆ๋‹ค. + +### ๊ณต๊ฐœ ์‹ ๊ณ  + +๋ฏผ๊ฐํ•˜์ง€ ์•Š๊ฑฐ๋‚˜ ์ด๋ฏธ ๊ณต๊ฐœ๋œ ์ด์Šˆ์˜ ๊ฒฝ์šฐ: + +1. `security` ๋ผ๋ฒจ์„ ์‚ฌ์šฉํ•˜์—ฌ GitHub Issue๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. +2. ๋‹ค์Œ ์ •๋ณด๋ฅผ ํฌํ•จํ•ฉ๋‹ˆ๋‹ค. + - ์ œ๋ชฉ: `[SECURITY]` ๋’ค์— ๊ฐ„๋‹จํ•œ ์„ค๋ช… + - ์ƒ์„ธ ์„ค๋ช… + - ์˜ํ–ฅ์„ ๋ฐ›๋Š” ํŒŒ์ผ ๋˜๋Š” ์„น์…˜ + - ์ž ์žฌ์  ์˜ํ–ฅ + - ์ œ์•ˆํ•˜๋Š” ์ˆ˜์ • ๋ฐฉ๋ฒ• + + +## ์ทจ์•ฝ์  ๋Œ€์‘ ์ ˆ์ฐจ + +### ํ‰๊ฐ€ (24์‹œ๊ฐ„ ์ด๋‚ด) + +1. ๋ณด๊ณ ์„œ ์ ‘์ˆ˜๋ฅผ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. +2. [CVSS v3.1](https://www.first.org/cvss/v3.1/specification-document)์„ ์‚ฌ์šฉํ•˜์—ฌ ์‹ฌ๊ฐ๋„๋ฅผ ํ‰๊ฐ€ํ•ฉ๋‹ˆ๋‹ค. +3. ๋ฒ”์œ„ ๋‚ด ์ด์Šˆ์ธ์ง€ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. +4. ์ดˆ๊ธฐ ํ‰๊ฐ€ ๊ฒฐ๊ณผ๋ฅผ ์ „๋‹ฌํ•ฉ๋‹ˆ๋‹ค. + +### ์ˆ˜์ • ๊ฐœ๋ฐœ (1~7์ผ) + +1. ์ˆ˜์ • ์‚ฌํ•ญ์„ ๊ฐœ๋ฐœํ•ฉ๋‹ˆ๋‹ค. +2. ์ˆ˜์ • ์‚ฌํ•ญ์„ ๊ฒ€ํ† ํ•˜๊ณ  ํ…Œ์ŠคํŠธํ•ฉ๋‹ˆ๋‹ค. +3. ๋ณด์•ˆ ๊ถŒ๊ณ ๋ฌธ์„ ์ž‘์„ฑํ•ฉ๋‹ˆ๋‹ค. +4. ๋ฆด๋ฆฌ์Šค ๋…ธํŠธ๋ฅผ ์ค€๋น„ํ•ฉ๋‹ˆ๋‹ค. + +### ๊ณต๊ฐœ (์‹ฌ๊ฐ๋„์— ๋”ฐ๋ผ ์ƒ์ด) + +**์น˜๋ช…์ (Critical) (CVSS 9.0-10.0)** +- ์ฆ‰์‹œ ์ˆ˜์ • ๋ฒ„์ „ ๋ฐฐํฌ +- ๊ณต๊ฐœ ๋ณด์•ˆ ๊ถŒ๊ณ ๋ฌธ ๋ฐœํ–‰ +- ์‹ ๊ณ ์ž์—๊ฒŒ 24์‹œ๊ฐ„ ์‚ฌ์ „ ํ†ต์ง€ + +**๋†’์Œ(High) (CVSS 7.0-8.9)** +- 48~72์‹œ๊ฐ„ ๋‚ด ์ˆ˜์ • ๋ฒ„์ „ ๋ฐฐํฌ +- ์‹ ๊ณ ์ž์—๊ฒŒ 5์ผ ์‚ฌ์ „ ํ†ต์ง€ +- ๋ฆด๋ฆฌ์Šค ์‹œ ๊ณต๊ฐœ ๊ถŒ๊ณ ๋ฌธ ๋ฐœํ–‰ + +**๋ณดํ†ต(Medium) (CVSS 4.0-6.9)** +- ๋‹ค์Œ ์ •๊ธฐ ์—…๋ฐ์ดํŠธ์— ํฌํ•จ +- ๋ฆด๋ฆฌ์Šค ์‹œ ๊ณต๊ฐœ ๊ถŒ๊ณ ๋ฌธ ๋ฐœํ–‰ + +**๋‚ฎ์Œ(Low) (CVSS 0.1-3.9)** +- ๋‹ค์Œ ์ •๊ธฐ ์—…๋ฐ์ดํŠธ์— ํฌํ•จ +- ๋ฆด๋ฆฌ์Šค ์‹œ ๊ถŒ๊ณ ๋ฌธ ๋ฐœํ–‰ + + +### ๊ฒŒ์‹œ + +๋ฐœํ–‰๋˜๋Š” ๋ณด์•ˆ ๊ถŒ๊ณ ๋ฌธ์—๋Š” ๋‹ค์Œ์ด ํฌํ•จ๋ฉ๋‹ˆ๋‹ค. +- ์ทจ์•ฝ์  ์„ค๋ช… +- ์˜ํ–ฅ์„ ๋ฐ›๋Š” ๊ตฌ์„ฑ ์š”์†Œ +- ์‹ฌ๊ฐ๋„ ํ‰๊ฐ€(CVSS ์ ์ˆ˜) +- ์ˆ˜์ • ๋ฒ„์ „ +- ์šฐํšŒ ๋ฐฉ๋ฒ•(ํ•ด๋‹นํ•˜๋Š” ๊ฒฝ์šฐ) +- ์‹ ๊ณ ์ž ํฌ๋ ˆ๋”ง(๋™์˜ํ•œ ๊ฒฝ์šฐ) + +## ์‹ ๊ณ ์ž๋ฅผ ์œ„ํ•œ ๋ชจ๋ฒ” ์‚ฌ๋ก€ + +### ์‹ ๊ณ  ์ „ + +- **์ด์Šˆ ๊ฒ€์ฆ**: ์ผ๊ด€๋˜๊ฒŒ ์žฌํ˜„ ๊ฐ€๋Šฅํ•œ๊ฐ€์š”? +- **๊ธฐ์กด ์ด์Šˆ ๊ฒ€์ƒ‰**: ์ด๋ฏธ ๋ณด๊ณ ๋œ ๋ฌธ์ œ์ธ๊ฐ€์š”? +- **๋ฌธ์„œ ํ™•์ธ**: ์•ˆ์ „ํ•œ ์‚ฌ์šฉ ๋ฐฉ๋ฒ•์ด ์•ˆ๋‚ด๋˜์–ด ์žˆ๋‚˜์š”? +- **์ˆ˜์ •์•ˆ ํ…Œ์ŠคํŠธ**: ์ œ์•ˆํ•œ ์ˆ˜์ • ๋ฐฉ๋ฒ•์ด ์‹ค์ œ๋กœ ๋™์ž‘ํ•˜๋‚˜์š”? + +### ์‹ ๊ณ  ์‹œ + +- **๊ตฌ์ฒด์ ์œผ๋กœ ์ž‘์„ฑ**: ์ •ํ™•ํ•œ ํŒŒ์ผ ๊ฒฝ๋กœ์™€ ์ค„ ๋ฒˆํ˜ธ๋ฅผ ์ œ๊ณตํ•˜์„ธ์š”. +- **๋งฅ๋ฝ ์ œ๊ณต**: ์™œ ์ด๊ฒƒ์ด ๋ณด์•ˆ ๋ฌธ์ œ์ธ์ง€ ์„ค๋ช…ํ•˜์„ธ์š”. +- **์˜ํ–ฅ ์„ค๋ช…**: ๊ณต๊ฒฉ์ž๊ฐ€ ๋ฌด์—‡์„ ํ•  ์ˆ˜ ์žˆ๋Š”์ง€ ์„ค๋ช…ํ•˜์„ธ์š”. +- **์žฌํ˜„ ์ ˆ์ฐจ ์ œ๊ณต**: ์–ด๋–ป๊ฒŒ ์žฌํ˜„ํ•  ์ˆ˜ ์žˆ๋Š”์ง€ ์„ค๋ช…ํ•˜์„ธ์š”. +- **์ˆ˜์ •์•ˆ ์ œ์•ˆ**: ์–ด๋–ป๊ฒŒ ์ˆ˜์ •ํ•  ์ˆ˜ ์žˆ์„์ง€ ์ œ์•ˆํ•˜์„ธ์š”. + +### ์‹ ๊ณ  ํ›„ + +- **์ธ๋‚ด์‹ฌ์„ ๊ฐ€์ ธ์ฃผ์„ธ์š”**: ํ”„๋กœ์ ํŠธ์˜ ๋ฆฌ์†Œ์Šค๋Š” ์ œํ•œ์ ์ž…๋‹ˆ๋‹ค. +- **์‹ ์†ํžˆ ์‘๋‹ตํ•ด ์ฃผ์„ธ์š”**: ํ›„์† ์งˆ๋ฌธ์— ๋น ๋ฅด๊ฒŒ ๋‹ต๋ณ€ํ•ด ์ฃผ์„ธ์š”. +- **๊ธฐ๋ฐ€์„ ์œ ์ง€ํ•ด ์ฃผ์„ธ์š”**: ์ˆ˜์ • ์ „์—๋Š” ๊ณต๊ฐœํ•˜์ง€ ๋ง์•„ ์ฃผ์„ธ์š”. +- **์กฐ์œจ์„ ์กด์ค‘ํ•ด ์ฃผ์„ธ์š”**: ๊ณต๊ฐœ ์ผ์ •์— ํ˜‘์กฐํ•ด ์ฃผ์„ธ์š”. + +## ๋ณด์•ˆ ํ—ค๋” ๋ฐ ๊ตฌ์„ฑ + +### ์ €์žฅ์†Œ ๋ณด์•ˆ + +- **๋ธŒ๋žœ์น˜ ๋ณดํ˜ธ**: ๋ฉ”์ธ ๋ธŒ๋žœ์น˜ ๋ณ€๊ฒฝ ์‹œ 2๋ช…์˜ ์Šน์ธ ํ•„์š” +- **์ƒํƒœ ๊ฒ€์‚ฌ**: ๋ชจ๋“  CI/CD ๊ฒ€์‚ฌ๋ฅผ ํ†ต๊ณผํ•ด์•ผ ํ•จ +- **CODEOWNERS**: ์ฃผ์š” ํŒŒ์ผ์— ๋Œ€ํ•œ ์ง€์ • ๋ฆฌ๋ทฐ์–ด ์šด์˜ +- **์„œ๋ช…๋œ ์ปค๋ฐ‹**: ๊ธฐ์—ฌ์ž์—๊ฒŒ ๊ถŒ์žฅ + +### ๊ฐœ๋ฐœ ๋ณด์•ˆ + +```bash +# Install pre-commit hooks +pre-commit install + +# Run security scans locally +bandit -c pyproject.toml -r scripts/ +mypy scripts/ --ignore-missing-imports +ruff check scripts/ +``` + +### ์˜์กด์„ฑ ๋ณด์•ˆ + +```bash +# Check for known vulnerabilities +pip install safety +safety check + +# Or use pip-audit +pip install pip-audit +pip-audit +``` + +## ๊ธฐ์—ฌ์ž๋ฅผ ์œ„ํ•œ ๋ณด์•ˆ ๊ฐ€์ด๋“œ๋ผ์ธ + +### ์˜ˆ์ œ ์ž‘์„ฑ ์‹œ + +1. **๋น„๋ฐ€ ์ •๋ณด๋ฅผ ์ ˆ๋Œ€ ํ•˜๋“œ์ฝ”๋”ฉํ•˜์ง€ ๋งˆ์„ธ์š”** + ```python + # โŒ Bad + api_key = "sk-1234567890" + + # โœ… Good + api_key = os.getenv("API_KEY") + ``` + +2. **๋ณด์•ˆ ์˜ํ–ฅ์„ ๊ฒฝ๊ณ ํ•˜์„ธ์š”** + ```markdown + โš ๏ธ **Security Note**: Never commit `.env` files to git. + Add to `.gitignore` immediately. + ``` + +3. **์•ˆ์ „ํ•œ ๊ธฐ๋ณธ๊ฐ’์„ ์‚ฌ์šฉํ•˜์„ธ์š”** + - ๊ธฐ๋ณธ์ ์œผ๋กœ ์ธ์ฆ์„ ํ™œ์„ฑํ™”ํ•ฉ๋‹ˆ๋‹ค. + - ๊ฐ€๋Šฅํ•œ ๊ฒฝ์šฐ HTTPS๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + - ์ž…๋ ฅ๊ฐ’์„ ๊ฒ€์ฆํ•˜๊ณ  ์ •์ œํ•ฉ๋‹ˆ๋‹ค. + - ๋งค๊ฐœ๋ณ€์ˆ˜ํ™”๋œ ์ฟผ๋ฆฌ๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + +4. **๋ณด์•ˆ ๊ณ ๋ ค ์‚ฌํ•ญ์„ ๋ฌธ์„œํ™”ํ•˜์„ธ์š”** + - ๋ณด์•ˆ์ด ์ค‘์š”ํ•œ ์ด์œ ๋ฅผ ์„ค๋ช…ํ•ฉ๋‹ˆ๋‹ค. + - ์•ˆ์ „ํ•œ ํŒจํ„ด๊ณผ ์•ˆ์ „ํ•˜์ง€ ์•Š์€ ํŒจํ„ด์„ ๋น„๊ตํ•˜์—ฌ ๋ณด์—ฌ์ค๋‹ˆ๋‹ค. + - ์‹ ๋ขฐํ•  ์ˆ˜ ์žˆ๋Š” ๊ณต์‹ ์ž๋ฃŒ๋ฅผ ์—ฐ๊ฒฐํ•ฉ๋‹ˆ๋‹ค. + - ๊ฒฝ๊ณ  ์‚ฌํ•ญ์„ ๋ˆˆ์— ๋„๊ฒŒ ํ‘œ์‹œํ•ฉ๋‹ˆ๋‹ค. + +### ๊ธฐ์—ฌ ๋‚ด์šฉ ๊ฒ€ํ†  ์‹œ + +1. **๋…ธ์ถœ๋œ ๋น„๋ฐ€ ์ •๋ณด๋ฅผ ํ™•์ธํ•˜์„ธ์š”** + - ์ผ๋ฐ˜์ ์ธ ํŒจํ„ด(`api_key=`, `password=` ๋“ฑ)์„ ๊ฒ€์‚ฌํ•ฉ๋‹ˆ๋‹ค. + - ์„ค์ • ํŒŒ์ผ์„ ๊ฒ€ํ† ํ•ฉ๋‹ˆ๋‹ค. + - ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋ฅผ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. + +2. **์•ˆ์ „ํ•œ ์ฝ”๋”ฉ ๊ด€ํ–‰์„ ๊ฒ€์ฆํ•˜์„ธ์š”** + - ํ•˜๋“œ์ฝ”๋”ฉ๋œ ์ž๊ฒฉ ์ฆ๋ช…์ด ์—†๋Š”์ง€ ํ™•์ธ + - ์ ์ ˆํ•œ ์ž…๋ ฅ ๊ฒ€์ฆ ์ˆ˜ํ–‰ + - ์•ˆ์ „ํ•œ ์ธ์ฆ ๋ฐ ๊ถŒํ•œ ๋ถ€์—ฌ ์ ์šฉ + - ์•ˆ์ „ํ•œ ํŒŒ์ผ ์ฒ˜๋ฆฌ ๊ตฌํ˜„ + +3. **๋ณด์•ˆ ์˜ํ–ฅ์„ ํ…Œ์ŠคํŠธํ•˜์„ธ์š”** + - ์•…์šฉ๋  ๊ฐ€๋Šฅ์„ฑ์ด ์žˆ๋Š”๊ฐ€? + - ์ตœ์•…์˜ ์‹œ๋‚˜๋ฆฌ์˜ค๋Š” ๋ฌด์—‡์ธ๊ฐ€? + - ๊ณ ๋ คํ•ด์•ผ ํ•  ์˜ˆ์™ธ ์ƒํ™ฉ์ด ์žˆ๋Š”๊ฐ€? + +## ๋ณด์•ˆ ๋ฆฌ์†Œ์Šค + +### ๊ณต์‹ ํ‘œ์ค€ +- [OWASP Top 10](https://owasp.org/www-project-top-ten/) +- [CWE Top 25](https://cwe.mitre.org/top25/) +- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) + +### Python ๋ณด์•ˆ +- [Python Security Advisories](https://www.python.org/dev/security/) +- [PyPI Security](https://pypi.org/help/#security) +- [Bandit Documentation](https://bandit.readthedocs.io/) + +### ์˜์กด์„ฑ ๊ด€๋ฆฌ +- [OWASP Dependency Check](https://owasp.org/www-project-dependency-check/) +- [GitHub Security Alerts](https://docs.github.com/en/code-security/dependabot/dependabot-alerts/about-dependabot-alerts) + +### ์ผ๋ฐ˜ ๋ณด์•ˆ +- [Anthropic Security](https://www.anthropic.com/) +- [GitHub Security Best Practices](https://docs.github.com/en/code-security) + +## ๋ณด์•ˆ ๊ถŒ๊ณ ๋ฌธ ์•„์นด์ด๋ธŒ + +Past security advisories are available in the [GitHub Security Advisories](https://github.com/luongnv89/claude-howto/security/advisories) tab. + +## ๋ฌธ์˜ + +๋ณด์•ˆ ๊ด€๋ จ ์งˆ๋ฌธ์ด๋‚˜ ๋ณด์•ˆ ๊ด€ํ–‰์— ๋Œ€ํ•œ ๋…ผ์˜๋ฅผ ์›ํ•˜์‹œ๋Š” ๊ฒฝ์šฐ: + +1. **๋น„๊ณต๊ฐœ ๋ณด์•ˆ ์‹ ๊ณ **: GitHub์˜ ๋น„๊ณต๊ฐœ ์ทจ์•ฝ์  ์‹ ๊ณ  ๊ธฐ๋Šฅ ์‚ฌ์šฉ +2. **์ผ๋ฐ˜ ๋ณด์•ˆ ์งˆ๋ฌธ**: `[SECURITY]` ํƒœ๊ทธ๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ Discussion ์ƒ์„ฑ +3. **๋ณด์•ˆ ์ •์ฑ… ํ”ผ๋“œ๋ฐฑ**: `security` ๋ผ๋ฒจ์„ ์‚ฌ์šฉํ•˜์—ฌ Issue ์ƒ์„ฑ + +## ๊ฐ์‚ฌ์˜ ๋ง์”€ + +ํ”„๋กœ์ ํŠธ์˜ ๋ณด์•ˆ์„ ์œ ์ง€ํ•˜๋Š” ๋ฐ ๋„์›€์„ ์ฃผ๋Š” ๋ณด์•ˆ ์—ฐ๊ตฌ์ž์™€ ์ปค๋ฎค๋‹ˆํ‹ฐ ๊ตฌ์„ฑ์›๋“ค๊ป˜ ๊นŠ์ด ๊ฐ์‚ฌ๋“œ๋ฆฝ๋‹ˆ๋‹ค. ์ฑ…์ž„๊ฐ ์žˆ๊ฒŒ ์ทจ์•ฝ์ ์„ ์‹ ๊ณ ํ•ด ์ฃผ์‹  ๊ธฐ์—ฌ์ž๋Š” ๋ณด์•ˆ ๊ถŒ๊ณ ๋ฌธ์— ์ด๋ฆ„์ด ๊ธฐ์žฌ๋ฉ๋‹ˆ๋‹ค(์ต๋ช…์„ฑ์„ ์›ํ•˜์ง€ ์•Š๋Š” ๊ฒฝ์šฐ). + +## ์ •์ฑ… ์—…๋ฐ์ดํŠธ + +์ด ๋ณด์•ˆ ์ •์ฑ…์€ ๋‹ค์Œ ๊ฒฝ์šฐ์— ๊ฒ€ํ†  ๋ฐ ์—…๋ฐ์ดํŠธ๋ฉ๋‹ˆ๋‹ค. +- ์ƒˆ๋กœ์šด ์ทจ์•ฝ์ ์ด ๋ฐœ๊ฒฌ๋  ๋•Œ +- ๋ณด์•ˆ ๋ชจ๋ฒ” ์‚ฌ๋ก€๊ฐ€ ๋ฐœ์ „ํ•  ๋•Œ +- ํ”„๋กœ์ ํŠธ ๋ฒ”์œ„๊ฐ€ ๋ณ€๊ฒฝ๋  ๋•Œ +- ์ตœ์†Œ ์—ฐ 1ํšŒ ์ •๊ธฐ ๊ฒ€ํ†  ์‹œ + +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: 2026๋…„ 4์›” 27์ผ +**๋‹ค์Œ ๊ฒ€ํ†  ์˜ˆ์ •**: 2027๋…„ 4์›” + +--- + +Claude How To์˜ ๋ณด์•ˆ ์œ ์ง€์— ๋„์›€์„ ์ฃผ์…”์„œ ๊ฐ์‚ฌํ•ฉ๋‹ˆ๋‹ค! ๐Ÿ”’ diff --git a/ko/STYLE_GUIDE.md b/ko/STYLE_GUIDE.md new file mode 100644 index 00000000..af4d2f49 --- /dev/null +++ b/ko/STYLE_GUIDE.md @@ -0,0 +1,655 @@ + + + Claude How To + + +# ์Šคํƒ€์ผ ๊ฐ€์ด๋“œ + +> Claude How To์— ๊ธฐ์—ฌํ•˜๊ธฐ ์œ„ํ•œ ๊ทœ์น™๊ณผ ์„œ์‹ ์ง€์นจ์ž…๋‹ˆ๋‹ค. ์ฝ˜ํ…์ธ ์˜ ์ผ๊ด€์„ฑ, ์ „๋ฌธ์„ฑ, ์œ ์ง€๋ณด์ˆ˜์„ฑ์„ ์œ ์ง€ํ•˜๊ธฐ ์œ„ํ•ด ์ด ๊ฐ€์ด๋“œ๋ฅผ ๋”ฐ๋ฅด์‹ญ์‹œ์˜ค. + +--- + +## ๋ชฉ์ฐจ + +- [ํŒŒ์ผ ๋ฐ ํด๋” ๋ช…๋ช… ๊ทœ์น™](#ํŒŒ์ผ-๋ฐ-ํด๋”-๋ช…๋ช…-๊ทœ์น™) +- [๋ฌธ์„œ ๊ตฌ์กฐ](#๋ฌธ์„œ-๊ตฌ์กฐ) +- [์ œ๋ชฉ](#์ œ๋ชฉ) +- [ํ…์ŠคํŠธ ์„œ์‹](#ํ…์ŠคํŠธ-์„œ์‹) +- [๋ชฉ๋ก](#๋ชฉ๋ก) +- [ํ‘œ](#ํ‘œ) +- [์ฝ”๋“œ ๋ธ”๋ก](#์ฝ”๋“œ-๋ธ”๋ก) +- [๋งํฌ ๋ฐ ์ƒํ˜ธ ์ฐธ์กฐ](#๋งํฌ-๋ฐ-์ƒํ˜ธ-์ฐธ์กฐ) +- [๋‹ค์ด์–ด๊ทธ๋žจ](#๋‹ค์ด์–ด๊ทธ๋žจ) +- [์ด๋ชจ์ง€ ์‚ฌ์šฉ](#์ด๋ชจ์ง€-์‚ฌ์šฉ) +- [YAML ํ”„๋ŸฐํŠธ๋งคํ„ฐ](#yaml-ํ”„๋ŸฐํŠธ๋งคํ„ฐ) +- [์ด๋ฏธ์ง€ ๋ฐ ๋ฏธ๋””์–ด](#์ด๋ฏธ์ง€-๋ฐ-๋ฏธ๋””์–ด) +- [ํ†ค๊ณผ ๋ฌธ์ฒด](#ํ†ค๊ณผ-๋ฌธ์ฒด) +- [์ปค๋ฐ‹ ๋ฉ”์‹œ์ง€](#์ปค๋ฐ‹-๋ฉ”์‹œ์ง€) +- [์ž‘์„ฑ์ž ์ฒดํฌ๋ฆฌ์ŠคํŠธ](#์ž‘์„ฑ์ž-์ฒดํฌ๋ฆฌ์ŠคํŠธ) + + +--- + +## ํŒŒ์ผ ๋ฐ ํด๋” ๋ช…๋ช… ๊ทœ์น™ + +### ๊ฐ•์˜ ํด๋” + +๊ฐ•์˜ ํด๋”๋Š” **๋‘ ์ž๋ฆฌ ์ˆซ์ž ์ ‘๋‘์‚ฌ** ๋’ค์— **kebab-case** ์„ค๋ช…์ž๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + + +``` +01-slash-commands/ +02-memory/ +03-skills/ +04-subagents/ +05-mcp/ +``` + +์ˆซ์ž๋Š” ์ดˆ๊ธ‰๋ถ€ํ„ฐ ๊ณ ๊ธ‰๊นŒ์ง€์˜ ํ•™์Šต ์ˆœ์„œ๋ฅผ ๋‚˜ํƒ€๋ƒ…๋‹ˆ๋‹ค. + +### ํŒŒ์ผ ์ด๋ฆ„ + +| Type | Convention | Examples | +|------|-----------|----------| +| **Lesson README** | `README.md` | `01-slash-commands/README.md` | +| **Feature file** | Kebab-case `.md` | `code-reviewer.md`, `generate-api-docs.md` | +| **Shell script** | Kebab-case `.sh` | `format-code.sh`, `validate-input.sh` | +| **Config file** | Standard names | `.mcp.json`, `settings.json` | +| **Memory file** | Scope-prefixed | `project-CLAUDE.md`, `personal-CLAUDE.md` | +| **Top-level docs** | UPPER_CASE `.md` | `CATALOG.md`, `QUICK_REFERENCE.md`, `CONTRIBUTING.md` | +| **Image assets** | Kebab-case | `pr-slash-command.png`, `claude-howto-logo.svg` | + +### ๊ทœ์น™ + +- ๋ชจ๋“  ํŒŒ์ผ ๋ฐ ํด๋” ์ด๋ฆ„์€ **์†Œ๋ฌธ์ž**๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค(๋‹จ, `README.md`, `CATALOG.md`์™€ ๊ฐ™์€ ์ตœ์ƒ์œ„ ๋ฌธ์„œ๋Š” ์˜ˆ์™ธ). +- ๋‹จ์–ด ๊ตฌ๋ถ„์ž๋Š” ํ•˜์ดํ”ˆ(`-`)์„ ์‚ฌ์šฉํ•˜๋ฉฐ, ์–ธ๋”์Šค์ฝ”์–ด(`_`)๋‚˜ ๊ณต๋ฐฑ์€ ์‚ฌ์šฉํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. +- ์ด๋ฆ„์€ ์„ค๋ช…์ ์ด๋ฉด์„œ๋„ ๊ฐ„๊ฒฐํ•˜๊ฒŒ ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. + + +--- + +## ๋ฌธ์„œ ๊ตฌ์กฐ + +### ๋ฃจํŠธ README + +๋ฃจํŠธ `README.md`๋Š” ๋‹ค์Œ ์ˆœ์„œ๋ฅผ ๋”ฐ๋ฆ…๋‹ˆ๋‹ค. + +1. ๋กœ๊ณ (๋‹คํฌ/๋ผ์ดํŠธ ๋ฒ„์ „์„ ํฌํ•จํ•œ `` ์š”์†Œ) +2. H1 ์ œ๋ชฉ +3. ์†Œ๊ฐœ์šฉ ์ธ์šฉ๋ฌธ ๋ธ”๋ก(ํ•œ ์ค„ ๊ฐ€์น˜ ์ œ์•ˆ) +4. ๋น„๊ต ํ‘œ๊ฐ€ ํฌํ•จ๋œ "Why This Guide?" ์„น์…˜ +5. ๊ตฌ๋ถ„์„ (`---`) +6. ๋ชฉ์ฐจ +7. ๊ธฐ๋Šฅ ์นดํƒˆ๋กœ๊ทธ +8. ๋น ๋ฅธ ์ด๋™ +9. ํ•™์Šต ๊ฒฝ๋กœ +10. ๊ธฐ๋Šฅ ์„น์…˜ +11. ์‹œ์ž‘ํ•˜๊ธฐ +12. ๋ชจ๋ฒ” ์‚ฌ๋ก€ / ๋ฌธ์ œ ํ•ด๊ฒฐ +13. ๊ธฐ์—ฌ ๋ฐฉ๋ฒ• / ๋ผ์ด์„ ์Šค + + +### ๊ฐ•์˜ README + +๊ฐ ๊ฐ•์˜ `README.md`๋Š” ๋‹ค์Œ ์ˆœ์„œ๋ฅผ ๋”ฐ๋ฆ…๋‹ˆ๋‹ค. + +1. H1 ์ œ๋ชฉ(์˜ˆ: `# Slash Commands`) +2. ๊ฐ„๋‹จํ•œ ๊ฐœ์š” ๋ฌธ๋‹จ +3. ๋น ๋ฅธ ์ฐธ์กฐ ํ‘œ(์„ ํƒ ์‚ฌํ•ญ) +4. ์•„ํ‚คํ…์ฒ˜ ๋‹ค์ด์–ด๊ทธ๋žจ(Mermaid) +5. ์ƒ์„ธ ์„น์…˜(H2) +6. ์‹ค์Šต ์˜ˆ์ œ(๋ฒˆํ˜ธ ๋ชฉ๋ก, 4~6๊ฐœ ์˜ˆ์ œ) +7. ๋ชจ๋ฒ” ์‚ฌ๋ก€(Do's ๋ฐ Don'ts ํ‘œ) +8. ๋ฌธ์ œ ํ•ด๊ฒฐ +9. ๊ด€๋ จ ๊ฐ€์ด๋“œ / ๊ณต์‹ ๋ฌธ์„œ +10. ๋ฌธ์„œ ๋ฉ”ํƒ€๋ฐ์ดํ„ฐ ํ‘ธํ„ฐ + + +### ๊ธฐ๋Šฅ/์˜ˆ์ œ ํŒŒ์ผ + +๊ฐœ๋ณ„ ๊ธฐ๋Šฅ ํŒŒ์ผ(์˜ˆ: `optimize.md`, `pr.md`)์€ ๋‹ค์Œ ์ˆœ์„œ๋ฅผ ๋”ฐ๋ฆ…๋‹ˆ๋‹ค. + +1. YAML ํ”„๋ŸฐํŠธ๋งคํ„ฐ(ํ•„์š”ํ•œ ๊ฒฝ์šฐ) +2. H1 ์ œ๋ชฉ +3. ๋ชฉ์  / ์„ค๋ช… +4. ์‚ฌ์šฉ ๋ฐฉ๋ฒ• +5. ์ฝ”๋“œ ์˜ˆ์ œ +6. ์‚ฌ์šฉ์ž ์ •์˜ ํŒ + + +### ์„น์…˜ ๊ตฌ๋ถ„์„  + +์ฃผ์š” ๋ฌธ์„œ ์˜์—ญ์„ ๊ตฌ๋ถ„ํ•  ๋•Œ๋Š” ๊ตฌ๋ถ„์„ (`---`)์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + + +```markdown +--- + +## New Major Section +``` + +์†Œ๊ฐœ์šฉ ์ธ์šฉ๋ฌธ ๋’ค์™€ ๋…ผ๋ฆฌ์ ์œผ๋กœ ๊ตฌ๋ถ„๋˜๋Š” ์ฃผ์š” ์„น์…˜ ์‚ฌ์ด์— ๋ฐฐ์น˜ํ•ฉ๋‹ˆ๋‹ค. + +--- + +## ์ œ๋ชฉ + +### ๊ณ„์ธต ๊ตฌ์กฐ + +| Level | Use | Example | +| --------- | ---------------- | ---------------------------- | +| `#` H1 | ๋ฌธ์„œ ์ œ๋ชฉ(๋ฌธ์„œ๋‹น ํ•˜๋‚˜) | `# Slash Commands` | +| `##` H2 | ์ฃผ์š” ์„น์…˜ | `## Best Practices` | +| `###` H3 | ํ•˜์œ„ ์„น์…˜ | `### Adding a Skill` | +| `####` H4 | ํ•˜์œ„-ํ•˜์œ„ ์„น์…˜(๋“œ๋ฌผ๊ฒŒ ์‚ฌ์šฉ) | `#### Configuration Options` | + +### ๊ทœ์น™ + +- **๋ฌธ์„œ๋‹น H1์€ ํ•˜๋‚˜๋งŒ ์‚ฌ์šฉ** โ€” ํŽ˜์ด์ง€ ์ œ๋ชฉ ์ „์šฉ +- **๋‹จ๊ณ„๋ฅผ ๊ฑด๋„ˆ๋›ฐ์ง€ ๋งˆ์‹ญ์‹œ์˜ค** โ€” H2 ๋‹ค์Œ์— ๋ฐ”๋กœ H4๋ฅผ ์‚ฌ์šฉํ•˜์ง€ ๋งˆ์‹ญ์‹œ์˜ค +- **์ œ๋ชฉ์€ ๊ฐ„๊ฒฐํ•˜๊ฒŒ ์œ ์ง€** โ€” 2~5๋‹จ์–ด ๊ถŒ์žฅ +- **๋ฌธ์žฅํ˜• ๋Œ€์†Œ๋ฌธ์ž ์‚ฌ์šฉ** โ€” ์ฒซ ๋‹จ์–ด์™€ ๊ณ ์œ ๋ช…์‚ฌ๋งŒ ๋Œ€๋ฌธ์ž ์‚ฌ์šฉ(๋‹จ, ๊ธฐ๋Šฅ ์ด๋ฆ„์€ ์›๋ฌธ ์œ ์ง€) +- **์ด๋ชจ์ง€ ์ ‘๋‘์‚ฌ๋Š” ๋ฃจํŠธ README ์„น์…˜ ์ œ๋ชฉ์—์„œ๋งŒ ์‚ฌ์šฉ**([์ด๋ชจ์ง€ ์‚ฌ์šฉ](#์ด๋ชจ์ง€-์‚ฌ์šฉ) ์ฐธ๊ณ ) + + +--- + +## ํ…์ŠคํŠธ ์„œ์‹ + +### ๊ฐ•์กฐ + +| Style | When to Use | Example | +| --------------------- | --------------------- | ------------------- | +| **Bold** (`**text**`) | ํ•ต์‹ฌ ์šฉ์–ด, ํ‘œ์˜ ๋ ˆ์ด๋ธ”, ์ค‘์š”ํ•œ ๊ฐœ๋… | `**Installation**:` | +| *Italic* (`*text*`) | ๊ธฐ์ˆ  ์šฉ์–ด์˜ ์ฒซ ๋“ฑ์žฅ, ์„œ์ /๋ฌธ์„œ ์ œ๋ชฉ | `*frontmatter*` | +| `Code` (`` `text` ``) | ํŒŒ์ผ๋ช…, ๋ช…๋ น์–ด, ์„ค์ • ๊ฐ’, ์ฝ”๋“œ ์ฐธ์กฐ | `` `CLAUDE.md` `` | + +### ์•ˆ๋‚ด์šฉ ๋ธ”๋ก ์ธ์šฉ๋ฌธ + +์ค‘์š”ํ•œ ์•ˆ๋‚ด ์‚ฌํ•ญ์—๋Š” ๊ตต์€ ์ ‘๋‘์‚ฌ๊ฐ€ ํฌํ•จ๋œ ์ธ์šฉ๋ฌธ ๋ธ”๋ก์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + +```markdown +> **Note**: Custom slash commands have been merged into skills since v2.0. + +> **Important**: Never commit API keys or credentials. + +> **Tip**: Combine memory with skills for maximum effectiveness. +``` + +์ง€์›๋˜๋Š” ์•ˆ๋‚ด ์œ ํ˜•: **Note**, **Important**, **Tip**, **Warning** + +### ๋ฌธ๋‹จ + +- ๋ฌธ๋‹จ์€ ์งง๊ฒŒ ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค(2~4๋ฌธ์žฅ). +- ๋ฌธ๋‹จ ์‚ฌ์ด์—๋Š” ๋นˆ ์ค„์„ ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค. +- ํ•ต์‹ฌ ๋‚ด์šฉ์„ ๋จผ์ € ์ œ์‹œํ•œ ๋’ค ๋งฅ๋ฝ์„ ์„ค๋ช…ํ•ฉ๋‹ˆ๋‹ค. +- "๋ฌด์—‡(what)"๋ฟ ์•„๋‹ˆ๋ผ "์™œ(why)"๋„ ์„ค๋ช…ํ•ฉ๋‹ˆ๋‹ค. + +--- + +## ๋ชฉ๋ก + +### ์ˆœ์„œ ์—†๋Š” ๋ชฉ๋ก + +์ค‘์ฒฉ ์‹œ 2์นธ ๋“ค์—ฌ์“ฐ๊ธฐ๋ฅผ ์‚ฌ์šฉํ•˜๋ฉฐ ๋Œ€์‹œ(`-`)๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + +```markdown +- First item +- Second item + - Nested item + - Another nested item + - Deep nested (avoid going deeper than 3 levels) +- Third item +``` + +### ์ˆœ์„œ ์žˆ๋Š” ๋ชฉ๋ก + +์ˆœ์ฐจ์ ์ธ ๋‹จ๊ณ„, ์‚ฌ์šฉ ๋ฐฉ๋ฒ•, ์ˆœ์œ„๊ฐ€ ์žˆ๋Š” ํ•ญ๋ชฉ์—๋Š” ๋ฒˆํ˜ธ ๋ชฉ๋ก์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + +```markdown +1. First step +2. Second step + - Sub-point detail + - Another sub-point +3. Third step +``` + +### ์„ค๋ช…ํ˜• ๋ชฉ๋ก + +ํ‚ค-๊ฐ’ ํ˜•ํƒœ์˜ ๋ชฉ๋ก์—๋Š” ๊ตต์€ ๋ ˆ์ด๋ธ”์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + +```markdown +- **Performance bottlenecks** - identify O(n^2) operations, inefficient loops +- **Memory leaks** - find unreleased resources, circular references +- **Algorithm improvements** - suggest better algorithms or data structures +``` + +### ๊ทœ์น™ + + +- ์ผ๊ด€๋œ ๋“ค์—ฌ์“ฐ๊ธฐ๋ฅผ ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค(๋‹จ๊ณ„๋‹น ๊ณต๋ฐฑ 2์นธ). +- ๋ชฉ๋ก ์ „ํ›„์— ๋นˆ ์ค„์„ ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค. +- ๋ชฉ๋ก ํ•ญ๋ชฉ์˜ ๊ตฌ์กฐ๋ฅผ ์ผ๊ด€๋˜๊ฒŒ ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค(๋ชจ๋‘ ๋™์‚ฌ๋กœ ์‹œ์ž‘ํ•˜๊ฑฐ๋‚˜ ๋ชจ๋‘ ๋ช…์‚ฌ๋กœ ์‹œ์ž‘ํ•˜๋Š” ๋“ฑ). +- 3๋‹จ๊ณ„ ์ด์ƒ ์ค‘์ฒฉํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. + + +--- + +## ํ‘œ + +### ๊ธฐ๋ณธ ํ˜•์‹ + +```markdown +| Column 1 | Column 2 | Column 3 | +|----------|----------|----------| +| Data | Data | Data | +``` + +### ์ž์ฃผ ์‚ฌ์šฉํ•˜๋Š” ํ‘œ ํŒจํ„ด + +**๊ธฐ๋Šฅ ๋น„๊ต(3~4๊ฐœ ์—ด):** + +```markdown +| Feature | Invocation | Persistence | Best For | +|---------|-----------|------------|----------| +| **Slash Commands** | Manual (`/cmd`) | Session only | Quick shortcuts | +| **Memory** | Auto-loaded | Cross-session | Long-term learning | +``` + +**๊ถŒ์žฅ ์‚ฌํ•ญ๊ณผ ๊ธˆ์ง€ ์‚ฌํ•ญ:** + +```markdown +| Do | Don't | +|----|-------| +| Use descriptive names | Use vague names | +| Keep files focused | Overload a single file | +``` + +**๋น ๋ฅธ ์ฐธ์กฐ:** + +```markdown +| Aspect | Details | +|--------|---------| +| **Purpose** | Generate API documentation | +| **Scope** | Project-level | +| **Complexity** | Intermediate | +``` + +### ๊ทœ์น™ + +- ์ฒซ ๋ฒˆ์งธ ์—ด์ด ํ–‰ ๋ ˆ์ด๋ธ”์ธ ๊ฒฝ์šฐ **๊ตต๊ฒŒ ํ‘œ์‹œ**ํ•ฉ๋‹ˆ๋‹ค. +- ์›๋ณธ ์†Œ์Šค์˜ ๊ฐ€๋…์„ฑ์„ ์œ„ํ•ด ํŒŒ์ดํ”„(`|`) ์ •๋ ฌ์„ ๊ถŒ์žฅํ•ฉ๋‹ˆ๋‹ค. +- ์…€ ๋‚ด์šฉ์€ ๊ฐ„๊ฒฐํ•˜๊ฒŒ ์œ ์ง€ํ•˜๊ณ , ์ž์„ธํ•œ ๋‚ด์šฉ์€ ๋งํฌ๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +- ์…€ ๋‚ด๋ถ€์˜ ๋ช…๋ น์–ด ๋ฐ ํŒŒ์ผ ๊ฒฝ๋กœ์—๋Š” `์ฝ”๋“œ ์„œ์‹`์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + +--- + +## ์ฝ”๋“œ ๋ธ”๋ก + +### ์–ธ์–ด ํƒœ๊ทธ + +๊ตฌ๋ฌธ ๊ฐ•์กฐ๋ฅผ ์œ„ํ•ด ํ•ญ์ƒ ์–ธ์–ด ํƒœ๊ทธ๋ฅผ ์ง€์ •ํ•ฉ๋‹ˆ๋‹ค. + +| Language | Tag | Use For | +| ---------- | ------------ | -------------- | +| Shell | `bash` | CLI ๋ช…๋ น์–ด, ์Šคํฌ๋ฆฝํŠธ | +| Python | `python` | Python ์ฝ”๋“œ | +| JavaScript | `javascript` | JS ์ฝ”๋“œ | +| TypeScript | `typescript` | TS ์ฝ”๋“œ | +| JSON | `json` | ์„ค์ • ํŒŒ์ผ | +| YAML | `yaml` | ํ”„๋ŸฐํŠธ๋งคํ„ฐ, ์„ค์ • | +| Markdown | `markdown` | Markdown ์˜ˆ์ œ | +| SQL | `sql` | ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ์ฟผ๋ฆฌ | + + +### ๊ทœ์น™ + +```bash +# Comment explaining what the command does +claude mcp add notion --transport http https://mcp.notion.com/mcp +``` + +- ๋ช…ํ™•ํ•˜์ง€ ์•Š์€ ๋ช…๋ น์–ด ์•ž์—๋Š” **์ฃผ์„ ์ค„**์„ ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค. +- ๋ชจ๋“  ์˜ˆ์ œ๋Š” **๋ณต์‚ฌ ํ›„ ๋ฐ”๋กœ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ๋Š” ์ƒํƒœ**๋กœ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. +- ๊ด€๋ จ์ด ์žˆ๋‹ค๋ฉด **๊ธฐ๋ณธ ๋ฒ„์ „๊ณผ ๊ณ ๊ธ‰ ๋ฒ„์ „ ๋ชจ๋‘** ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. +- ์ดํ•ด์— ๋„์›€์ด ๋œ๋‹ค๋ฉด **์˜ˆ์ƒ ์ถœ๋ ฅ**์„ ํฌํ•จํ•ฉ๋‹ˆ๋‹ค(์–ธ์–ด ํƒœ๊ทธ ์—†๋Š” ์ฝ”๋“œ ๋ธ”๋ก ์‚ฌ์šฉ). + +### ์„ค์น˜ ๋ธ”๋ก + +์„ค์น˜ ์•ˆ๋‚ด์—๋Š” ๋‹ค์Œ ํŒจํ„ด์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + +```bash +# Copy files to your project +cp 01-slash-commands/*.md .claude/commands/ +``` + +### ๋‹ค๋‹จ๊ณ„ ์›Œํฌํ”Œ๋กœ์šฐ + +```bash +# Step 1: Create the directory +mkdir -p .claude/commands + +# Step 2: Copy the templates +cp 01-slash-commands/*.md .claude/commands/ + +# Step 3: Verify installation +ls .claude/commands/ +``` + +--- + +## ๋งํฌ ๋ฐ ์ƒํ˜ธ ์ฐธ์กฐ + +### ๋‚ด๋ถ€ ๋งํฌ(์ƒ๋Œ€ ๊ฒฝ๋กœ) + +๋ชจ๋“  ๋‚ด๋ถ€ ๋งํฌ์—๋Š” ์ƒ๋Œ€ ๊ฒฝ๋กœ๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + +```markdown +[Slash Commands](01-slash-commands/) +[Skills Guide](03-skills/) +[Memory Architecture](02-memory/#memory-architecture) +``` + +๊ฐ•์˜ ํด๋”์—์„œ ๋ฃจํŠธ ๋˜๋Š” ๋‹ค๋ฅธ ๊ฐ•์˜ ํด๋”๋กœ ์ด๋™ํ•  ๋•Œ: + +```markdown +[Back to main guide](../README.md) +[Related: Skills](../03-skills/) +``` + +### ์™ธ๋ถ€ ๋งํฌ(์ ˆ๋Œ€ ๊ฒฝ๋กœ) + +์„ค๋ช…์ ์ธ ์•ต์ปค ํ…์ŠคํŠธ์™€ ํ•จ๊ป˜ ์ „์ฒด URL์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + +```markdown +[Anthropic's official documentation](https://code.claude.com/docs/en/overview) +``` + +- ์•ต์ปค ํ…์ŠคํŠธ๋กœ "click here" ๋˜๋Š” "this link"๋ฅผ ์‚ฌ์šฉํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. +- ๋ฌธ๋งฅ ์—†์ด๋„ ์˜๋ฏธ๊ฐ€ ์ „๋‹ฌ๋˜๋Š” ์„ค๋ช…์ ์ธ ํ…์ŠคํŠธ๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + +### ์„น์…˜ ์•ต์ปค + +๋™์ผ ๋ฌธ์„œ ๋‚ด ์„น์…˜ ๋งํฌ์—๋Š” GitHub ์Šคํƒ€์ผ ์•ต์ปค๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + +```markdown +[Feature Catalog](#-feature-catalog) +[Best Practices](#best-practices) +``` + +### ๊ด€๋ จ ๊ฐ€์ด๋“œ ํŒจํ„ด + +๊ฐ ๊ฐ•์˜๋Š” ๊ด€๋ จ ๊ฐ€์ด๋“œ ์„น์…˜์œผ๋กœ ๋งˆ๋ฌด๋ฆฌํ•ฉ๋‹ˆ๋‹ค. + +```markdown +## Related Guides + +- [Slash Commands](../01-slash-commands/) - Quick shortcuts +- [Memory](../02-memory/) - Persistent context +- [Skills](../03-skills/) - Reusable capabilities +``` + +--- + +## ๋‹ค์ด์–ด๊ทธ๋žจ + +### Mermaid + +๋ชจ๋“  ๋‹ค์ด์–ด๊ทธ๋žจ์—๋Š” Mermaid๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. ์ง€์›๋˜๋Š” ์œ ํ˜•์€ ๋‹ค์Œ๊ณผ ๊ฐ™์Šต๋‹ˆ๋‹ค. + +- `graph TB` / `graph LR` โ€” ์•„ํ‚คํ…์ฒ˜, ๊ณ„์ธต ๊ตฌ์กฐ, ํ๋ฆ„ +- `sequenceDiagram` โ€” ์ƒํ˜ธ์ž‘์šฉ ํ๋ฆ„ +- `timeline` โ€” ์‹œ๊ฐ„ ์ˆœ์„œ ํ๋ฆ„ + +### ์Šคํƒ€์ผ ๊ทœ์น™ + +์Šคํƒ€์ผ ๋ธ”๋ก์„ ์‚ฌ์šฉํ•˜์—ฌ ์ผ๊ด€๋œ ์ƒ‰์ƒ์„ ์ ์šฉํ•ฉ๋‹ˆ๋‹ค. + +```mermaid +graph TB + A["Component A"] --> B["Component B"] + B --> C["Component C"] + + style A fill:#e1f5fe,stroke:#333,color:#333 + style B fill:#fce4ec,stroke:#333,color:#333 + style C fill:#e8f5e9,stroke:#333,color:#333 +``` + +**์ƒ‰์ƒ ํŒ”๋ ˆํŠธ:** + +| Color | Hex | Use For | +|-------|-----|---------| +| Light blue | `#e1f5fe` | Primary components, inputs | +| Light pink | `#fce4ec` | Processing, middleware | +| Light green | `#e8f5e9` | Outputs, results | +| Light yellow | `#fff9c4` | Configuration, optional | +| Light purple | `#f3e5f5` | User-facing, UI | + +### ๊ทœ์น™ + +- ๋…ธ๋“œ ๋ ˆ์ด๋ธ”์—๋Š” `["Label text"]` ํ˜•์‹์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค(ํŠน์ˆ˜ ๋ฌธ์ž ์‚ฌ์šฉ ๊ฐ€๋Šฅ). +- ๋ ˆ์ด๋ธ” ๋‚ด ์ค„๋ฐ”๊ฟˆ์—๋Š” `
`๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +- ๋‹ค์ด์–ด๊ทธ๋žจ์€ ๋‹จ์ˆœํ•˜๊ฒŒ ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค(์ตœ๋Œ€ 10~12๊ฐœ ๋…ธ๋“œ). +- ์ ‘๊ทผ์„ฑ์„ ์œ„ํ•ด ๋‹ค์ด์–ด๊ทธ๋žจ ์•„๋ž˜์— ๊ฐ„๋‹จํ•œ ์„ค๋ช…์„ ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค. +- ๊ณ„์ธต ๊ตฌ์กฐ์—๋Š” ์œ„์—์„œ ์•„๋ž˜ ๋ฐฉํ–ฅ(`TB`), ์›Œํฌํ”Œ๋กœ์šฐ์—๋Š” ์™ผ์ชฝ์—์„œ ์˜ค๋ฅธ์ชฝ ๋ฐฉํ–ฅ(`LR`)์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + +--- + +## ์ด๋ชจ์ง€ ์‚ฌ์šฉ + +### ์ด๋ชจ์ง€๋ฅผ ์‚ฌ์šฉํ•˜๋Š” ์œ„์น˜ + +์ด๋ชจ์ง€๋Š” **์‹ ์ค‘ํ•˜๊ณ  ๋ชฉ์ ์— ๋งž๊ฒŒ** ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. ๋‹ค์Œ๊ณผ ๊ฐ™์€ ํŠน์ • ์ƒํ™ฉ์—์„œ๋งŒ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + +| Context | Emojis | Example | +| --------------- | --------- | ----------------------------------------- | +| ๋ฃจํŠธ README ์„น์…˜ ์ œ๋ชฉ | ์นดํ…Œ๊ณ ๋ฆฌ ์•„์ด์ฝ˜ | `## ๐Ÿ“š Learning Path` | +| ์ˆ™๋ จ๋„ ํ‘œ์‹œ | ์ƒ‰์ƒ ์›ํ˜• ์•„์ด์ฝ˜ | ๐ŸŸข Beginner, ๐Ÿ”ต Intermediate, ๐Ÿ”ด Advanced | +| ๊ถŒ์žฅ ์‚ฌํ•ญ ๋ฐ ๊ธˆ์ง€ ์‚ฌํ•ญ | ์ฒดํฌ/์—‘์Šค ํ‘œ์‹œ | โœ… Do this, โŒ Don't do this | +| ๋ณต์žก๋„ ๋“ฑ๊ธ‰ | ๋ณ„ํ‘œ | โญโญโญ | + +### ํ‘œ์ค€ ์ด๋ชจ์ง€ ์„ธํŠธ + +| Emoji | Meaning | +| ----- | --------------- | +| ๐Ÿ“š | ํ•™์Šต, ๊ฐ€์ด๋“œ, ๋ฌธ์„œ | +| โšก | ์‹œ์ž‘ํ•˜๊ธฐ, ๋น ๋ฅธ ์ฐธ์กฐ | +| ๐ŸŽฏ | ๊ธฐ๋Šฅ, ๋น ๋ฅธ ์ฐธ์กฐ | +| ๐ŸŽ“ | ํ•™์Šต ๊ฒฝ๋กœ | +| ๐Ÿ“Š | ํ†ต๊ณ„, ๋น„๊ต | +| ๐Ÿš€ | ์„ค์น˜, ๋น ๋ฅธ ๋ช…๋ น์–ด | +| ๐ŸŸข | ์ดˆ๊ธ‰ ์ˆ˜์ค€ | +| ๐Ÿ”ต | ์ค‘๊ธ‰ ์ˆ˜์ค€ | +| ๐Ÿ”ด | ๊ณ ๊ธ‰ ์ˆ˜์ค€ | +| โœ… | ๊ถŒ์žฅ๋˜๋Š” ๋ฐฉ์‹ | +| โŒ | ํ”ผํ•ด์•ผ ํ•  ๋ฐฉ์‹ / ์•ˆํ‹ฐํŒจํ„ด | +| โญ | ๋ณต์žก๋„ ๋“ฑ๊ธ‰ ๋‹จ์œ„ | + +### ๊ทœ์น™ + +- **๋ณธ๋ฌธ์ด๋‚˜ ๋ฌธ๋‹จ์—๋Š” ์ด๋ชจ์ง€๋ฅผ ์‚ฌ์šฉํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค.** +- **์ด๋ชจ์ง€๋Š” ๋ฃจํŠธ README์˜ ์ œ๋ชฉ์—์„œ๋งŒ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค.** (๊ฐ•์˜ README์—์„œ๋Š” ์‚ฌ์šฉํ•˜์ง€ ์•Š์Œ) +- **์žฅ์‹์šฉ ์ด๋ชจ์ง€๋ฅผ ์ถ”๊ฐ€ํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค.** ๋ชจ๋“  ์ด๋ชจ์ง€๋Š” ์˜๋ฏธ๋ฅผ ์ „๋‹ฌํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. +- ์œ„ ํ‘œ์— ์ •์˜๋œ ์‚ฌ์šฉ ๋ฐฉ์‹์„ ์ผ๊ด€๋˜๊ฒŒ ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. + +--- + +## YAML ํ”„๋ŸฐํŠธ๋งคํ„ฐ + +### ๊ธฐ๋Šฅ ํŒŒ์ผ(Skills, Commands, Agents) + +```yaml +--- +name: unique-identifier +description: What this feature does and when to use it +allowed-tools: Bash, Read, Grep +--- +``` + +### ์„ ํƒ ํ•„๋“œ + +```yaml +--- +name: my-feature +description: Brief description +argument-hint: "[file-path] [options]" +allowed-tools: Bash, Read, Grep, Write, Edit +model: opus # opus, sonnet, or haiku +disable-model-invocation: true # User-only invocation +user-invocable: false # Hidden from user menu +context: fork # Run in isolated subagent +agent: Explore # Agent type for context: fork +--- +``` + +### ๊ทœ์น™ + +- ํ”„๋ŸฐํŠธ๋งคํ„ฐ๋Š” ํ•ญ์ƒ ํŒŒ์ผ ์ตœ์ƒ๋‹จ์— ๋ฐฐ์น˜ํ•ฉ๋‹ˆ๋‹ค. +- `name` ํ•„๋“œ์—๋Š” **kebab-case**๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +- `description`์€ ํ•œ ๋ฌธ์žฅ์œผ๋กœ ์ž‘์„ฑํ•ฉ๋‹ˆ๋‹ค. +- ํ•„์š”ํ•œ ํ•„๋“œ๋งŒ ํฌํ•จํ•ฉ๋‹ˆ๋‹ค. + +--- + +## ์ด๋ฏธ์ง€ ๋ฐ ๋ฏธ๋””์–ด + +### ๋กœ๊ณ  ํŒจํ„ด + +๋กœ๊ณ ๋กœ ์‹œ์ž‘ํ•˜๋Š” ๋ชจ๋“  ๋ฌธ์„œ๋Š” ๋‹คํฌ ๋ชจ๋“œ์™€ ๋ผ์ดํŠธ ๋ชจ๋“œ ์ง€์›์„ ์œ„ํ•ด `` ์š”์†Œ๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค: + + +```html + + + Claude How To + +``` + +### ์Šคํฌ๋ฆฐ์ƒท + +- ๊ด€๋ จ ๊ฐ•์˜ ํด๋”์— ์ €์žฅํ•ฉ๋‹ˆ๋‹ค(์˜ˆ: `01-slash-commands/pr-slash-command.png`). +- ํŒŒ์ผ ์ด๋ฆ„์€ kebab-case๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +- ์„ค๋ช…์ด ํฌํ•จ๋œ alt ํ…์ŠคํŠธ๋ฅผ ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค. +- ๋‹ค์ด์–ด๊ทธ๋žจ์—๋Š” SVG, ์Šคํฌ๋ฆฐ์ƒท์—๋Š” PNG๋ฅผ ์šฐ์„  ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + +### ๊ทœ์น™ + +- ๋ชจ๋“  ์ด๋ฏธ์ง€์— alt ํ…์ŠคํŠธ๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. +- ์ด๋ฏธ์ง€ ํŒŒ์ผ ํฌ๊ธฐ๋Š” ์ ์ ˆํ•˜๊ฒŒ ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค(PNG ๊ธฐ์ค€ 500KB ์ดํ•˜ ๊ถŒ์žฅ). +- ์ด๋ฏธ์ง€ ์ฐธ์กฐ์—๋Š” ์ƒ๋Œ€ ๊ฒฝ๋กœ๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +- ์ด๋ฏธ์ง€๋Š” ํ•ด๋‹น ๋ฌธ์„œ์™€ ๊ฐ™์€ ๋””๋ ‰ํ„ฐ๋ฆฌ ๋˜๋Š” ๊ณต์šฉ ์ด๋ฏธ์ง€์šฉ `assets/` ๋””๋ ‰ํ„ฐ๋ฆฌ์— ์ €์žฅํ•ฉ๋‹ˆ๋‹ค. + +--- + +## ํ†ค๊ณผ ๋ฌธ์ฒด + +### ์ž‘์„ฑ ์Šคํƒ€์ผ + +- **์ „๋ฌธ์ ์ด์ง€๋งŒ ์นœ๊ทผํ•˜๊ฒŒ** โ€” ๊ธฐ์ˆ ์  ์ •ํ™•์„ฑ์„ ์œ ์ง€ํ•˜๋˜ ๊ณผ๋„ํ•œ ์ „๋ฌธ ์šฉ์–ด ์‚ฌ์šฉ์€ ํ”ผํ•ฉ๋‹ˆ๋‹ค. +- **๋Šฅ๋™ํ˜• ๋ฌธ์žฅ ์‚ฌ์šฉ** โ€” "A file should be created" ๋Œ€์‹  "Create a file" ํ˜•ํƒœ๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +- **์ง์ ‘์ ์ธ ์ง€์‹œ๋ฌธ ์‚ฌ์šฉ** โ€” "You might want to run this command" ๋Œ€์‹  "Run this command"๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +- **์ดˆ๋ณด์ž ์นœํ™”์ ** โ€” ๋…์ž๊ฐ€ Claude Code์—๋Š” ์ต์ˆ™ํ•˜์ง€ ์•Š์ง€๋งŒ ํ”„๋กœ๊ทธ๋ž˜๋ฐ์€ ์•Œ๊ณ  ์žˆ๋‹ค๊ณ  ๊ฐ€์ •ํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. + +### ์ฝ˜ํ…์ธ  ์›์น™ + +| Principle | Example | +| -------------------------- | -------------------------------------------------------------- | +| **Show, don't tell** | ์ถ”์ƒ์ ์ธ ์„ค๋ช…๋ณด๋‹ค ๋™์ž‘ํ•˜๋Š” ์˜ˆ์ œ๋ฅผ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค | +| **Progressive complexity** | ๊ฐ„๋‹จํ•œ ๋‚ด์šฉ์œผ๋กœ ์‹œ์ž‘ํ•˜์—ฌ ์ดํ›„ ์„น์…˜์—์„œ ์‹ฌํ™” ๋‚ด์šฉ์„ ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค | +| **Explain the "why"** | "Use memory for..."๊ฐ€ ์•„๋‹ˆ๋ผ "Use memory for... because..."๋ฅผ ์„ค๋ช…ํ•ฉ๋‹ˆ๋‹ค | +| **Copy-paste ready** | ๋ชจ๋“  ์ฝ”๋“œ ๋ธ”๋ก์€ ๊ทธ๋Œ€๋กœ ๋ณต์‚ฌํ•˜์—ฌ ์‹คํ–‰ ๊ฐ€๋Šฅํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค | +| **Real-world context** | ์ธ์œ„์ ์ธ ์˜ˆ์ œ๊ฐ€ ์•„๋‹Œ ์‹ค์ œ ์ƒํ™ฉ์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค | + +### ์šฉ์–ด ์‚ฌ์šฉ + +- "Claude Code"๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค("Claude CLI" ๋˜๋Š” "the tool" ์‚ฌ์šฉ ๊ธˆ์ง€). +- "skill"์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค("custom command"๋Š” ๊ณผ๊ฑฐ ์šฉ์–ด). +- ๋ฒˆํ˜ธ๊ฐ€ ์žˆ๋Š” ์„น์…˜์—๋Š” "lesson" ๋˜๋Š” "guide"๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +- ๊ฐœ๋ณ„ ๊ธฐ๋Šฅ ํŒŒ์ผ์—๋Š” "example"์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + + +--- + +## ์ปค๋ฐ‹ ๋ฉ”์‹œ์ง€ + +[Conventional Commits](https://www.conventionalcommits.org/) ๊ทœ์น™์„ ๋”ฐ๋ฆ…๋‹ˆ๋‹ค. + +``` +type(scope): description +``` + +### ํƒ€์ž… + +| Type | Use For | +| ---------- | ---------------------- | +| `feat` | ์ƒˆ๋กœ์šด ๊ธฐ๋Šฅ, ์˜ˆ์ œ ๋˜๋Š” ๊ฐ€์ด๋“œ | +| `fix` | ๋ฒ„๊ทธ ์ˆ˜์ •, ์˜ค๋ฅ˜ ์ •์ •, ๊นจ์ง„ ๋งํฌ ์ˆ˜์ • | +| `docs` | ๋ฌธ์„œ ๊ฐœ์„  | +| `refactor` | ๋™์ž‘ ๋ณ€๊ฒฝ ์—†๋Š” ๊ตฌ์กฐ ๊ฐœ์„  | +| `style` | ์„œ์‹ ๋ณ€๊ฒฝ๋งŒ ์ˆ˜ํ–‰ | +| `test` | ํ…Œ์ŠคํŠธ ์ถ”๊ฐ€ ๋˜๋Š” ์ˆ˜์ • | +| `chore` | ๋นŒ๋“œ, ์˜์กด์„ฑ, CI ๊ด€๋ จ ์ž‘์—… | + +### ์Šค์ฝ”ํ”„ + +๊ฐ•์˜ ์ด๋ฆ„ ๋˜๋Š” ํŒŒ์ผ ์˜์—ญ์„ ์Šค์ฝ”ํ”„๋กœ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + +``` +feat(slash-commands): Add API documentation generator +docs(memory): Improve personal preferences example +fix(README): Correct table of contents link +docs(skills): Add comprehensive code review skill +``` + +--- + +## ๋ฌธ์„œ ๋ฉ”ํƒ€๋ฐ์ดํ„ฐ ํ‘ธํ„ฐ + +๊ฐ•์˜ README๋Š” ๋‹ค์Œ ๋ฉ”ํƒ€๋ฐ์ดํ„ฐ ๋ธ”๋ก์œผ๋กœ ๋งˆ๋ฌด๋ฆฌํ•ฉ๋‹ˆ๋‹ค. + +```markdown +--- +**Last Updated**: May 29, 2026 +**Claude Code Version**: 2.1.156 +**Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5 +``` + +- ๋‚ ์งœ๋Š” ์›” + ์ผ + ์—ฐ๋„ ํ˜•์‹์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค(์˜ˆ: "May 20, 2026"). +- ๊ธฐ๋Šฅ์ด ๋ณ€๊ฒฝ๋˜๋ฉด ๋ฒ„์ „์„ ์—…๋ฐ์ดํŠธํ•ฉ๋‹ˆ๋‹ค. +- ๋ชจ๋“  ํ˜ธํ™˜ ๋ชจ๋ธ์„ ๋‚˜์—ดํ•ฉ๋‹ˆ๋‹ค. + + +--- + +## ์ž‘์„ฑ์ž ์ฒดํฌ๋ฆฌ์ŠคํŠธ + +์ฝ˜ํ…์ธ  ์ œ์ถœ ์ „์— ๋‹ค์Œ ์‚ฌํ•ญ์„ ํ™•์ธํ•˜์‹ญ์‹œ์˜ค. + +- [ ] ํŒŒ์ผ/ํด๋” ์ด๋ฆ„์ด kebab-case๋ฅผ ์‚ฌ์šฉํ•˜๋Š”๊ฐ€ +- [ ] ๋ฌธ์„œ๊ฐ€ H1 ์ œ๋ชฉ์œผ๋กœ ์‹œ์ž‘ํ•˜๋Š”๊ฐ€(ํŒŒ์ผ๋‹น 1๊ฐœ) +- [ ] ์ œ๋ชฉ ๊ณ„์ธต ๊ตฌ์กฐ๊ฐ€ ์˜ฌ๋ฐ”๋ฅธ๊ฐ€(๋‹จ๊ณ„ ์ƒ๋žต ์—†์Œ) +- [ ] ๋ชจ๋“  ์ฝ”๋“œ ๋ธ”๋ก์— ์–ธ์–ด ํƒœ๊ทธ๊ฐ€ ์žˆ๋Š”๊ฐ€ +- [ ] ์ฝ”๋“œ ์˜ˆ์ œ๊ฐ€ ๋ฐ”๋กœ ๋ณต์‚ฌํ•˜์—ฌ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ๋Š” ์ƒํƒœ์ธ๊ฐ€ +- [ ] ๋‚ด๋ถ€ ๋งํฌ๊ฐ€ ์ƒ๋Œ€ ๊ฒฝ๋กœ๋ฅผ ์‚ฌ์šฉํ•˜๋Š”๊ฐ€ +- [ ] ์™ธ๋ถ€ ๋งํฌ์— ์„ค๋ช…์ ์ธ ์•ต์ปค ํ…์ŠคํŠธ๊ฐ€ ์žˆ๋Š”๊ฐ€ +- [ ] ํ‘œ ํ˜•์‹์ด ์˜ฌ๋ฐ”๋ฅธ๊ฐ€ +- [ ] ์ด๋ชจ์ง€๊ฐ€ ํ‘œ์ค€ ๊ทœ์น™์„ ๋”ฐ๋ฅด๋Š”๊ฐ€(์‚ฌ์šฉํ•œ ๊ฒฝ์šฐ) +- [ ] Mermaid ๋‹ค์ด์–ด๊ทธ๋žจ์ด ํ‘œ์ค€ ์ƒ‰์ƒ ํŒ”๋ ˆํŠธ๋ฅผ ์‚ฌ์šฉํ•˜๋Š”๊ฐ€ +- [ ] ๋ฏผ๊ฐํ•œ ์ •๋ณด(API ํ‚ค, ์ž๊ฒฉ ์ฆ๋ช…)๊ฐ€ ํฌํ•จ๋˜์ง€ ์•Š์•˜๋Š”๊ฐ€ +- [ ] YAML ํ”„๋ŸฐํŠธ๋งคํ„ฐ๊ฐ€ ์œ ํšจํ•œ๊ฐ€(ํ•ด๋‹นํ•˜๋Š” ๊ฒฝ์šฐ) +- [ ] ์ด๋ฏธ์ง€์— alt ํ…์ŠคํŠธ๊ฐ€ ์žˆ๋Š”๊ฐ€ +- [ ] ๋ฌธ๋‹จ์ด ์งง๊ณ  ํ•ต์‹ฌ์— ์ง‘์ค‘๋˜์–ด ์žˆ๋Š”๊ฐ€ +- [ ] ๊ด€๋ จ ๊ฐ€์ด๋“œ ์„น์…˜์ด ์ ์ ˆํ•œ ๊ฐ•์˜๋ฅผ ๋งํฌํ•˜๋Š”๊ฐ€ +- [ ] ์ปค๋ฐ‹ ๋ฉ”์‹œ์ง€๊ฐ€ Conventional Commits ํ˜•์‹์„ ๋”ฐ๋ฅด๋Š”๊ฐ€ + + +--- + +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: 2026๋…„ 5์›” 29์ผ +**Claude Code ๋ฒ„์ „**: 2.1.156 +**์ถœ์ฒ˜**: +- https://code.claude.com/docs/en/overview +- https://code.claude.com/docs/en/changelog +- https://www.anthropic.com/news/claude-opus-4-8 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.154 +**ํ˜ธํ™˜ ๋ชจ๋ธ**: Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5 diff --git a/ko/claude-howto-logo.png b/ko/claude-howto-logo.png new file mode 100644 index 00000000..94d34a45 Binary files /dev/null and b/ko/claude-howto-logo.png differ diff --git a/ko/claude-howto-logo.svg b/ko/claude-howto-logo.svg new file mode 100644 index 00000000..af7931ac --- /dev/null +++ b/ko/claude-howto-logo.svg @@ -0,0 +1,162 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + $_ + + + + + + + + + + + + + Claude- + + + + + Howto + + + + + + Visual guide to Claude Code โ€” examples you can use today + + + + + <agent> + skill.invoke() + /commit + CLAUDE.md + hooks[] + + + + + + + + + + + + + + + + + + + v1.0+ + + diff --git a/ko/clean-code-rules.md b/ko/clean-code-rules.md new file mode 100644 index 00000000..df5c90d2 --- /dev/null +++ b/ko/clean-code-rules.md @@ -0,0 +1,126 @@ +# AI ์ฝ”๋“œ ์ƒ์„ฑ์„ ์œ„ํ•œ ํด๋ฆฐ ์ฝ”๋“œ ๊ทœ์น™ + +์ด ๊ทœ์น™์€ ์œ ์ง€๋ณด์ˆ˜ ๊ฐ€๋Šฅํ•˜๊ณ  ์ „๋ฌธ์ ์ธ ํ’ˆ์งˆ์˜ ์ฝ”๋“œ๋ฅผ ์ƒ์„ฑํ•˜๋„๋ก ์ฝ”๋“œ ์ƒ์„ฑ์„ ์•ˆ๋‚ดํ•ฉ๋‹ˆ๋‹ค. + +## ์˜๋ฏธ ์žˆ๋Š” ์ด๋ฆ„ + +* ์กด์žฌ ์ด์œ ๋ฅผ ์„ค๋ช…ํ•˜๋Š” ์˜๋„๊ฐ€ ๋“œ๋Ÿฌ๋‚˜๋Š” ์ด๋ฆ„์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +* ์˜คํ•ด๋ฅผ ์œ ๋ฐœํ•˜๊ฑฐ๋‚˜ ์˜๋ฏธ ์—†๋Š” ๊ตฌ๋ถ„(`data`, `info`, `manager` ๋“ฑ)์„ ํ”ผํ•ฉ๋‹ˆ๋‹ค. +* ๋ฐœ์Œํ•˜๊ธฐ ์‰ฝ๊ณ  ๊ฒ€์ƒ‰ ๊ฐ€๋Šฅํ•œ ์ด๋ฆ„์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +* ํด๋ž˜์Šค ์ด๋ฆ„: ๋ช…์‚ฌ (์˜ˆ: `UserAccount`, `PaymentProcessor`) +* ๋ฉ”์„œ๋“œ ์ด๋ฆ„: ๋™์‚ฌ (์˜ˆ: `calculateTotal`, `sendEmail`) +* ์ •์‹ ์  ๋งคํ•‘๊ณผ ์ธ์ฝ”๋”ฉ(ํ—๊ฐ€๋ฆฌ์•ˆ ํ‘œ๊ธฐ๋ฒ•, ์ ‘๋‘์‚ฌ ๋“ฑ)์„ ํ”ผํ•ฉ๋‹ˆ๋‹ค. + +## ํ•จ์ˆ˜ + +* ํ•จ์ˆ˜๋Š” ์ž‘๊ฒŒ ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค(์ด์ƒ์ ์œผ๋กœ 20์ค„ ๋ฏธ๋งŒ). +* ํ•˜๋‚˜์˜ ์ผ๋งŒ ์ˆ˜ํ–‰ํ•ฉ๋‹ˆ๋‹ค - ๋‹จ์ผ ์ฑ…์ž„ ์›์น™(Single Responsibility Principle) +* ํ•จ์ˆ˜๋งˆ๋‹ค ํ•˜๋‚˜์˜ ์ถ”์ƒํ™” ์ˆ˜์ค€๋งŒ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +* ๋งค๊ฐœ๋ณ€์ˆ˜๋Š” ์ œํ•œํ•ฉ๋‹ˆ๋‹ค: ์ด์ƒ์ ์œผ๋กœ 0~2๊ฐœ, ์ตœ๋Œ€ 3๊ฐœ, ํ”Œ๋ž˜๊ทธ ์ธ์ˆ˜๋Š” ํ”ผํ•ฉ๋‹ˆ๋‹ค. +* ๋ถ€์ž‘์šฉ์ด ์—†์–ด์•ผ ํ•ฉ๋‹ˆ๋‹ค - ํ•จ์ˆ˜๋Š” ์ด๋ฆ„์ด ์˜๋ฏธํ•˜๋Š” ๋™์ž‘๋งŒ ์ˆ˜ํ–‰ํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. +* ๋ช…๋ น(์ƒํƒœ ๋ณ€๊ฒฝ)๊ณผ ์กฐํšŒ(์ •๋ณด ๋ฐ˜ํ™˜)๋ฅผ ๋ถ„๋ฆฌํ•ฉ๋‹ˆ๋‹ค. +* ์˜ค๋ฅ˜ ์ฝ”๋“œ๋ณด๋‹ค ์˜ˆ์™ธ๋ฅผ ์„ ํ˜ธํ•ฉ๋‹ˆ๋‹ค. + +## ์ฃผ์„ + +* ์ฝ”๋“œ๋Š” ์Šค์Šค๋กœ ์„ค๋ช… ๊ฐ€๋Šฅํ•ด์•ผ ํ•˜๋ฏ€๋กœ ๊ฐ€๋Šฅํ•œ ํ•œ ์ฃผ์„์„ ํ”ผํ•ฉ๋‹ˆ๋‹ค. +* ์ข‹์€ ์ฃผ์„: ๋ฒ•์  ์ •๋ณด, ๊ฒฝ๊ณ , TODO, ๊ณต๊ฐœ API ๋ฌธ์„œ +* ๋‚˜์œ ์ฃผ์„: ์ค‘๋ณต, ์˜คํ•ด๋ฅผ ์œ ๋ฐœํ•˜๋Š” ๋‚ด์šฉ, ์ž˜๋ชป๋œ ์ฝ”๋“œ๋ฅผ ์„ค๋ช…ํ•˜๋Š” ๋‚ด์šฉ +* ์ฝ”๋“œ๋ฅผ ์ฃผ์„ ์ฒ˜๋ฆฌํ•˜์ง€ ๋งˆ์‹ญ์‹œ์˜ค - ์‚ญ์ œํ•˜์‹ญ์‹œ์˜ค(๋ฒ„์ „ ๊ด€๋ฆฌ ์‹œ์Šคํ…œ์ด ์ด๋ ฅ์„ ๋ณด์กดํ•ฉ๋‹ˆ๋‹ค). +* ์ฃผ์„์ด ํ•„์š”ํ•˜๋‹ค๋ฉด ๋จผ์ € ๋ฆฌํŒฉํ† ๋งํ•  ์ˆ˜ ์žˆ๋Š”์ง€ ๊ฒ€ํ† ํ•˜์‹ญ์‹œ์˜ค. + +## ํฌ๋งทํŒ… + +* ํŒŒ์ผ์€ ์ž‘๊ณ  ํ•˜๋‚˜์˜ ๋ชฉ์ ์— ์ง‘์ค‘๋˜๋„๋ก ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. +* ์„ธ๋กœ ํฌ๋งทํŒ…: ๊ด€๋ จ ๊ฐœ๋…์€ ๊ฐ€๊น๊ฒŒ ๋ฐฐ์น˜ํ•˜๊ณ , ๋นˆ ์ค„๋กœ ๊ฐœ๋…์„ ๊ตฌ๋ถ„ํ•ฉ๋‹ˆ๋‹ค. +* ๊ฐ€๋กœ ํฌ๋งทํŒ…: ์ค„ ๊ธธ์ด๋ฅผ ์ œํ•œํ•ฉ๋‹ˆ๋‹ค(80~120์ž). +* ์ผ๊ด€๋œ ๋“ค์—ฌ์“ฐ๊ธฐ์™€ ํŒ€ ์Šคํƒ€์ผ์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +* ๊ด€๋ จ๋œ ํ•จ์ˆ˜๋“ค์„ ํ•จ๊ป˜ ๋ฐฐ์น˜ํ•ฉ๋‹ˆ๋‹ค. + +## ๊ฐ์ฒด์™€ ๋ฐ์ดํ„ฐ ๊ตฌ์กฐ + +* ๊ฐ์ฒด: ๋ฐ์ดํ„ฐ๋ฅผ ์ถ”์ƒํ™” ๋’ค์— ์ˆจ๊ธฐ๊ณ  ๋ฉ”์„œ๋“œ๋ฅผ ํ†ตํ•ด ๋™์ž‘์„ ๋…ธ์ถœํ•ฉ๋‹ˆ๋‹ค. +* ๋ฐ์ดํ„ฐ ๊ตฌ์กฐ: ๋ฐ์ดํ„ฐ๋ฅผ ๋…ธ์ถœํ•˜๊ณ  ๋™์ž‘์€ ์ตœ์†Œํ™”ํ•ฉ๋‹ˆ๋‹ค. +* ๋””๋ฏธํ„ฐ ๋ฒ•์น™(Law of Demeter): ์ง์ ‘์ ์ธ ํ˜‘๋ ฅ ๊ฐ์ฒด์™€๋งŒ ์ƒํ˜ธ์ž‘์šฉํ•˜๋ฉฐ, `a.getB().getC().doSomething()` ํ˜•ํƒœ๋ฅผ ํ”ผํ•ฉ๋‹ˆ๋‹ค. +* Getter/Setter๋ฅผ ๋ฌด๋ถ„๋ณ„ํ•˜๊ฒŒ ์‚ฌ์šฉํ•˜์—ฌ ๋‚ด๋ถ€ ๊ตฌ์กฐ๋ฅผ ๋…ธ์ถœํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. + +## ์˜ค๋ฅ˜ ์ฒ˜๋ฆฌ + +* ๋ฐ˜ํ™˜ ์ฝ”๋“œ๋‚˜ ์˜ค๋ฅ˜ ํ”Œ๋ž˜๊ทธ ๋Œ€์‹  ์˜ˆ์™ธ๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +* ์‹คํŒจ ๊ฐ€๋Šฅ์„ฑ์ด ์žˆ๋Š” ์ฝ”๋“œ์—์„œ๋Š” ๋จผ์ € `try-catch-finally` ๊ตฌ์กฐ๋ฅผ ๊ณ ๋ คํ•ฉ๋‹ˆ๋‹ค. +* ์˜ˆ์™ธ ๋ฉ”์‹œ์ง€์— ์ถฉ๋ถ„ํ•œ ๋ฌธ๋งฅ์„ ์ œ๊ณตํ•ฉ๋‹ˆ๋‹ค. +* `null`์„ ๋ฐ˜ํ™˜ํ•˜์ง€ ๋งˆ์‹ญ์‹œ์˜ค - ๋นˆ ์ปฌ๋ ‰์…˜ ๋˜๋Š” Optional/Maybe๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +* `null`์„ ์ธ์ˆ˜๋กœ ์ „๋‹ฌํ•˜์ง€ ๋งˆ์‹ญ์‹œ์˜ค. + +## ํด๋ž˜์Šค + +* ํด๋ž˜์Šค์˜ ํฌ๊ธฐ๋Š” ์ค„ ์ˆ˜๊ฐ€ ์•„๋‹Œ ์ฑ…์ž„์˜ ๊ฐœ์ˆ˜๋กœ ํŒ๋‹จํ•ฉ๋‹ˆ๋‹ค. +* ๋‹จ์ผ ์ฑ…์ž„ ์›์น™(SRP): ๋ณ€๊ฒฝ ์ด์œ ๋Š” ํ•˜๋‚˜์—ฌ์•ผ ํ•ฉ๋‹ˆ๋‹ค. +* ๋†’์€ ์‘์ง‘๋„: ํด๋ž˜์Šค ๋ณ€์ˆ˜๋“ค์ด ์—ฌ๋Ÿฌ ๋ฉ”์„œ๋“œ์—์„œ ํ•จ๊ป˜ ์‚ฌ์šฉ๋˜์–ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. +* ๋‚ฎ์€ ๊ฒฐํ•ฉ๋„: ํด๋ž˜์Šค ๊ฐ„ ์˜์กด์„ฑ์„ ์ตœ์†Œํ™”ํ•ฉ๋‹ˆ๋‹ค. +* ๊ฐœ๋ฐฉ-ํ์‡„ ์›์น™(OCP): ํ™•์žฅ์—๋Š” ์—ด๋ ค ์žˆ๊ณ  ์ˆ˜์ •์—๋Š” ๋‹ซํ˜€ ์žˆ์–ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. + +## ๋‹จ์œ„ ํ…Œ์ŠคํŠธ + +* F.I.R.S.T. ์›์น™ ์ค€์ˆ˜: Fast, Independent, Repeatable, Self-validating, Timely +* ํ…Œ์ŠคํŠธ๋‹น ํ•˜๋‚˜์˜ ๊ฒ€์ฆ(๋˜๋Š” ํ•˜๋‚˜์˜ ๊ฐœ๋…) +* ํ…Œ์ŠคํŠธ ์ฝ”๋“œ ํ’ˆ์งˆ๋„ ์šด์˜ ์ฝ”๋“œ ํ’ˆ์งˆ๊ณผ ๋™์ผํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. +* ๋ฌด์—‡์„ ํ…Œ์ŠคํŠธํ•˜๋Š”์ง€ ์„ค๋ช…ํ•˜๋Š” ์ฝ๊ธฐ ์‰ฌ์šด ํ…Œ์ŠคํŠธ ์ด๋ฆ„์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +* Arrange-Act-Assert ํŒจํ„ด์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + +## ์ฝ”๋“œ ํ’ˆ์งˆ ์›์น™ + +* **DRY (Don't Repeat Yourself)**: ์ค‘๋ณต์„ ์ œ๊ฑฐํ•ฉ๋‹ˆ๋‹ค. +* **YAGNI (You Aren't Gonna Need It)**: ๊ฐ€์ƒ์˜ ๋ฏธ๋ž˜ ์š”๊ตฌ์‚ฌํ•ญ์„ ์œ„ํ•ด ๊ตฌํ˜„ํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. +* **KISS (Keep It Simple)**: ๋ถˆํ•„์š”ํ•œ ๋ณต์žก์„ฑ์„ ํ”ผํ•ฉ๋‹ˆ๋‹ค. +* **Boy Scout Rule**: ๋ฐœ๊ฒฌํ–ˆ์„ ๋•Œ๋ณด๋‹ค ๋” ๊นจ๋—ํ•œ ์ƒํƒœ๋กœ ์ฝ”๋“œ๋ฅผ ๋‚จ๊น๋‹ˆ๋‹ค. + +## ํ”ผํ•ด์•ผ ํ•  ์ฝ”๋“œ ์Šค๋ฉœ + +* ๊ธด ํ•จ์ˆ˜ ๋˜๋Š” ํด๋ž˜์Šค +* ์ค‘๋ณต ์ฝ”๋“œ +* ์ฃฝ์€ ์ฝ”๋“œ(์‚ฌ์šฉ๋˜์ง€ ์•Š๋Š” ๋ณ€์ˆ˜, ํ•จ์ˆ˜, ๋งค๊ฐœ๋ณ€์ˆ˜) +* Feature Envy(๋‹ค๋ฅธ ํด๋ž˜์Šค์— ๊ณผ๋„ํ•˜๊ฒŒ ์˜์กดํ•˜๋Š” ๋ฉ”์„œ๋“œ) +* Inappropriate Intimacy(ํด๋ž˜์Šค ๊ฐ„ ๊ณผ๋„ํ•œ ๋‚ด๋ถ€ ์ง€์‹ ๊ณต์œ ) +* ๊ธด ๋งค๊ฐœ๋ณ€์ˆ˜ ๋ชฉ๋ก +* Primitive Obsession(์ž‘์€ ๊ฐ์ฒด ๋Œ€์‹  ์›์‹œ ํƒ€์ž… ๊ณผ๋‹ค ์‚ฌ์šฉ) +* Switch/Case ๋ฌธ(๋‹คํ˜•์„ฑ ๊ณ ๋ ค) +* Temporary Field(์ผ๋ถ€ ์ƒํ™ฉ์—์„œ๋งŒ ์‚ฌ์šฉ๋˜๋Š” ํด๋ž˜์Šค ๋ณ€์ˆ˜) + +## ๋™์‹œ์„ฑ + +* ๋™์‹œ์„ฑ ์ฝ”๋“œ๋Š” ๋‹ค๋ฅธ ์ฝ”๋“œ์™€ ๋ถ„๋ฆฌํ•ฉ๋‹ˆ๋‹ค. +* ๋™๊ธฐํ™” ๋˜๋Š” ์ž ๊ธˆ ๋ฐ์ดํ„ฐ์˜ ๋ฒ”์œ„๋ฅผ ์ตœ์†Œํ™”ํ•ฉ๋‹ˆ๋‹ค. +* ์Šค๋ ˆ๋“œ ์•ˆ์ „ ์ปฌ๋ ‰์…˜์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +* ๋™๊ธฐํ™” ๊ตฌ๊ฐ„์€ ์งง๊ฒŒ ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. +* ์‹คํ–‰ ๋ชจ๋ธ๊ณผ ๋™์‹œ์„ฑ ๋„๊ตฌ๋ฅผ ์ถฉ๋ถ„ํžˆ ์ดํ•ดํ•ฉ๋‹ˆ๋‹ค. + +## ์‹œ์Šคํ…œ ์„ค๊ณ„ + +* ์ƒ์„ฑ๊ณผ ์‚ฌ์šฉ์„ ๋ถ„๋ฆฌํ•ฉ๋‹ˆ๋‹ค(์˜์กด์„ฑ ์ฃผ์ž…). +* ๋ณต์žกํ•œ ๊ฐ์ฒด ์ƒ์„ฑ์—๋Š” Factory, Builder๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. +* ๊ตฌํ˜„์ด ์•„๋‹Œ ์ธํ„ฐํŽ˜์ด์Šค์— ์˜์กดํ•ฉ๋‹ˆ๋‹ค. +* ์ƒ์†๋ณด๋‹ค ํ•ฉ์„ฑ์„ ์„ ํ˜ธํ•ฉ๋‹ˆ๋‹ค. +* ๋””์ž์ธ ํŒจํ„ด์€ ๋‹จ์ˆœํ™”๋ฅผ ์œ„ํ•ด ์‚ฌ์šฉํ•˜๋ฉฐ ๊ณผ์‹œ๋ฅผ ์œ„ํ•ด ์‚ฌ์šฉํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. + +## ๋ฆฌํŒฉํ† ๋ง + +* ๋Œ€๊ทœ๋ชจ ์ž‘์—…์ด ์•„๋‹Œ ์ง€์†์ ์œผ๋กœ ๋ฆฌํŒฉํ† ๋งํ•ฉ๋‹ˆ๋‹ค. +* ๋ฆฌํŒฉํ† ๋ง ์ „ํ›„ ๋ชจ๋‘ ํ…Œ์ŠคํŠธ๊ฐ€ ํ†ต๊ณผํ•ด์•ผ ํ•ฉ๋‹ˆ๋‹ค. +* ์ž‘์€ ๋‹จ๊ณ„๋กœ ์ง„ํ–‰ํ•ฉ๋‹ˆ๋‹ค - ํ•œ ๋ฒˆ์— ํ•˜๋‚˜์˜ ๋ณ€๊ฒฝ๋งŒ ์ˆ˜ํ–‰ํ•ฉ๋‹ˆ๋‹ค. +* ๋Œ€ํ‘œ์ ์ธ ๋ฆฌํŒฉํ† ๋ง: Extract Method, Rename, Move, Inline + +## ๋ฌธ์„œํ™” + +* ์ž๊ธฐ ์„ค๋ช…์ ์ธ ์ฝ”๋“œ > ์ฃผ์„ > ์™ธ๋ถ€ ๋ฌธ์„œ +* ๊ณต๊ฐœ API๋Š” ๋ช…ํ™•ํ•œ ๋ฌธ์„œ๊ฐ€ ํ•„์š”ํ•ฉ๋‹ˆ๋‹ค. +* ๋ฌธ์„œ์—๋Š” ์˜ˆ์ œ๋ฅผ ํฌํ•จํ•ฉ๋‹ˆ๋‹ค. +* ๋ฌธ์„œ๋Š” ์ฝ”๋“œ ๊ฐ€๊นŒ์ด์— ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค(๊ฐ€๋Šฅํ•˜๋ฉด ์ฝ”๋“œ ๋‚ด๋ถ€). + +--- + +**ํ•ต์‹ฌ ์ฒ ํ•™**: ์ฝ”๋“œ๋Š” ์ž‘์„ฑ๋˜๋Š” ๊ฒƒ๋ณด๋‹ค ์ฝํžˆ๋Š” ํšŸ์ˆ˜๊ฐ€ 10๋ฐฐ ๋” ๋งŽ์Šต๋‹ˆ๋‹ค. ์˜๋ฆฌํ•จ๋ณด๋‹ค ๊ฐ€๋…์„ฑ๊ณผ ์œ ์ง€๋ณด์ˆ˜์„ฑ์„ ์ตœ์šฐ์„ ์œผ๋กœ ์ตœ์ ํ™”ํ•˜์‹ญ์‹œ์˜ค. + +--- + +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: 2026๋…„ 4์›” 9์ผ diff --git a/ko/find_broken_fences.py b/ko/find_broken_fences.py new file mode 100644 index 00000000..51938829 --- /dev/null +++ b/ko/find_broken_fences.py @@ -0,0 +1,41 @@ +import re +from pathlib import Path + +# ๊ฒ€์‚ฌํ•  ํŒŒ์ผ ๊ฒฝ๋กœ +target_file = Path("./07-plugins/README.md") + +if not target_file.exists(): + print(f"โŒ ํŒŒ์ผ์„ ์ฐพ์„ ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค: {target_file}") + exit(1) + +with open(target_file, "r", encoding="utf-8") as f: + lines = f.readlines() + +# ์—ด๋ ค ์žˆ๋Š” ๋ฐฑํ‹ฑ์˜ ์œ„์น˜๋ฅผ ์ถ”์ ํ•  ๋ฆฌ์ŠคํŠธ +fence_history = [] +in_fence = False +open_line = None + +print("๐Ÿ” ์ฝ”๋“œ ๋ธ”๋ก(```) ๋งคํ•‘ ์‹œ์ž‘...") +for index, line in enumerate(lines, start=1): + if re.match(r"^\s*```", line): + if not in_fence: + in_fence = True + open_line = index + else: + in_fence = False + fence_history.append((open_line, index)) + open_line = None + +# ๋งˆ์ง€๋ง‰์— ๋‹ซํžˆ์ง€ ์•Š์€ ๋ธ”๋ก์ด ์žˆ๋‹ค๋ฉด ๊ธฐ๋ก +if in_fence: + fence_history.append((open_line, "๋ฏธ์ข…๋ฃŒ (๋ฌธ์„œ ๋)")) + +# ๋งคํ•‘ ๊ฒฐ๊ณผ ์ถœ๋ ฅ (์—๋Ÿฌ ์ฃผ๋ณ€ ์œ„์ฃผ๋กœ ์ถœ๋ ฅ) +print("\n--- ์ฝ”๋“œ ๋ธ”๋ก ์—ด๋ฆผ/๋‹ซํž˜ ๋ฆฌ์ŠคํŠธ ---") +for open_ln, close_ln in fence_history: + status = "โœ… ์ •์ƒ ์—ฐ๊ฒฐ" if isinstance(close_ln, int) else "โŒ ์—๋Ÿฌ ๋ฐœ์ƒ" + print(f"[{status}] ์‹œ์ž‘: {open_ln}์ค„ โžก๏ธ ์ข…๋ฃŒ: {close_ln}์ค„") + +print("\n๐Ÿ’ก [ํŒ] ์ง์ด ๋งž์ง€ ์•Š์•„ ๋ฐ€๋ฆฌ๊ธฐ ์‹œ์ž‘ํ•œ ์ฒซ ๋ฒˆ์งธ 'โŒ ์—๋Ÿฌ ๋ฐœ์ƒ' ๋˜๋Š” '์‹œ์ž‘ ์ค„'์˜ ๋ฐ”๋กœ ์œ—๋ถ€๋ถ„์„ ํ™•์ธํ•ด ๋ณด์„ธ์š”!") +eof diff --git a/ko/resources.md b/ko/resources.md new file mode 100644 index 00000000..6dbff959 --- /dev/null +++ b/ko/resources.md @@ -0,0 +1,265 @@ + + + Claude How To + + +# ์œ ์šฉํ•œ ๋ฆฌ์†Œ์Šค ๋ชฉ๋ก + +## ๊ณต์‹ ๋ฌธ์„œ + +| Resource | Description | Link | +|----------|-------------|------| +| Claude Code Docs | ๊ณต์‹ Claude Code ๋ฌธ์„œ | [code.claude.com/docs/en/overview](https://code.claude.com/docs/en/overview) | +| Anthropic Docs | Anthropic ์ „์ฒด ๋ฌธ์„œ | [docs.anthropic.com](https://docs.anthropic.com) | +| MCP Protocol | Model Context Protocol ๋ช…์„ธ | [modelcontextprotocol.io](https://modelcontextprotocol.io) | +| MCP Servers | ๊ณต์‹ MCP ์„œ๋ฒ„ ๊ตฌํ˜„์ฒด | [github.com/modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) | +| Anthropic Cookbook | ์ฝ”๋“œ ์˜ˆ์ œ ๋ฐ ํŠœํ† ๋ฆฌ์–ผ | [github.com/anthropics/anthropic-cookbook](https://github.com/anthropics/anthropic-cookbook) | +| Claude Code Skills | ์ปค๋ฎค๋‹ˆํ‹ฐ ์Šคํ‚ฌ ์ €์žฅ์†Œ | [github.com/anthropics/skills](https://github.com/anthropics/skills) | +| Agent Teams | ๋ฉ€ํ‹ฐ ์—์ด์ „ํŠธ ์กฐ์ • ๋ฐ ํ˜‘์—… | [code.claude.com/docs/en/agent-teams](https://code.claude.com/docs/en/agent-teams) | +| Scheduled Tasks | /loop ๋ฐ cron์„ ํ™œ์šฉํ•œ ๋ฐ˜๋ณต ์ž‘์—… | [code.claude.com/docs/en/scheduled-tasks](https://code.claude.com/docs/en/scheduled-tasks) | +| Chrome Integration | ๋ธŒ๋ผ์šฐ์ € ์ž๋™ํ™” | [code.claude.com/docs/en/chrome](https://code.claude.com/docs/en/chrome) | +| Keybindings | ํ‚ค๋ณด๋“œ ๋‹จ์ถ•ํ‚ค ์‚ฌ์šฉ์ž ์ •์˜ | [code.claude.com/docs/en/keybindings](https://code.claude.com/docs/en/keybindings) | +| Desktop App | ๋„ค์ดํ‹ฐ๋ธŒ ๋ฐ์Šคํฌํ†ฑ ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜ | [code.claude.com/docs/en/desktop](https://code.claude.com/docs/en/desktop) | +| Remote Control | ์›๊ฒฉ ์„ธ์…˜ ์ œ์–ด | [code.claude.com/docs/en/remote-control](https://code.claude.com/docs/en/remote-control) | +| Auto Mode | ์ž๋™ ๊ถŒํ•œ ๊ด€๋ฆฌ | [code.claude.com/docs/en/permissions](https://code.claude.com/docs/en/permissions) | +| Channels | ๋ฉ€ํ‹ฐ ์ฑ„๋„ ํ†ต์‹  | [code.claude.com/docs/en/channels](https://code.claude.com/docs/en/channels) | +| Voice Dictation | Claude Code๋ฅผ ์œ„ํ•œ ์Œ์„ฑ ์ž…๋ ฅ | [code.claude.com/docs/en/voice-dictation](https://code.claude.com/docs/en/voice-dictation) | + +## Anthropic ์—”์ง€๋‹ˆ์–ด๋ง ๋ธ”๋กœ๊ทธ + +| Article | Description | Link | +|---------|-------------|------| +| Code Execution with MCP | ์ฝ”๋“œ ์‹คํ–‰์„ ํ™œ์šฉํ•˜์—ฌ MCP ์ปจํ…์ŠคํŠธ ํŒฝ์ฐฝ ๋ฌธ์ œ๋ฅผ ํ•ด๊ฒฐํ•˜๋Š” ๋ฐฉ๋ฒ• โ€” ํ† ํฐ ์‚ฌ์šฉ๋Ÿ‰ 98.7% ๊ฐ์†Œ | [anthropic.com/engineering/code-execution-with-mcp](https://www.anthropic.com/engineering/code-execution-with-mcp) | + +--- + +## 30๋ถ„ ๋งŒ์— Claude Code ๋งˆ์Šคํ„ฐํ•˜๊ธฐ + +_Video_: https://www.youtube.com/watch?v=6eBSHbLKuN0 + +_**๋ชจ๋“  ํŒ**_ +- **๊ณ ๊ธ‰ ๊ธฐ๋Šฅ ๋ฐ ๋‹จ์ถ•ํ‚ค ํ™œ์šฉํ•˜๊ธฐ** + - ๋ฆด๋ฆฌ์Šค ๋…ธํŠธ๋ฅผ ์ •๊ธฐ์ ์œผ๋กœ ํ™•์ธํ•˜์—ฌ Claude์˜ ์ƒˆ๋กœ์šด ์ฝ”๋“œ ํŽธ์ง‘ ๋ฐ ์ปจํ…์ŠคํŠธ ๊ธฐ๋Šฅ์„ ํŒŒ์•…ํ•˜์„ธ์š”. + - ํ‚ค๋ณด๋“œ ๋‹จ์ถ•ํ‚ค๋ฅผ ์ตํ˜€ ์ฑ„ํŒ…, ํŒŒ์ผ, ์—๋””ํ„ฐ ํ™”๋ฉด์„ ๋น ๋ฅด๊ฒŒ ์ „ํ™˜ํ•˜์„ธ์š”. + +- **ํšจ์œจ์ ์ธ ์„ค์ •** + - ํ”„๋กœ์ ํŠธ๋ณ„ ์„ธ์…˜์„ ๋ช…ํ™•ํ•œ ์ด๋ฆ„๊ณผ ์„ค๋ช…์œผ๋กœ ์ƒ์„ฑํ•˜์—ฌ ์‰ฝ๊ฒŒ ์ฐพ์„ ์ˆ˜ ์žˆ๋„๋ก ํ•˜์„ธ์š”. + - ์ž์ฃผ ์‚ฌ์šฉํ•˜๋Š” ํŒŒ์ผ์ด๋‚˜ ํด๋”๋ฅผ ๊ณ ์ •ํ•˜์—ฌ Claude๊ฐ€ ์–ธ์ œ๋“  ์ ‘๊ทผํ•  ์ˆ˜ ์žˆ๋„๋ก ํ•˜์„ธ์š”. + - GitHub, ์ฃผ์š” IDE ๋“ฑ Claude์˜ ์—ฐ๋™ ๊ธฐ๋Šฅ์„ ์„ค์ •ํ•ด ๊ฐœ๋ฐœ ๊ณผ์ •์„ ๊ฐ„์†Œํ™”ํ•˜์„ธ์š”. + +- **ํšจ๊ณผ์ ์ธ ์ฝ”๋“œ๋ฒ ์ด์Šค ์งˆ์˜์‘๋‹ต** + - ์•„ํ‚คํ…์ฒ˜, ๋””์ž์ธ ํŒจํ„ด, ํŠน์ • ๋ชจ๋“ˆ์— ๋Œ€ํ•ด Claude์—๊ฒŒ ๊ตฌ์ฒด์ ์œผ๋กœ ์งˆ๋ฌธํ•˜์„ธ์š”. + - ์งˆ๋ฌธ ์‹œ ํŒŒ์ผ ๋ฐ ๋ผ์ธ ๋ฒˆํ˜ธ๋ฅผ ํ•จ๊ป˜ ์ œ๊ณตํ•˜์„ธ์š”(์˜ˆ: `app/models/user.py`์˜ ๋กœ์ง์€ ๋ฌด์—‡์„ ์ˆ˜ํ–‰ํ•˜๋‚˜์š”?). + - ๋Œ€๊ทœ๋ชจ ์ฝ”๋“œ๋ฒ ์ด์Šค์—์„œ๋Š” ์š”์•ฝ๋ณธ์ด๋‚˜ ๋งค๋‹ˆํŽ˜์ŠคํŠธ๋ฅผ ์ œ๊ณตํ•ด Claude๊ฐ€ ํ•ต์‹ฌ์— ์ง‘์ค‘ํ•  ์ˆ˜ ์žˆ๋„๋ก ํ•˜์„ธ์š”. + - **์˜ˆ์‹œ ํ”„๋กฌํ”„ํŠธ**: _"src/auth/AuthService.ts:45-120์— ๊ตฌํ˜„๋œ ์ธ์ฆ ํ๋ฆ„์„ ์„ค๋ช…ํ•ด ์ฃผ์„ธ์š”. ์ด ๋กœ์ง์ด src/middleware/auth.ts์˜ ๋ฏธ๋“ค์›จ์–ด์™€ ์–ด๋–ป๊ฒŒ ํ†ตํ•ฉ๋˜๋Š”์ง€๋„ ์•Œ๋ ค์ฃผ์„ธ์š”."_ + +- **์ฝ”๋“œ ํŽธ์ง‘ ๋ฐ ๋ฆฌํŒฉํ„ฐ๋ง** + - ์ฝ”๋“œ ๋ธ”๋ก ๋‚ด ์ธ๋ผ์ธ ์ฃผ์„์ด๋‚˜ ์š”์ฒญ์„ ์‚ฌ์šฉํ•ด ์›ํ•˜๋Š” ์ˆ˜์ •๋งŒ ์ง‘์ค‘์ ์œผ๋กœ ์ˆ˜ํ–‰ํ•˜๋„๋ก ํ•˜์„ธ์š”("๊ฐ€๋…์„ฑ์„ ์œ„ํ•ด ์ด ํ•จ์ˆ˜๋ฅผ ๋ฆฌํŒฉํ„ฐ๋งํ•ด ์ฃผ์„ธ์š”"). + - ์ˆ˜์ • ์ „ํ›„ ๋น„๊ต๋ฅผ ์š”์ฒญํ•˜์„ธ์š”. + - ์ฃผ์š” ์ˆ˜์ • ์ดํ›„์—๋Š” ํ…Œ์ŠคํŠธ ์ฝ”๋“œ๋‚˜ ๋ฌธ์„œ๋ฅผ ์ƒ์„ฑํ•˜๋„๋ก ์š”์ฒญํ•ด ํ’ˆ์งˆ์„ ํ™•๋ณดํ•˜์„ธ์š”. + - **์˜ˆ์‹œ ํ”„๋กฌํ”„ํŠธ**: _"api/users.js์˜ getUserData ํ•จ์ˆ˜๋ฅผ Promise ๋Œ€์‹  async/await๋ฅผ ์‚ฌ์šฉํ•˜๋„๋ก ๋ฆฌํŒฉํ„ฐ๋งํ•ด ์ฃผ์„ธ์š”. ์ˆ˜์ • ์ „ํ›„ ๋น„๊ต๋ฅผ ๋ณด์—ฌ์ฃผ๊ณ , ๋ฆฌํŒฉํ„ฐ๋ง๋œ ๋ฒ„์ „์— ๋Œ€ํ•œ ๋‹จ์œ„ ํ…Œ์ŠคํŠธ๋„ ์ƒ์„ฑํ•ด ์ฃผ์„ธ์š”."_ + +- **์ปจํ…์ŠคํŠธ ๊ด€๋ฆฌ** + - ํ˜„์žฌ ์ž‘์—…๊ณผ ๊ด€๋ จ๋œ ์ฝ”๋“œ์™€ ์ปจํ…์ŠคํŠธ๋งŒ ์ œ๊ณตํ•˜์„ธ์š”. + - "ํŒŒ์ผ A๊ฐ€ ์žˆ๊ณ , ํ•จ์ˆ˜ B๊ฐ€ ์žˆ์œผ๋ฉฐ, ์งˆ๋ฌธ์€ X์ž…๋‹ˆ๋‹ค"์™€ ๊ฐ™์€ ๊ตฌ์กฐํ™”๋œ ํ”„๋กฌํ”„ํŠธ๋ฅผ ์‚ฌ์šฉํ•˜์„ธ์š”. + - ์ปจํ…์ŠคํŠธ ํ•œ๋„๋ฅผ ์ดˆ๊ณผํ•˜์ง€ ์•Š๋„๋ก ํฐ ํŒŒ์ผ์€ ์ œ๊ฑฐํ•˜๊ฑฐ๋‚˜ ์ถ•์•ฝํ•˜์„ธ์š”. + - **์˜ˆ์‹œ ํ”„๋กฌํ”„ํŠธ**: _"models/User.js์˜ User ๋ชจ๋ธ๊ณผ utils/validation.js์˜ validateUser ํ•จ์ˆ˜์ž…๋‹ˆ๋‹ค. ์ด๋ฉ”์ผ ๊ฒ€์ฆ ๊ธฐ๋Šฅ์„ ์ถ”๊ฐ€ํ•˜๋ฉด์„œ๋„ ๊ธฐ์กด ํ˜ธํ™˜์„ฑ์„ ์œ ์ง€ํ•˜๋ ค๋ฉด ์–ด๋–ป๊ฒŒ ํ•ด์•ผ ํ•˜๋‚˜์š”?"_ + +- **ํŒ€ ๋„๊ตฌ ํ†ตํ•ฉ** + - Claude ์„ธ์…˜์„ ํŒ€์˜ ์ €์žฅ์†Œ ๋ฐ ๋ฌธ์„œ์™€ ์—ฐ๊ฒฐํ•˜์„ธ์š”. + - ๋ฐ˜๋ณต์ ์ธ ์—”์ง€๋‹ˆ์–ด๋ง ์ž‘์—…์„ ์œ„ํ•ด ๊ธฐ๋ณธ ํ…œํ”Œ๋ฆฟ์„ ์‚ฌ์šฉํ•˜๊ฑฐ๋‚˜ ์‚ฌ์šฉ์ž ์ •์˜ ํ…œํ”Œ๋ฆฟ์„ ๋งŒ๋“œ์„ธ์š”. + - ์„ธ์…˜ ๊ธฐ๋ก๊ณผ ํ”„๋กฌํ”„ํŠธ๋ฅผ ํŒ€์›๋“ค๊ณผ ๊ณต์œ ํ•˜์—ฌ ํ˜‘์—…ํ•˜์„ธ์š”. + +- **์„ฑ๋Šฅ ํ–ฅ์ƒ** + - Claude์—๊ฒŒ ๋ช…ํ™•ํ•˜๊ณ  ๋ชฉํ‘œ ์ง€ํ–ฅ์ ์ธ ์ง€์‹œ๋ฅผ ์ œ๊ณตํ•˜์„ธ์š”(์˜ˆ: "์ด ํด๋ž˜์Šค๋ฅผ ๋‹ค์„ฏ ๊ฐœ์˜ ํ•ต์‹ฌ ํ•ญ๋ชฉ์œผ๋กœ ์š”์•ฝํ•ด ์ฃผ์„ธ์š”"). + - ๋ถˆํ•„์š”ํ•œ ์ฃผ์„๊ณผ ๋ณด์ผ๋Ÿฌํ”Œ๋ ˆ์ดํŠธ ์ฝ”๋“œ๋ฅผ ์ปจํ…์ŠคํŠธ์—์„œ ์ œ๊ฑฐํ•˜์„ธ์š”. + - ๊ฒฐ๊ณผ๊ฐ€ ๊ธฐ๋Œ€์™€ ๋‹ค๋ฅผ ๊ฒฝ์šฐ ์ปจํ…์ŠคํŠธ๋ฅผ ์ดˆ๊ธฐํ™”ํ•˜๊ฑฐ๋‚˜ ์งˆ๋ฌธ์„ ๋‹ค์‹œ ํ‘œํ˜„ํ•˜์„ธ์š”. + - **์˜ˆ์‹œ ํ”„๋กฌํ”„ํŠธ**: _"src/db/Manager.ts์˜ DatabaseManager ํด๋ž˜์Šค๋ฅผ ์ฃผ์š” ์ฑ…์ž„๊ณผ ํ•ต์‹ฌ ๋ฉ”์„œ๋“œ ์ค‘์‹ฌ์œผ๋กœ ๋‹ค์„ฏ ๊ฐœ ํ•ญ๋ชฉ์œผ๋กœ ์š”์•ฝํ•ด ์ฃผ์„ธ์š”."_ + +- **์‹ค์ „ ํ™œ์šฉ ์‚ฌ๋ก€** + - ๋””๋ฒ„๊น…: ์˜ค๋ฅ˜ ๋ฉ”์‹œ์ง€์™€ ์Šคํƒ ํŠธ๋ ˆ์ด์Šค๋ฅผ ๋ถ™์—ฌ ๋„ฃ๊ณ  ์›์ธ๊ณผ ํ•ด๊ฒฐ ๋ฐฉ๋ฒ•์„ ์š”์ฒญํ•˜์„ธ์š”. + - ํ…Œ์ŠคํŠธ ์ƒ์„ฑ: ๋ณต์žกํ•œ ๋กœ์ง์— ๋Œ€ํ•ด ์†์„ฑ ๊ธฐ๋ฐ˜ ํ…Œ์ŠคํŠธ, ๋‹จ์œ„ ํ…Œ์ŠคํŠธ, ํ†ตํ•ฉ ํ…Œ์ŠคํŠธ๋ฅผ ์š”์ฒญํ•˜์„ธ์š”. + - ์ฝ”๋“œ ๋ฆฌ๋ทฐ: ์œ„ํ—˜ํ•œ ๋ณ€๊ฒฝ ์‚ฌํ•ญ, ์˜ˆ์™ธ ์ƒํ™ฉ, ์ฝ”๋“œ ์Šค๋ฉœ์„ ์ฐพ์•„๋‹ฌ๋ผ๊ณ  ์š”์ฒญํ•˜์„ธ์š”. + - **์˜ˆ์‹œ ํ”„๋กฌํ”„ํŠธ** + - _"components/UserList.jsx์˜ 42๋ฒˆ์งธ ์ค„์—์„œ 'TypeError: Cannot read property 'map' of undefined' ์˜ค๋ฅ˜๊ฐ€ ๋ฐœ์ƒํ•ฉ๋‹ˆ๋‹ค. ์Šคํƒ ํŠธ๋ ˆ์ด์Šค์™€ ๊ด€๋ จ ์ฝ”๋“œ๋Š” ๋‹ค์Œ๊ณผ ๊ฐ™์Šต๋‹ˆ๋‹ค. ์›์ธ๊ณผ ํ•ด๊ฒฐ ๋ฐฉ๋ฒ•์„ ์•Œ๋ ค์ฃผ์„ธ์š”."_ + - _"PaymentProcessor ํด๋ž˜์Šค์— ๋Œ€ํ•œ ํฌ๊ด„์ ์ธ ๋‹จ์œ„ ํ…Œ์ŠคํŠธ๋ฅผ ์ƒ์„ฑํ•ด ์ฃผ์„ธ์š”. ์‹คํŒจํ•œ ๊ฑฐ๋ž˜, ํƒ€์ž„์•„์›ƒ, ์ž˜๋ชป๋œ ์ž…๋ ฅ ๋“ฑ ์˜ˆ์™ธ ์ƒํ™ฉ๋„ ํฌํ•จํ•ด ์ฃผ์„ธ์š”."_ + - _"์ด Pull Request diff๋ฅผ ๊ฒ€ํ† ํ•˜๊ณ  ์ž ์žฌ์ ์ธ ๋ณด์•ˆ ๋ฌธ์ œ, ์„ฑ๋Šฅ ๋ณ‘๋ชฉ, ์ฝ”๋“œ ์Šค๋ฉœ์„ ์ฐพ์•„์ฃผ์„ธ์š”."_ + +- **์›Œํฌํ”Œ๋กœ ์ž๋™ํ™”** + - Claude ํ”„๋กฌํ”„ํŠธ๋ฅผ ํ™œ์šฉํ•ด ํฌ๋งทํŒ…, ์ •๋ฆฌ ์ž‘์—…, ๋ฐ˜๋ณต์ ์ธ ์ด๋ฆ„ ๋ณ€๊ฒฝ ๋“ฑ์˜ ์ž‘์—…์„ ์ž๋™ํ™”ํ•˜์„ธ์š”. + - Git diff๋ฅผ ๊ธฐ๋ฐ˜์œผ๋กœ PR ์„ค๋ช…, ๋ฆด๋ฆฌ์Šค ๋…ธํŠธ, ๋ฌธ์„œ๋ฅผ ์ž‘์„ฑํ•˜๋„๋ก Claude๋ฅผ ํ™œ์šฉํ•˜์„ธ์š”. + - **์˜ˆ์‹œ ํ”„๋กฌํ”„ํŠธ**: _"git diff๋ฅผ ๊ธฐ๋ฐ˜์œผ๋กœ ๋ณ€๊ฒฝ ์‚ฌํ•ญ ์š”์•ฝ, ์ˆ˜์ •๋œ ํŒŒ์ผ ๋ชฉ๋ก, ํ…Œ์ŠคํŠธ ์ ˆ์ฐจ, ์ž ์žฌ์  ์˜ํ–ฅ์„ ํฌํ•จํ•œ ์ƒ์„ธํ•œ PR ์„ค๋ช…์„ ์ž‘์„ฑํ•ด ์ฃผ์„ธ์š”. ๋˜ํ•œ 2.3.0 ๋ฒ„์ „์— ๋Œ€ํ•œ ๋ฆด๋ฆฌ์Šค ๋…ธํŠธ๋„ ์ƒ์„ฑํ•ด ์ฃผ์„ธ์š”."_ + +**ํŒ**: ์ตœ์ƒ์˜ ๊ฒฐ๊ณผ๋ฅผ ์œ„ํ•ด ์—ฌ๋Ÿฌ ๋ฐฉ๋ฒ•์„ ํ•จ๊ป˜ ํ™œ์šฉํ•˜์„ธ์š”. ์ค‘์š”ํ•œ ํŒŒ์ผ์„ ๊ณ ์ •ํ•˜๊ณ  ๋ชฉํ‘œ๋ฅผ ์š”์•ฝํ•˜๋Š” ๊ฒƒ๋ถ€ํ„ฐ ์‹œ์ž‘ํ•œ ํ›„, ์ง‘์ค‘์ ์ธ ํ”„๋กฌํ”„ํŠธ์™€ Claude์˜ ๋ฆฌํŒฉํ„ฐ๋ง ๊ธฐ๋Šฅ์„ ํ™œ์šฉํ•˜์—ฌ ์ฝ”๋“œ๋ฒ ์ด์Šค์™€ ์ž๋™ํ™”๋ฅผ ์ ์ง„์ ์œผ๋กœ ๊ฐœ์„ ํ•˜์„ธ์š”. + + +**Claude Code ์ถ”์ฒœ ์›Œํฌํ”Œ๋กœ** + +### Claude Code ์ถ”์ฒœ ์›Œํฌํ”Œ๋กœ + +#### ์ƒˆ๋กœ์šด ์ €์žฅ์†Œ์˜ ๊ฒฝ์šฐ + +1. **์ €์žฅ์†Œ ๋ฐ Claude ์—ฐ๋™ ์ดˆ๊ธฐํ™”** + - ์ƒˆ๋กœ์šด ์ €์žฅ์†Œ์— README, LICENSE, .gitignore, ๋ฃจํŠธ ์„ค์ • ํŒŒ์ผ ๋“ฑ ๊ธฐ๋ณธ ๊ตฌ์กฐ๋ฅผ ๊ตฌ์„ฑํ•ฉ๋‹ˆ๋‹ค. + - ์•„ํ‚คํ…์ฒ˜, ์ƒ์œ„ ์ˆ˜์ค€ ๋ชฉํ‘œ, ์ฝ”๋”ฉ ๊ฐ€์ด๋“œ๋ผ์ธ์„ ์„ค๋ช…ํ•˜๋Š” `CLAUDE.md` ํŒŒ์ผ์„ ์ž‘์„ฑํ•ฉ๋‹ˆ๋‹ค. + - Claude Code๋ฅผ ์„ค์น˜ํ•˜๊ณ  ์ €์žฅ์†Œ์™€ ์—ฐ๊ฒฐํ•˜์—ฌ ์ฝ”๋“œ ์ œ์•ˆ, ํ…Œ์ŠคํŠธ ์Šค์บํด๋”ฉ, ์›Œํฌํ”Œ๋กœ ์ž๋™ํ™”๋ฅผ ํ™œ์šฉํ•ฉ๋‹ˆ๋‹ค. + +2. **๊ณ„ํš ๋ชจ๋“œ์™€ ๋ช…์„ธ ํ™œ์šฉ** + - ๊ณ„ํš ๋ชจ๋“œ(`shift-tab` ๋˜๋Š” `/plan`)๋ฅผ ์‚ฌ์šฉํ•ด ๊ธฐ๋Šฅ ๊ตฌํ˜„ ์ „์— ์ƒ์„ธํ•œ ๋ช…์„ธ๋ฅผ ์ž‘์„ฑํ•ฉ๋‹ˆ๋‹ค. + - ์•„ํ‚คํ…์ฒ˜ ์ œ์•ˆ๊ณผ ์ดˆ๊ธฐ ํ”„๋กœ์ ํŠธ ๊ตฌ์กฐ๋ฅผ Claude์—๊ฒŒ ์š”์ฒญํ•ฉ๋‹ˆ๋‹ค. + - ๋ช…ํ™•ํ•˜๊ณ  ๋ชฉํ‘œ ์ง€ํ–ฅ์ ์ธ ํ”„๋กฌํ”„ํŠธ ํ๋ฆ„์„ ์œ ์ง€ํ•˜๋ฉฐ ์ปดํฌ๋„ŒํŠธ ๊ตฌ์กฐ, ์ฃผ์š” ๋ชจ๋“ˆ, ์ฑ…์ž„ ๋ฒ”์œ„๋ฅผ ์ •์˜ํ•ฉ๋‹ˆ๋‹ค. + +3. **๋ฐ˜๋ณต ๊ฐœ๋ฐœ ๋ฐ ๊ฒ€ํ† ** + - ํ•ต์‹ฌ ๊ธฐ๋Šฅ์„ ์ž‘์€ ๋‹จ์œ„๋กœ ๊ตฌํ˜„ํ•˜๋ฉด์„œ Claude์—๊ฒŒ ์ฝ”๋“œ ์ƒ์„ฑ, ๋ฆฌํŒฉํ„ฐ๋ง, ๋ฌธ์„œํ™”๋ฅผ ์š”์ฒญํ•ฉ๋‹ˆ๋‹ค. + - ๊ฐ ๋‹จ๊ณ„๋งˆ๋‹ค ๋‹จ์œ„ ํ…Œ์ŠคํŠธ์™€ ์˜ˆ์ œ๋ฅผ ์ƒ์„ฑํ•˜๋„๋ก ์š”์ฒญํ•ฉ๋‹ˆ๋‹ค. + - `CLAUDE.md`์— ์ง€์†์ ์œผ๋กœ ์ž‘์—… ๋ชฉ๋ก์„ ๊ด€๋ฆฌํ•ฉ๋‹ˆ๋‹ค. + +4. **CI/CD ๋ฐ ๋ฐฐํฌ ์ž๋™ํ™”** + - Claude๋ฅผ ํ™œ์šฉํ•˜์—ฌ GitHub Actions, npm/yarn ์Šคํฌ๋ฆฝํŠธ ๋˜๋Š” ๋ฐฐํฌ ์›Œํฌํ”Œ๋กœ๋ฅผ ์ž๋™ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. + - `CLAUDE.md`๋ฅผ ์—…๋ฐ์ดํŠธํ•˜๊ณ  ๊ด€๋ จ ๋ช…๋ น์–ด๋‚˜ ์Šคํฌ๋ฆฝํŠธ ์ƒ์„ฑ์„ ์š”์ฒญํ•˜์—ฌ ํŒŒ์ดํ”„๋ผ์ธ์„ ์‰ฝ๊ฒŒ ์ˆ˜์ •ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. + +```mermaid +graph TD + A[Start New Repository] --> B[Initialize Repository Structure] + B --> C[Create README, LICENSE, .gitignore] + C --> D[Create CLAUDE.md] + D --> E[Document Architecture & Guidelines] + E --> F[Install & Link Claude Code] + + F --> G[Enter Plan Mode] + G --> H[Draft Feature Specification] + H --> I[Get Architecture Suggestions] + I --> J[Define Components & Modules] + + J --> K[Implement Feature Chunk] + K --> L[Generate Code with Claude] + L --> M[Request Unit Tests] + M --> N[Review & Refactor] + N --> O{More Features?} + O -->|Yes| K + O -->|No| P[Update Task List in CLAUDE.md] + + P --> Q[Setup CI/CD Pipeline] + Q --> R[Scaffold GitHub Actions] + R --> S[Create Deployment Scripts] + S --> T[Test Automation] + T --> U[Repository Ready] + + style A fill:#e1f5ff + style G fill:#fff4e1 + style K fill:#f0ffe1 + style Q fill:#ffe1f5 + style U fill:#90EE90 +``` + +#### ๊ธฐ์กด ์ €์žฅ์†Œ์˜ ๊ฒฝ์šฐ + +1. **์ €์žฅ์†Œ ๋ฐ ์ปจํ…์ŠคํŠธ ์„ค์ •** + - ์ €์žฅ์†Œ ๊ตฌ์กฐ, ์ฝ”๋”ฉ ํŒจํ„ด, ํ•ต์‹ฌ ํŒŒ์ผ์„ ๋ฌธ์„œํ™”ํ•˜๊ธฐ ์œ„ํ•ด `CLAUDE.md`๋ฅผ ์ถ”๊ฐ€ํ•˜๊ฑฐ๋‚˜ ์—…๋ฐ์ดํŠธํ•ฉ๋‹ˆ๋‹ค. + - ๋ ˆ๊ฑฐ์‹œ ์ €์žฅ์†Œ์˜ ๊ฒฝ์šฐ ํ”„๋ ˆ์ž„์›Œํฌ, ๋ฒ„์ „ ๋งคํ•‘, ์ž‘์—… ์ง€์นจ, ์•Œ๋ ค์ง„ ๋ฒ„๊ทธ, ์—…๊ทธ๋ ˆ์ด๋“œ ๋…ธํŠธ๋ฅผ ํฌํ•จํ•œ `CLAUDE_LEGACY.md`๋ฅผ ์ž‘์„ฑํ•ฉ๋‹ˆ๋‹ค. + - Claude๊ฐ€ ์ปจํ…์ŠคํŠธ๋กœ ํ™œ์šฉํ•ด์•ผ ํ•  ์ฃผ์š” ํŒŒ์ผ์„ ๊ณ ์ •ํ•˜๊ฑฐ๋‚˜ ๊ฐ•์กฐ ํ‘œ์‹œํ•ฉ๋‹ˆ๋‹ค. + +2. **์ปจํ…์ŠคํŠธ ๊ธฐ๋ฐ˜ ์ฝ”๋“œ ์งˆ์˜์‘๋‹ต** + - ํŠน์ • ํŒŒ์ผ์ด๋‚˜ ํ•จ์ˆ˜๋ฅผ ์ฐธ์กฐํ•˜์—ฌ ์ฝ”๋“œ ๋ฆฌ๋ทฐ, ๋ฒ„๊ทธ ๋ถ„์„, ๋ฆฌํŒฉํ„ฐ๋ง ๋˜๋Š” ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ ๊ณ„ํš์„ Claude์—๊ฒŒ ์š”์ฒญํ•ฉ๋‹ˆ๋‹ค. + - "์ด ํŒŒ์ผ๋งŒ ์ˆ˜์ •", "์ƒˆ๋กœ์šด ์˜์กด์„ฑ ์ถ”๊ฐ€ ๊ธˆ์ง€"์™€ ๊ฐ™์ด ๋ช…ํ™•ํ•œ ์ž‘์—… ๋ฒ”์œ„๋ฅผ ์ง€์ •ํ•ฉ๋‹ˆ๋‹ค. + +3. **๋ธŒ๋žœ์น˜, ์›ŒํฌํŠธ๋ฆฌ ๋ฐ ๋ฉ€ํ‹ฐ ์„ธ์…˜ ๊ด€๋ฆฌ** + - ๊ธฐ๋Šฅ ๊ฐœ๋ฐœ์ด๋‚˜ ๋ฒ„๊ทธ ์ˆ˜์ •์„ ๋ถ„๋ฆฌํ•˜๊ธฐ ์œ„ํ•ด ์—ฌ๋Ÿฌ Git ์›ŒํฌํŠธ๋ฆฌ๋ฅผ ์‚ฌ์šฉํ•˜๊ณ , ๊ฐ ์›ŒํฌํŠธ๋ฆฌ๋งˆ๋‹ค ๋ณ„๋„์˜ Claude ์„ธ์…˜์„ ์‹คํ–‰ํ•ฉ๋‹ˆ๋‹ค. + - ๋ณ‘๋ ฌ ์ž‘์—…์„ ์œ„ํ•ด ํ„ฐ๋ฏธ๋„ ํƒญ์ด๋‚˜ ์ฐฝ์„ ๋ธŒ๋žœ์น˜ ๋˜๋Š” ๊ธฐ๋Šฅ ๋‹จ์œ„๋กœ ์ •๋ฆฌํ•ฉ๋‹ˆ๋‹ค. + +4. **ํŒ€ ๋„๊ตฌ ๋ฐ ์ž๋™ํ™”** + - `.claude/commands/`๋ฅผ ํ†ตํ•ด ์‚ฌ์šฉ์ž ์ •์˜ ๋ช…๋ น์–ด๋ฅผ ๋™๊ธฐํ™”ํ•˜์—ฌ ํŒ€ ์ „์ฒด์˜ ์ผ๊ด€์„ฑ์„ ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. + - Claude์˜ ์Šฌ๋ž˜์‹œ ๋ช…๋ น์–ด ๋˜๋Š” ํ›…์„ ํ™œ์šฉํ•˜์—ฌ ๋ฐ˜๋ณต ์ž‘์—…, PR ์ƒ์„ฑ, ์ฝ”๋“œ ํฌ๋งทํŒ…์„ ์ž๋™ํ™”ํ•ฉ๋‹ˆ๋‹ค. + - ํ˜‘์—… ๋””๋ฒ„๊น… ๋ฐ ๋ฆฌ๋ทฐ๋ฅผ ์œ„ํ•ด ์„ธ์…˜๊ณผ ์ปจํ…์ŠคํŠธ๋ฅผ ํŒ€์›๋“ค๊ณผ ๊ณต์œ ํ•ฉ๋‹ˆ๋‹ค. + +```mermaid +graph TD + A[Start with Existing Repository] --> B{Legacy Codebase?} + B -->|Yes| C[Create CLAUDE_LEGACY.md] + B -->|No| D[Create/Update CLAUDE.md] + C --> E[Document Frameworks & Version Maps] + D --> F[Document Structure & Patterns] + E --> G[Pin Key Files for Context] + F --> G + + G --> H[Identify Task Type] + H --> I{Task Category} + I -->|Bug Fix| J[Ask Claude for Bug Analysis] + I -->|Code Review| K[Request Code Review] + I -->|Refactor| L[Plan Refactoring Strategy] + I -->|Migration| M[Create Migration Plan] + + J --> N[Set Explicit Boundaries] + K --> N + L --> N + M --> N + + N --> O{Multiple Features?} + O -->|Yes| P[Create Git Worktrees] + O -->|No| Q[Work on Main Branch] + P --> R[Launch Separate Claude Sessions] + R --> S[Organize Terminal Tabs] + Q --> S + + S --> T[Setup Team Automation] + T --> U[Sync .claude/commands/] + U --> V[Configure Slash Commands] + V --> W[Setup Hooks for Automation] + W --> X[Share Session Context with Team] + + X --> Y{More Tasks?} + Y -->|Yes| H + Y -->|No| Z[Workflow Complete] + + style A fill:#e1f5ff + style C fill:#ffecec + style D fill:#fff4e1 + style P fill:#f0ffe1 + style T fill:#ffe1f5 + style Z fill:#90EE90 +``` + +**Tips**:**ํŒ**:- Start each new feature or fix with a spec and plan mode prompt. +- ์ƒˆ๋กœ์šด ๊ธฐ๋Šฅ ๊ฐœ๋ฐœ์ด๋‚˜ ๋ฒ„๊ทธ ์ˆ˜์ •์€ ํ•ญ์ƒ ๋ช…์„ธ(Spec)์™€ ๊ณ„ํš ๋ชจ๋“œ ํ”„๋กฌํ”„ํŠธ๋กœ ์‹œ์ž‘ํ•˜์„ธ์š”. +- ๋ ˆ๊ฑฐ์‹œ ์ €์žฅ์†Œ๋‚˜ ๋ณต์žกํ•œ ์ €์žฅ์†Œ์˜ ๊ฒฝ์šฐ ์ƒ์„ธํ•œ ๊ฐ€์ด๋“œ๋ฅผ `CLAUDE.md` ๋˜๋Š” `CLAUDE_LEGACY.md`์— ๊ธฐ๋กํ•ด ๋‘์„ธ์š”. +- ๋ช…ํ™•ํ•˜๊ณ  ์ง‘์ค‘๋œ ์ง€์‹œ๋ฅผ ์ œ๊ณตํ•˜๊ณ , ๋ณต์žกํ•œ ์ž‘์—…์€ ์—ฌ๋Ÿฌ ๋‹จ๊ณ„์˜ ๊ณ„ํš์œผ๋กœ ๋‚˜๋ˆ„์–ด ์ง„ํ–‰ํ•˜์„ธ์š”. +- ์„ธ์…˜์„ ์ •๊ธฐ์ ์œผ๋กœ ์ •๋ฆฌํ•˜๊ณ , ๋ถˆํ•„์š”ํ•œ ์ปจํ…์ŠคํŠธ๋ฅผ ์ œ๊ฑฐํ•˜๋ฉฐ, ์™„๋ฃŒ๋œ ์›ŒํฌํŠธ๋ฆฌ๋ฅผ ์‚ญ์ œํ•ด ์ž‘์—… ํ™˜๊ฒฝ์„ ๊น”๋”ํ•˜๊ฒŒ ์œ ์ง€ํ•˜์„ธ์š”. + +์œ„ ๋‹จ๊ณ„๋“ค์€ ์‹ ๊ทœ ์ฝ”๋“œ๋ฒ ์ด์Šค์™€ ๊ธฐ์กด ์ฝ”๋“œ๋ฒ ์ด์Šค ๋ชจ๋‘์—์„œ Claude Code๋ฅผ ํšจ์œจ์ ์œผ๋กœ ํ™œ์šฉํ•˜๊ธฐ ์œ„ํ•œ ํ•ต์‹ฌ ๊ถŒ์žฅ ์‚ฌํ•ญ์„ ๋‹ด๊ณ  ์žˆ์Šต๋‹ˆ๋‹ค. + +--- + +## ์ƒˆ๋กœ์šด ๊ธฐ๋Šฅ ๋ฐ ๊ธฐ๋Šฅ ํ–ฅ์ƒ (2026๋…„ 5์›”) + +### ์ฃผ์š” ๊ธฐ๋Šฅ ๋ฆฌ์†Œ์Šค + + +| Feature | Description | Learn More | +|---------|-------------|------------| +| **Auto Memory** | Claude๊ฐ€ ์„ธ์…˜ ๊ฐ„ ์‚ฌ์šฉ์ž ์„ ํ˜ธ๋„๋ฅผ ์ž๋™์œผ๋กœ ํ•™์Šตํ•˜๊ณ  ๊ธฐ์–ต | [Memory Guide](02-memory/) | +| **Remote Control** | ์™ธ๋ถ€ ๋„๊ตฌ ๋ฐ ์Šคํฌ๋ฆฝํŠธ์—์„œ Claude Code ์„ธ์…˜์„ ํ”„๋กœ๊ทธ๋ž˜๋ฐ ๋ฐฉ์‹์œผ๋กœ ์ œ์–ด | [Advanced Features](09-advanced-features/) | +| **Web Sessions** | ๋ธŒ๋ผ์šฐ์ € ๊ธฐ๋ฐ˜ ์ธํ„ฐํŽ˜์ด์Šค๋ฅผ ํ†ตํ•ด ์›๊ฒฉ ๊ฐœ๋ฐœ ํ™˜๊ฒฝ์—์„œ Claude Code ์‚ฌ์šฉ | [CLI Reference](10-cli/) | +| **Desktop App** | ํ–ฅ์ƒ๋œ UI๋ฅผ ์ œ๊ณตํ•˜๋Š” Claude Code ๋„ค์ดํ‹ฐ๋ธŒ ๋ฐ์Šคํฌํ†ฑ ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜ | [Claude Code Docs](https://code.claude.com/docs/en/desktop) | +| **Extended Thinking** | `Alt+T`/`Option+T` ๋˜๋Š” `MAX_THINKING_TOKENS` ํ™˜๊ฒฝ ๋ณ€์ˆ˜๋ฅผ ํ†ตํ•œ ์‹ฌ์ธต ์ถ”๋ก  ๋ชจ๋“œ | [Advanced Features](09-advanced-features/) | +| **Permission Modes** | default, acceptEdits, plan, auto, dontAsk, bypassPermissions ๋“ฑ ์„ธ๋ฐ€ํ•œ ๊ถŒํ•œ ์ œ์–ด | [Advanced Features](09-advanced-features/) | +| **7-Tier Memory** | Managed Policy, Project, Project Rules, User, User Rules, Local, Auto Memory๋กœ ๊ตฌ์„ฑ๋œ 7๋‹จ๊ณ„ ๋ฉ”๋ชจ๋ฆฌ ๊ตฌ์กฐ | [Memory Guide](02-memory/) | +| **Hook Events** | PreToolUse, PostToolUse, PostToolUseFailure, Stop, StopFailure, SubagentStart, SubagentStop, Notification, Elicitation ๋“ฑ 29๊ฐœ ์ด๋ฒคํŠธ ์ง€์› | [Hooks Guide](06-hooks/) | +| **Agent Teams** | ๋ณต์žกํ•œ ์ž‘์—…์„ ์œ„ํ•ด ์—ฌ๋Ÿฌ ์—์ด์ „ํŠธ๋ฅผ ์กฐ์ •ํ•˜๊ณ  ํ˜‘์—… | [Subagents Guide](04-subagents/) | +| **Scheduled Tasks** | `/loop` ๋ฐ cron ๋„๊ตฌ๋ฅผ ์‚ฌ์šฉํ•œ ๋ฐ˜๋ณต ์ž‘์—… ์„ค์ • | [Advanced Features](09-advanced-features/) | +| **Chrome Integration** | Headless Chromium์„ ํ™œ์šฉํ•œ ๋ธŒ๋ผ์šฐ์ € ์ž๋™ํ™” | [Advanced Features](09-advanced-features/) | +| **Keyboard Customization** | ํ‚ค ์กฐํ•ฉ(Chord Sequence)์„ ํฌํ•จํ•œ ๋‹จ์ถ•ํ‚ค ์‚ฌ์šฉ์ž ์ •์˜ | [Advanced Features](09-advanced-features/) | +| **Monitor Tool** | ํด๋ง ๋Œ€์‹  ๋ฐฑ๊ทธ๋ผ์šด๋“œ ๋ช…๋ น์˜ stdout ์ŠคํŠธ๋ฆผ์„ ๋ชจ๋‹ˆํ„ฐ๋งํ•˜๊ณ  ์ด๋ฒคํŠธ์— ๋ฐ˜์‘ (v2.1.98+) | [Advanced Features](09-advanced-features/) | +| **/goal mode** | ์„ธ์…˜ ๋‹จ์œ„ ์™„๋ฃŒ ์กฐ๊ฑด์„ ๋“ฑ๋กํ•˜๋ฉด ๋‹ฌ์„ฑ๋  ๋•Œ๊นŒ์ง€ Claude๊ฐ€ ์ž‘์—…์„ ๊ณ„์† ์ˆ˜ํ–‰ (v2.1.139+) | [Slash Commands](01-slash-commands/) | +| **claude agents (Agent View)** | ํ„ฐ๋ฏธ๋„์—์„œ ๋ฐฑ๊ทธ๋ผ์šด๋“œ ์—์ด์ „ํŠธ ์กฐํšŒ, ํ™•์ธ ๋ฐ ์žฌ๊ฐœ ๊ฐ€๋Šฅ. ๊ธฐ๊ณ„ ํŒ๋…์šฉ ์ถœ๋ ฅ์€ `--json` ์‚ฌ์šฉ (v2.1.139+, `--json`์€ v2.1.145 ์ถ”๊ฐ€) | [code.claude.com/docs/en/agent-view](https://code.claude.com/docs/en/agent-view) | +| **/run, /verify, /run-skill-generator** | ํ”„๋กœ์ ํŠธ ์‹คํ–‰, ์ˆ˜์ • ์‚ฌํ•ญ ๊ฒ€์ฆ, ํ”„๋กœ์ ํŠธ๋ณ„ run/verify ์Šคํ‚ฌ ์ƒ์„ฑ ๊ธฐ๋Šฅ ์ œ๊ณต (v2.1.145+) | [Skills Guide](03-skills/) | + +--- +**์ตœ์ข… ์—…๋ฐ์ดํŠธ**: 2026๋…„ 6์›” 2์ผ +**Claude Code ๋ฒ„์ „**: 2.1.160 +**์ถœ์ฒ˜**: +- https://code.claude.com/docs/en/overview +- https://code.claude.com/docs/en/changelog +- https://code.claude.com/docs/en/agent-view +- https://github.com/anthropics/claude-code/releases/tag/v2.1.144 +- https://github.com/anthropics/claude-code/releases/tag/v2.1.145 +**ํ˜ธํ™˜ ๋ชจ๋ธ**: Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5 diff --git a/ko/scripts/README.md b/ko/scripts/README.md new file mode 100644 index 00000000..c3325b02 --- /dev/null +++ b/ko/scripts/README.md @@ -0,0 +1,193 @@ + + + Claude How To + + +# ๋นŒ๋“œ ์Šคํฌ๋ฆฝํŠธ + +์ด ๋””๋ ‰ํ„ฐ๋ฆฌ์—๋Š” ํŠœํ† ๋ฆฌ์–ผ Markdown ํŒŒ์ผ์„ ๋ฐฐํฌ ๊ฐ€๋Šฅํ•œ ํ˜•์‹์œผ๋กœ ๋ณ€ํ™˜ํ•˜๋Š” ๋‘ ๊ฐœ์˜ ์ƒ์„ฑ๊ธฐ๊ฐ€ ํฌํ•จ๋˜์–ด ์žˆ์Šต๋‹ˆ๋‹ค. + +- [**EPUB ๋นŒ๋”**](#epub-๋นŒ๋”-์Šคํฌ๋ฆฝํŠธ) โ€” `build_epub.py` +- [**์ •์  ์›น์‚ฌ์ดํŠธ ๋นŒ๋”**](#์ •์ -์›น์‚ฌ์ดํŠธ-๋นŒ๋”) โ€” `build_website.py` + +๋‘ ์ƒ์„ฑ๊ธฐ ๋ชจ๋‘ `.md` ํŒŒ์ผ์„ ๋‹จ์ผ ์›๋ณธ(Source of Truth)์œผ๋กœ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. Markdown์„ ์ˆ˜์ •ํ•œ ํ›„์—๋Š” ํ•ด๋‹น ์Šคํฌ๋ฆฝํŠธ๋ฅผ ๋‹ค์‹œ ์‹คํ–‰ํ•˜์—ฌ ๊ฒฐ๊ณผ๋ฌผ์„ ์ƒ์„ฑํ•˜์‹ญ์‹œ์˜ค. + +--- + +# EPUB ๋นŒ๋” ์Šคํฌ๋ฆฝํŠธ + +Claude How-To Markdown ํŒŒ์ผ๋กœ EPUB ์ „์ž์ฑ…์„ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. + +## ๊ธฐ๋Šฅ + +- ํด๋” ๊ตฌ์กฐ(01-slash-commands, 02-memory ๋“ฑ)์— ๋”ฐ๋ผ ์ฑ•ํ„ฐ ๊ตฌ์„ฑ +- Kroki.io API๋ฅผ ํ†ตํ•ด Mermaid ๋‹ค์ด์–ด๊ทธ๋žจ์„ PNG ์ด๋ฏธ์ง€๋กœ ๋ Œ๋”๋ง +- ๋น„๋™๊ธฐ ๋ณ‘๋ ฌ ์ฒ˜๋ฆฌ๋กœ ๋ชจ๋“  ๋‹ค์ด์–ด๊ทธ๋žจ์„ ๋™์‹œ์— ๋ Œ๋”๋ง +- ํ”„๋กœ์ ํŠธ ๋กœ๊ณ ๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ํ‘œ์ง€ ์ด๋ฏธ์ง€ ์ƒ์„ฑ +- ๋‚ด๋ถ€ Markdown ๋งํฌ๋ฅผ EPUB ์ฑ•ํ„ฐ ์ฐธ์กฐ๋กœ ๋ณ€ํ™˜ +- ์—„๊ฒฉํ•œ ์˜ค๋ฅ˜ ์ฒ˜๋ฆฌ ๋ชจ๋“œ - ๋‹ค์ด์–ด๊ทธ๋žจ ํ•˜๋‚˜๋ผ๋„ ๋ Œ๋”๋ง์— ์‹คํŒจํ•˜๋ฉด ๋นŒ๋“œ ์‹คํŒจ + +## ์š”๊ตฌ ์‚ฌํ•ญ + +- Python 3.10+ +- [uv](https://github.com/astral-sh/uv) +- Mermaid ๋‹ค์ด์–ด๊ทธ๋žจ ๋ Œ๋”๋ง์„ ์œ„ํ•œ ์ธํ„ฐ๋„ท ์—ฐ๊ฒฐ + +## ๋น ๋ฅธ ์‹œ์ž‘ + +```bash +# Simplest way - uv handles everything +uv run scripts/build_epub.py +``` + +## ๊ฐœ๋ฐœ ํ™˜๊ฒฝ ์„ค์ • + +```bash +# Create virtual environment +uv venv + +# Activate and install dependencies +source .venv/bin/activate +uv pip install -r requirements-dev.txt + +# Run tests +pytest scripts/tests/ -v + +# Run the script +python scripts/build_epub.py +``` + +## ๋ช…๋ น์ค„ ์˜ต์…˜ + +``` +usage: build_epub.py [-h] [--root ROOT] [--output OUTPUT] [--verbose] + [--timeout TIMEOUT] [--max-concurrent MAX_CONCURRENT] + +options: + -h, --help show this help message and exit + --root, -r ROOT Root directory (default: repo root) + --output, -o OUTPUT Output path (default: claude-howto-guide.epub) + --verbose, -v Enable verbose logging + --timeout TIMEOUT API timeout in seconds (default: 30) + --max-concurrent N Max concurrent requests (default: 10) +``` + +## ์˜ˆ์ œ + +```bash +# Build with verbose output +uv run scripts/build_epub.py --verbose + +# Custom output location +uv run scripts/build_epub.py --output ~/Desktop/claude-guide.epub + +# Limit concurrent requests (if rate-limited) +uv run scripts/build_epub.py --max-concurrent 5 +``` + +## ์ถœ๋ ฅ ๊ฒฐ๊ณผ + +์ €์žฅ์†Œ ๋ฃจํŠธ ๋””๋ ‰ํ„ฐ๋ฆฌ์— `claude-howto-guide.epub` ํŒŒ์ผ์„ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. + +EPUB์—๋Š” ๋‹ค์Œ์ด ํฌํ•จ๋ฉ๋‹ˆ๋‹ค. + +- ํ”„๋กœ์ ํŠธ ๋กœ๊ณ ๊ฐ€ ํฌํ•จ๋œ ํ‘œ์ง€ ์ด๋ฏธ์ง€ +- ์ค‘์ฒฉ๋œ ์„น์…˜์ด ํฌํ•จ๋œ ๋ชฉ์ฐจ +- EPUB ํ˜ธํ™˜ HTML๋กœ ๋ณ€ํ™˜๋œ ๋ชจ๋“  Markdown ์ฝ˜ํ…์ธ  +- PNG ์ด๋ฏธ์ง€๋กœ ๋ Œ๋”๋ง๋œ Mermaid ๋‹ค์ด์–ด๊ทธ๋žจ + +## ํ…Œ์ŠคํŠธ ์‹คํ–‰ + +```bash +# With virtual environment +source .venv/bin/activate +pytest scripts/tests/ -v + +# Or with uv directly +uv run --with pytest --with pytest-asyncio \ + --with ebooklib --with markdown --with beautifulsoup4 \ + --with httpx --with pillow --with tenacity \ + pytest scripts/tests/ -v +``` + +## ์˜์กด์„ฑ + +PEP 723 ์ธ๋ผ์ธ ์Šคํฌ๋ฆฝํŠธ ๋ฉ”ํƒ€๋ฐ์ดํ„ฐ๋ฅผ ํ†ตํ•ด ๊ด€๋ฆฌ๋ฉ๋‹ˆ๋‹ค. + +| ํŒจํ‚ค์ง€ | ์šฉ๋„ | +|---------|---------| +| `ebooklib` | EPUB ์ƒ์„ฑ | +| `markdown` | Markdown์„ HTML๋กœ ๋ณ€ํ™˜ | +| `beautifulsoup4` | HTML ํŒŒ์‹ฑ | +| `httpx` | ๋น„๋™๊ธฐ HTTP ํด๋ผ์ด์–ธํŠธ | +| `pillow` | ํ‘œ์ง€ ์ด๋ฏธ์ง€ ์ƒ์„ฑ | +| `tenacity` | ์žฌ์‹œ๋„ ๋กœ์ง | + +## ๋ฌธ์ œ ํ•ด๊ฒฐ + +**๋„คํŠธ์›Œํฌ ์˜ค๋ฅ˜๋กœ ๋นŒ๋“œ ์‹คํŒจ**: ์ธํ„ฐ๋„ท ์—ฐ๊ฒฐ๊ณผ Kroki.io ์„œ๋น„์Šค ์ƒํƒœ๋ฅผ ํ™•์ธํ•˜์‹ญ์‹œ์˜ค. `--timeout 60` ์˜ต์…˜์„ ์‚ฌ์šฉํ•ด ๋ณด์‹ญ์‹œ์˜ค. + +**์š”์ฒญ ์ œํ•œ(Rate Limiting)**: `--max-concurrent 3`์œผ๋กœ ๋™์‹œ ์š”์ฒญ ์ˆ˜๋ฅผ ์ค„์ด์‹ญ์‹œ์˜ค. + +**๋กœ๊ณ  ํŒŒ์ผ ์—†์Œ**: `claude-howto-logo.png`๋ฅผ ์ฐพ์„ ์ˆ˜ ์—†์œผ๋ฉด ํ…์ŠคํŠธ๋งŒ ํฌํ•จ๋œ ํ‘œ์ง€๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. + +--- + +# ์ •์  ์›น์‚ฌ์ดํŠธ ๋นŒ๋” + +EPUB ์ƒ์„ฑ์— ์‚ฌ์šฉํ•˜๋Š” ๋™์ผํ•œ Markdown ํŒŒ์ผ๋กœ ์„ธ๋ จ๋˜๊ณ  ๋ชจ๋ฐ”์ผ ์นœํ™”์ ์ธ ์ •์  ์›น์‚ฌ์ดํŠธ๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. ์›น์‚ฌ์ดํŠธ๋Š” ๋ Œ๋”๋ง๋œ ๊ฒฐ๊ณผ๋ฌผ์ด๋ฉฐ, `.md` ํŒŒ์ผ์€ ๊ณ„์†ํ•ด์„œ ๋‹จ์ผ ์›๋ณธ(Source of Truth)์œผ๋กœ ์œ ์ง€๋ฉ๋‹ˆ๋‹ค. + +## ๊ธฐ๋Šฅ + +- Markdown ํŒŒ์ผ๋งˆ๋‹ค ํ•˜๋‚˜์˜ HTML ํŽ˜์ด์ง€ ์ƒ์„ฑ โ€” ๋‚ด๋ถ€ `.md` ๋งํฌ๋Š” ํ•ด๋‹น ์›นํŽ˜์ด์ง€ ๋งํฌ๋กœ ์ž๋™ ๋ณ€ํ™˜ +- Markdown์ด ์•„๋‹Œ ์ €์žฅ์†Œ ํŒŒ์ผ(ํ…œํ”Œ๋ฆฟ, ์Šคํฌ๋ฆฝํŠธ, JSON) ์ฐธ์กฐ๋Š” github.com์—์„œ ์†Œ์Šค ํŒŒ์ผ์„ ์—ฌ๋Š” GitHub blob URL๋กœ ๋ณ€ํ™˜ +- Mermaid ๋‹ค์ด์–ด๊ทธ๋žจ์€ ๋นŒ๋“œ๋œ ์‚ฌ์ดํŠธ์—์„œ ์ œ๊ณต๋˜๋Š” `mermaid.min.js`๋ฅผ ์‚ฌ์šฉํ•˜์—ฌ ํด๋ผ์ด์–ธํŠธ ์ธก์—์„œ ๋ Œ๋”๋ง(CDN ๋ถˆํ•„์š”) +- ๋…๋ฆฝ ์‹คํ–‰ํ˜• Tailwind CSS CLI(Go ๋ฐ”์ด๋„ˆ๋ฆฌ, Node.js ๋ถˆํ•„์š”)๋กœ CSS๋ฅผ ์ปดํŒŒ์ผํ•˜์—ฌ ์‚ฌ์ดํŠธ์— ํฌํ•จ โ€” ๋ฐ˜์‘ํ˜• ๋ ˆ์ด์•„์›ƒ, ์‚ฌ์ด๋“œ๋ฐ” ํƒ์ƒ‰, ํŽ˜์ด์ง€ ๋‚ด ๋ชฉ์ฐจ, ๋‹คํฌ ๋ชจ๋“œ ์ „ํ™˜, ์ด์ „/๋‹ค์Œ ํŽ˜์ด์ง€ ํƒ์ƒ‰ ์ œ๊ณต +- Inter ๋ฐ JetBrains Mono ๊ธ€๊ผด์„ CSS์™€ ํ•จ๊ป˜ ์ž์ฒด ํ˜ธ์ŠคํŒ… โ€” ํŽ˜์ด์ง€ ๋กœ๋“œ ์‹œ ์™ธ๋ถ€ ์š”์ฒญ ์—†์Œ +- EPUB์˜ ์ปค๋ฆฌํ˜๋Ÿผ ์ˆœ์„œ(`01-` โ€ฆ `10-` ๋ฐ ์ตœ์ƒ์œ„ ๋ฌธ์„œ ํฌํ•จ) ์œ ์ง€ +- ์ผ๋ฐ˜ ์ •์  ํŒŒ์ผ๋กœ ํ˜ธ์ŠคํŒ… ๊ฐ€๋Šฅ โ€” GitHub Pages ๋ฐฐํฌ์— ์ตœ์ ํ™” + +## ๋น ๋ฅธ ์‹œ์ž‘ + +```bash +# Build the English website into ./site/ +uv run scripts/build_website.py + +# Preview locally +python -m http.server --directory site 8080 +# then open http://localhost:8080 +``` + +## ๋ช…๋ น์ค„ ์˜ต์…˜ + +``` +usage: build_website.py [-h] [--root ROOT] [--output OUTPUT] + [--lang {en,vi,zh,ja,uk}] [--repo-url REPO_URL] + [--branch BRANCH] [--verbose] + +options: + --root, -r ROOT Source root (default: repo root) + --output, -o OUTPUT Output directory (default: /site) + --lang LANG Language to build: en | vi | zh | ja | uk + --repo-url URL GitHub repo for blob links (default: luongnv89/claude-howto) + --branch BRANCH Branch for blob links (default: main) + --verbose, -v Enable verbose logging +``` + +## GitHub Pages ๋ฐฐํฌ + +์ด ์ €์žฅ์†Œ์—๋Š” `.github/workflows/pages.yml` ์›Œํฌํ”Œ๋กœ๊ฐ€ ํฌํ•จ๋˜์–ด ์žˆ์œผ๋ฉฐ, `main` ๋ธŒ๋žœ์น˜์— ํ‘ธ์‹œ๋  ๋•Œ๋งˆ๋‹ค(`.md` ๋˜๋Š” ์ƒ์„ฑ๊ธฐ ํŒŒ์ผ์ด ๋ณ€๊ฒฝ๋œ ๊ฒฝ์šฐ) ์‚ฌ์ดํŠธ๋ฅผ ๋นŒ๋“œํ•œ ํ›„ `actions/deploy-pages`๋ฅผ ํ†ตํ•ด ๊ฒŒ์‹œํ•ฉ๋‹ˆ๋‹ค. + +์ด๋ฅผ ํ™œ์„ฑํ™”ํ•˜๋ ค๋ฉด ์ €์žฅ์†Œ ์„ค์ •์—์„œ GitHub Pages์˜ **Source: GitHub Actions**๋ฅผ ์„ ํƒํ•˜์‹ญ์‹œ์˜ค. + +## ์•„ํ‚คํ…์ฒ˜ + +`build_website.py`๋Š” `build_epub.py`์˜ ์ฑ•ํ„ฐ ์ •๋ ฌ ๋กœ์ง์„ ์žฌ์‚ฌ์šฉํ•˜๋ฉฐ, `scripts/website_templates/` ์•„๋ž˜์˜ HTML ํ…œํ”Œ๋ฆฟ์„ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. + +- `page.html.j2` โ€” ์‚ฌ์ด๋“œ๋ฐ” ํƒ์ƒ‰, ๋ชฉ์ฐจ, ์ด์ „/๋‹ค์Œ ํŽ˜์ด์ง€ ๊ธฐ๋Šฅ์„ ํฌํ•จํ•˜๋Š” ํŽ˜์ด์ง€๋ณ„ Jinja2 ํ…œํ”Œ๋ฆฟ +- `tailwind.config.js`, `tailwind.input.css` โ€” Tailwind ๋…๋ฆฝ ์‹คํ–‰ํ˜• CLI๋ฅผ ์œ„ํ•œ ์„ค์ • ๋ฐ ์ž…๋ ฅ CSS. CLI๋Š” ์ƒ์„ฑ๋œ HTML์„ ๋ถ„์„ํ•˜์—ฌ ์‹ค์ œ ์‚ฌ์šฉ๋˜๋Š” ์œ ํ‹ธ๋ฆฌํ‹ฐ๋งŒ ํฌํ•จํ•œ `site/assets/tailwind.css`๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค. +- `site.css` โ€” ์‚ฌ์ดํŠธ ์ „์šฉ ์Šคํƒ€์ผ๊ณผ Pygments ํ…Œ๋งˆ๋ฅผ ํฌํ•จํ•˜๋Š” ์ž‘์€ ์Šคํƒ€์ผ ๋ ˆ์ด์–ด + +Tailwind CLI ๋ฐ”์ด๋„ˆ๋ฆฌ, Mermaid ๋ฒˆ๋“ค ๋ฐ ๊ธ€๊ผด ํŒŒ์ผ์€ ์ฒซ ๋ฒˆ์งธ ๋นŒ๋“œ ์‹œ `scripts/.vendor-cache/`(gitignore ์ ์šฉ)๋กœ ๋‹ค์šด๋กœ๋“œ๋ฉ๋‹ˆ๋‹ค. ์ž์„ธํ•œ ๋‚ด์šฉ์€ `scripts/vendor_assets.py`๋ฅผ ์ฐธ๊ณ ํ•˜์‹ญ์‹œ์˜ค. + +์ œ๋ชฉ(anchor) ๋งํฌ๋Š” `check_cross_references.heading_to_anchor`์™€ ๋™์ผํ•œ ์•Œ๊ณ ๋ฆฌ์ฆ˜์œผ๋กœ ์ƒ์„ฑ๋˜๋ฏ€๋กœ, pre-commit Hook์—์„œ ๊ฒ€์ฆํ•œ `#anchor` ๋งํฌ๊ฐ€ ๋ Œ๋”๋ง๋œ ์‚ฌ์ดํŠธ์—์„œ๋„ ์˜ฌ๋ฐ”๋ฅด๊ฒŒ ๋™์ž‘ํ•ฉ๋‹ˆ๋‹ค. diff --git a/ko/translate_docs.py b/ko/translate_docs.py new file mode 100644 index 00000000..f76292ae --- /dev/null +++ b/ko/translate_docs.py @@ -0,0 +1,72 @@ +import os +from pathlib import Path +from google import genai +import time + +# 1. ํด๋ผ์ด์–ธํŠธ ์ดˆ๊ธฐํ™” +client = genai.Client() + +# ๋ฒˆ์—ญ ๋Œ€์ƒ ๊ฒฝ๋กœ (์šฐ๋ฆฌ๊ฐ€ ๋ณต์‚ฌํ•ด๋‘” ko ํด๋”) +# TARGET_DIR = Path("./06-hooks") + +# LLM์—๊ฒŒ ์ค„ ๋ฒˆ์—ญ ๊ฐ€์ด๋“œ๋ผ์ธ ์ง€์‹œ์„œ (์‹œ์Šคํ…œ ํ”„๋กฌํ”„ํŠธ) +SYSTEM_PROMPT = """ +You are a professional technical translator specializing in software engineering. +Your task is to translate the provided Markdown document from English to Korean. + +Strictly adhere to the following rules: +1. Translate only the explanatory text sentences into natural, professional Korean. +2. NEVER translate or modify code blocks (```python, ```sh, ```json, ```mermaid, etc.). Keep them exactly as they are. +3. NEVER translate Git commands, Claude Code slash commands (e.g., /init, /compact), or configuration keys. +4. Maintain all Markdown syntax, headings (#, ##), bold texts (**), and relative links ([text](./path)) exactly as in the original. +5. Return ONLY the translated markdown content without any introduction or out-of-context remarks. +6. Heading and Table of Contents (TOC) Translation Rules: + - When translating headings (e.g., `# Heading`, `## Subheading`), do NOT keep the original English text alongside the Korean translation. Replace the English title completely with the natural Korean translation. + - Example: Change `## Configuration` directly to `## ๊ตฌ์„ฑ`. Do NOT output `## Configuration\n## ๊ตฌ์„ฑ`. +7. Internal Anchor Link Rules: + - When translating a Table of Contents or internal links (e.g., `[Overview](#overview)`), translate the visible text into Korean and update the anchor block link to match the newly translated Korean heading. + - Spaces in Korean headings must be replaced with hyphens (-) in the anchor link, and all special characters should be handled according to standard Markdown slug rules. + - Example: + - `1. [Overview](#overview)` -> `1. [๊ฐœ์š”](#๊ฐœ์š”)` + - `2. [Planning Mode](#planning-mode)` -> `2. [๊ธฐํš ๋ชจ๋“œ](#๊ธฐํš-๋ชจ๋“œ)` + - `3. [File Format](#file-format)` -> `3. [ํŒŒ์ผ ํ˜•์‹](#ํŒŒ์ผ-ํ˜•์‹)` +""" + +def translate_file(file_path: Path): + print(f"๐Ÿ“„ ๋ฒˆ์—ญ ์‹œ์ž‘: {file_path}") + + # ํŒŒ์ผ ์ฝ๊ธฐ (์ธ์ฝ”๋”ฉ ์—๋Ÿฌ ๋ฐฉ์ง€๋ฅผ ์œ„ํ•ด utf-8 ๋ช…์‹œ) + with open(file_path, "r", encoding="utf-8") as f: + content = f.read() + + if not content.strip(): + return + + # 2. Gemini API ํ˜ธ์ถœ + response = client.models.generate_content( + model='gemini-2.5-flash', # ๋น ๋ฅด๊ณ  ๋น„์šฉ ํšจ์œจ์ ์ธ ๋ชจ๋ธ ์„ ํƒ + contents=f"{SYSTEM_PROMPT}\n\n[Document to Translate]\n{content}" + ) + + translated_text = response.text + + # 3. ๋ฒˆ์—ญ๋ณธ ๋ฎ์–ด์“ฐ๊ธฐ + with open(file_path, "w", encoding="utf-8") as f: + f.write(translated_text) + + print(f"โœ… ๋ฒˆ์—ญ ์™„๋ฃŒ: {file_path}\n") + +def main(): + # ๐ŸŽฏ ํŠน์ • ํŒŒ์ผ ๊ฒฝ๋กœ ์ง€์ • (์—ญ์Šฌ๋ž˜์‹œ \ ๋Œ€์‹  ํŒŒ์ด์ฌ Path๊ฐ€ ํ˜ธํ™˜๋˜๋„๋ก ์Šฌ๋ž˜์‹œ / ์‚ฌ์šฉ) + target_file = Path("./CHANGELOG.md") + + if target_file.exists(): + try: + translate_file(target_file) + except Exception as e: + print(f"โŒ ์—๋Ÿฌ ๋ฐœ์ƒ ({target_file}): {e}") + else: + print(f"โŒ ํŒŒ์ผ์„ ์ฐพ์„ ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค: {target_file}") + +if __name__ == "__main__": + main()