How to Build a Civil 3D Plugin with Claude Code Without Being a Programmer: End-to-End 2026 Guide

Before you start, here are the words you'll see throughout the rest of the article, explained in plain language. Read them now and you won't have to Google anything later.

1. Plugin (or "extension") — a small file that adds new buttons and functions to a program you already use. Like a Chrome extension, but for Civil 3D.

2. API — the official list of things a program lets you do to it from the outside. Think of a restaurant menu: the Civil 3D API is "the menu" of what you can ask it to do through code. If it's not on the menu (the API), you can't order it.

3. SDK — the "developer toolkit." An official package you download that contains the files your code needs to talk to Civil 3D.

4. DLL — the final file your plugin produces. It's like an .exe, but one that another program (Civil 3D) loads inside itself. When we say "compile the DLL," we mean "generate the final file."

5. Bundle — a folder with a special structure that Civil 3D automatically recognizes on startup. It's the "professional" way to deliver your plugin — a single folder you copy over and you're done.

6. Compile — the step that converts your code (text) into an installable file (.dll). Like printing a document: the Word file (code) becomes a PDF (final file).

7. Visual Studio — the editor where you write code. It's a free Microsoft application. Don't be intimidated by how heavy it looks when it opens — you'll use maybe 5% of its features.

8. .NET Framework — the "version" of the Windows runtime your plugin runs on. Civil 3D requires a specific version (for example 4.8 or 8) — you just need to match it once and you're set.

9. Git — the system that keeps a history of your code. Every time something works, you make a "commit" (a checkpoint) and you can always go back to it. It's your infinite backup — a beginner's best friend.

10. Claude Code — Anthropic's tool that writes code for you from your terminal. You talk to it in plain English, it understands your project, and it proposes what to write. You confirm, and it applies the changes.

A Civil 3D plugin is a .dll file compiled in .NET that Civil 3D loads on startup. It adds commands, buttons, windows, and panels that didn't ship out of the box.

What you can do:

• Loop through every object in the drawing (alignments, surfaces, profiles, corridors, etc.).
• Read and modify their properties.
• Create new objects programmatically.
• Export data to Excel, CSV, JSON.
• Automate command sequences.
• Add your own window with forms.
• Listen to events (when the user creates/modifies/deletes something).

What you can't do:

• Change the internal behavior of official commands.
• Access parts of the API that Autodesk doesn't expose.
• Run outside the Civil 3D process.
• Run on Mac or Linux (the API is Windows only).

Examples of real, useful plugins:

• A quantity takeoff exporter with your firm's own format.
• A bulk alignment renamer that follows a naming standard.
• An automatic generator of longitudinal profiles every X meters.
• A drawing standards checker (naming conventions, allowed layers).
• A report of classified survey points exported to CSV.

What you need installed before writing a single line:

1. Windows 10/11 with Civil 3D installed (whichever version you use at work).
2. Visual Studio Community 2022 (free) — visualstudio.microsoft.com. During installation, check the ".NET desktop development" workload.
3. Civil 3D SDK — download it from Autodesk's developer portal. Search for "Civil 3D <your version> SDK". Installing it registers the DLLs you'll need to reference.
4. A claude.ai account (Pro plan recommended for long coding sessions).
5. Claude Code — install it via terminal with npm install -g @anthropic-ai/claude-code (requires Node.js).
6. Git — git-scm.com, or GitHub Desktop if you prefer a visual interface.

Verify everything is working:

# In a terminal:
dotnet --version    # should show 6.0 or higher
claude --version    # should show your Claude Code version
git --version       # any modern version

Step 1 — Open a terminal in your projects folder:

cd C:\Dev\CivilPlugins
mkdir MyFirstC3DPlugin
cd MyFirstC3DPlugin

Step 2 — Launch Claude Code:

claude

The interactive session opens. Now you'll give it the initial prompt. This prompt is the cornerstone of everything that follows:

Act as a senior .NET plugin architect for Autodesk Civil 3D.

Context:
- I'm building my FIRST Civil 3D plugin.
- I'm using Civil 3D 2025 (.NET 8).
- I'm on Windows with Visual Studio 2022 installed.
- Civil 3D SDK installed at C:\Program Files\Autodesk\Civil 3D 2025\
- The plugin will be called "ZeistTools" and its root namespace will be "ZeistTools".

Goal:
Create the initial project structure following the
Command → Service → Repository architecture that I'll describe in
the next message. Do NOT generate functional code yet — only:

1. The .csproj file with the necessary references to AcCoreMgd,
   AcDbMgd, AcMgd (AutoCAD) and AeccDbMgd (Civil 3D).
2. A README.md describing the project.
3. A proper .gitignore for .NET Framework + Visual Studio projects.
4. The empty folder structure:
   - Commands/
   - Services/
   - Repositories/
   - Models/
   - UI/
   - Resources/

Before creating anything, show me the plan and ask for confirmation.

Step 3 — Claude Code shows its plan. Read it. If something doesn't add up, ask it to adjust. Once you confirm, it creates the files.

Step 4 — Verify:

