From Vibe to Scribe: Using AI Coding Assistants Effectively

AI will not replace the need for engineers and developers. However, it will change the way we work. We will still need to learn and follow software engineering best practices, yet will need to also learn how to effectively use AI within that process to help us work more efficiently and effectively. As a systems engineer and software developer, I'm very excited about the potential of AI to help me work more efficiently and effectively, and I've had great success with AI coding assistants. I'm looking forward to sharing some of what I've learned with you.

Large Language Models

While AI coding assistants are powerful, they're built on Large Language Models (LLMs), which are, essentially, probabilistic token predictors--you might think of them as “fill in the blank” tools that are good at picking the statistically most likely way to complete the “blank”.  They are not actually doing logical reasoning (although their output may appear to look like logical reasoning, it is merely an echo of some of past collective reasoning on similar input/topics).  Essentially, they are good at filling in the “whats” yet are not actually good at answering the “whys”.  And that’s where human oversight is not just valuable, but necessary.  Understanding the limitations of this technology helps us know when to trust AI suggestions and when to rely on traditional engineering methods

What is "Vibe Coding"?

There's a term right now called "vibe coding" where you simply ask AI to create something and it does it (over and over again). You ask for changes/additions. You wash, rinse, repeat. Yet, this cycle can quickly result in a huge quantity of technical debt, if good software engineering practices are not followed.

"Vibe coding" has become a bit of a pejorative term, as it has enabled people who don't know much about the technical details of software development to create applications that look like they were created by a professional, but are riddled with security vulnerabilities, performance issues, and other problems.

The antidote to "vibe coding" isn't to abandon AI, but to integrate it into a disciplined workflow. Ultimately, this guide is about applying time-tested software engineering principles to the new world of AI-assisted development. By doing so, you can harness the power of AI, as another tool in your toolbox, yet without sacrificing quality, maintainability, or your own professional growth.

Image courtesy of Benjamin Lehman

In this guide, we'll explore why 'vibe coding' is hitting its limits, introduce a structured 'scribe' approach to AI-assisted development, and share practical tips for managing technical debt, building essential skills, and structuring projects effectively. This matters because unstructured use of AI leads to mounting technical debt and missed opportunities—by adopting these strategies, you'll code smarter, not harder; reducing bugs, boosting productivity, and future-proofing your engineering practice, whether you're a seasoned pro or just getting started with AI tools.

We’ll walk through five key phases—Exploration, Requirements, Design, Implementation, and Acceptance Testing—so you can adopt a repeatable, debt-free workflow.

Enter the Scribe

If "vibe coding" is the problem, the "Scribe" approach is the solution. Historically, scribes were highly literate and skilled in the art of writing. They were able to capture the thoughts and ideas of their clients, and then transcribe them into a written form that was easy to read and understand. They ensured spelling and grammar were correct, and that the document was well-organized and easy to follow. To use AI coding assistants effectively, you need to be able to do the same thing -- become a "scribe".

A Scribe brings order and intention to the process, much like a skilled writer. Image courtesy of Kelly Sikkema

Creativity Unleashed (and a warning)

As a creative type who enjoys learning how things work and collecting tools and techniques for solving problems, I LOVE AI coding assistants. Never before have I been able to learn new languages, frameworks, and tools as quickly as I have with AI coding assistants. They provide practical examples and implementations so quickly. However, it's tempting to stack quick fixes without considering long-term consequences, as AI excels at generating code but not always a holistic design.

AI can unleash creativity, but it can get a little messy at times. Image courtesy of Alice Dietrich

Managing Technical Debt

To avoid the pitfalls of "vibe coding" and stay productive, it's essential to adopt disciplined practices. Here’s how you can group your efforts:

Process and Workflow

• Structured Phases: Separate your work into distinct phases: Exploration, Requirements, Design, Implementation, and Acceptance Testing.

• Rigorous Testing: All along the way, build a comprehensive test suite that captures all requirements and edge cases.

• Version Control: Use version control (like Git) and create branches for each feature or bug fix to isolate changes.

Automation and CI/CD

• Automated Pipelines: Set up a CI/CD (Continuous Integration/Continuous Deployment) pipeline that automatically runs tests and gates the merging of pull requests on whether all tests pass.

• Code Quality Gates: Go a step further and enforce style guidelines using a linter and format checker, and run these checks automatically in your CI/CD pipeline on every commit.

