{"id":51719330,"url":"https://github.com/ayato-labs/projectcodemap","last_synced_at":"2026-07-17T08:05:02.119Z","repository":{"id":370941801,"uuid":"1297969687","full_name":"ayato-labs/ProjectCodeMap","owner":"ayato-labs","description":"AIへのディレクトリ構造伝達を最適化し、AI駆動開発（AIDD）を円滑にするためのツール。","archived":false,"fork":false,"pushed_at":"2026-07-12T06:07:52.000Z","size":159,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-12T06:11:56.558Z","etag":null,"topics":["ai-development","aider","cli-tool","cline","context-engineering","context-optimization","cursor-ide","developer-productivity","developer-tools","llm","productivity","project-structure","python","rag","tree-sitter"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ayato-labs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-12T04:09:48.000Z","updated_at":"2026-07-12T06:07:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ayato-labs/ProjectCodeMap","commit_stats":null,"previous_names":["ayato-labs/projectcodemap"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ayato-labs/ProjectCodeMap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayato-labs%2FProjectCodeMap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayato-labs%2FProjectCodeMap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayato-labs%2FProjectCodeMap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayato-labs%2FProjectCodeMap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ayato-labs","download_url":"https://codeload.github.com/ayato-labs/ProjectCodeMap/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayato-labs%2FProjectCodeMap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35573737,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-17T02:00:06.162Z","response_time":116,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-development","aider","cli-tool","cline","context-engineering","context-optimization","cursor-ide","developer-productivity","developer-tools","llm","productivity","project-structure","python","rag","tree-sitter"],"created_at":"2026-07-17T08:04:58.783Z","updated_at":"2026-07-17T08:05:02.114Z","avatar_url":"https://github.com/ayato-labs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ProjectCodeMap\n\n[![PyPI Version](https://img.shields.io/pypi/v/project-code-map.svg)](https://pypi.org/project/project-code-map/)\n[![Python Versions](https://img.shields.io/pypi/pyversions/project-code-map.svg)](https://pypi.org/project/project-code-map/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Build Status](https://github.com/ayato-labs/ProjectCodeMap/actions/workflows/ci.yml/badge.svg)](https://github.com/ayato-labs/ProjectCodeMap/actions/workflows/ci.yml)\n[![Code Style: Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n\n**AI駆動開発（AIDD）における「コンテキスト伝達の壁」を突破する、リポジトリ構造マッピングツール。**\n\nWebのAIチャット（ChatGPT, Claude, Gemini等）やAI IDE（Cursor, Cline, Aider等）にプロジェクト全体を理解させたいとき、「ディレクトリ構造をどう伝えるか」で毎回苦労していませんか？  \n`ProjectCodeMap` は、プロジェクトをスキャンし、**LLMが最小トークンで最大の文脈を把握できる形式（ツリー構造＋関数シグネチャ＋依存関係）** で出力します。\n\n## 解決する課題\n\n| 従来の悩み | ProjectCodeMapでの解決 |\n|---|---|\n| ツリー構造を手動でコピペしてトークンを浪費する | **トークン効率の良い構造化出力（Text/JSON/XML/Markdown）** でワンショット注入 |\n| 関数名しか見えず、責任境界がAIに伝わらない | **tree-sitterによるAST解析**でシグネチャ＋ドックストリング要約を自動抽出 |\n| `node_modules` や `__pycache__` 等のノイズが混入する | **`.gitignore`準拠・独自設定（`.pcmignore`）で高精度な除外** |\n| AI IDEごとに設定方法がバラバラ | **Aider / Cursor / Cline 等の標準プロトコル対応出力オプション** を内蔵 |\n\n## インストール\n\n### 即座に実行（推奨: `uv` / `pipx`）\n```bash\n# インストール不要で即実行 (uv)\nuvx project-code-map\n\n# または 専用環境にインストール (pipx)\npipx install project-code-map\nproject-code-map\n```\n\n### 開発・プロジェクトローカル導入\n```bash\n# プロジェクトの dev 依存に追加\npip install --editable .[dev]\n# または poetry/uv 等で\nuv add --dev project-code-map\n```\n\n## クイックスタート\n\n```bash\n# 1. プロジェクトルートで実行\nproject-code-map\n\n# 2. AIに最適な形式で出力してファイル保存 (XMLはトークン効率が良い)\nproject-code-map --format xml \u003e context.xml\n\n# 3. 生成された context.xml をAIチャットに貼り付け、または Cursor/Cline のカスタム指示に設定\n```\n\n## 出力形式の例\n\n### デフォルト（人間可読・Markdownツリー）\n```markdown\n# Project Code Map\n\n## Directory Structure\nproject_root/\n├── src/\n│   ├── __init__.py\n│   ├── core/\n│   │   ├── __init__.py\n│   │   ├── scanner.py      # scan_project, FileNode\n│   │   └── parser.py       # parse_python, extract_functions\n│   └── cli.py              # main entry point\n├── tests/\n│   └── test_scanner.py\n├── pyproject.toml\n└── README.md\n\n## Function Index (src/)\n### src/core/scanner.py\n- `scan_project(root: Path, config: Config) -\u003e ProjectMap`\n- `filter_ignored(files: list[Path], patterns: list[str]) -\u003e list[Path]`\n\n### src/core/parser.py\n- `parse_python(content: str) -\u003e list[FunctionDef]`\n- `extract_docstring(node: ast.AST) -\u003e str | None`\n```\n\n### AI注入用（XML・トークン効率重視）\n```xml\n\u003cproject_map\u003e\n  \u003cstructure\u003e\n    \u003cdir name=\"src\"\u003e\n      \u003cdir name=\"core\"\u003e\n        \u003cfile name=\"scanner.py\"\u003e\n          \u003cfunction name=\"scan_project\" signature=\"scan_project(root: Path, config: Config) -\u003e ProjectMap\" docstring=\"Recursively scans project root...\" /\u003e\n          \u003cfunction name=\"filter_ignored\" signature=\"filter_ignored(files: list[Path], patterns: list[str]) -\u003e list[Path]\" docstring=\"Filters files based on gitignore patterns...\" /\u003e\n        \u003c/file\u003e\n      \u003c/dir\u003e\n    \u003c/dir\u003e\n  \u003c/structure\u003e\n  \u003cstats\u003e\n    \u003cfiles_total\u003e42\u003c/files_total\u003e\n    \u003cfunctions_total\u003e128\u003c/functions_total\u003e\n    \u003ctokens_estimate\u003e3.2k\u003c/tokens_estimate\u003e\n  \u003c/stats\u003e\n\u003c/project_map\u003e\n```\n\n## AIツール連携ガイド（ワークフロー統合）\n\n### Aider (CLI AI Pair Programming)\n```bash\n# リポジトリマップとして自動利用させる\nproject-code-map --format aider \u003e .aider.repo-map\naider --read-map .aider.repo-map\n```\n\n### Cursor (IDE)\n1. `project-code-map --format xml \u003e .cursor/context.xml`\n2. **Settings → Rules → Custom Instructions** に以下を追加：\n   ```\n   @.cursor/context.xml を参照してプロジェクト全体構造を把握してください。\n   ```\n\n### Cline (VS Code Extension)\n1. `project-code-map --format markdown \u003e .cline/project_map.md`\n2. `.clinerules` またはタスク指示で：\n   \u003e プロジェクト構造は `.cline/project_map.md` に定義されています。必ず参照してからコード生成を行ってください。\n\n### 汎用LLM (ChatGPT / Claude / Gemini Web UI)\n```bash\n# トークン制限に合わせてサイズ調整\nproject-code-map --format xml --max-tokens 8000 \u003e context.xml\n```\n生成された `context.xml` をプロンプトの冒頭に貼り付け：\n\u003e 「以下のプロジェクトマップを参照し、XXXのバグ修正案を提示してください。」\n\n## 設定カスタマイズ\n\nプロジェクトルートに `.pcmignore` または `pyproject.toml` の `[tool.project-code-map]` セクションで設定可能。\n\n### `.pcmignore` (`.gitignore` 互換シンタックス)\n```gitignore\n# デフォルト除外に追加\n*.generated.py\ndocs/\n*.snap\n```\n\n### `pyproject.toml` での詳細設定\n```toml\n[tool.project-code-map]\n# 解析対象言語 (tree-sitter対応分)\nlanguages = [\"python\", \"php\"]\n\n# 出力制御\nmax_file_size_kb = 500\nmax_functions_per_file = 50\ninclude_docstrings = true\ndocstring_max_length = 200\n\n# 除外パターン (正規表現も可)\nexclude_patterns = [\n    \"**/migrations/**\",\n    \"**/fixtures/**\",\n    \"**/*.test.py\"\n]\n\n# 出力デフォルト\ndefault_format = \"xml\"\ndefault_max_tokens = 8000\n```\n\n## CLI リファレンス\n\n```bash\nproject-code-map [OPTIONS]\n\nOptions:\n  -r, --root PATH              スキャン対象ルートディレクトリ (default: .)\n  -f, --format [text|json|xml|markdown|aider]  出力形式 (default: text)\n  -o, --output FILE            出力先ファイル (default: stdout)\n  --max-tokens INT             概算トークン上限で出力を切り詰め\n  --config FILE                設定ファイル指定 (default: pyproject.toml / .pcmignore)\n  --include-hidden             ドットファイル/隠しディレクトリも対象にする\n  --no-gitignore               .gitignore を無視する\n  -v, --verbose                詳細ログ\n  --version                    バージョン表示\n  -h, --help                   ヘルプ表示\n```\n\n## 開発・コントリビューション\n\n### 環境構築\n```bash\ngit clone https://github.com/ayato-labs/ProjectCodeMap.git\ncd ProjectCodeMap\nuv sync --dev  # または pip install -e .[dev]\n```\n\n### テスト・リンティング実行\n```bash\n# 全チェック (CIと同等)\nuv run ruff check .\nuv run ruff format --check .\nuv run mypy src/\nuv run pytest -v\n```\n\n### リリース手順 (Maintainer用)\n```bash\n# バージョン更新後\nuv build\nuv publish  upload dist/*\ngit tag v$(uv version --short)\ngit push --tags\n```\n\n## アーキテクチャ概要\n\n```\nproject-code-map\n├── src/\n│   ├── __init__.py\n│   ├── cli.py              # Typer CLI エントリーポイント\n│   ├── config.py           # 設定読み込み (pydantic + pyproject.toml)\n│   ├── scanner.py          # ファイルシステム走査 + .gitignore/.pcmignore 適用\n│   ├── parser/             # 言語別パーサー (tree-sitter ラッパー)\n│   │   ├── __init__.py\n│   │   ├── base.py         # 共通インターフェース\n│   │   ├── python.py       # Python AST 抽出\n│   │   └── php.py          # PHP AST 抽出\n│   ├── formatters/         # 出力フォーマッタ\n│   │   ├── __init__.py\n│   │   ├── text.py\n│   │   ├── json.py\n│   │   ├── xml.py\n│   │   ├── markdown.py\n│   │   └── aider.py\n│   └── models.py           # データクラス\n├── tests/\n├── pyproject.toml\n└── .github/workflows/ci.yml\n```\n\n## 依存関係 (主要)\n- **`tree-sitter` / `tree-sitter-python` / `tree-sitter-php`**: 高速・堅牢なAST解析\n- **`pathspec`**: `.gitignore` パターンマッチング (Git互換)\n- **`pydantic`**: 設定バリデーション\n- **`typer`**: モダンなCLI構築\n- **`rich`**: コンソール出力\n\n## ライセンス\nMIT License - 詳細は [LICENSE](LICENSE) を参照。\n\n## 謝辞\n- [Aider](https://github.com/Aider-AI/aider) の Repo Map 概念に着想を得ています。\n- [tree-sitter](https://tree-sitter.github.io/tree-sitter/) コミュニティに感謝。\n\n---\n\n**Star ⭐ していただけると開発の励みになります！**  \nIssue・PR・質問・要望は [GitHub Issues](https://github.com/ayato-labs/ProjectCodeMap/issues) までお気軽に。","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fayato-labs%2Fprojectcodemap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fayato-labs%2Fprojectcodemap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fayato-labs%2Fprojectcodemap/lists"}