Skip to content

Samsen Internal Framework

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

Claude Code — Best Practices

What Claude Code Is

Claude Code is a command-line AI tool that operates inside your development environment. Unlike chat-based AI (ChatGPT, Claude.ai), Claude Code has direct access to your filesystem, can run commands, read files, execute builds, and make changes to your codebase. It works conversationally — you describe what you want, it acts, you review, you iterate.

Core Principles

1. Be Specific, Not Vague

AI output quality correlates directly with input specificity.

Vague: "Make a nice header component" Specific: "Create a header component using our design system. It should have a logo on the left, navigation links in the center, and a user avatar dropdown on the right. Use --spacing-lg for horizontal padding, --color-surface-primary for background. Mobile: hamburger menu replaces nav links."

The more constraints you provide, the fewer decisions AI has to guess.

2. Work Iteratively

Don't try to generate a complete feature in one prompt. Build incrementally:

  1. Start with the basic structure
  2. Add functionality one piece at a time
  3. Review after each step
  4. Course-correct early

This prevents compounding errors and gives you checkpoints to validate against.

3. Let AI Read Before Writing

Before asking Claude Code to create something new, ask it to read what already exists:

  • "Read the components directory and tell me how existing components are structured"
  • "Look at the Button component and show me the patterns it uses"
  • "Read the design system tokens file and summarize the naming convention"

This gives AI the context it needs to match existing patterns.

4. Use Natural Language for Intent, Specifics for Constraints

Describe the what and why in natural language. Use specific terms for technical constraints:

"I need a notification banner that slides in from the top when there's a new message. It should auto-dismiss after 5 seconds. Use the --color-feedback-info token for the background, --spacing-sm for padding. Follow the same animation pattern as the existing Toast component."

Intent (what it does, why) + constraints (tokens, patterns, references) = reliable output.

5. Review Output, Not Process

You don't need to read every line of generated code. Focus on:

  • Does it look right in the browser?
  • Does it pass linting and tests?
  • Does the component behave correctly?
  • Does the git diff look reasonable?

If all four are true, the code is shippable regardless of whether you understand every line.

Effective Prompting Patterns

The Context-Task-Constraint Pattern

Structure prompts as:

  1. Context — What already exists, what the project is about
  2. Task — What you want Claude Code to do
  3. Constraints — Technical requirements, tokens to use, patterns to follow

Example: "We have a React 19 project using CSS modules and our custom design system tokens. [Context] Create a pagination component with page numbers, prev/next buttons, and an ellipsis for large page counts. [Task] Use --spacing-sm between page buttons, --color-action-primary for the active page, and match the Button component's hover pattern. [Constraints]"

The Reference Pattern

Point Claude Code to existing code as a reference:

"Look at how the DataTable component handles sorting. Build the same pattern for the UserList component."

This is more reliable than describing a pattern from scratch because Claude Code can read the actual implementation.

The Fix-and-Explain Pattern

When something goes wrong:

"This component renders incorrectly on mobile — the text overflows the card. Fix it and explain what was causing the issue."

Asking for an explanation builds understanding and catches cases where AI might fix the symptom but not the root cause.

The Incremental Complexity Pattern

For complex features, add complexity in layers:

  1. "Build a basic data table that renders rows and columns"
  2. "Add sorting when clicking column headers"
  3. "Add pagination with 10 rows per page"
  4. "Add a search filter that highlights matching text"
  5. "Add keyboard navigation for accessibility"

Each step is a checkpoint you can review and validate.

Common Mistakes

Over-Prompting

Writing a 500-word prompt when 50 words would suffice. Claude Code has access to the codebase — it can figure out conventions by reading files. You don't need to explain everything.

Under-Reviewing

Accepting AI output without checking in the browser. Always visually review. AI can generate syntactically correct but visually wrong code.

Fighting Instead of Iterating

If Claude Code produces something wrong, don't rewrite the prompt from scratch. Iterate: "The spacing is too tight. Use --spacing-md instead of --spacing-sm." Conversation is the workflow.

Ignoring Errors

When Claude Code encounters build errors, linting failures, or test failures, address them. Don't push code that doesn't pass CI. AI can fix most errors if you share the error output.

Not Using Branches

Always work on a branch. Never let Claude Code commit directly to main. The PR workflow is the safety net.