11 Working with Claude Code¶

This chapter is for you when you work on an edakit project with Claude Code. After it you know what the plugin brings, how sessions share EasyEDA, and the agreements every session starts with. The short way: Decide on what was found.

The toolkit is half code, half agreements about how Claude works, and the agreements are as important as the scripts.

11.1 What the plugin brings¶

Component	Name	Use
skill	`/edakit:start`	EasyEDA ready, long runs, GUI clicks, crash recovery – before any EasyEDA work
skill	`/edakit:new-project`	set up edakit in a repository – a new project, or one that moves to edakit with hardware files, scripts or agents of its own (then the inventory first): an interview from boards, the schematic's drawing, the maker, assembly, order, money and purpose to firmware, documents and the project's own tools, every key from an answer, written after your OK (2.7)
skill	`/edakit:requirements`	what the circuit must do, with you: needs and requirements with their evidence in `hardware/requirements.toml`, as those involved state them, not as edakit derives them, asked back in a decision round until vague words are your numbers – Claude drafts, you accept (3.6)
skill	`/edakit:circuit-design`	from requirements to a graph: blocks, parts, computed values, checks, hints, simulation (chapter 14)
skill	`/edakit:hardware-change`	a change from graph to PCB and docs
skill	`/edakit:part-search`	find a part at the project's distributors, create and sign its parts entry
skill	`/edakit:own-part`	the parts entry of a part nobody sells and no edakit project describes – own board, from the bin, made by hand – from your documents and measurement (4.5)
skill	`/edakit:pcb-round`	one layout round
skill	`/edakit:release`	the gate, sign-offs, order checklist
skill	`/edakit:cart`	a released board into the maker's cart with Claude in Chrome in your browser – JLCPCB, PCBWay, Eurocircuits, AISLER –: the job of `edakit cart prepare`, every field set and read back, the quote checked (ORDER.form to ORDER.review), the regulatory review of the order, then the cart button and stop – never orders, never pays; afterwards the real cost into the fee table (8.4)
skill	`/edakit:decision-round`	numbered findings asked as questions, answers picked in the form or written short, numbered decisions
skill	`/edakit:propose-rule`	a check, hint, block or part fact as a sealed issue to the edakit repository, and its outcome back into the decision (chapter 14.4)
skill	`/edakit:propose-feature`	a feature edakit lacks and a project had to build or work around, as a sealed issue to the edakit repository, and its outcome back into the project (11.6)
skill	`/edakit:version`	which edakit runs, the plugin per scope, the newest version and what the changelog says in between – its When updating: lines first –, the project's pins; the update on your word; `pin` and `unpin` – one version in every edakit.toml and CI call, or following the updates again (2.3)
agent	`edakit:requirements-engineer`	reads every document of a project for what its circuit must do and returns candidates with their source, contradictions, vague words and requirements without evidence – the first inventory and a second opinion on the requirements file, in its own context; changes nothing (3.6)
agent	`edakit:project-surveyor`	reads a repository that moves to edakit and returns per place – hardware data, EasyEDA project and released runs, scripts, agents, skills, documents with values, decisions, guard rails – candidates with where it found them, a proposal and its reason, the answers the repository gives to the setup's interview, contradictions and what it could not read – the inventory of the skill new-project, in its own context; changes nothing (2.7)
agent	`edakit:part-selector`	finds a part at the project's distributors (a profile each) and writes its parts entry, in its own context (chapter 4.2)
agent	`edakit:easyeda-operator`	runs one long EasyEDA step and returns only the result – keeps the main conversation clean
agent	`edakit:electrical-reviewer`	independent circuit review; its result is the sign-off M-1
agent	`edakit:regulatory-reviewer`	circuit and parts against EU law for the board's purpose; its result is the sign-off M-6 (chapter 15) – and "At the order" what an order adds (finish, quantity, the maker's seat), checked by ORDER.review; support, not legal advice
agent	`edakit:pcb-reviewer`	independent layout review (read-only EasyEDA tools); its result is the sign-off M-5
MCP	`easyeda`	easyeda-mcp-pro, pinned, safe defaults
hook	PreToolUse on the easyeda tools	claims EasyEDA for the session, refuses when another session holds it
hook	SessionStart	in an edakit project: the working agreements of 11.4 – their first line names the edakit that runs – and the project's own scripts and agents (8.6), one line each, into the session's context; a line when the running edakit does not meet `[project] edakit` (2.3), and one when the pre-commit hook is missing, has no edakit block or an older one, or git does not run it (`edakit hook install`, 2.7); on KiCad a line on the tool chain, and the path of `bin/edakit` where `edakit` is not on the PATH
bin	`edakit`	the command line on the Bash PATH