ls    # you should see .csproj, README.md, .gitignore, and the folders

Step 5 — First commit:

git init
git add .
git commit -m "Initial project structure"

This is the most important module in the article. Getting the architecture right from the start saves you weeks of pain down the road.

The recommended architecture: Command → Service → Repository

Translated into folders and responsibilities:

ZeistTools/
├── Commands/          → entry point (what Civil 3D executes)
│   └── ExportAlignmentsCommand.cs
├── Services/          → business logic (your rules)
│   └── AlignmentExportService.cs
├── Repositories/      → talks to the Civil 3D API
│   └── AlignmentRepository.cs
├── Models/            → plain data objects
│   └── AlignmentInfo.cs
├── UI/                → windows, forms (optional)
│   └── ExportOptionsWindow.xaml
├── Resources/         → icons, images, text
│   └── icons/
└── ZeistTools.csproj

The golden rule for each layer:

• Command: only orchestrates. It receives the event from Civil 3D, delegates to the Service, and shows the result to the user. It never touches the API directly.
• Service: contains YOUR logic ("alignments shorter than 100m don't count," "the CSV needs this header"). It knows nothing about Civil 3D — it works with Models.
• Repository: the only layer that knows the Civil 3D API. It translates between Civil 3D objects and your Models.

Concrete advantages of this separation:

1. Testable. You can test the Service without opening Civil 3D — just simulate data in Models.
2. Upgradable. When Autodesk changes the API in the next version (and it always happens), you only touch the Repository. Service and Command stay untouched.
3. Reusable. The same Service can have one Command for Civil 3D and another for AutoCAD Map, each with its own Repository.
4. Scalable. Adding a new command means: 1 new Command + reusing existing Services.
5. Debuggable. When something breaks, you know exactly which layer to check.

The antipattern you'll see in old tutorials:

A single giant Class1.cs file with a [CommandMethod] that does EVERYTHING: calls the API, calculates, formats, shows a window. Never do this. It's fast at first and a nightmare three months later.

Claude Code works 10x better with structured prompts. Here are the patterns I use.

Pattern 1 — Adding a new feature:

Add a new command "ExportAlignmentsToCsv" following the project's
architecture. Requirements:

- Command in Commands/ExportAlignmentsToCsvCommand.cs
  - Registers with [CommandMethod("ZEIST_EXPORT_ALIGN_CSV")]
  - Shows the user how many alignments were exported and where
- Service in Services/AlignmentExportService.cs
  - Method ExportToCsv(IEnumerable<AlignmentInfo>, string path)
  - CSV header: Name, StartStation, EndStation, Length, Layer
  - Skips alignments whose Length is less than 100
- Repository in Repositories/AlignmentRepository.cs
  - Method GetAllAlignments() : IEnumerable<AlignmentInfo>
  - Must read from the active Civil 3D document
- Model in Models/AlignmentInfo.cs with the 5 properties

Rules:
- Do NOT modify files outside those 4 paths.
- Do NOT add new NuGet dependencies.
- Follow the code style of the existing files.
- At the end, list the files you created/modified
  and explain in 2 lines what each one does.

Pattern 2 — Debugging an error:

I get this error when compiling:

[paste the EXACT error with line number]

