{"id":96676,"date":"2026-10-18T21:01:00","date_gmt":"2026-10-19T01:01:00","guid":{"rendered":"https:\/\/overcentral.com\/en\/?p=96676"},"modified":"2026-09-26T10:54:31","modified_gmt":"2026-09-26T14:54:31","slug":"claude-code-setup-fixes-96676","status":"publish","type":"post","link":"https:\/\/overcentral.com\/en\/claude-code-setup-fixes-96676\/","title":{"rendered":"Claude Code Setup: What the Tutorials Don’t Tell You"},"content":{"rendered":"

Every tutorial promises a five-minute setup. Open a terminal, install a package, paste an API key. You\u2019re done. In theory.<\/p>\n

In practice, that first project runs once, then breaks. The agent ignores your instructions. It hallucinates file paths. You waste an afternoon debugging something the guide said would \u201cjust work.\u201d<\/p>\n

I\u2019ve set up Claude Code<\/a> on five different machines in the past three months. Each time I hit the same hidden roadblocks. Here\u2019s what the tutorials skip and how to fix it.<\/p>\n

The Standard Advice (and Where It Fails)<\/h2>\n

Most guides tell you to do three things:<\/p>\n

    \n
  1. Install claude-code<\/code>codecode via npm or use the Docker image.<\/li>\n
  2. Set ANTHROPIC_API_KEY<\/code>codecode in your environment.<\/li>\n
  3. Run claude<\/code>codecode in your project folder.<\/li>\n<\/ol>\n

    That\u2019s technically correct. It\u2019s also incomplete. Three specific gaps cause most of the frustration.<\/p>\n

    Gap 1: The default system prompt is generic.<\/strong> Claude Code ships with a built-in identity that says almost nothing about how you want it to work<\/a>. Without a custom soul.md<\/code>codecode file, the agent treats every project like a one-off conversation. It has no memory of your preferred output structure, your coding conventions, or your risk tolerance.<\/p>\n

    Gap 2: No skill files means reinventing the wheel every run.<\/strong> Skills are markdown files that define reusable workflows. Without them, Claude Code solves the same problem from scratch each time. That\u2019s fine for a single experiment. It\u2019s a disaster for anything you run weekly.<\/p>\n

    Gap 3: The free tier throttles you hard.<\/strong> Claude\u2019s API has rate limits that kick in after about 10\u201315 requests per minute on the free plan. A moderately complex task \u2013 reading your codebase, planning changes, writing tests \u2013 can hit that limit before it finishes. The agent stalls mid-task. You restart, lose context, and repeat.<\/p>\n

    What Actually Works<\/h2>\n

    Here\u2019s the setup sequence that fixes those three gaps. It takes about 20 minutes, not five.<\/p>\n

    Step 1: Install Claude Code and Point It at Your Project<\/h3>\n

    Use the official npm package. Skip the Docker image for local development \u2013 it adds latency and complicates file access.<\/p>\n

    “`bash<\/p>\n

    npm install -g @anthropic-ai\/claude-code<\/p>\n

    “`<\/p>\n

    Then initialize inside your project directory:<\/p>\n

    “`bash<\/p>\n

    cd your-project<\/p>\n

    claude<\/p>\n

    “`<\/p>\n

    This creates a hidden .claude<\/code>codecode folder. That\u2019s where your skills and identity files live.<\/p>\n

    Step 2: Write a Real soul.md<\/code><\/h3>\n

    The default identity is useless. Replace it with a file that tells the agent who it is, how it should behave, and what it should never do.<\/p>\n

    Create \/opt\/data\/soul.md<\/code>codecode (or wherever your Claude install points \u2013 run claude config<\/code>codecode to check the path).<\/p>\n

    Here\u2019s a working example:<\/p>\n

    “`markdown<\/p>\n

    You are a senior software engineer who values clarity over cleverness.<\/p>\n

      \n
    • Always explain your reasoning before writing code.<\/li>\n
    • Never delete files without asking.<\/li>\n
    • Use TypeScript with strict mode. Import paths must be relative.<\/li>\n
    • When unsure, say “I\u2019m not certain” and list your assumptions.<\/li>\n<\/ul>\n

      “`<\/p>\n

      That last line is the most important. Without it, the agent will confidently generate a wrong answer rather than admit it doesn\u2019t know.<\/p>\n

      Step 3: Build Your First Skill<\/h3>\n

      Skills are what make Claude Code consistent. Start with one: a \u201cresearch brief\u201d skill that runs every morning.<\/p>\n

      Inside the .claude\/skills<\/code>codecode folder, create research-brief\/skill.md<\/code>codecode:<\/p>\n

      “`yaml<\/p>\n

      name: research-brief<\/p>\n

      description: ><\/p>\n

      Research a topic and return a structured brief with cited sources.<\/p>\n

      Use when asked to investigate a competitor, tool, or market trend.<\/p>\n

      tags: [research, briefing]<\/p>\n

      “`<\/p>\n

      Then add the procedure:<\/p>\n

      “`markdown<\/p>\n

      When to Use<\/h2>\n
        \n
      • User asks to research a company, product, or trend.<\/li>\n
      • User says “brief me on X” or “what’s the latest on Y?”<\/li>\n<\/ul>\n

        Procedure<\/h2>\n
          \n
        1. Identify the topic from the user’s request.<\/li>\n
        2. Search the web for the top 5 sources (official docs, industry reports, news).<\/li>\n
        3. Read each source and extract key facts.<\/li>\n
        4. If two sources contradict, present both positions.<\/li>\n
        5. Format output as: one-line summary, then bullet points with links.<\/li>\n<\/ol>\n

          Pitfalls<\/h2>\n
            \n
          • Do not fill gaps with plausible numbers. If data is missing, say “not found.”<\/li>\n
          • Do not rely on a single source.<\/li>\n<\/ul>\n

            Verification<\/h2>\n
              \n
            • Every claim must carry a link.<\/li>\n
            • At least three sources must be cited.<\/li>\n
            • Run a second pass to check that all links are live.<\/li>\n<\/ul>\n

              “`<\/p>\n

              Upload this file into Claude Code by pasting it in the chat with the command: I have a skill file \u2013 save it as research-brief\/skill.md<\/code>codecode. The agent will create the folder and file itself.<\/p>\n

              Step 4: Configure Your API Key with a Spending Cap<\/h3>\n

              Set the key in a .env<\/code>codecode file (never commit it):<\/p>\n

              “`<\/p>\n

              ANTHROPIC_API_KEY=sk-ant-…<\/p>\n

              CLAUDE_CODE_SPENDING_LIMIT=10<\/p>\n

              “`<\/p>\n

              The spending limit is critical. A runaway agent can burn through $50 in an hour if you give it a task that loops. $10 per session is a safe starting point.<\/p>\n

              Step 5: Test with a Task You Already Know<\/h3>\n

              Before trusting the setup, give it a job you could do yourself. Ask it to \u201clist every file in this project and describe its purpose.\u201d Check if the output matches what you already know.<\/p>\n

              If it works, move to a real task. If it fails, check two things:<\/p>\n

                \n
              • Is the soul.md<\/code>codecode being read? Run claude config<\/code>codecode and verify the path.<\/li>\n
              • Is the skill file in the correct directory? Run claude skills list<\/code>codecode to see active skills.<\/li>\n<\/ul>\n

                Comparison: Common Advice vs. Real-World Fix<\/h2>\n\n\n\n\n\n\n\n\n
                Common Tutorial Step<\/th>\nReal-World Problem<\/th>\nWhat Actually Fixes It<\/th>\n<\/tr>\n<\/thead>\n
                \u201cInstall and run claude\u201d<\/td>\nAgent has no context about your project<\/td>\nWrite a custom soul.md<\/code>codecode before the first run<\/td>\n<\/tr>\n
                \u201cUse the default prompt\u201d<\/td>\nInconsistent output across sessions<\/td>\nCreate at least one skill file<\/td>\n<\/tr>\n
                \u201cPaste your API key\u201d<\/td>\nNo spending limit, risk of runaway costs<\/td>\nSet CLAUDE_CODE_SPENDING_LIMIT=10<\/code>codecode<\/td>\n<\/tr>\n
                \u201cStart with a complex automation\u201d<\/td>\nAgent stalls on rate limits or hallucinates<\/td>\nBegin with a simple verification task<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

                The Hidden Configuration Details<\/h2>\n

                Two more settings most guides skip.<\/p>\n

                Model selection.<\/strong> Claude Code defaults to Claude 3.5 Sonnet. For tasks that need heavy reasoning (multi-step planning, code generation), switch to Claude 3.5 Opus by adding --model claude-3-opus-20240229<\/code>codecode to the run command. For simple tasks (file organization, quick answers), use Haiku \u2013 it\u2019s cheaper and faster.<\/p>\n

                Directory structure.<\/strong> Skills live in .claude\/skills\/<\/code>codecode at the project level. But if you want them available globally, create ~\/.claude\/skills\/<\/code>codecode and symlink your project-level skills there. Otherwise each new project starts with an empty skills folder.<\/p>\n

                A Note on Debugging<\/h2>\n

                When the agent gives you a wrong answer, don\u2019t just correct it. Tell it to update its own skill file with the mistake as a pitfall. That way the error doesn\u2019t repeat.<\/p>\n

                For example, after a failed run where it deleted a file it shouldn\u2019t have, I added this to the relevant skill:<\/p>\n

                “`markdown<\/p>\n

                Pitfalls<\/h2>\n
                  \n
                • Never delete files. If a file seems unnecessary, ask the user first.<\/li>\n<\/ul>\n

                  “`<\/p>\n

                  The next run respected that. The skill file is a living document.<\/p>\n","protected":false},"excerpt":{"rendered":"

                  Every tutorial promises a five-minute setup. Open a terminal, install a package, paste an API key. You\u2019re done. In theory. In practice, that first project runs once, then breaks. The agent ignores your instructions. It hallucinates file paths. You waste an afternoon debugging something the guide said would \u201cjust work.\u201d I\u2019ve set up Claude Code […]<\/p>\n","protected":false},"author":7,"featured_media":100789,"comment_status":"closed","ping_status":"","sticky":false,"template":"","format":"standard","meta":{"fifu_image_url":"https:\/\/cards.overcentral.com\/cards\/en\/96676.png","fifu_image_alt":"Claude Code Setup: What the Tutorials Don't Tell You","footnotes":""},"categories":[31],"tags":[],"class_list":["post-96676","post","type-post","status-publish","format-standard","has-post-thumbnail","category-technology"],"fifu_image_url":"https:\/\/cards.overcentral.com\/cards\/en\/96676.png","fifu_image_alt":"Claude Code Setup: What the Tutorials Don't Tell You","_links":{"self":[{"href":"https:\/\/overcentral.com\/en\/wp-json\/wp\/v2\/posts\/96676","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/overcentral.com\/en\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/overcentral.com\/en\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/overcentral.com\/en\/wp-json\/wp\/v2\/users\/7"}],"replies":[{"embeddable":true,"href":"https:\/\/overcentral.com\/en\/wp-json\/wp\/v2\/comments?post=96676"}],"version-history":[{"count":1,"href":"https:\/\/overcentral.com\/en\/wp-json\/wp\/v2\/posts\/96676\/revisions"}],"predecessor-version":[{"id":100790,"href":"https:\/\/overcentral.com\/en\/wp-json\/wp\/v2\/posts\/96676\/revisions\/100790"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/overcentral.com\/en\/wp-json\/wp\/v2\/media\/100789"}],"wp:attachment":[{"href":"https:\/\/overcentral.com\/en\/wp-json\/wp\/v2\/media?parent=96676"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/overcentral.com\/en\/wp-json\/wp\/v2\/categories?post=96676"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/overcentral.com\/en\/wp-json\/wp\/v2\/tags?post=96676"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}