Using Claude Code as a Real Developer Workflow, Not Just an AI Chatbot

A lot of people open Cursor, Claude Code, ChatGPT, or any other LLM-based coding assistant and ask things like:

“Fix this bug.”
“Write this component.”
“Explain this file.”

That is useful, but it is not where the real value is.

The real value starts when we stop treating LLMs like random chat windows and start treating them like structured engineering collaborators that understand the project, the architecture, the coding standards, the testing strategy, and the team’s way of working.

That is where tools like Claude Code, CLAUDE.md, SKILL.md, custom skills, commands, MCP, hooks, agents, and context engineering become very important.

In practice, the difference between average AI usage and powerful AI usage usually comes down to one thing:

How much structured context you give the model.

Why Context Matters More Than Prompting

One mistake I see often is that developers expect the LLM to automatically understand the entire system from one prompt.

But real software engineering is not just about code.

It involves architecture decisions, naming conventions, database patterns, API contracts, testing rules, deployment assumptions, performance constraints, security concerns, and product-level tradeoffs.

A senior engineer joining a project does not become productive only by reading one file. They need onboarding docs, architecture notes, local setup instructions, code review expectations, common pitfalls, and business context.

LLMs are similar.

The better the context, the better the output.

That is why files like CLAUDE.md matter.

What CLAUDE.md Actually Solves

For me, CLAUDE.md is like an onboarding document for the AI inside your repository.

Instead of repeatedly telling Claude:

• Use TypeScript.
• Follow our folder structure.
• Don’t use inline CSS.
• Run tests before suggesting a final answer.
• Use service objects for business logic.
• Do not directly query from React components.

You define those expectations once in CLAUDE.md.

# Project Overview

This is a Ruby on Rails backend with a React TypeScript frontend connected through Inertia.js.

# Architecture Rules

- Keep business logic in services.
- Keep controllers thin.
- Use existing serializers before introducing new response shapes.
- Follow the existing component structure in the frontend.

# Frontend Standards

- Use TypeScript.
- Use Tailwind CSS.
- Avoid inline styles unless absolutely necessary.
- Reuse existing atoms and molecules before creating new components.

# Backend Standards

- Prefer ActiveRecord scopes for reusable queries.
- Avoid N+1 queries.
- Add tests for service-level logic.
- Keep migrations reversible where possible.

# Testing

Before finalizing a change:
- Run relevant backend tests.
- Run TypeScript checks.
- Mention any test that could not be run.

This changes the way Claude behaves.

Instead of generating generic code, it starts generating code that is closer to your team’s standards.

Where SKILL.md Fits In

If CLAUDE.md is project memory, then SKILL.md is more like a reusable capability.

A skill is a folder that teaches Claude how to perform a specific task or workflow.

In simple terms:

For example, you can create skills for:

skills/
  code-review/
    SKILL.md

  backend-debugging/
    SKILL.md

  frontend-refactor/
    SKILL.md

  database-performance/
    SKILL.md

  api-design/
    SKILL.md

A SKILL.md for code review might look like this:

---
name: code-review
description: Use this skill when reviewing pull requests, checking code changes, finding bugs, reviewing architecture, security, performance, maintainability, and test coverage.
---

You are reviewing code like a senior software engineer.

Review in this order:

1. Correctness
2. Security
3. Performance
4. Maintainability
5. Test coverage
6. Project conventions

Return feedback in this format:

## Blocking Issues
## Suggestions
## Nice-to-Haves
## Summary

Now you are not relying on memory or one-off prompting. You are creating a reusable engineering workflow.

That is powerful because it makes AI output more consistent across developers, features, and reviews.

How Claude Actually Uses a Skill

Claude does not usually “run a skill” like a developer runs a script.

A skill is more like a specialized instruction package. Claude can discover it, read its metadata, decide whether it is relevant to the current task, and then load the detailed instructions from SKILL.md.

The flow looks something like this:

User request
   ↓
Claude checks available skill metadata
   ↓
Claude decides which skill is relevant
   ↓
Claude reads that skill’s SKILL.md
   ↓
Claude may read extra files inside the skill folder
   ↓
Claude applies those instructions while working

So, if you ask:

Review my current git diff like a senior engineer.
Focus on correctness, performance, and missing tests.

Claude may load the code-review skill because the task matches its description.

This is why the description inside SKILL.md is very important. If the description is vague, Claude may not know when to use the skill. If the description is specific, the skill becomes much more reliable.

Commands vs Skills vs Project Context

A lot of LLM tooling concepts sound similar, but I think about them like this:

A command is something you intentionally call.

A skill is something Claude can load when the task matches.

CLAUDE.md is the project-level context that should influence almost everything Claude does inside that repository.

A Practical Folder Structure

If I were setting up Claude Code properly for a serious project, I would start with something like this:

CLAUDE.md

.claude/
  commands/
    review-pr.md
    fix-tests.md
    explain-flow.md
    generate-tests.md
    refactor-safely.md

skills/
  code-review/
    SKILL.md

  backend-debugging/
    SKILL.md

  frontend-refactor/
    SKILL.md

  database-performance/
    SKILL.md

  api-design/
    SKILL.md