• Consistent Environments: Create dev containers (e.g., using Docker or Podman) for your CI/CD pipeline so that AI coding assistants and team members operate in the same, consistent development environment.

Leveraging AI Effectively

• AI-Powered Reviews: AI can supplement human code reviews by catching obvious issues, but shouldn't replace human engineering judgment, especially for complex logic or domain-specific code.

• Critical Oversight: Combine AI reviews with human oversight, as AI tools may have consistent blind spots that only human engineering judgment can catch.

• Prompt Engineering: Create prompt templates for common tasks (such as a critical review of a code review) to ensure consistent and high-quality results.

• Integrated AI: Integrate AI coding assistants into your Pull Request and Issue Tracking systems (and your CI/CD pipeline) to allow for cloud-based AI execution.

A structured approach is key to managing the technical debt that can accumulate with AI-generated code. Image courtesy of Pakata Goh

Skills for the Scribe

To excel as a Scribe, you need a blend of foundational software engineering skills and modern, AI-specific knowledge.

Foundational Skills

• Domain Knowledge: Maintain expertise in your specific engineering domain - AI can't replace deep technical understanding of your field

• Critical Evaluation: Learn to quickly assess whether AI suggestions align with engineering principles and domain constraint

• Markdown: Learn how to use Markdown. This text format is easy for both humans and AI to read, and it's the standard for documentation in most modern projects

• Programming Literacy: Learn a few text-based programming languages at a "conversational" level. You don't need to be an expert, but you should be able to read and understand code (an AI assistant can help you learn as you go).

• Tool Selection: Understand what different programming languages excel at and where they are not a great fit. This will help you choose the right tool for the job.

Tooling and Automation

• CI/CD Pipelines: Master CI/CD pipelines for automated testing and deployment

• Scripting: You'll need to understand YAML for configuration files, along with Bash and/or PowerShell scripting, and Python or other scripting languages to automate your workflows.

AI-Specific Knowledge

• LLM Capabilities: Learn about different Large Language Models (LLMs) and their capabilities and limitations, including their technical skill in various programming languages and domains.

• AI Assistant Mastery: Learn about different coding assistants (like Cursor, GitHub Copilot, Claude, and Gemini) and how they work. Master their use in IDEs (like VS Code, Cursor, and JetBrains) and from the command line, as the latter is essential for CI/CD integration.

• Configuration: Learn about the configuration and rules files for different coding assistants. This allows you to provide the assistant with an overview of your codebase, coding style, and other guidelines for working effectively on your project.

Becoming a Scribe means blending traditional software skills with new AI-specific knowledge. Image courtesy of Jakub Zerdzicki

Structure of a Project

A structured project follows a clear path from idea to implementation. Here’s how you can break it down:

Project Background

• Problem Statement: Define your problem statement and why it's important to solve it.

• Success Criteria: Clearly state what success looks like for both you and your end-users.

• User Stories: Document step-by-step user stories that describe what end-users will be able to do.

• Value Proposition: Define how the project adds value to the end user.

• Scope Definition: Define the key features that need to be implemented and, just as importantly, explicitly state what is out of scope.

• Non-Functional Requirements: Define key performance indicators, security requirements, scalability needs, etc.

• AI as a Reviewer: Have the coding assistant review the project background for clarity and completeness. However, do not ask the AI to write the background for you. This "why" phase requires your human insight.

A well-structured project plan is the foundation of the Scribe method. Image courtesy of Clay Banks

Exploration

• Brainstorm with AI: With the background defined, ask your AI assistant to suggest tools, frameworks, and architectural approaches.

• Compare Options: Ask for a list of pros and cons for different approaches.

• Prototype: Ask the AI to develop simple functional examples of the most promising options.

• Validate: Run the examples and evaluate the results to make an informed decision.

• Deeper Research: Use research-focused AI tools to generate a report on different approaches, using your project background as context.

• Real-World Example: For instance, at JKI when we built Jake—our LabVIEW-trained AI assistant at JKI—we used this phase to evaluate and compare different training data sources and tools.

The Exploration phase involves surveying the landscape of new possibilities with your AI assistant. Image courtesy of Guilherme Farinha

Project Setup

• Initialize the Project: Ask the coding assistant to initialize a new, empty project, creating a simple scaffold for your work.

• Set Up CI/CD: Ensure that you have CI/CD set up to run tests automatically. Push your initial code to the repository and confirm that the pipeline runs correctly.

Requirements

