probo/contrib/claude/file-naming.md

File naming conventions

Template files

Template files use the extension pattern <name>.<output-ext>.tmpl:

pkg/complianceportal/visitor/sitemap.xml.tmpl
pkg/server/mailactions/templates/page.html.tmpl
pkg/cookiebanner/prompts/tracker_identification.txt.tmpl
pkg/probo/templates/risk_list.json.tmpl
compose/keycloak/probo-realm.json.tmpl
pkg/esign/certificate.html.tmpl

The <output-ext> indicates the format produced after rendering (.xml, .html, .txt, .json). The final .tmpl suffix marks the file as a template requiring substitution before use.

Dynamic values over hardcoded lists

Never hardcode enum values or source-of-truth lists in template text. Use a placeholder and substitute at runtime so the template stays in sync with the code:

Use one of: {{.Categories}}.

For single-placeholder templates, strings.Replace is sufficient. For multiple placeholders, use text/template.

Worker files

Background worker files use the <name>_worker.go naming pattern. The file contains the handler struct, NewXxxWorker constructor, and the Claim/Process methods. Keep domain-specific helper methods (match, resolve, etc.) in the same file.

pkg/cookiebanner/tracker_mapping_worker.go
pkg/cookiebanner/pattern_analysis_worker.go

Agent files

A file whose sole purpose is to construct and operate an agent uses the <name>_agent.go suffix. The agent file owns agent construction, prompt building, the //go:embed directive for prompt templates, the typed result, the agent-specific config, and any agent-only constants (timeout, confidence threshold). Callers (workers, services) hold a *agent.Agent field and import the file's Build…Agent constructor.

This applies in two shapes:

1. Paired with a worker (most common). The worker file <worker_prefix>_worker.go stays focused on Claim/Process, and the agent it uses lives in <worker_prefix>_agent.go next to it.

   pkg/cookiebanner/tracker_mapping_worker.go   -- worker handler
   pkg/cookiebanner/tracker_mapping_agent.go    -- agent construction + prompts
   

2. Standalone, called from elsewhere. When the agent is consumed by a different package (or by multiple packages — e.g. an agent that operates on a domain entity, used by several feature workers), it lives in the package that owns the domain, named <purpose>_agent.go.

   pkg/thirdparty/disambiguation_agent.go   -- catalog→org ThirdParty matcher
   pkg/vetting/sub_agent.go                  -- generic vetting sub-agent
   

A file is NOT renamed to _agent.go when the agent is incidental to a service that does substantially more than agent orchestration (e.g. CRUD, caching, auth). In that case the file keeps its service name and the agent is built inline:

pkg/evidencedescriber/evidencedescriber.go   -- single-file describer service
pkg/vetting/assessment.go                     -- third-party assessment service

If the agent construction grows past a few dozen lines or sprouts its own prompt embed / typed result / config struct, extract it into a sibling <purpose>_agent.go.

Tool files

Each agent tool lives in its own <tool_name>_tool.go file, named after the tool constructor function (without the Tool suffix). The file contains the constructor function plus its param/result types. Avoid grouping multiple tools in a single file.

pkg/cookiebanner/search_tracker_patterns_tool.go   -- searchTrackerPatternsTool
pkg/cookiebanner/search_third_parties_tool.go       -- searchThirdPartiesTool