Coding Standards
Global standards that apply to all projects and languages.
Single Source of Truth
Any value defined in one place and consumed in another should be referenced, not copied.
Applies to versions, paths, URLs, schema constants, and configuration.
- If two files would need to be updated in lockstep, the second is a derived artifact —
generate it, don't hand-maintain it.
- CI verification of two files agreeing is a smell: the right pattern is
run-the-generator + , not parse-and-compare.
- Hand-maintained mirrors of canonical sources rot silently. The cost of a small
generator is always lower than the cost of recurring drift bugs.
Before You Write
Before implementing utility logic (file traversal, string parsing, config lookup,
error wrapping), search the codebase for an existing implementation.
- Found a close match? Import or extend it instead of reimplementing.
- Same pattern already in 2+ files? Extract it to a shared module before adding
a third instance.
- Duplication accumulates one compliant PR at a time — prevent it at writing time
rather than relying on later audits.
Pre-Implementation
Answer three questions before creating a new file, module, or significant function:
- Does this logic already exist? Search first; reuse beats rewrite.
- Is this the right module? An existing module growing too large is a signal
to refactor it, not to create a parallel module beside it.
- Will this create duplication later? If similar future cases are foreseeable,
put the logic in a shared location from the start.
Architectural Awareness
When adding a module or significant function:
- Confirm it fits the layer it lives in, and that its dependency direction matches
the existing architecture.
- Every new dependency arrow between modules must be intentional — never a
side effect of convenient imports.
- A module growing past ~300–400 lines is a signal to split it along
responsibility boundaries.
Dependency Update Triage (Renovate/Dependabot)
- Merge safe green bumps. For breaking major bumps, fix and migrate —
never just close the PR to dodge the work.
- Don't: close a failing Astro 6→7 Renovate PR because
no longer builds.
- Do: migrate to the replacement () in the same PR, then
merge.
- Green doesn't mean safe. On a repo where CI doesn't cover every path, a
green PR can still be broken in the un-CI'd parts. Validate those parts
locally before merging, not just the parts CI checks.
- Backlog handling for dependency issues/PRs (closing, repurposing,
announcing changes): follow the skill's Backlog Stewardship section.
Per-repo agent context ( / )
Every target repo may carry a standing context file that assessment and
implementation skills load automatically.
Precedence: if both
and
exist,
is authoritative — apply it
and do not also apply conflicting
instructions. If only one
exists, use that file. If both exist and their requirements conflict in a
way that blocks safe progress, stop and ask the user which wins rather than
guessing. When present, treat its standards, constraints, and contract as
binding for the session — do not re-type them from chat memory.
Expected sections
Write the file so the per-repo delta is only the repo facts. Put recurring
org-wide rules in an org preset section (or point at a shared org doc) rather
than copying them into every repo.
- House standards pointers — toolchains (e.g. / / ),
lint entry point, CI source / reusable workflows, model repos to copy
conventions from, and any org-managed ruleset notes.
- Contract / operating agreement — autonomy level, merge policy (who
merges, squash vs queue, signed commits), babysit/review expectations, and
how the agent should surface vs keep going.
- Standing constraints — safety limits (e.g. no paid LLM API calls during
assessment), scope rules, storage limits (e.g. local SQLite only), and
no-side-effects rules for assessment-only work.
- Org preset — recurring org-wide rules referenced once so each repo file
stays short; only repo-specific product/org facts belong outside this
section.
Consumers
At start of a run, these skills read the target repo's
/
when present and apply it as binding context:
Missing the file is fine — fall back to chat instructions and
skills. Do not invent standing constraints that are not in the file or the
user's message.
Cross-cutting References
- Linting and formatting: follow the skill
- Ignoring lint issues: follow the skill (Rules section)
- Testing: follow the skill
- Commits: follow the skill
- Pull requests: follow the skill
- Pre-push AI review (CodeRabbit): follow the skill
- Pre-push AI review (Greptile): follow the skill
- Per-repo standing context: see Per-repo agent context above
Pre-push review workflow
CLI review mirrors CI and catches issues before slow CI completes. Default: run
both Greptile and CodeRabbit when CI uses both.
Short flow:
text
commit → [greptile ‖ coderabbit] → pr
Explicit flow:
text
lint → test → commit → [greptile ‖ coderabbit] → pr
Each step names the skill to follow.
means run greptile and coderabbit in parallel when possible. Fix findings, then optional
verify pass. Do not re-run either CLI on unchanged code. CI remains the merge-time
confirmation.