Skills trigger on their description, or you call them by name. The rules of one project – what you want from the layout, which parts must stay hand-soldered, the decision numbering – go into its own CLAUDE.md or skills; the plugin's skills stay generic.

A project's own agents that sign what edakit releases are registered in edakit.toml as [agents.<name>] (project scripts and agents, 8.6). One takes over an edakit reviewer – only explicitly, with replaces – or has a sign-off of its own. Every session starts with a line for each (the session start, 11.4), the skills start them where edakit scripts says ("Who reviews where"), and the gate counts their sign-offs only when done_by names them. The project's skills are not registered: Claude Code finds them by itself.

Several Claude sessions at once are normal, but there is one EasyEDA per machine, and every script and most MCP tools switch its active tab. A second session's run pulls the tab away: a run in progress is lost, and writes can land in the wrong document.

So EasyEDA is claimed per session (edakit lock), independent of anything git does:

The first EasyEDA access claims it – the hook for MCP tools, every edakit command for scripts. Every access renews the claim; it expires after 15 minutes without access. Tools that only ask about the connection are free.
Library lookups pass the claim: the device search (easyeda_schematic_search_device) and the device reads through easyeda_api_call (paths beginning LIB_Device.search or LIB_Device.get) leave the open document and tab as they are. They neither take nor renew a claim, so a part search runs while another session routes and does not block EasyEDA for 15 minutes afterwards. The list is data in edakit/lock.py (READ_ONLY_TOOLS, READ_ONLY_API); an entry joins only with the evidence that the call leaves the active document as it was.
Another session is refused with who holds EasyEDA and since when. It waits or asks the holder (ListAgents → SendMessage).
Letting a short run in: a run under 5 minutes on another document need not wait behind a long one. Between two of its own runs, with nothing unsaved it might discard, the holder runs edakit lock yield <session>. When the guest releases or its claim expires, EasyEDA goes back to the holder, not free, so a third session cannot snatch the gap.
Waiting for your click holds nothing: release EasyEDA while waiting.

The state is machine-wide, as EasyEDA is: $XDG_STATE_HOME/edakit/easyeda-lock.json, by default ~/.local/state/edakit/easyeda-lock.json; EDAKIT_LOCK_FILE names another file.

Git needs the same thinking when several sessions share one working tree: one branch switch moves everyone, and a git add -A takes other sessions' files. edakit has no tool for it, as it is not EDA-specific. If you run parallel sessions in one repository, build or adopt one – a commit lock, an active branch and a log book, enforced by a PreToolUse hook on git commands.

11.3 Long runs¶

Say up front how long a run takes and which step is the longest, and show progress (step n/m, minutes). edakit's long commands print a line before each step, flushed at once – [ 3.2 min] step 4/8: pours: route all, gate (each stage and project check, with --eda each board), pcb apply, silk apply, export (two steps per board), schematic create/layout (each phase, followed by its duration and EasyEDA's memory). A Monitor on step lines shows where a run is and since when; a stalled run stalls in the step it last named.
Start long runs in the background, and wait for the notification or watch the log. Never wait with pgrep -f on a pattern in the same command line – it finds its own shell and never ends. Write an end line and the PID, and wait for either.
Do not filter a long run's output down to a few lines – a silent abort is then invisible.
uv installed as a snap cannot write to files Claude Code hands it as stdout: … 2>&1 | cat.