Then I would keep improving these files based on real usage.

If Claude repeatedly makes the same mistake, I would not just complain about the model.

I would update the context.

• If it creates components in the wrong folder, add that rule.
• If it over-engineers simple tasks, add a preference for minimal changes.
• If it forgets tests, add a testing checklist.
• If it breaks conventions, document the conventions better.

This is exactly how we improve onboarding docs for human engineers as well.

Example: A Real AI-Assisted Development Flow

A strong Claude Code workflow for a real feature could look like this:

1. Claude reads CLAUDE.md to understand the project architecture, coding style, testing expectations, and constraints.
2. The developer gives a feature request.
3. Claude explores the relevant files.
4. A command or skill guides Claude through a predictable workflow.
5. Claude proposes a plan before making changes.
6. Claude makes small, focused changes.
7. Claude adds or updates tests.
8. Claude summarizes what changed and mentions risks.

For example:

Add filtering to the admin users table by role and status.
Follow existing table patterns.
Add backend tests for the query logic.
Avoid changing unrelated UI.

This is much better than simply saying:

“Build this feature.”

Because now the AI is working inside a predictable software delivery process.

The Real Skill Is Context Engineering

Prompt engineering was the first wave.

Context engineering is more important now.

Context engineering means deciding what information the model needs, where that information should live, how it should be structured, and when it should be used.

For development work, context can include:

• Project architecture
• Tech stack
• Business rules
• Coding conventions
• API contracts
• Database schema
• Testing strategy
• Deployment assumptions
• Common bugs
• Performance constraints
• Security rules
• PR review standards

Good developers already think this way.

When we debug a production issue, we do not randomly edit files. We check logs, reproduce the issue, inspect the data path, isolate the layer, test assumptions, and then patch the root cause.

LLM-assisted development should work the same way.

The model should not just generate code.

It should understand the system.

MCP and Tool Use

Another key concept is MCP, or Model Context Protocol.

The basic idea is that LLMs become much more useful when they can safely connect to external tools and data sources instead of only relying on pasted context.

For engineering teams, this can mean connecting Claude to things like:

• GitHub
• Linear or Jira
• Sentry
• Datadog
• Database documentation
• Internal docs
• API specs
• CI/CD pipelines
• Deployment logs

This is where AI gets closer to real engineering support.

Instead of asking:

“Here is an error, what does it mean?”

You can move toward:

“Check the related logs, inspect the recent PR, compare it with the failing test, and suggest the smallest safe fix.”

That is a very different level of productivity.

Guardrails Still Matter

The more power we give AI tools, the more we need guardrails.

AI tools can help us move fast, but they can also make bad decisions faster if we allow them to operate without boundaries.

Engineering teams should think carefully about:

• Permissions
• Secrets exposure
• File access
• Shell command execution
• Production database access
• Dependency changes
• Generated migrations
• Auto-approved changes
• CI/CD access

In my opinion, AI should be allowed to move fast in low-risk areas, but it should be restricted around production systems, secrets, destructive commands, and large architectural changes.

A good workflow is not:

“Let AI do everything.”

A good workflow is:

“Let AI accelerate the repeatable work, while engineers still own judgment, architecture, security, and final review.”

Where Claude Code Helps Most

Claude Code is especially useful for work like:

• Understanding unfamiliar codebases
• Refactoring legacy modules
• Writing tests for existing logic
• Debugging multi-file flows
• Reviewing pull requests
• Explaining complex code paths
• Generating migration plans
• Improving documentation
• Creating repeatable dev workflows
• Converting team conventions into reusable instructions

For example, if I am working in a Rails + React codebase, I do not just want Claude to write a random component.

I want it to understand:

• Where frontend components live
• How API data is passed
• Whether we use REST or GraphQL
• How authorization is handled
• How errors are displayed
• How loading states are managed
• How tests are written
• What patterns already exist

That is the difference between junior-level AI usage and senior-level AI-assisted engineering.

The Big Shift

The big shift is that AI-assisted development is moving from:

Prompt → Output

to:

Context → Workflow → Tool Use → Review → Iteration

That is a much more serious engineering model.

In the future, I do not think the best developers will simply be the ones who know how to write clever prompts.

The best developers will be the ones who can design reliable AI-assisted workflows around real software systems.

They will know how to give the model the right context, restrict it where needed, let it automate repeatable work, and still apply strong engineering judgment.

Final Thought

Claude Code, Cursor, ChatGPT, and other LLM tools are not replacements for engineering fundamentals.

They amplify them.

If your architecture is messy, your docs are missing, your tests are weak, and your conventions are unclear, AI will often make the mess faster.

But if your project has clear boundaries, good documentation, reusable workflows, strong tests, and well-defined engineering standards, AI can become a serious productivity multiplier.

For me, the real lesson is simple:

Do not just use AI to write code. Use AI to improve the way your team understands, changes, reviews, and ships code.

That is where tools like CLAUDE.md, SKILL.md, custom skills, commands, MCP, hooks, and agents become genuinely useful.

Not as hype.

But as engineering infrastructure.