ci: add PR English check and translate AGENTS.md for Codex review (#68)

YuminosukeSato · claude · web-flow · commit f591022a1907 · 2026-02-06T22:15:08.000+09:00
* ci: add PR English language check job Add pr-language job that checks PR title and body contain primarily ASCII characters (threshold: 30% non-ASCII fails). This enforces English-only PR descriptions for consistency. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: translate all AGENTS.md files to English Translate root and subdirectory AGENTS.md files from Japanese to English for Codex automatic review compatibility. Add Review Guidelines sections for Codex to follow. CLAUDE.md remains in Japanese as the Claude Code instruction file. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * ci: add Claude Code PR review workflow Add GitHub Actions workflow for automated PR review using anthropics/claude-code-action. Runs on PR open/sync and @claude comments. Uses OAuth token (Pro/Max plan) to avoid API usage costs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -232,6 +232,47 @@ jobs:
           name: benchmark-results
           path: bench/benchmark_results.txt
 
+  pr-language:
+    name: PR language check (English)
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check PR title and body are in English
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const title = context.payload.pull_request.title;
+            const body = context.payload.pull_request.body || '';
+
+            // Detect non-ASCII heavy content (CJK, Cyrillic, etc.)
+            const nonAsciiRatio = (str) => {
+              if (!str || str.length === 0) return 0;
+              const nonAscii = str.match(/[^\x00-\x7F]/g) || [];
+              return nonAscii.length / str.length;
+            };
+
+            const titleRatio = nonAsciiRatio(title);
+            const bodyRatio = nonAsciiRatio(body);
+
+            console.log(`Title non-ASCII ratio: ${(titleRatio * 100).toFixed(1)}%`);
+            console.log(`Body non-ASCII ratio: ${(bodyRatio * 100).toFixed(1)}%`);
+
+            const threshold = 0.3;
+            const issues = [];
+
+            if (titleRatio > threshold) {
+              issues.push(`PR title contains ${(titleRatio * 100).toFixed(0)}% non-ASCII characters. Please use English.`);
+            }
+            if (body.length > 0 && bodyRatio > threshold) {
+              issues.push(`PR body contains ${(bodyRatio * 100).toFixed(0)}% non-ASCII characters. Please use English.`);
+            }
+
+            if (issues.length > 0) {
+              core.setFailed(issues.join('\n'));
+            } else {
+              console.log('PR title and body are in English.');
+            }
+
   links:
     name: README and docs link check
     runs-on: ubuntu-latest
diff --git a/.github/workflows/claude.yml b/.github/workflows/claude.yml
@@ -0,0 +1,38 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          prompt: |
+            Review this PR. Follow the guidelines in CLAUDE.md and AGENTS.md.
+            Focus on:
+            - Correctness and potential bugs
+            - Go error wrapping (fmt.Errorf with %w)
+            - Python type hints and docstrings
+            - UDS security (socket permissions, HMAC)
+            - Performance regressions in IPC paths
+            Be concise. Only flag real issues.
+          claude_args: "--max-turns 5 --model claude-sonnet-4-5-20250929"
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,116 @@
+<!-- OPENSPEC:START -->
+# OpenSpec Integration
+
+This project uses OpenSpec for spec-driven development. When creating proposals, refer to:
+
+- `openspec/AGENTS.md` - Workflow and format
+- `openspec/project.md` - Project conventions
+- `openspec/specs/` - Current specifications
+- `openspec/changes/` - In-progress proposals
+
+Before starting spec-driven development, run `openspec list` and `openspec show [item]` to review the current state.
+<!-- OPENSPEC:END -->
+
+---
+
+# pyproc - AI Agent Instructions
+
+## Project Core
+
+pyproc's scope is fixed to "fast, stable invocation of Python from Go as if it were a local function, within the same host/Pod via UDS." Cross-host communication is out of scope.
+
+v1.0 "Done" means not adding features, but "meeting the conditions for enterprise adoption":
+- API/protocol stabilization
+- Documentation and automation of operations, observability, security, compatibility, and release processes
+
+## Public API (subject to SemVer)
+
+1. Go API: exported symbols in `pkg/pyproc` (Pool, WorkerConfig, CallTyped, CodecType, Transport, etc.)
+2. Python worker API: `expose`, `run_worker`
+3. Wire protocol: compatibility conditions for JSON/MessagePack/Protobuf codecs
+4. Config schema & env vars: `PYPROC_POOL_WORKERS`, `PYPROC_SOCKET_DIR`, etc.
+
+## SemVer Policy (0.y.z period)
+
+- Breaking changes bump MINOR (y)
+- v1.0.0 defines the Public API
+- Released versions are immutable (fixes ship as new versions)
+- Go: tags `vX.Y.Z` (Go Modules convention)
+- Python: PEP 440 compliant `X.Y.Z`
+
+Current version gap: Go v0.4.0 / pyproc-worker 0.1.0
+
+## Non-Goals
+
+- Cross-host communication (use gRPC/REST services instead)
+- Arbitrary user-submitted Python code execution (trusted code assumption)
+- GPU cluster management or distributed inference infrastructure
+
+## K8s/Container Strategy
+
+Achieved through "K8s + container distribution completeness," not cloud-specific solutions:
+- Reference Dockerfile (Go binary + Python runtime + pyproc-worker)
+- K8s manifests (emptyDir for socket write directory)
+- Same-container configuration is first-class (sidecar separation is a non-goal for v1.0)
+
+## v1.0 Roadmap
+
+- v0.5.0: High-efficiency IPC enhancements, config schema formalization, Dockerfile stabilization
+- v0.6.0: Public API outline freeze, deprecate-then-remove procedure, compatibility table publication
+- v0.7.0: Observability (metrics name/label/semantics stabilization)
+- v0.8.0: Security hardening (UDS permissions/HMAC auth templating, K8s emptyDir design guidelines)
+- v0.9.0: API Freeze, compatibility tests (contract tests) in CI
+- v1.0.0: Public API finalized, enterprise-ready release
+
+See `.ssd/` for details.
+
+## Command Reference
+
+```bash
+# Go tests (race detector enabled)
+go test -v -race ./...
+
+# Python tests
+cd worker/python && uv run pytest -v --cov=pyproc_worker
+
+# Go lint
+golangci-lint run ./...
+
+# Python lint + format
+cd worker/python && uv run ruff check . && uv run ruff format --check .
+
+# Benchmarks
+make bench-quick
+
+# OpenSpec
+openspec list
+openspec show [item]
+openspec validate --strict
+```
+
+## Subdirectory AGENTS.md
+
+- `worker/python/AGENTS.md` - Python worker development
+- `internal/AGENTS.md` - Go internal implementation
+- `docs/AGENTS.md` - Documentation
+- `bench/AGENTS.md` - Benchmarks
+
+## Documentation
+
+- `README.md` - User-facing overview
+- `CONTRIBUTING.md` - Contribution guide
+- `docs/design.md` - Design decisions
+- `docs/security.md` - Security threat model
+- `docs/ops.md` - Operations guide
+
+## Review Guidelines
+
+- Go errors must be wrapped with `fmt.Errorf("context: %w", err)`
+- Python functions must have type hints and Google-style docstrings
+- All exported Go types/functions must have doc comments
+- Channel operations must use `select + context.Done()` for cancellation
+- UDS socket permissions must be 0660
+- Do not log PII or secrets
+- Do not weaken tests, lints, or CI gates to pass checks
+- Security-related files (`docs/security.md`, `internal/protocol/`, `.claude/rules/security.md`) require explicit reviewer approval
+- Performance-sensitive changes in IPC hot paths must include benchmark results
diff --git a/bench/AGENTS.md b/bench/AGENTS.md
@@ -0,0 +1,44 @@
+# Benchmarks
+
+Performance measurement and CI gates.
+
+## Commands
+
+```bash
+# Quick run
+go test -bench=BenchmarkPool -benchtime=10x .
+
+# Full run (with memory profiling)
+go test -bench=. -benchtime=100x -benchmem .
+
+# Latency percentiles
+go test -bench=BenchmarkLatencyPercentiles -benchtime=10s .
+```
+
+## CI Gate Thresholds
+
+| Metric | Target | Notes |
+|--------|--------|-------|
+| p50 | < 100us | Simple function call |
+| p99 | < 500us | Includes GC and process overhead |
+
+Threshold violations trigger CI warnings (currently non-blocking).
+
+## Adding Benchmarks
+
+- `Benchmark` prefix required
+- Reflect real use cases (synthetic benchmarks must be labeled separately)
+- Include parallelism tests with varying worker counts
+- Output both req/s and latency
+
+## Notes
+
+- Python worker required (`uv sync` must be completed)
+- Socket files created at `/tmp/pyproc-*.sock`; cleaned up on exit
+- CI and local results may differ (use relative comparisons, not absolute values)
+
+## Review Guidelines
+
+- Benchmark changes must include before/after comparison results
+- Do not lower CI gate thresholds without explicit approval
+- New benchmarks must test realistic workloads
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
@@ -0,0 +1,41 @@
+# Documentation
+
+User-facing documentation. Built with MkDocs.
+
+## Commands
+
+```bash
+# Local preview
+mkdocs serve
+
+# Link validation (runs in CI)
+lychee --config ../.lychee.toml *.md
+```
+
+## File Structure
+
+```
+docs/
+├── design.md     Architecture, design decisions
+├── ops.md        Operations guide, monitoring, troubleshooting
+└── security.md   Threat model, security boundaries
+```
+
+## Writing Conventions
+
+- Heading levels: H1 for title only, body starts at H2
+- Code blocks: language specifier required (```go, ```python, ```bash)
+- Internal links: use relative paths (`[ops](ops.md)`)
+- External links: CI validates with lychee; broken links block merge
+
+## Notes
+
+- Changes to `security.md` require review (security impact)
+- Maintain consistency with README.md (avoid duplication, cross-reference)
+- Diagrams: use Mermaid or ASCII art (avoid external image dependencies)
+
+## Review Guidelines
+
+- All code examples must be runnable and tested
+- Security documentation changes require explicit reviewer approval
+- Links must be valid (CI enforced via lychee)
diff --git a/internal/AGENTS.md b/internal/AGENTS.md
@@ -0,0 +1,41 @@
+# Internal Packages
+
+Non-public implementation. Referenced only from pkg/pyproc.
+
+## Design Principles
+
+- Thin pkg, thick internal: public API in pkg/, implementation details in internal/
+- Interface boundaries: protocol, health, logging are independently swappable
+- Error propagation: always wrap with `fmt.Errorf("context: %w", err)`
+
+## Package Structure
+
+```
+internal/
+├── protocol/   UDS communication, message serialization (msgpack)
+├── health/     Health checks, automatic restart
+└── logging/    Structured logging
+```
+
+## Code Conventions
+
+- Doc comments required on all exported types/functions
+- context.Context is the first parameter
+- Channel operations must use select + context.Done() for cancellation
+- Table-driven tests recommended
+
+## Tests
+
+```bash
+go test -v -race ./internal/...
+go test -coverprofile=coverage.out ./internal/...
+```
+
+Coverage target: 100% (CI non-blocking but aimed for)
+
+## Review Guidelines
+
+- Errors must be wrapped with `fmt.Errorf("context: %w", err)`
+- All channel operations must be cancellable via context
+- Security-sensitive code in protocol/ requires explicit approval
+- No exported symbols should leak from internal/
diff --git a/worker/python/AGENTS.md b/worker/python/AGENTS.md
@@ -0,0 +1,61 @@
+# Python Worker
+
+pyproc-worker PyPI package. Python worker implementation called from Go via UDS.
+
+## Commands
+
+```bash
+# Install dependencies (pip is not supported)
+uv sync --all-extras --dev
+
+# Tests
+uv run pytest -v --cov=pyproc_worker --cov-report=term-missing
+
+# Lint & Format
+uv run ruff check .
+uv run ruff format --check .
+
+# Type check
+uv run ty check .
+```
+
+## Code Conventions
+
+- Type hints required on all function signatures
+- Docstrings: Google style (Args/Returns/Raises)
+- Use `@expose` decorator to register public functions
+- Raise errors explicitly; minimize catch blocks
+
+## File Structure
+
+```
+pyproc_worker/
+├── __init__.py       # expose, Worker class, run_worker exports
+├── codec.py          # JSONCodec, get_codec()
+├── tracing.py        # OpenTelemetry integration
+├── cancellation.py   # CancellationError, CancellationManager
+└── cli.py            # CLI entry point
+tests/
+└── test_*.py         # pytest format
+```
+
+## Public API (subject to SemVer)
+
+- `expose` decorator
+- `run_worker` function
+- Their arguments, exceptions, and return types will be frozen at v1.0
+
+## Notes
+
+- GIL is bypassed via process isolation (not threads)
+- Load models/heavy libraries at worker startup (not per-request)
+- Avoid memory leaks: do not accumulate global state
+- orjson is the default codec; msgspec is optional
+- Currently v0.1.0. Maintain compatibility table with Go side v0.4.0
+
+## Review Guidelines
+
+- All functions must have type hints and Google-style docstrings
+- Do not use pip; uv is the only supported package manager
+- Error messages must not leak internal state or PII
+- Test coverage must not decrease
