{
  "markdown": "# Python + uv + AI Agent Development Template\n\nThis repository serves as a template for developing Python applications using the [uv](https://docs.astral.sh/uv/) package manager. It comes pre-configured with Docker, Dev Containers, GitHub Actions CI, and common development tools.\n\n## Scope\n\nThis template targets **non-distributed Python applications** (services, internal tools, scripts) — it is not intended for building distributable libraries or wheels. It provides only the **outer scaffolding** (CI, containers, security tooling); the inner application code is intentionally minimal.\n\n`myapp/` is a placeholder package — rename it and replace its contents with your own. Tests are co-located under each package's `tests/` directory.\n\n## Features\n\n*   **Modern Python Stack:** Uses Python 3.14+ and `uv` for fast dependency management.\n*   **Containerized Development:**\n    *   **Docker & Docker Compose:** Provides consistent development and production environments using multi-stage builds (`dev`, `prod`, `devcontainer`).\n    *   **VSCode Dev Containers:** Includes a `.devcontainer/devcontainer.json` configuration that layers the AI agent toolchain (Claude Code CLI, Codex CLI, GitHub CLI, common utilities) on top of the project's Python environment via [Dev Container Features](https://containers.dev/implementors/features/) and post-create setup.\n*   **AI Agent Sandbox:** [Docker Sandboxes](https://docs.docker.com/ai/sandboxes/) (`sbx`) kits in `.sandbox/` run agents under stronger isolation — a microVM kernel boundary, deny-by-default networking, and credentials that never enter the VM. Coexists with the Dev Container; launched from the host.\n*   **Development Tools:** Integrated with standard development tools:\n    *   [`ruff`](https://docs.astral.sh/ruff/) for linting and formatting.\n    *   [`pyright`](https://microsoft.github.io/pyright/) for static type checking.\n    *   [`pytest`](https://docs.pytest.org/) for testing (including coverage reports).\n    *   [`taskipy`](https://github.com/taskipy/taskipy) for managing project tasks.\n*   **CI/CD:** GitHub Actions workflows (`.github/workflows/`) — a consolidated `ci.yml` runs linting, type checking, and tests (with a coverage PR comment) in a single job; companion workflows cover security scanning, SBOM generation, Dockerfile/workflow linting, and labeling.\n*   **Pre-commit Hooks:** `.pre-commit-config.yaml` runs ruff, pyright, and a lockfile check at commit time via [prek](https://github.com/j178/prek) — set up automatically in the Dev Container, optional elsewhere.\n*   **Shared Knowledge Base:** `docs/knowledge/` is an [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) bundle — a plain-Markdown knowledge base (ADRs, architecture notes, conventions, runbooks, research) that both humans and AI agents read and write. Ships as a labeled-sample skeleton; start at [`docs/knowledge/index.md`](docs/knowledge/index.md).\n\n## Security\n\nThis project implements supply chain attack protections.\ncf. https://zenn.dev/dajiaji/articles/47164ff27d2123\n\n- **Lockfile Integrity**: CI uses `uv sync --locked`, which fails when `uv.lock` is missing, tampered with, or out of sync with `pyproject.toml`\n- **Minimum Privileges**: Workflows use `permissions: {}` at top level\n- **SHA Pinning**: All GitHub Actions are pinned to commit SHAs\n- **Dependabot Cooldown**: 7-day delay before accepting new package versions\n- **Resolution Cooldown**: uv's [`exclude-newer`](https://docs.astral.sh/uv/concepts/resolution/#reproducible-resolutions) is set to `7 days`, so `uv lock` never resolves to packages released within the last 7 days (kept in sync with the Dependabot cooldown)\n- **Vulnerability Scanning**: Trivy scans dependencies on dependency/Dockerfile/workflow changes and weekly — PRs fail on CRITICAL/HIGH findings; `push`/`schedule` runs upload SARIF results to the GitHub Security tab\n- **SBOM Generation**: CycloneDX SBOM generated on dependency changes\n- **Workflow Auditing**: zizmor checks for workflow security issues\n\n> [!NOTE]\n> **Using this template in a private repository?** The SARIF upload to the Security tab requires Code scanning, which is free for public repositories but needs [GitHub Code Security](https://docs.github.com/en/code-security) for private ones — without it, the upload step fails with `Resource not accessible by integration`. If you keep your repository private, edit `.github/workflows/security.yml` to always use the table + exit-code approach instead:\n>\n> 1. Delete the SARIF-format \"Run Trivy vulnerability scanner\" step and the \"Upload Trivy scan results to GitHub Security tab\" step.\n> 2. Remove the `if: github.event_name == 'pull_request'` condition from the remaining table-format step.\n> 3. Remove `security-events: write` from the job's `permissions`.\n>\n> Alternatively, enable GitHub Code Security on the repository to keep the Security tab integration.\n\n## Directory Structure\n\n```\n.\n├── .claude/                    # Claude Code settings (permissions.defaultMode: auto)\n├── .devcontainer/              # Dev Container config (also runs the AI agent toolchain via Features)\n│   ├── codex-config.toml       # Initial Codex CLI config copied into the persisted ~/.codex volume\n│   ├── compose.yaml            # Devcontainer compose definition (merged with git-ignored compose.local.yaml)\n│   ├── devcontainer.json\n│   ├── initialize.sh           # Host-side hook: stages host git/Claude config for the container\n│   ├── post-create.sh\n│   ├── post-start.sh\n│   └── README.md               # AI agent toolchain, auth, isolation modes, PAT setup\n├── .dockerignore\n├── .editorconfig\n├── .github/                    # GitHub-specific files\n│   ├── copilot-instructions.md # Pointer to AGENTS.md for GitHub Copilot\n│   ├── dependabot.yml          # Dependabot configuration\n│   ├── ISSUE_TEMPLATE/         # Issue forms (bug, feature, task)\n│   ├── labeler.yml             # Path-based PR labeling config (used by label_pr.yml)\n│   ├── labels.yml              # Repository label definitions (synced via the manual Sync Labels workflow)\n│   ├── PULL_REQUEST_TEMPLATE.md\n│   ├── scripts/\n│   │   └── sync-labels.sh\n│   └── workflows/              # GitHub Actions CI workflows\n│       ├── ci.yml              # Lint + type check + tests (single job)\n│       ├── label_pr.yml        # PR auto-labeling (actions/labeler)\n│       ├── labels.yml          # Label sync (manual: workflow_dispatch)\n│       ├── lint_docker.yml\n│       ├── lint_gha.yml\n│       ├── sbom.yml            # SBOM generation\n│       └── security.yml        # Vulnerability scanning\n├── .gitignore\n├── .pre-commit-config.yaml     # Pre-commit hooks (run via prek)\n├── .python-version             # Specifies Python version (primarily for uv/tooling)\n├── .sandbox/                   # Docker Sandboxes (sbx) kits — stronger agent isolation (host-side)\n│   ├── claude-auto/            # Fork kit: claude's YOLO default -> --permission-mode auto\n│   ├── codex-approve/          # Fork kit: codex's YOLO default -> --approve-for-me\n│   ├── kit/                    # Shared mixin kit (uv, Python, prek, Codex CLI, network/credential rules)\n│   └── README.md               # sbx setup and host hand-off steps\n├── .vscode/                    # VSCode-specific files\n│   └── settings.json\n├── AGENTS.md                   # Project guidelines for AI agents and humans\n├── CLAUDE.md                   # Pointer to AGENTS.md for Claude Code\n├── Dockerfile                  # Defines container images (dev, prod, devcontainer)\n├── LICENSE\n├── README.md                   # This file\n├── compose.dev.yml             # Docker Compose configuration for development\n├── compose.yml                 # Docker Compose configuration for production\n├── docs/\n│   └── knowledge/              # Shared knowledge base (OKF bundle): ADRs, conventions, runbooks, ...\n├── myapp/                      # Placeholder application package — rename and replace\n│   ├── __init__.py\n│   ├── main.py                 # Sample application code\n│   └── tests/                  # Co-located tests (no __init__.py — uses pytest importlib mode)\n│       └── main_test.py\n├── pyproject.toml              # Project metadata and tool config (uv, ruff, pyright, pytest, taskipy)\n└── uv.lock                     # Pinned versions of dependencies\n```\n\n## Adopting This Template\n\nAfter creating a repository from this template:\n\n1. Rename the `myapp/` package directory to your project's name, then update every reference to it:\n    - `pyproject.toml`: `[project] name` and `description`, `--cov=myapp` in the `test_cov` task, `testpaths` under `[tool.pytest.ini_options]`, and `source` under `[tool.coverage.run]`\n    - `myapp/tests/main_test.py`: the `from myapp.main import hello` import\n2. Fill in the `LICENSE` placeholders (`[yyyy]`, `[name of copyright owner]`) — or replace the license entirely.\n3. Replace the sample documents in `docs/knowledge/` with real project knowledge (each sample carries a \"replace me\" banner).\n4. If your repository is private, adjust `.github/workflows/security.yml` as described in [Security](#security) (the Security-tab upload requires GitHub Code Security on private repositories).\n5. Run the **Sync Labels** workflow once (Actions → Sync Labels → Run workflow) to create the project labels (e.g. `meta`, used by PR auto-labeling) — label sync is manual-only.\n6. Run `uv sync && uv run task lint && uv run task test` to confirm the renamed project is healthy.\n\n## Getting Started\n\n### Prerequisites\n\n*   Docker and Docker Compose\n*   VSCode with the \"Dev Containers\" extension\n*   uv (if not using Docker)\n\n### Setup Options\n\n#### Option 1: Using VSCode Dev Containers\n\n1.  Open this repository in VSCode.\n2.  When prompted (\"Reopen in Container\"), click it. VSCode will build the development container and connect to it automatically.\n3.  You can now use the integrated terminal in VSCode, which runs inside the container.\n\n#### Option 2: Using Docker Compose Manually\n\n1.  **Build the development image:**\n    ```bash\n    docker compose -f compose.dev.yml build\n    ```\n2.  **Run commands inside the container:**\n    ```bash\n    docker compose -f compose.dev.yml run --rm app <command>\n    ```\n    For example, to run tests:\n    ```bash\n    docker compose -f compose.dev.yml run --rm app task test\n    ```\n    To get an interactive shell:\n    ```bash\n    docker compose -f compose.dev.yml run --rm app bash\n    ```\n\n#### Option 3: Using uv locally (without Docker)\n1.  **Install `uv`** (if not already installed):\n    ```bash\n    # cf. https://github.com/astral-sh/uv?tab=readme-ov-file#installation\n    curl -LsSf https://astral.sh/uv/install.sh | sh\n    ```\n2.  **Install dependencies:**\n    ```bash\n    uv sync\n    ```\n3.  **Run commands:**\n    ```bash\n    uv run <command>\n    ```\n    For example, to run tests:\n    ```bash\n    uv run task test\n    ```\n\n### Pre-commit Hooks (optional outside the Dev Container)\n\nThe Dev Container registers the git pre-commit hooks automatically (see `.devcontainer/post-create.sh`). If you work outside the container, [install prek](https://github.com/j178/prek?tab=readme-ov-file#installation) and run:\n\n```bash\nprek install\n```\n\nThe hooks (defined in `.pre-commit-config.yaml`) run `ruff check`, `ruff format --check`, `pyright`, and `uv lock --check` on each commit.\n\n### Available Tasks (using Taskipy)\n\nRun these tasks inside the development container (either via Dev Containers terminal or `docker compose run`):\n\n*   `task lint`: Run linters (`ruff check` and `pyright`).\n*   `task fix`: Automatically fix linting issues with `ruff`.\n*   `task format`: Format code with `ruff format`.\n*   `task test`: Run tests with `pytest`.\n*   `task test_cov`: Run tests and generate coverage reports.\n\nExample:\n```bash\n# Inside Dev Container terminal or after `docker compose run ... bash`\ntask lint\ntask test_cov\n```\n\n## AI Agent Dev Container\n\nThe Dev Container also serves as the runtime for AI coding agents (Claude Code, Codex, etc.) — setup and authentication are in [`.devcontainer/README.md`](.devcontainer/README.md); the mechanics behind it (host config inheritance, isolation modes and their limits, scoped GitHub PAT, task secrets) live in [`docs/knowledge/`](docs/knowledge/index.md).\n\n## AI Agent Sandbox (Docker Sandboxes)\n\nFor unattended agent runs that need stronger isolation than a Linux container —\na microVM kernel boundary, deny-by-default networking, and secrets that never enter the VM —\n`.sandbox/` ships kits for [Docker Sandboxes](https://docs.docker.com/ai/sandboxes/) (`sbx`).\nIt coexists with the Dev Container and is launched from the host, e.g.:\n\n```bash\nsbx create --clone --kit ./.sandbox/kit claude .\nsbx exec -it -w \"$PWD\" claude-<dir> claude --permission-mode auto\n```\n\n`sbx` runs on the host OS and cannot be used from inside the Dev Container.\nSee [`.sandbox/README.md`](.sandbox/README.md) for setup and for getting the work\nback to the host; [`docs/knowledge/runbooks/agent-sandbox-sbx.md`](docs/knowledge/runbooks/agent-sandbox-sbx.md)\ncovers the mechanics (why `--clone` is mandatory, network policy, secrets, troubleshooting).\n",
  "bytes": 13124,
  "sha": "d97708885248d2618c4845588b416df1c5322c7d8991f029b3f83bc69f5b4d6a",
  "repo_slug": "hanamizuno/python-uv-template",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_hanamizuno_python_uv_template_docs_knowl_65d8f7fd/readme"
}