repo-best-practices

name	repo-best-practices
description	Code-generation skill. Use when generating or reviewing repo code so it matches the codebase’s reuse-first, minimal-diff, config-driven implementation habits.
metadata	{"family":"code","owner":"engineering","last_reviewed":"2026-04-30T00:00:00.000Z","version":"1.0.0"}

Repo Best Practices

This is a code-generation skill. Use it only when the task ends in shipped repo code.

Use When

• generating new code
• editing existing code
• reviewing whether generated code feels native to the repo
• deciding whether to reuse, extract, or inline something

Main Principle

Prefer the codebase’s existing patterns over inventing new ones.

The repo favors:

• reuse before creation
• config/registry driven content
• feature-local logic.ts or helper files for pure business rules
• helper functions over repeated inline logic
• feature-local constants instead of repeated literals
• shared shells and sections instead of bespoke page composition

Reuse Before Creating

Before writing a new component, helper, or layout:

1. search the current feature folder
2. search src/features/career-hub/shared
3. search src/components/common
4. search src/components/ui

Do not create a new abstraction until you confirm an existing one does not fit.

No Duplication Rules

• Do not duplicate page shells when an existing shell already fits.
• Do not duplicate cards, CTA sections, FAQ sections, breadcrumbs, or internal-link sections.
• Do not duplicate class combinations across multiple components if a shared helper or primitive already owns them.
• Do not repeat the same slugs, labels, FAQs, breadcrumb arrays, or metadata fragments inline across files when they can live in one constants/config/data file.

Constants And Config Rules

Prefer feature-local constants/config files when values are reused or structural.

Current repo patterns:

• header navigation config in src/features/career-hub/shared/header/config.tsx
• unemployment page constants in src/features/unemployment-benefits/constants.ts
• hiring calendar config/helpers in src/features/career-hub/shared/content/hiring-calendar/*
• guide/tool/category arrays in feature data files

When repeated values appear, move them into:

• constants.ts
• config.ts
• data.ts

inside the owning feature.

Registry And Selector Rules

Prefer registry/helper access over repeated inline lookup logic.

Current examples:

• tool registry in src/features/tools/shared/data/tool-registry/*
• getToolBySlug
• getRoleBySlug
• getCityBySlug
• wage-report Map-backed selectors

Preferred pattern:

• define canonical data once
• expose helper functions like getXBySlug
• use precomputed Maps for canonical slug lookup when the dataset is reused heavily

Avoid:

• repeated inline .find(...) across many files for the same domain object
• re-deriving the same lookup logic separately in multiple components

Derived Data Rules

If logic derives links, stats, or filtered lists and is used by a page family, move it into a helper/service file.

Current examples:

• src/features/how-to-become/services.ts
• src/features/career-hub/shared/navigation/internal-link-hub/helpers.ts

Avoid embedding large filtering/sorting/link-construction blocks directly inside JSX if they can be reused or tested as helpers.

For calculator math, business rules, and other pure feature-owned transforms, default to a feature-local logic.ts file unless an existing helper/service file is already the better fit.

Testing-Friendly Extraction

• Export pure feature logic as plain functions so tests/unit can cover it directly.
• Keep client components focused on state wiring and rendering. If a rule can be expressed as a pure function, do not trap it inside an event handler by default.
• Promote logic to cross-feature utilities only when at least two real features need the same low-level behavior.

Shared Page Composition Rules

Prefer existing composition pieces:

• ToolPageShell
• RolePageShell
• StandardPageLayout
• ContentPageShell
• IndustryPageShell
• SeasonalPageShell
• FAQSection
• CTASection
• InternalLinkHub
• PageContainer
• PageSection

If a page needs these concepts, reuse them instead of rebuilding them.

Typed Config Rules

Prefer typed config objects plus satisfies for structured page config.

Current repo pattern:

const config = {
  slug: tool.slug,
  name: tool.name,
  description: tool.description,
  canonical: "/career-hub/tools/pay-calculator",
  applicationCategory: "FinanceApplication",
  faqs: tool.faqTemplates,
} satisfies ToolPageConfig;

Use this when a page/shell expects a stable config contract.

Styling Rules

• Use cn from @/lib/utils.
• Prefer variant/class maps and helper functions over duplicated long Tailwind strings.
• Extend existing components/ui or common layout helpers before creating one-off wrapper patterns.

Current examples:

• src/lib/utils.ts
• src/components/common/layout/PageLayout.tsx

Avoid hand-merging classes with string concatenation when cn should be used.

Dynamic Route Rules

Follow the current Next.js route signature used in the repo.

Current common pattern:

• params: Promise<{ ... }>

Do not mix old and new route parameter conventions arbitrarily inside the same codebase.

Null And Type Narrowing Rules

When mapping optional lookups:

• return null when lookup fails
• filter with a type guard

Pattern already used in the repo:

const links: (LinkItem | null)[] = slugs.map((slug) => {
  const tool = getToolBySlug(slug);
  if (!tool) return null;
  return { href: `/career-hub/tools/${tool.slug}`, label: tool.name };
});

return links.filter((item): item is LinkItem => item !== null);

Content And Metadata Placement Rules

• FAQs that belong to a feature should live in feature data/constants, not be duplicated inline across pages.
• keywords, related tools, category lists, breadcrumbs, and similar structured content should live in the owning feature’s data/config/constants.
• if a tool already has registry fields like primaryKeyword, secondaryKeywords, or faqTemplates, reuse them.

Reviewer-Friendly Implementation Rules

• prefer the smallest change that fits the current architecture
• avoid opportunistic refactors during feature work
• do not introduce parallel abstractions for something the repo already has
• if you extract code, extract it to the place the repo would already expect

Final Self-Check

Before finishing generated code, confirm:

1. existing component/shell/helper reuse was attempted first
2. repeated literals were not scattered inline
3. selectors/helpers were reused instead of reimplemented
4. new code matches current feature ownership
5. pure business logic was extracted out of bulky JSX when practical
6. no unnecessary duplication was introduced