Agent Skills › flexprice/flexprice › arch

arch

GitHub

用于导航和理解FlexPrice仓库架构，包括目录结构、依赖关系和关键流程。提供文档映射与分析方法，指导如何快速定位代码上下文、检查异步边缘及耦合度，并在修改后更新架构文档以维持代码库知识的一致性。

.cursor/skills/arch/SKILL.md flexprice/flexprice

Trigger Scenarios

需要理解仓库整体结构时进行代码重构或新功能开发前需梳理依赖需要定位特定功能模块的边界上下文更新架构相关文档

Install

npx skills add flexprice/flexprice --skill arch -g -y

More Options

Use without installing

npx skills use flexprice/flexprice@arch

指定 Agent (Claude Code)

npx skills add flexprice/flexprice --skill arch -a claude-code -g -y

安装 repo 全部 skill

npx skills add flexprice/flexprice --all -g -y

预览 repo 内 skill

npx skills add flexprice/flexprice --list

SKILL.md

Frontmatter

{
    "name": "arch",
    "description": "FlexPrice repo architecture — docs\/ layering, deps, hotspots, flows, Graphify. Say arch, repo architecture, FLEXPRICE structure, onboarding codebase."
}

`arch` — repository architecture

Use when navigating cmd/, internal/, ent/ (billing, metering, Temporal, Kafka, integrations).

Other repos: repo-architecture-intelligence (~/.cursor/skills/repo-architecture-intelligence/SKILL.md).

Sibling skills: README (apitest, devenv, godev, openapi, pr, gh, compose).

Canonical documentation map

Doc	Purpose
`docs/REPO_MAP.md`	Directory census, deployment modes, major systems
`docs/ARCHITECTURE.md`	Principles, infra choices, layering, conventions
`docs/DEPENDENCY_GRAPH.md`	Fan-in/out, messaging DAG, coupling notes
`docs/HOTSPOTS.md`	Large files & structural risks
`docs/FLOWS/*.md`	End-to-end narratives for critical paths

Rule: Prefer these artifacts over improvised mental models. If docs drift from code during your change, patch the relevant markdown.

How to analyze architecture quickly

Identify deployment surface — cmd/server/main.go + deployment.mode. Determine whether edits affect API-only paths, Kafka consumers, or Temporal workers (registerRouterHandlers & startTemporalWorker branches).
Locate the bounded context — map feature → domain package (internal/domain/<ctx>) → repository impl (repository/ent vs repository/clickhouse) → service (internal/ee/service/<file>) → handler (internal/api/v1).
Check async edges — list Kafka topics touched (search config keys under internal/config) and Temporal workflow names (internal/temporal/workflows).
Assess coupling — if you need half of ServiceParams, consider narrowing new code’s dependencies deliberately.

How to reason about dependencies

Follow canonical direction: handlers → services → (domain interfaces + repos/integrations) → storage/IO (see diagram in docs/DEPENDENCY_GRAPH.md).
Watch logical cycles: Temporal registration reconstructs some services independently of Fx (internal/temporal/registration.go).
Question globals: prefer replacing new uses of GetGlobalTemporalService with injected interfaces when editing those call sites safely.

How to persist repository memory

After meaningful structural edits:

Change type	Update
New package / major subsystem	`REPO_MAP.md` (+ `ARCHITECTURE.md` boundaries if philosophical)
New topic/consumer or coupling	`DEPENDENCY_GRAPH.md` + YAML pointer
Emerging risk/god file growth	`HOTSPOTS.md` entry
Flow behavior change	Relevant `docs/FLOWS/<name>.md`

Treat docs as durable context for future automation and onboarding.

How to refactor safely

Freeze scope — isolate one bounded context or one pipeline stage.
Add or extend characterization tests closest to seams you cut (heavy services deserve targeted tests despite size).
Avoid splitting multi-thousand-line files blindly — extract cohesive types/helpers with stable interfaces (subscription.go, invoice.go, billing.go).
For schema changes — always make generate-ent + deliberate migration rollout; annotate operational risk if backfill jobs required.
For messaging — verify consumer group uniqueness and DLQ configuration when adjusting handler semantics (internal/pubsub/router).