11.4 Working agreements that proved themselves¶

Every session in an edakit project starts with this list: the plugin's SessionStart hook (edakit/agreements.py) finds the project's edakit.toml and adds one line per agreement – its number and bold title, read from this section – with the path of this chapter. A new agreement needs nothing but its numbered item with a bold title here. Outside an edakit project the hook adds nothing. After the agreements it lists the project's own scripts and agents, one line each (below the list); [project] agreements = false in edakit.toml turns off the agreements, not that list. A project with toolchain = "kicad" gets one more line – no EasyEDA, no claim, no easyeda-operator, the commands run kicad-cli (chapter 16) –, and where edakit is not on the PATH a last line names the plugin's bin/edakit.

Everything in EasyEDA is generated, so it may be deleted. Claude deletes tracks, pours, parts, schematics and regenerates them without asking for permission or proposing a backup.
Fix the tooling instead of asking for clicks. When automation keeps failing, find the cause (the EasyEDA editor bundle, the MCP server source), adapt the scripts, the server configuration, EasyEDA's start options; restarting EasyEDA is fine (save first, announce it to other sessions).
A dialog the user must handle is a plain OK. Prepare everything so that OK is right; never ask them to read, copy or judge a dialog's content. Ask when they are there, and only then say "click now".
An agent's check is the sign-off. If an independent agent checked it, it is either OK (signed, done_by = the agent – a project agent by its name, the gate holds its sign-off to it, 8.6) or not OK (fixed and checked again). No checklists for the user to re-check what an agent can check. Only real decisions go to the user: accepting a warning, approving a requirement (skill requirements), looks and operation, money.
Open questions go to the user in decision rounds. Numbered findings with consequence and a recommended proposal, asked as questions in Claude Code's form (AskUserQuestion) – the alternatives, the recommendation first – or answered in writing, "ad 1 ack, ad 2 b, ad 3 you decide"; every answer becomes a numbered decision with reason and date (decision-round skill). Nineteen open decisions sent as one-line recommendations came back with "where are the questions? those are statements"; in the form the user picks from afar and asks back in its text field.
Realistic risks: how likely, what it costs. Per risk, and the review agents per finding too. Delivery delays and stock problems are force majeure – one line. A deviation from a datasheet recommendation without a realistic consequence is not a finding.
Check that a proposal fits before proposing it. Dimensions from the datasheet of the exact part (including solder tabs) against the board geometry; electrical specs of the exact part, not of a similar one.
Robust, not fitted to today's layout. Mechanical parts derived from the layout (enclosures, stands) get uniform clearances over areas and contact only where needed – not pockets fitted to today's pins.
Name stages and checks with words. "Stage L (board)", "GEO.hole (hole fits the lead)" – nobody remembers letters.
Cost matters, effort is no argument. A cheaper part is worth a gate run; a gate run is routine, not a cost.
Requests to the user stand apart at the end of a message, not hidden in a paragraph.
Circuit, layout and review are separate roles (chapter 14.1). The circuit designer (skill circuit-design) hands over in writing, the PCB designer works from that in a session of its own (skill pcb-round), and the agents electrical-reviewer and pcb-reviewer review in theirs. A design reviewed by its designer has not been reviewed.
A finding a rule could have found can become one. Reviewers mark such findings as candidates; the user decides, nothing is filed by itself; an accepted candidate is a decision in the project's log, goes to the edakit repository as a proposal when the user asks (skill propose-rule), and is triaged and built there (skills triage-rule and add-rule, chapter 14.4). Rules come from the catalog and the datasheets – a rule from memory is said to be one and reported as a candidate.
What a project had to build itself goes back as a feature proposal, not as a quiet copy in edakit and not as a lasting workaround in the project (11.6).
Time-box a failing tool. When a tool keeps failing, read its documented limits and try the alternative before writing repair tooling around it – fixing the tooling (2) starts there. In the reference project about a day and 1000 lines of repair code went into EasyEDA's autorouter, whose documented behaviour is all or nothing; Freerouting then routed the same board in 1.5 minutes with DRC 0.
Reported means read back. A change written to the EDA is reported or documented only after save, reload and read-back – best from the exported files. A fix of hole sizes and slots was reported, and written into the parts database and a decision, while EasyEDA had reverted it; the documents were wrong for about 1.5 hours.
Tool and UI facts only from verified output. Commands, API names, menu entries and options in documents or instructions come from the tool itself – the API inventory, the extension's manifest, the editor's bundle – never from memory; look for the EDA's own API before building a fallback around it. About 600 lines of invented automation docs (commands, a package, API calls that do not exist) and mock scripts with invented part numbers took about an hour to clean up; a raster PDF stitched from 36 screenshots was presented as the only option while the API had a vector export (35 minutes).
Probes on a throwaway document. Tests and probes run on a scratch document, never on a generated document the project uses; probe documents and library objects without a device are removed when done. A test run overwrote the real 113-part schematic; later, leftover probe schematics and a footprint copy without a device put a dialog in front of the user whose wrong answer would have changed the footprint of the main module in the order data.
A principle the user has set stays set. State the effort once, plainly; do not reopen a decided principle with effort arguments. After the user had set "nothing on the visible side but the LEDs", moving the tracks was answered with "a day of work with risk" and two more questions about alternatives – two extra decision rounds.
Fix defects in your own choices. A failing check on a part, footprint or value Claude chose is fixed and reported, not put to the user as "may I swap?"; only real trade-offs go to the user (4). On a second project Claude asked the user to approve swapping a footprint it had chosen itself, after the hole check failed on it.
Say honestly how far the automation goes. Documents and READMEs name the steps that were done or fixed by hand and the ones never run live. A README claimed that nothing in the EDA project was drawn by hand while much had been developed by hand around it; it had to be rewritten.
Prefer what the project already does. Among options, recommend the mechanism the project already uses (a plug and a cable, screws) over a new one (spring contacts, docking); if a new one is the only way, say that it is new and what must be tested. Spring-contact docking was recommended where a plug and a cable like the existing ones did the job, and rejected as a mechanism the project never had.
Take a stated rule literally, keep a new feature on its own. Do not tie it to existing mappings or build on an optional aside. A progress display stated as "from bottom left to top right" was mapped onto an unrelated existing order of the LEDs, followed by the question whether to rearrange other content to fit it.
A declared phase limits what changes. While the user calls the work a concept phase, every request changes the concept documents only – not graph, board files or firmware – until an explicit go. In a concept phase, requests about a 3D-printed part were taken as orders to change it; the phase had to be restated three times.
Project documents stay in the repository. Reports and documentation are files in the repository; nothing is published to an outside service unless the user asks. A documentation request once ended as a page hosted outside the repository.

