Samsen Internal Framework

This is Samsen's internal framework content for Claude Code & Agentic Coding. It is read-only reference material.

Claude Code — Common Patterns

Reusable Approaches Across Project Types

These patterns apply to any project using Claude Code, regardless of framework, language, or domain.

Pattern: Read-Before-Write

When: Starting any new task in an existing codebase.

How: Before creating or modifying anything, ask Claude Code to read and understand what already exists.

"Read the src/components directory and summarize the patterns used: file structure, naming conventions, styling approach, and how props are typed."

Why: This prevents AI from inventing new patterns that conflict with established conventions. It takes 30 seconds and saves minutes of correction.

Pattern: Scaffold-Then-Fill

When: Building a complex feature or component.

How: First generate the structure with placeholder content, then fill in details:

1. "Create the file structure for a dashboard page: layout, sidebar, main content area, header. Use placeholder components."
2. "Now implement the sidebar with navigation links using our nav component."
3. "Add the data table to the main content area."
4. "Wire up the filtering logic."

Why: Each step is reviewable. Errors are caught early before they cascade. Complex features become a series of simple tasks.

Pattern: Error-Feedback Loop

When: Generated code has issues (build errors, lint failures, test failures).

How: Share the error output directly with Claude Code:

"Running `npm run build` gives this error: [paste error]. Fix it."

Claude Code can read the error, understand the context, and fix the issue — often more effectively than describing the problem in your own words.

Why: Error messages contain precise information about what's wrong. Passing them directly to AI is more efficient than paraphrasing.

Pattern: Migration by Example

When: Updating many files to follow a new pattern.

How: 1. Manually update one file (or have Claude Code update it with guidance) 2. Review and approve the updated file 3. "Now apply the same pattern to all components in src/components/ui/"

Why: Establishing the pattern on one file removes ambiguity. AI can then apply it consistently across the codebase.

Pattern: Spec-Driven Generation

When: Building from a specification or requirements document.

How: Write or provide the spec, then reference it:

"Read the spec in docs/card-component.md and implement the Card component according to those requirements."

Why: The spec becomes the contract. If the output doesn't match the spec, the feedback loop is clear: "This doesn't match the spec on line X. The spec says Y but you built Z."

See: ../ai-assisted-design/specs-first-methodology.md

Pattern: Test-First with AI

When: You want confidence that a component works correctly.

How: 1. "Write tests for a Card component that: renders title and description, applies compact class when variant is compact, handles missing image gracefully, meets accessibility requirements." 2. "Now implement the Card component to make all tests pass."

Why: Tests-first gives AI clear, verifiable success criteria. The tests tell it exactly what "done" looks like.

Pattern: Refactor-in-Place

When: Improving existing code without changing behavior.

How:

"Refactor the UserProfile component to use design system tokens instead of hardcoded values. Don't change any behavior — just replace pixel values with token references."

Why: Explicit "don't change behavior" constraint focuses AI on the mechanical transformation. Running tests before and after verifies nothing broke.

Pattern: Parallel Exploration

When: Unsure which approach is best.

How: 1. "Create two versions of this layout: one using CSS Grid, one using Flexbox. Put them in separate files." 2. Review both in browser 3. "Delete the grid version. The flexbox approach works better for this use case."

Why: AI generation is cheap. Comparing two real implementations is more informative than debating approaches abstractly.

Pattern: Progressive Enhancement

When: Building features that need to work at multiple complexity levels.

How: 1. "Build the basic table: renders rows, columns, and data." 2. "Add client-side sorting." 3. "Add pagination." 4. "Add keyboard navigation and screen reader support." 5. "Add virtual scrolling for large datasets."

Why: Each layer adds complexity. Reviewing simpler versions first ensures the foundation is solid before adding sophistication.

Pattern: Context Injection for Unfamiliar Codebases

When: Claude Code needs to work with a library, framework, or pattern it might not know well.

How: Provide documentation or examples as context:

"Here's how our custom form library works: [paste relevant docs]. Build a registration form using this library."

Or: "Read the README in packages/form-lib/ for usage documentation, then build a registration form."

Why: Claude Code's training data may not include your specific internal libraries. Explicit context fills the gap.

Anti-Patterns to Avoid

The Mega-Prompt

Writing a single 1000-word prompt describing an entire feature. Break it into steps instead.

The Redo Loop

Throwing away AI output and reprompting from scratch instead of iterating. "Move the button 20px right" is better than "regenerate the entire component."

Prompt-Only Debugging

Describing a bug in prose instead of sharing the actual error message. "It's broken" tells AI nothing. The stack trace tells it everything.

Ignoring the Codebase

Asking Claude Code to build something "from scratch" when similar patterns already exist in the project. Always reference existing code first.