Documentation
¶
Overview ¶
Package generate curates mined patterns into the small, high-value subset worth placing in agent context files, and renders them as CLAUDE.md / AGENTS.md.
The selection core is the real deliverable: agents skim long files and begin dismissing instructions wholesale well before ~150 rules, so every emitted file must stay short. Discarding the vast majority of mined patterns is the product, not a limitation.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Options ¶
type Options struct {
RepoRoot string // absolute repo path (scopes are absolute under it)
OutputDir string // where files are written; defaults to RepoRoot
Format Format
DryRun bool
}
Options configures a Generate run.
type Result ¶
type Result struct {
RulesEmitted int
ScopesCovered int
Files []WrittenFile
AgentsOmitted int // scopes left out of AGENTS.md to stay under budget
AgentsTrunc bool
}
Result summarizes a Generate run for the stderr report.
func Generate ¶
func Generate(scoped []ScopedConventions, opts Options) (Result, error)
Generate writes the selected conventions as the requested output shapes. It never overwrites a human-authored file: when a target already exists without OpenTuple's markers, it diverts to a sibling *.opentuple.md.
type Rule ¶
type Rule struct {
Text string // imperative line, percentage in parentheses
Confidence float64
Evidence string // raw count, e.g. "0 of 131 functions use Errorf"
ClaimType string
// contains filtered or unexported fields
}
Rule is one human-readable imperative instruction with its supporting count.
type ScopedConventions ¶
ScopedConventions is the curated rule set for one directory scope (or the special "global" scope).
func SelectConventions ¶
func SelectConventions(patterns []store.Pattern, opts SelectOpts) []ScopedConventions
SelectConventions curates mined patterns into the high-value subset worth placing in agent context files. Identical patterns in produce identical ScopedConventions out, every run: ties always break on rendered rule text.
Three claim filters run before rendering. Prevalence rules matching universalConventions for opts.Language are dropped — a model already knows them — unless the rule is for a scope whose embedded repo-wide rate shows the repository as a whole does otherwise, in which case the local adherence is news. Scope rules whose claim restates the repo-wide rate the miner embedded next to it are dropped when a repository-level claim about the same thing was mined — a rule that is true everywhere tells the agent nothing about this directory, and the root file (or the model) already carries it; when no such claim exists the shard is the only place the rule can appear, so it stays (helper_absence is exempt either way: it already encodes divergence). Every rule outside fingerprintClaimTypes must also be one check.Enforces under opts.Check: that drops pairings that are artifacts of a ubiquitous helper, absences in scopes too small for the absence to mean anything, absences of anything but banned builtins unless the repository opts in (a package that never called fmt.Errorf usually never needed to, which is no reason to tell an agent not to), and rule types the repository disabled. The two mined directions of one helper pair collapse to a single rule per scope before capping, so the freed slot refills from the ranked remainder.
The returned slice leads with the "global" scope (if any), then non-global scopes ranked by (generated-code scopes last, top-rule confidence desc, function count desc, name asc) so callers can take a ranked prefix when emitting under a flat budget.
type SelectOpts ¶
type SelectOpts struct {
MinConfidence float64 // default 0.95, the miner's rule tier
MaxPerScope int // default 6
MaxScopes int // default 100
MaxGlobal int // default 8
IncludeNumeric bool // default false
// Language is the repository's dominant language; global rules listed
// in universalConventions for it are skipped. Empty disables the filter.
Language string
// ScopeFunctionCounts maps scope path → function count, used to break
// confidence ties in scope ranking (bigger scopes win). Scopes missing
// from the map count as zero; nil disables the tiebreak.
ScopeFunctionCounts map[string]int
// Check is the repository's check configuration. A call-graph or
// structural rule is stated only when check would enforce it under
// Check, so the rulebook never tells an agent what the check would not
// hold it to. Its MinConfidence is ignored: MinConfidence above applies.
Check check.Options
}
SelectOpts tunes how aggressively SelectConventions prunes mined patterns, and carries the repository context its filters and ranking consult.
func DefaultSelectOpts ¶
func DefaultSelectOpts(o SelectOpts) SelectOpts
DefaultSelectOpts returns the defaults, filling any zero-valued field. The caps are deliberately small: a root file of eight rules and shards of six are what an agent actually reads rather than skims, and only rule-tier claims are stated as rules — "Always pair X with Y" at 82% is not advice.
type WrittenFile ¶
type WrittenFile struct {
Path string // final path written (or that would be written)
Action string // "created", "regenerated", or "renamed"
Diverted bool // true when an existing human file forced a *.opentuple.md name
RuleN int // rules contained
}
WrittenFile records the disposition of one output file.
Source Files