Code, Context, and Calculation - A Modern Framework for Engineering

📌 A quick introduction from Seán

I'm pleased to welcome James O'Reilly to EngineeringSkills.com. James is a Senior Structural Engineer specialising in Power and Water infrastructure projects. James also writes about Python and principles of software development and automation in the context of Civil and Structural engineering. I highly recommend checking out his Flocode newsletter - if you like what we do here on EngineeringSkills, you'll also appreciate James' work on Flocode.

In this article, James makes the case for a specification-first framework for computational engineering. One that treats code as part of a broader professional system, grounded in:

• version control,
• reproducible environments,
• and structured workflows.

Only by adopting this approach, can we bring the same rigour applied to reports and drawings into the programming domain. James also provides plenty of links to additional resources throughout the article - so treat this as your signpost for further exploration of the topic.

Enjoy the article!

Dr Seán Carroll CEng MIEI

Founder of EngineeringSkills.com

The focus on “learning to code” in engineering often misses the point. Getting a handle on Python’s syntax is the price of admission; it is not the final objective. Durable professional advantage comes from the framework that surrounds the code.

I work primarily on large-scale infrastructure projects, and I rely on a host of specialised software for FEA, CFD, GIS, BIM, and more. Python is the universal solvent that stitches it all together, but the integrity of the work depends entirely on the system it lives within.

This framework assumes you have a basic handle on Python syntax. Our focus is not on the language but on the professional system it must inhabit.

The following roadmap (Fig. 1) will provide a good sense of where you might fit along the Python learning path, which is not definitive but presents one logical course from beginner to advanced tooling.

Fig 1. Python for engineers roadmap.

1.0 A Specification-First Approach to Modern Engineering

In professional engineering consulting, our work culminates in three primary deliverables:

• Reports,
• Drawings,
• Specifications.

Every model, detailed analysis, site inspection, cost estimate and feasibility study we perform is an input to one of these foundational outputs. We already operate within a professional environment built on clearly defined scopes and technical specifications; it is the language of our discipline.

Simultaneously, the lines between our work and the world of software engineering are blurring. Modern infrastructure contains embedded software, and the life-safety rigour that governs our profession is bleeding into code. As these silos diminish, we have an opportunity to learn from the practices of software development, a notoriously competitive landscape where every edge in efficiency, clarity, and reliability is pursued relentlessly.

Software teams are actively working to solve the problem of AI slop, unreliable brittle code. They are building systems to produce functional, robust code that integrates into massive, complex projects, both new and existing. For our purposes, there is no need to differentiate between a large software project and a large infrastructure project. Both must be logically and correctly connected, and both must adhere to a strict set of codes, specifications, and standards of care.

The art of context engineering is how we achieve this. It’s about applying the same rigour we use on a macro project level to the micro-scale of our individual design tasks. I will dig into context engineering in more detail in the future, but there are many subtleties that can have a significant effect on utility. As LLMs continue to evolve and expand both their reasoning capability and tool usage, the ground tends to shift beneath your feet, and you must adapt.

2.0 The Foundation: A Professional Environment

For years, computational work in engineering firms has happened in isolated pockets. That era of the "rogue coder" is coming to an end. While my perspective is shaped by my team and the people I communicate with, the trend is clear: computational design is becoming a mainstream expectation.

As these tools become integral to our workflows, our professional duty of care must adapt accordingly. A durable framework must be built on the following pillars.

1. Version Control: A systematic approach to managing work is essential. We should reframe Git from a "developer tool" to what it truly is in our context: a change management system, analogous to the revision history on a set of drawings/reports but with far more detailed tracked changes. Platforms like GitHub, GitLab, or Bitbucket provide the infrastructure to host this work, track its evolution, and collaborate without overwriting progress. They are ready-made project management suites for development. I use both Github (personally) and GitLab (work). Both are excellent. This is the most important step. Git repositories allow you to document, manage and control your project.
2. Environments: Every project requires an isolated and reproducible environment. This is achieved with virtual environments. I prefer uv for its speed, but the principle is what matters. A virtual environment locks in the specific versions of the libraries used for a project. It ensures that a calculation you run today will produce the exact same result a year from now and can be reproduced on any machine by anyone with access.

3. A Capable Workbench. Your Integrated Development Environment (IDE) is your modern workbench. A professional-grade tool like VS Code, JetBrains PyCharm, or the AI-focused editor Cursor helps you write, debug, and manage your work with efficiency. I use VS Code and Warp Terminal but they are all similar.

   I also use a few different AI powered CLI coding tools (claude code, gemini cli, qwen3-coder) - these tools require a little more nuance but are very efficient, once you have well defined processes.