• Domain Specific Requirements: For safety-critical systems, hardware interfaces, or mathematical algorithms, apply extra scrutiny to AI suggestions. In domains like LabVIEW, where AI training data is limited, treat AI as a brainstorming tool rather than an expert.

• Keep it Simple: When using AI coding assistants, be sure to tell them to keep things simple and concise. Focus on the task at hand and avoid letting the AI make additional edits or assumptions that expand the scope.

• AI as a Reviewer: Have an AI review your requirements document and provide feedback. You can ask the agent to edit your document directly and then use your IDE's review tools to accept or reject individual changes.

• Prioritize: Identify the highest-value, highest-risk features that should be implemented first. This helps mitigate risks early.

• Test-Driven Development: Create unit tests for your function(s) before writing the implementation. Be sure to review these tests carefully to confirm that they accurately capture the requirements.

• Tests Encode Requirements: Your test suite represents the mathematical and logical constraints your system must satisfy. Restrict AI coding assistants from changing tests. AI Changing tests to match AI-generated code is like changing physics to match a simulation - the requirements are the immutable foundation.

• Resist "Fixing" Tests: If a test fails, resist the temptation to let the AI alter the test itself. Instead, fix the code to meet the original requirement. An AI modifying test code is equivalent to it changing your project's requirements—a decision that you, the Scribe, must control.

• Strive for Coverage: Aim for high test coverage, but be mindful that test code also needs to be maintained.

Clear requirements give you a handle on your project, keeping both you and the AI on track to your final destination. Image courtesy of Wd Toro

Implementation

• Keep the Codebase Working: Your goal is to keep the codebase in a consistently working state. Implement features incrementally, one at a time, and test each one as you go. The more development you do without your tests passing, the harder it will be to fix the issues.

• The "Why" vs. the "What": Remember that AI is bad at why—for example, "Why doesn't my code work according to my requirements?" AI coding assistants struggle with 'why' because they're statistical pattern matchers, not logical reasoners—they can't enforce mathematical constraints or guarantee consistency the way deterministic systems can. Your test suite will point to exactly why the code fails. AI is good at generating the what, but if you let it build "what" on top of "what" without guidance, you will drift further from your project's "why."

• Iterate: For each feature, you'll likely do mini-iterations of this entire process. The size and duration of each iteration will depend on the complexity of the feature and the capabilities of your coding assistant.

Incremental implementation with continuous testing is core to constructing reliable software. Image courtesy of Zane Lee

Acceptance Testing

• Final Review: Have a combination of human and AI coding assistants review the pull request for the completed feature.

• Full Test Coverage: Ensure that you have full test coverage for all changes to the codebase.

• Knowledge Transfer: Make sure you have a good understanding of the changes and can explain them to someone else. This is a critical check for true ownership.

• Merge and Verify: Finally, once you're happy with the pull request, merge it into the main branch and confirm that the CI/CD pipeline for your main/default branch passes.

Acceptance testing is the final quality gate, ensuring the work meets all objectives. Image courtesy of Glenn Carstens-peters

Cycle to Success

• Since you've gone through a formal process for each feature, you are now managing your technical debt.

• Hopefully, you can now see what's missing when you're simply "vibe coding" and why you don't want to leave these important steps out.

The Scribe method creates a virtuous, winning cycle of quality and productivity. Image courtesy of Alice Kotlyarenko

Conclusion

As the field evolves toward more reliable, constraint-based AI systems, the disciplined practices outlined here will become the foundation for next-generation engineering tools. Transitioning from "vibe coding" to a more structured "Scribe" approach is essential for leveraging AI assistants effectively. By embracing clear project phases, rigorous testing, and continuous integration, you move from a reactive cycle of fixes to a proactive process of building high-quality, maintainable software. This disciplined method not only helps you manage technical debt but also enhances your productivity and solidifies your engineering skills. The future of development isn't about letting AI take the wheel; it's about becoming a masterful Scribe who directs the AI to achieve a clear vision.

In future articles, I'll cover these topics in more detail, and provide some examples of how to use AI coding assistants to help you with your projects.

You're now ready to start using an AI coding assistant successfully. Just don't let it fall asleep at the keyboard...

Even the best coding assistant needs a skilled supervisor. Image courtesy of Tai Bui

If you have questions or comments, please leave a comment below or contact JKI at info@jki.net for personalized guidance on implementing a winning "Scribe Coding" strategy in your team.