The project's scripts and agents. After the agreements the hook lists the project's own scripts and agents ([scripts.<name>], [agents.<name>], 8.6), one line each – a script with its kind and about, a check also with its id and phase, an agent with what it signs, whom it replaces and its about –, in the order of edakit.toml, each group under a line that says where its entries run and points to edakit scripts. So every session knows what the project registered and why, also once the skill that used to run a script is gone. A project without [scripts] and [agents] gets the agreements alone.

The project's scripts – [scripts.<name>] of edakit.toml (handbook 8.6): an input runs by itself before the step that reads it, a derive or easyeda script with `edakit run <name>` – an easyeda script on command only, under the EasyEDA claim –, a check in the gate or on the protocol's list of its phase. Their state – current, outdated, never run – and the order: `edakit scripts`
- baumgrafik (input) – Tree artwork on the silkscreen, clear of pads and vias
- led-footprints (easyeda) – The same polarity print on every LED footprint (owner, 2026-10-25)
- mechanik (check K, phase export) – The tree fits the stand: slot, hill, cable, feet (D-36)
The project's agents – [agents.<name>] of edakit.toml (handbook 8.6): each reviews in its own session at its hook point, one with replaces in place of that edakit agent; its sign-off counts only when done_by names it. Who reviews where: `edakit scripts`
- pcb-pruefer (signs M-5 in place of pcb-reviewer, phase export) – Checks the tree board for manufacturability, mechanics, operation and looks

