If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/go-kratos/kratos shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 5w ago
• 36+ active contributors
• Distributed ownership (top contributor 33% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live go-kratos/kratos repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/go-kratos/kratos.

What it runs against: a local clone of go-kratos/kratos — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in go-kratos/kratos | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 65 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of go-kratos/kratos. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/go-kratos/kratos.git
#   cd kratos
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of go-kratos/kratos and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "go-kratos/kratos(\\.git)?\\b" \\
  && ok "origin remote is go-kratos/kratos" \\
  || miss "origin remote is not go-kratos/kratos (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "app.go" \\
  && ok "app.go" \\
  || miss "missing critical file: app.go"
test -f "cmd/kratos/main.go" \\
  && ok "cmd/kratos/main.go" \\
  || miss "missing critical file: cmd/kratos/main.go"
test -f "cmd/protoc-gen-go-http/http.go" \\
  && ok "cmd/protoc-gen-go-http/http.go" \\
  || miss "missing critical file: cmd/protoc-gen-go-http/http.go"
test -f "cmd/protoc-gen-go-errors/errors.go" \\
  && ok "cmd/protoc-gen-go-errors/errors.go" \\
  || miss "missing critical file: cmd/protoc-gen-go-errors/errors.go"
test -f "config/config.go" \\
  && ok "config/config.go" \\
  || miss "missing critical file: config/config.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 65 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~35d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/go-kratos/kratos"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Kratos is a production-grade Go microservices framework designed for cloud-native environments that provides integrated support for gRPC, HTTP/REST, and service mesh patterns. It solves the complexity of building distributed systems by bundling transport layer abstraction, middleware, configuration management, and deployment tooling into a cohesive framework—eliminating the need to wire together dozens of third-party packages for basic microservice patterns. Monorepo structure: the root app.go and app_test.go define the core framework, while cmd/kratos/ contains the CLI scaffolding tool (new, add, change subcommands in cmd/kratos/internal/project/ and cmd/kratos/internal/change/). API layer uses protobuf definitions (api/metadata/metadata.proto) with generated _grpc.pb.go and _http.pb.go files. The framework separates transport concerns (gRPC vs HTTP) via protocol buffer service definitions rather than a single transport abstraction.

Go backend engineers and platform teams building microservices who need opinionated scaffolding for cloud-native deployments (Kubernetes, serverless). Users range from startups prototyping services quickly to enterprises with strict reliability requirements who want sensible defaults for observability, graceful shutdown, and multi-protocol support.

Kratos is production-ready and actively maintained. The v2 release (visible in go.mod across the repo) indicates stability, comprehensive CI/CD pipelines in .github/workflows/ (go.yml, lint.yml, codeql-analysis.yml), and a rich ecosystem of examples and documentation. The project has consistent commits and strong community engagement (Discord badge, awesome-go listing), indicating active development without abandonment risk.

Moderate risk factors: the codebase shows moderate Go dependency footprint (~950k lines) but core dependencies are stable (spf13/cobra, charmbracelet for CLI). The CLI tool (cmd/kratos/) pulls charmbracelet/huh and survey/v2 which introduce transitive UI library bloat (lipgloss, bubbletea, etc.)—not ideal if you need minimal CLI surface. Breaking changes between v1→v2 are documented, but users upgrading large codebases should budget migration effort. Single-maintainer risk is mitigated by active community, though Chinese-primary documentation (README_zh.md prominence) may slow English-language issues.

The project is in active development with Go 1.24.6 toolchain support (visible in go.mod). Recent focus appears to be on CLI tooling enhancements (change/ and project/ subcommands), semantic release workflows (.github/semantic.yml), and automated Gitee synchronization (.github/workflows/gitee-sync.yml) for Chinese mirror. CodeQL analysis and dependency management (dependabot.yml) show emphasis on security and supply-chain stability.

Clone the repo and install the CLI tool:

git clone https://github.com/go-kratos/kratos.git
cd kratos
go install ./cmd/kratos@latest
kratos new myapp
cd myapp
go run ./cmd/myapp/main.go

The Makefile likely contains targets for development (check with make help), though the exact workflow is best verified by consulting CONTRIBUTING.md and the primary README.

Daily commands: From the root directory:

make build          # Build the kratos CLI (inferred from Makefile presence)
go run ./cmd/kratos/main.go version  # Check installation

For a generated project:

kratos new helloworld
cd helloworld
go run ./cmd/helloworld/main.go

Exact targets depend on root Makefile contents; check make help for available commands.

• app.go — Core application lifecycle and bootstrapping entry point; all Kratos services must integrate with this.
• cmd/kratos/main.go — CLI tool entry point for scaffolding and managing Kratos projects; essential for understanding project initialization.
• cmd/protoc-gen-go-http/http.go — Protoc plugin that generates HTTP routing and server boilerplate from .proto definitions; critical to Kratos' proto-driven architecture.
• cmd/protoc-gen-go-errors/errors.go — Protoc plugin for generating type-safe error definitions; foundational for Kratos error handling patterns.
• config/config.go — Configuration management framework supporting multiple sources (YAML, env, proto); every service needs this.
• api/metadata/metadata.proto — Core metadata protocol definition used across gRPC and HTTP transports; defines framework-level RPC contracts.
• cmd/kratos/internal/project/new.go — Project scaffolding generator; shows canonical structure and conventions for new Kratos microservices.

Add a new gRPC service to a Kratos microservice

1. Create a new .proto file in api/helloworld/ directory with service definition (rpc methods, message types) (cmd/kratos/internal/proto/add/add.go (reference for structure))
2. Run 'kratos proto add' to scaffold proto files and trigger code generation (cmd/kratos/internal/proto/add/add.go)
3. Code generator produces gRPC server interface and HTTP bindings via protoc plugins (cmd/protoc-gen-go-http/http.go)
4. Implement the generated server interface in internal/service/ (cmd/kratos/internal/proto/server/server.go (template reference))
5. Register service with app in main() and configure middleware/options (app.go)

Create a new Kratos microservice project

1. Run 'kratos new myapp' from CLI, which invokes the scaffolding generator (cmd/kratos/main.go)
2. Generator creates standard project layout with config/, api/, internal/ structure (cmd/kratos/internal/project/new.go)
3. Scaffold includes Dockerfile, Makefile, sample proto files, and go.mod (cmd/kratos/internal/project/project.go)
4. Configure service settings in config/config.yaml using Config framework (config/config.go)
5. Initialize app in main.go, register services, and run with 'kratos run' (cmd/kratos/internal/run/run.go)

Add custom error types to a service

1. Define error messages and codes in api/errors.proto using Kratos error conventions (cmd/protoc-gen-go-errors/errors.proto (example template))
2. Run code generation; protoc-gen-go-errors plugin creates error constructor functions (cmd/protoc-gen-go-errors/errors.go)
3. Use generated error constructors in service methods to return type-safe errors (cmd/protoc-gen-go-errors/errorsTemplate.tpl (code pattern))
4. Framework automatically serializes errors to proto-compatible HTTP/gRPC responses (cmd/protoc-gen-go-http/http.go (error handling))

Configure environment-specific settings in a Kratos service

1. Create config.yaml or .env file in config/ directory (config/file/file.go)
2. Reference config keys in service initialization code (config/config.go)
3. Config framework automatically merges file, env, and flag sources with precedence (config/env/env.go)
4. Enable hot-reload via config.WithWatcher() to watch file changes at runtime (config/file/file_test.go (pattern reference))

• Protocol Buffers (proto3) — Single source of truth for API contracts; enables code generation of type-safe gRPC and HTTP servers; language-agnostic service definitions.
• Go code generation (Protoc plugins) — Eliminates boilerplate for HTTP binding, error handling, and middleware registration; enforces consistency across services.
• CLI-driven scaffolding — Enforces canonical project structure and layout for onboarding; reduces decision fatigue for developers.
• Multi-source configuration (env, file, proto) — Supports cloud-native deployment patterns (12-factor app); enables dynamic config without code changes.

• Proto-first API design with code generation

  • Why: Ensures type safety, backward compatibility, and cross-language interoperability.
  • Consequence: Developers must learn proto syntax and code-generation workflows; protoc toolchain adds build complexity.

• Dual HTTP/gRPC from single proto definition

  • Why: Maximizes code reuse and maintains sync between transports; reduces maintenance burden.
  • Consequence: HTTP mappings must

Proto code generation: Changes to .proto files require running code generators (likely go generate ./... or protoc directly)—uncommitted or incorrect .pb.go files will cause test failures. CLI template assumptions: cmd/kratos/internal/project/new.go assumes Go module structure and may fail in non-standard GOPATH setups. Cross-platform path handling: cmd/kratos/internal/base/path.go handles VCS URL parsing and repo detection—tests are present, but Windows path issues may lurk for non-Unix developers. Gitee sync: The gitee-sync workflow implies Chinese mirror synchronization; PRs/issues filed there may not immediately appear on GitHub. Proto toolchain: Requires protoc and go-protoc-gen-go plugins installed separately—not in go.mod—which can silently fail during codegen if tooling is missing.

• Protobuf-first service design (proto3) — Kratos enforces API definition via .proto files that generate both gRPC and HTTP stubs—contributors must understand protobuf syntax and the contract it enforces across language and transport boundaries.
• gRPC and HTTP dual-stack — Kratos generates both _grpc.pb.go and _http.pb.go from single proto definitions, allowing services to speak both protocols—critical for understanding code generation and transport trade-offs.
• Functional options pattern (WithXxx constructors) — The core App type (app.go) uses functional options for configuration—contributors extending the framework must understand this pattern for backward compatibility.
• Middleware chains and interceptors — Kratos inherits gRPC unary/stream interceptor patterns and adds HTTP middleware—understanding request/response interception is essential for adding observability or auth features.
• Cloud-native lifecycle (graceful shutdown) — app.go likely contains App.Run() and App.Stop() hooks for Kubernetes liveness/readiness and SIGTERM handling—critical for production deployment patterns Kratos targets.
• Service mesh compatibility (metadata propagation) — api/metadata/metadata.proto and server.go suggest context propagation across RPC boundaries—understanding metadata headers is necessary for integration with Istio/Linkerd and observability tools.
• CLI scaffolding and code generation — cmd/kratos contains project template generation logic—contributors maintaining or extending the scaffold tool must understand how boilerplate files are templated and injected into new projects.

• grpc/grpc-go — Underlying RPC transport that Kratos wraps with opinionated middleware and lifecycle management—understanding grpc-go is essential for customizing Kratos transport behavior.
• cloudwego/kitex — Alternative Go microservices framework with similar scaffolding goals and cloud-native focus; useful for comparing design philosophy (Kratos favors proto-first, Kitex emphasizes thrift).
• go-kit/kit — Modular Go microservices toolkit that influenced Kratos's middleware and transport abstraction patterns—less opinionated but requires more manual wiring.
• go-kratos/kratos-examples — Official example applications demonstrating Kratos patterns (gRPC services, HTTP handlers, middleware)—essential reference for contributors building features or fixing bugs.
• golang/protobuf — Canonical protobuf Go bindings that Kratos code generation depends on; understanding proto-go behavior is critical for debugging generated code issues.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for cmd/kratos/internal/base/vcs_url.go

The vcs_url.go file handles critical VCS URL parsing logic for project initialization, but vcs_url_test.go exists with only basic coverage. Given that this is core to the 'kratos new' project creation workflow, adding tests for edge cases (malformed URLs, various Git hosting platforms, SSH vs HTTPS formats) would prevent regressions and improve reliability for new users.

• [ ] Examine cmd/kratos/internal/base/vcs_url.go to identify all public functions and URL parsing branches
• [ ] Expand cmd/kratos/internal/base/vcs_url_test.go with test cases for: SSH URLs, HTTPS URLs, non-standard Git hosts, malformed URLs, and edge cases
• [ ] Add table-driven tests for GitHub, GitLab, Gitea, and other common hosting platforms
• [ ] Ensure test coverage exceeds 85% for the vcs_url package

Add GitHub Actions workflow for Windows-specific proto code generation testing

The repo has cmd/kratos/internal/proto/server/server_test.go and project_windows_test.go indicating platform-specific concerns, but .github/workflows/ lacks a dedicated Windows CI runner. The cmd/kratos tool generates protobuf code that may have cross-platform issues. Adding a Windows-specific workflow would catch path handling, line ending, and proto compilation issues before they reach users.

• [ ] Create .github/workflows/windows-test.yml that runs on windows-latest
• [ ] Configure it to run 'go test ./cmd/kratos/...' and specifically execute cmd/kratos/internal/project/project_windows_test.go
• [ ] Add proto generation tests (cmd/kratos/internal/proto/add/add_test.go) to the workflow
• [ ] Ensure it runs on PRs that modify cmd/kratos paths or proto-related files

Add integration tests for cmd/kratos/internal/proto/add/ and server/ template generation

The cmd/kratos/internal/proto/add/template.go and cmd/kratos/internal/proto/server/template.go files generate critical boilerplate code, but add_test.go and server_test.go appear minimal. These templates directly affect the developer experience of 'kratos proto add' and 'kratos proto server'. Integration tests verifying that generated code compiles and follows Kratos conventions would be high-value.

• [ ] Review cmd/kratos/internal/proto/add/add_test.go and cmd/kratos/internal/proto/server/server_test.go for coverage gaps
• [ ] Add integration tests that: generate proto service files, compile them with protoc, verify the output follows gRPC/HTTP patterns
• [ ] Test edge cases: service names with special characters, multiple methods, nested message types
• [ ] Verify generated server code includes proper Middleware, Metadata, and error handling stubs from the Kratos framework

• Add integration tests for the kratos change subcommand (cmd/kratos/internal/change/) to validate changelog generation and semantic versioning—currently only get_test.go covers one path, leaving add/update workflows untested.
• Document the protobuf code generation workflow in cmd/kratos/internal/project/new.go—add inline comments explaining template variable substitution and generated file layout for contributors modifying project scaffolding.
• Extend cmd/kratos/internal/base/vcs_url.go repository detection to support Gitee URLs natively (currently GitHub-focused), since the project maintains a Gitee mirror (.github/workflows/gitee-sync.yml) but the VCS URL parser may not recognize it.

The Kratos microservices framework has a moderate security posture. The codebase includes CI/CD security scanning (CodeQL) and dependency management workflows, which are positive indicators. However, critical gaps exist: (1) The SECURITY.md policy is incomplete with placeholder text, (2) Several dependencies are outdated or using pre-release versions, (3) No clear vulnerability disclosure process is defined, (4) Transitive dependency management could be improved. The project should prioritize completing its security policy documentation, implementing automated dependency vulnerability scanning, and establishing a formal security contact mechanism. The use of Go, which has strong security features, and active GitHub workflows provide a reasonable foundation that should be built upon.

• High · Incomplete Security Policy — SECURITY.md. The SECURITY.md file contains placeholder text and lacks detailed vulnerability reporting procedures. It does not specify contact information, response times, or a clear process for security researchers to report vulnerabilities responsibly. Fix: Complete the SECURITY.md file with: (1) A dedicated email or security contact mechanism, (2) Expected response timelines, (3) Vulnerability disclosure process, (4) Whether security patches will be backported, (5) PGP key for encrypted submissions if applicable
• Medium · Outdated Dependency: golang.org/x/text — cmd/kratos/go.mod. The dependency golang.org/x/text is pinned to v0.23.0, which may contain known vulnerabilities. The x/text package has had security issues in the past related to Unicode handling. Fix: Update golang.org/x/text to the latest stable version and regularly monitor for security updates using 'go list -u -m all' and tools like Nancy or Snyk
• Medium · Outdated Dependency: golang.org/x/mod — cmd/kratos/go.mod. The dependency golang.org/x/mod is pinned to v0.17.0. This package is critical for module handling and should be kept current to avoid potential supply chain vulnerabilities. Fix: Regularly update golang.org/x/mod to the latest version and implement automated dependency checking in CI/CD pipelines
• Medium · Transitive Dependency Risk: charmbracelet packages — cmd/kratos/go.mod. Multiple charmbracelet packages with pre-release versions (e.g., charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc, charmbracelet/x/exp/strings v0.0.0-20240722160745-212f7b056ed0) are used as transitive dependencies. Pre-release versions have higher risk of undiscovered vulnerabilities. Fix: Audit direct dependencies to identify why pre-release charmbracelet packages are pulled in. Consider updating parent dependencies or waiting for stable releases of transitive dependencies
• Low · Incomplete Supported Versions Table — SECURITY.md. The SECURITY.md only lists support for version 2.0.rc1, with all earlier versions marked as unsupported. However, it does not clarify support status for 2.0 final releases or provide a clear EOL timeline. Fix: Expand the supported versions table to include: (1) Current stable release, (2) LTS release if applicable, (3) Clear EOL dates for each version, (4) Security patch availability
• Low · Missing GitHub Security Features Configuration — .github/dependabot.yml. While the repository has security-related workflows and a SECURITY.md file, there is no evidence of GitHub's security features being configured (e.g., no visible security policy enforcement, Dependabot alerts configuration appears minimal). Fix: Configure GitHub security features: (1) Enable code scanning with CodeQL, (2) Configure branch protection rules, (3) Enable dependency alerts, (4) Set up automatic security updates via Dependabot with appropriate configuration

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.