If you want an easy way to get all of these pieces up and running, check out the Flocode Python Starter Kit. It’s an automated setup that installs and validates the core tooling you need before you write a single line of code. You can read more about it here.

3.0 AI as a Co-Pilot

With a robust environment established, we can integrate AI tools. This requires the same professional scepticism we apply to any other analysis software.

The topic of context engineering is deep - you can dig into it and a lot more supporting resources in the Flocode Prompt Library on GitHub.

First, recognise that not all models are created equal. You must choose the right tool for the task. Some are optimised for technical writing, others for code generation. Some have vast context windows for processing large reports; others excel at data extraction. A thoughtful practice is to cultivate a small portfolio of preferred tools and understand their respective trade-offs. Only you will know as you experiment with your workflow.

More critically, we must address data privacy and professional liability. Before you use any project data in a prompt, your organisation must have a corporate agreement with the LLM service provider. This agreement must guarantee that your proprietary data is not used for training their models and that you are in full compliance with your client's privacy agreements.

4.0 The Practical Implementation

The most common failure mode in using AI or automation is an unstructured, conversational back-and-forth that leaves no durable artefacts behind. It’s the equivalent of running a hand-calculation on a scrap of paper and then throwing it away. The answer might be right, but the process is invisible and unverifiable.

The professional alternative is to adopt the specification-first approach we already use for large projects. By providing clear guardrails and communicating the exact steps involved, we can build robust scaffolding for reliable computational work. This is achieved through a deliberate, three-phase workflow.

4.1 Phase 1: Research

Before implementation, you must understand the system. This phase involves gathering all relevant information: identifying design codes, locating source data, and defining project constraints. The output is a concise, well-structured brief that documents your findings. If you don’t really know what you’re doing, how can you possibly expect to get good results? Until you know exactly what’s going on, keep researching. You need to fully understand the problem and the solution space before you proceed to the next step. This is where 60% of your effort should be focused.

4.2 Phase 2: Plan

With research complete, you create a detailed plan, the technical specification for your task. It must outline every step of the analysis, the specific calculations to be performed, and the verification steps for each output, breaking them up into key milestones depending on complexity. This plan is the most important artefact. It documents your engineering intent and can be reviewed for conceptual errors before you invest hours in implementation. Allocate 20% of your effort here.

4.3 Phase 3: Implement

With a verified plan in hand, you execute. You feed your tools with compact, highly relevant context from your research and planning documents. This creates a clear silo of context that provides no more and no less than what is required to get the job done efficiently and correctly - 20% effort here.

This workflow reveals the hierarchy of impact: a flaw in research can invalidate thousands of lines of code. A flaw in the plan can invalidate hundreds. A flaw in implementation is often trivial.

Our professional value lies in focusing our critical review on the highest-leverage stages.

There are many levels of context engineering, starting with clear, objective prompts and growing in complexity to agentic workflows and sub-agents.

I am actively working on a detailed spec-driven-development template but while you wait for that you can use https://github.com/joreilly86/create_notebook_project and create a context.md file for your project. Depending on your AI tool of choice, it may be renamed ‘claude.md’ or ‘warp.md’ or ‘gemini.md’ etc.

This file is the pure essence of your project, the location, the objectives, the design criteria. For an example of a project I have been working on recently see this GitHub gist for a context.md file for a steel framed building.

This will give you a general sense of how it works. This is a simplified version, and adding hierarchical control and milestones for development involves a more opinionated system which I plan to share in the future.

5.0 Developing the Skill

Mastering this framework is a craft developed through deliberate practice. I find two analogies useful.

The first is the Japanese principle of kaizen, the meticulous application of small improvements over time. Your first attempts to build these systems may feel coarse and clumsy. With repetition, your ability to structure a problem, provide effective context, and generate a high-quality solution will improve.

The second is from the gym. You don't walk in on day one and try to deadlift 400 kg. A few people might, but the rest of us will paralyse ourselves or in my case, come home from the gym feeling great only to throw out your back putting on a sock in the morning. The same goes for these tools. You need to start with a weight you can manage with decent form, break the problem down into smaller and smaller pieces until you find a component you can solve with confidence. Solve that, verify it, and then build from there. Attempting too much too soon is the fastest path to flawed work.

This framework is intended to be bolted on to your engineering judgment by providing a more consistent, robust and verifiable structure for computational work. By design, there is no black box. Just a big transparent box with names, dates, versions and information that explain how we get from A to B in a complex design.

These skills and systems are no longer a niche interest; they are becoming a standard component of our profession. The tools are here, there’s no going back.

Experiment. Stay curious. Be persistent.

James 🌊