The state – current, outdated, never run – is not in it: it is the hash of everything a script reads, from the board files to a gate run's Gerber files, compared with hardware/scripts.lock, and computing it needs edakit's own modules; a session must start at once, so the hook reads edakit.toml and nothing else. edakit scripts gives the state, and the skills call it at their steps (8.6). [[release.stages]] and sim_plugin are not listed: the gate and edakit sim run them. With a python3 older than 3.11, which lacks tomllib, or an edakit.toml that does not parse, one line says that the project registers scripts or agents and that edakit scripts lists them.

[project] agreements = false turns off the agreements and leaves the list: the list is the project's own data, registered so that every session knows it – a project that keeps working agreements of its own still needs it.

11.5 Memory and project knowledge¶

The working agreements (11.4) reach every session through the plugin, so a new project starts with them. Claude Code's memory (per project) and the project's CLAUDE.md hold one project's preferences that are not in the code. Facts about the project – decisions, checks, API behaviour – belong in the repository: the decision log, the handbook, comments next to the code they explain. Each EasyEDA quirk (chapter 9) is also a comment where edakit works around it, so the next person does not "simplify" the workaround away.

11.6 When edakit falls short: feature proposals¶

A project finds what edakit cannot do yet: a false finding (a 0 Ω bridge that the checks do not see through), a crash, a part of the circuit the simulation leaves out, a routing or pour capability, a silkscreen it cannot place, a check without a test. It builds the capability itself or works around it, and edakit and the project drift apart. This loop brings the gap back the way a rule comes (from a finding to a rule, 14.4), with its own text and triage:

Decision in the project. Which gaps go to edakit is your decision, in the project's log.
Proposal. The skill propose-feature writes one issue per capability from edakit proposal template --feature: Capability (what edakit should do, for any board), Gap (the command and what it says today), Reference (how the project does it: file, function, commit, the method in words), Interface (keys in edakit.toml or a board or schematic file, fields, options – each with the default that leaves existing projects as they are), Test (how a test shows it without EasyEDA), Origin. The issue is public: you see it before it goes out, a private project's code is quoted only with your OK, and it is sealed like a rule proposal.
Triage. The Action proposals reads the section Kind and runs the skill triage-feature with the checks and layers of a rule proposal – who and the format in the workflow, then Claude's judgement. Safe as for rules; plausible: new, the gap real at this commit; acceptable: a feature and not a rule, general rather than one project's taste, fitting (project data in the project's files, not in the code), testable without EasyEDA, one capability, clear enough. Result as for rules: Accepted, Rejected with a reason a person can check, or Question.
Build. The skill add-feature: the gap red in a test first, then the interface with its default, the code – whatever needs EasyEDA a thin call around a function that is tested –, the example and the projects at hand unchanged, the handbook. One commit per proposal, all in one open pull request from features/proposals, pushed by the Action's own job once the commit keeps off the pipeline's paths.
Back in the project. The Action cannot clone a private project, so the pull request gives the commands that show the gap closed there; the project runs them against the branch before the merge. After it the project's workaround goes and the decision gets edakit: #14 built.

A gap someone else reports in an issue is welcome too: the Action wrap wraps its texts, and edakit's repository owner answers with review, accept or reject – or hands it over with a sealed proposal as a comment there, as for rules (14.4).