Sunday Coffee & Code: Turning Existing Architecture Into Refactoring (with Claude Code + Gherkin)

This weekend’s experiment was conceptually simple: 𝘤𝘢𝘯 𝘐 𝘶𝘴𝘦 “𝘨𝘰𝘰𝘥 𝘥𝘦𝘴𝘪𝘨𝘯” 𝘪𝘯 𝘰𝘯𝘦 𝘤𝘰𝘥𝘦𝘣𝘢𝘴𝘦 𝘵𝘰 𝘳𝘦𝘧𝘢𝘤𝘵𝘰𝘳 𝘢 𝘗𝘰𝘊 𝘪𝘯 𝘢𝘯𝘰𝘵𝘩𝘦𝘳 𝘤𝘰𝘥𝘦𝘣𝘢𝘴𝘦? The short answer is yes, here’s the approach I took: 𝗦𝘁𝗲𝗽 𝟭. Prompt Claude Code (Opus 4.6) to extract the key design characteristics (architectural patterns, boundaries, scalability model, UX patterns, and operational behaviours) from a repo I am happy with - all the non-functional stuff. Save that analysis in Gherkin requirements syntax (The idea is to use that Gherkin file as a 𝗽𝗼𝗿𝘁𝗮𝗯𝗹𝗲 𝗱𝗲𝘀𝗶𝗴𝗻 𝗰𝗼𝗻𝘁𝗿𝗮𝗰𝘁). 𝗦𝘁𝗲𝗽 𝟮. Prompt CC, against the destination code-base (which had a PoC Python script and README) to refactor it based on the Gherkin requirements. No change to the functionality, just the non-functional pieces. 𝗪𝗵𝗮𝘁 𝗰𝗮𝗺𝗲 𝗼𝘂𝘁 𝗼𝗳 𝗦𝘁𝗲𝗽 𝟭: • 12 Feature groups covering architecture, orchestration, scalability, security, observability, data, and deployment, e.g. Web and Agent separation, API contract, multi-agent orchestration, job completion etc. • 61 Gherkin formatted requirements A few examples of the kinds of architecture rules captured: • The web tier 𝗼𝗻𝗹𝘆 𝗱𝗼𝗲𝘀 𝘂𝗽𝗹𝗼𝗮𝗱 / 𝘀𝘁𝗮𝘁𝘂𝘀 / 𝗱𝗼𝘄𝗻𝗹𝗼𝗮𝗱 - it never runs agent logic. • Web ↔ agents communicate 𝗼𝗻𝗹𝘆 𝘃𝗶𝗮 𝘁𝗵𝗲 𝗱𝗮𝘁𝗮𝗯𝗮𝘀𝗲 and the job runner. • Job runners 𝘀𝗰𝗮𝗹𝗲 𝗵𝗼𝗿𝗶𝘇𝗼𝗻𝘁𝗮𝗹𝗹𝘆. • Per-step pipeline 𝗽𝗿𝗼𝗴𝗿𝗲𝘀𝘀 𝗶𝘀 𝘁𝗿𝗮𝗰𝗸𝗲𝗱, timed, and queryable. • Uploads artifacts and 𝗲𝗻𝗳𝗼𝗿𝗰𝗲s 𝗼𝘄𝗻𝗲𝗿𝘀𝗵𝗶𝗽 𝗶𝘀𝗼𝗹𝗮𝘁𝗶𝗼𝗻 for safe handling. • P𝗿𝗼𝗱𝘂𝗰𝗲𝘀 𝗮𝗻 𝗮𝘂𝗱𝗶𝘁 𝘁𝗿𝗮𝗶𝗹 that’s useful when things go sideways. 𝗢𝗯𝘀𝗲𝗿𝘃𝗮𝘁𝗶𝗼𝗻𝘀 𝗳𝗿𝗼𝗺 𝗦𝘁𝗲𝗽 𝟮: • Consumed 56% of my Pro plan capacity. • Took 16 minutes to develop a plan, checklist, generate code and PR. • Generated 2,892 lines of code. • Had to be prompted to update documentation, which was fair enough, I didn’t have it in the original prompt. • With the process down, the refactoring of a small PoC into a multi-agent solution, while maintaining good design would takes less than 45 minutes. (𝘖𝘧 𝘤𝘰𝘶𝘳𝘴𝘦 𝘸𝘦 𝘢𝘭𝘭 𝘬𝘯𝘰𝘸 𝘵𝘩𝘪𝘴 𝘰𝘯𝘭𝘺 𝘨𝘦𝘵𝘴 𝘶𝘴 𝘰𝘯𝘦 𝘴𝘵𝘦𝘱 𝘰𝘧 𝘵𝘩𝘦 𝘸𝘢𝘺 𝘵𝘰 𝘱𝘳𝘰𝘥𝘶𝘤𝘵𝘪𝘰𝘯 - 𝘣𝘶𝘵 𝘪𝘵’𝘴 𝘢 𝘣𝘪𝘨 𝘴𝘵𝘦𝘱). Why I like this approach: • It’s 𝗺𝗼𝗿𝗲 𝗱𝘂𝗿𝗮𝗯𝗹𝗲 than a README that you rely on someone to use. • It’s harder to accidentally violate during a refactor - let CC do it and use it’s own checklist to 𝘁𝗿𝗮𝗰𝗸 𝘁𝗵𝗲 𝘄𝗼𝗿𝗸. • It makes architecture something you can 𝗿𝗲𝘃𝗶𝗲𝘄 𝗮𝗻𝗱 𝗲𝗻𝗳𝗼𝗿𝗰𝗲, not just talk about. Next step for me: fire up the code and test it If you’ve tried anything similar, I’d love to hear what worked and what didn’t.