Adrienenjalbert/nextjs-app/ai-src/skills/repo-best-practices

Repo Best Practices

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
• 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.

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. no unnecessary duplication was introduced