Step-by-step diagnosis:
1. Explain what the error means.
2. Identify which layer it's in.
3. Propose the simplest possible fix (don't refactor anything else).
4. Show it to me before applying it, so I can confirm.

Pattern 3 — Asking for an explanation:

Explain in plain language what this block of code does:

[paste the code]

Specifically:
- What is a "Transaction" and why is it used?
- What happens if I don't call .Commit()?
- Does this code work with multiple open documents?

Important rules when using Claude Code:

• Always give explicit context. Civil 3D version, .NET framework, architecture. Don't make it guess.
• Small steps. One command per session. Don't ask for "10 commands at once."
• Verify before confirming. Read the changes before it applies them.
• Commit often. After every change that works.
• Don't lose an important session — Claude Code keeps the history in the project, but export the important lessons to markdown too.

The classic "Hello World," adapted to Civil 3D: list every alignment in the active drawing in the command window.

Prompt for Claude Code:

Create the plugin's first working command following the architecture
we already set up. The command:

- Is called "ZEIST_LIST_ALIGN".
- When run, it shows in the Civil 3D command window
  the list of all alignments in the active drawing, with their name
  and length.
- If there are no alignments, it shows "No alignments in the drawing".
- Error handling: if something fails, show a useful message instead
  of a raw stack trace.

Follow the Command → Service → Repository architecture:
- ListAlignmentsCommand delegates to AlignmentQueryService.
- AlignmentQueryService returns a List<AlignmentInfo> from AlignmentRepository.
- AlignmentRepository is the only one that touches the Civil 3D API.

When you're done, give me instructions to:
1. Compile (Debug config).
2. Load it into Civil 3D with NETLOAD.
3. Run the command and see the result.

What to expect: Claude Code will create about 4-5 files. Review them. Compile with Ctrl+Shift+B in Visual Studio or dotnet build in the terminal.

Loading it into Civil 3D:

1. Open Civil 3D.
2. Run the NETLOAD command.
3. Select the bin\Debug\ZeistTools.dll file.
4. Run ZEIST_LIST_ALIGN.
5. If your drawing has alignments, you'll see the list. If not, draw an alignment first.

By this point you're officially a Civil 3D plugin developer. Everything else is adding more commands following the same pattern.

A command you type by keyboard works, but a visible button with an icon in the toolbar is what actually gets your coworkers to use it, since they won't have to remember the command name.

We're talking about the top strip in Civil 3D where the "Home," "Insert," "Annotate," etc. tabs already live. We'll add our own tab there called "Zeist" with our buttons.

Message for Claude Code:

Add a button to the Civil 3D toolbar that runs the
ZEIST_LIST_ALIGN command. Requirements:

- It registers automatically when the plugin loads (use the
  IExtensionApplication.Initialize interface — Claude Code will know
  what that is).
- Creates a new "Zeist" tab in the toolbar if it doesn't exist yet.
- Inside it, an "Alignments" panel with a "List alignments" button.
- The button uses a 32x32 pixel PNG icon that I'll place at
  Resources/icons/list-align.png (you don't need to create the
  icon, just reference it — if it doesn't exist, leave the code
  ready with a TODO to add it later).
- The button's text should default to English.

Also tell me:
- Where I should place the icon file.
- What configuration line makes the icon get copied alongside
  the plugin when compiled.

Follow the architecture: the button logic lives in UI/RibbonBuilder.cs
(Autodesk internally calls this bar the "ribbon" — that's where the
name comes from), which only delegates to the existing Command.

Afterward:

1. Download or draw a simple 32×32 pixel icon in PNG format. You can use Icons8 (a free icon library) or create one in Figma.
2. Place it at Resources/icons/list-align.png.
3. Compile (the final .dll file).
4. Reload it in Civil 3D (run NETLOAD and pick the new .dll).
5. You should see the new "Zeist" tab in the toolbar, with your button inside.

Your .dll works fine with manual NETLOAD. But to distribute it professionally, Autodesk has an official format: the bundle. It's a folder with a specific structure that Civil 3D loads automatically on startup.

Structure of a bundle:

ZeistTools.bundle/
├── PackageContents.xml
└── Contents/
    ├── Windows/
    │   └── ZeistTools.dll (your plugin compiled in Release)
    └── Resources/
        └── icons/
            └── list-align.png

Prompt for Claude Code:

Create the bundle structure and the PackageContents.xml file to
distribute the plugin as ZeistTools.bundle.

Requirements:
- Compatible with Civil 3D 2024 and 2025.
- Publisher: "Zeist" (this is what shows in the add-in manager).
- Version: 1.0.0.
- Bilingual description (EN/ES): "Zeist Tools for Civil 3D".
- Autoload when Civil 3D starts.
- Must load ZeistTools.dll from Contents/Windows.

Also, add a build.ps1 (PowerShell) script that:
1. Compiles the project in Release.
2. Copies the .dll and resources into the bundle structure.
3. Produces the finished .bundle, ready to distribute.

Explain the contents of PackageContents.xml line by line.

Afterward:

1. Run ./build.ps1 from the terminal (or build.sh if you're on WSL).
2. The script leaves ZeistTools.bundle/ ready to go.
3. Copy it to: %APPDATA%\Autodesk\ApplicationPlugins\ (single user) or %PROGRAMDATA%\Autodesk\ApplicationPlugins\ (system-wide).
4. Restart Civil 3D. It loads automatically.

Level 1 — Manual distribution (small teams, 1-5 users):

• Zip the .bundle and send it by email/Drive.
• A 3-line install manual:
  1. Unzip into %APPDATA%\Autodesk\ApplicationPlugins\
  2. Restart Civil 3D
  3. The "Zeist" tab appears in the Civil 3D toolbar

Level 2 — Installer with Inno Setup (medium teams, 10-50 users):

Inno Setup is a free tool for building .exe installers.

Create an Inno Setup script (installer.iss) that:
- Installs the bundle in Autodesk's standard path.
- Creates a Start Menu icon for "Zeist Tools".
- Includes an uninstaller.
- Requests elevated privileges to install system-wide.
- Shows a license and description before installing.

You compile it and get ZeistToolsSetup.exe — an installer anyone can run.

Level 3 — Distribution with automatic updates (enterprise, >50 users):

This is where it gets serious: you need a server that hosts new versions, and your plugin needs to check on startup whether a new version exists. Options:

• Squirrel.Windows — a .NET framework for Chrome/Slack-style auto-updates.
• WiX Toolset — enterprise .msi installers with update support.
• Internal distribution via SCCM or Autodesk Vault — if your company already uses one of these.

Level 4 — Publishing on the Autodesk App Store:

If you want to monetize or distribute to external clients, the Autodesk App Store is the official marketplace. It requires:

• Registering as a publisher.
• Passing the review process (code, documentation, screenshots).
• A digital signature on the .dll.

Start at Level 1 and move up as demand grows.