Building with Foresight: AI Development and the Power of Continuous Documentation

by

Author: Denis Avetisyan

This article explores how a structured approach to documentation and iterative development can significantly improve coherence and traceability in AI-assisted software projects.

The study leveraged a practical configuration integrating ChatGPT for project interaction, PyCharm for implementation, and Obsidian for repository management, enabling a cyclical workflow-Explore, Build, Use, Evaluate, and Learn-to facilitate iterative development.
The study leveraged a practical configuration integrating ChatGPT for project interaction, PyCharm for implementation, and Obsidian for repository management, enabling a cyclical workflow-Explore, Build, Use, Evaluate, and Learn-to facilitate iterative development.

A case study demonstrates the practical application of the SHAPR framework in building a share trading system, emphasizing cycle-boundary snapshots and a maintained source-of-truth.

While generative AI promises to accelerate research software development, maintaining methodological clarity and traceability remains a significant challenge. This is addressed in ‘Applying SHAPR in AI-Assisted Research Software Development: Lessons Learnt from Building a Share Trading System’, which details the application of the SHAPR (Solo, Human-centred, AI-assisted PRactice) framework during the development of a modular share trading system. The case study demonstrates that continuous documentation, supported by ‘quick capture’ techniques and a maintained source-of-truth, effectively strengthens project coherence and knowledge continuity throughout iterative development cycles. How can these practical insights inform the wider adoption of robust and reliable AI-assisted workflows in research software engineering?

The Escalating Complexity of Modern Software

Software development, even without the addition of artificial intelligence, has long been plagued by escalating complexity and the relentless pressure of shifting requirements. This often results in “technical debt”-shortcuts taken during development to meet deadlines, which accumulate over time and necessitate costly refactoring. The inherent difficulty lies in managing intricate systems where even minor changes can have unforeseen consequences, and where documentation frequently lags behind implementation. Consequently, a significant percentage of software projects experience delays, budget overruns, or outright failure-not due to fundamental flaws in concept, but due to the challenges of consistently building and maintaining robust, scalable, and understandable code in a dynamic environment. The accumulation of this technical debt isn’t merely a financial burden; it actively hinders future innovation and responsiveness, creating a vicious cycle that demands proactive mitigation strategies.

The proliferation of artificial intelligence tools within software development, while promising increased efficiency, presents significant hurdles to established control mechanisms. As AI autonomously generates and modifies code, maintaining a clear audit trail – traceability – becomes paramount yet increasingly difficult. Determining the rationale behind AI-driven decisions, and ensuring these align with project goals and security standards, requires novel approaches to human oversight. Without careful implementation, the ‘black box’ nature of some AI systems can obscure potential errors or vulnerabilities, diminishing developers’ ability to debug, validate, and ultimately, trust the software they deliver. This necessitates a shift towards AI-assisted development frameworks that prioritize transparency and allow for meaningful human intervention, rather than fully automated processes.

The escalating integration of artificial intelligence into software development necessitates a fundamental shift towards frameworks that prioritize both innovation and maintainability. Current approaches often treat AI as a supplementary tool, potentially introducing opacity and hindering the core tenets of sound engineering – clarity, testability, and predictability. A robust framework must therefore embed AI assistance within established software development lifecycles, ensuring that generated code or automated processes are demonstrably traceable, thoroughly vetted, and aligned with pre-defined architectural principles. This isn’t simply about augmenting existing tools; it requires a re-evaluation of how software is conceived, constructed, and maintained, fostering a symbiotic relationship where AI enhances, rather than compromises, the integrity and long-term viability of complex systems. The ultimate goal is to leverage AI’s capabilities while preserving the human understanding and control essential for building dependable and evolvable software.

SHAPR: A Framework for Structured Human-AI Collaboration

SHAPR, or Structured Human-AI PRactice, is an iterative development framework designed to integrate artificial intelligence tools into software engineering workflows while retaining critical human control. The framework is not intended to be a fully automated process; instead, it proposes cyclical phases of AI-assisted task completion followed by periods of human review, validation, and learning. This iterative approach allows developers to leverage the speed and efficiency of AI for code generation, testing, and documentation, but necessitates ongoing human oversight to ensure quality, security, and alignment with project requirements. Reflective learning, a key component, involves documenting successes and failures of AI assistance to refine future interactions and improve the overall effectiveness of the framework.

SHAPR’s operational foundation is built upon iterative development cycles, wherein code is produced, tested, and refined in repeated phases. Crucially, each iteration is delimited by a process called “snapshotting.” Snapshotting involves comprehensively recording the project’s complete state – encompassing all code, configurations, documentation, and test data – at the conclusion of each cycle. This ensures that a fully functional, documented baseline exists prior to subsequent modifications. Should a later iteration introduce errors or undesirable outcomes, the project can be reliably reverted to the previous, validated snapshot, minimizing disruption and preserving continuity. This cyclical process, coupled with immutable snapshots, provides a robust mechanism for managing complexity and mitigating risk in AI-assisted development workflows.

The SHAPR framework’s Source-of-Truth Layer functions as a central, actively maintained repository encompassing both project documentation and formal contracts defining system behavior. This layer serves to stabilize AI-assisted coding by providing a consistent, validated reference point against which AI-generated code can be evaluated and corrected. Specifically, it details intended functionality, data schemas, and API specifications, minimizing ambiguity for the AI and reducing the likelihood of divergent or incorrect implementations. Regular updates to this layer, reflecting evolving requirements or identified discrepancies, are crucial to maintain its effectiveness and ensure the AI consistently operates on accurate information. The Source-of-Truth Layer is not simply documentation; it’s a living contract defining the system’s expected state.

The SHAPR process-encompassing Explore, Build, Use, Evaluate, and Learn-iteratively refines both code and documentation through continuous capture and consolidation of accumulated records across development cycles.
The SHAPR process-encompassing Explore, Build, Use, Evaluate, and Learn-iteratively refines both code and documentation through continuous capture and consolidation of accumulated records across development cycles.

The SHAPR Toolkit: Instruments for Traceability and Control

The SHAPR toolkit leverages Obsidian as its core documentation repository, centralizing all project-related information. This includes not only standard documentation, but also critical Contracts and Control Artefacts, and detailed cycle records documenting iterative development processes. By consolidating these elements within a single Obsidian vault, SHAPR establishes a definitive Source-of-Truth Layer, mitigating data fragmentation and ensuring all stakeholders access consistent and verifiable information throughout the project lifecycle. This unified approach facilitates traceability, simplifies auditing, and enhances overall project control.

ChatGPT within the SHAPR Toolkit functions as the primary interface for developers to engage with AI-driven assistance throughout the software development lifecycle. It provides capabilities for complex reasoning tasks, allowing developers to explore design choices and validate assumptions. The platform facilitates automated summarization of lengthy documents, code blocks, and cycle records, improving information accessibility. Furthermore, ChatGPT is utilized for documentation refinement, including grammar correction, style consistency checks, and content clarity improvements, thereby enhancing the overall quality and maintainability of project artifacts.

PyCharm functions as the central environment for software implementation within the SHAPR toolkit, facilitating code organization through project structures and modular development practices. The IDE supports debugging workflows with features such as breakpoints, step-through execution, and variable inspection. Integrated AI tools within PyCharm provide assistance with code completion, static analysis, and automated refactoring, aiming to improve code quality and developer efficiency. These AI features operate directly within the development environment, streamlining the implementation process and reducing the need to switch between multiple applications.

The Quick Capture practice within the SHAPR Toolkit facilitates the immediate documentation of ideas, decisions, and observations during development. This involves rapidly recording information – such as design considerations, bug reports, or meeting notes – directly into the system, bypassing traditional, time-consuming documentation processes. Captured information is then directly integrated with the Source-of-Truth Layer, which is maintained in Obsidian, ensuring all development artifacts are consistently updated and readily accessible for traceability and control throughout the project lifecycle. This practice minimizes documentation lag and promotes a continuous flow of information, improving overall project efficiency and knowledge management.

Reflective Learning: Cultivating Adaptability and Insight

The iterative nature of the SHAPR framework culminates in the creation of detailed Cycle Review Notes at the close of each development phase. These notes serve as a crucial repository of collective knowledge, meticulously documenting not only the outcomes of decisions made, but also the rationale behind them and a candid assessment of areas requiring enhancement. This practice moves beyond simple error tracking; it fosters a nuanced understanding of the development process itself, capturing both successes and failures as opportunities for future refinement. By formally recording these insights, the framework ensures that lessons learned are not lost, but actively integrated into subsequent cycles, driving continuous improvement and bolstering the overall robustness of the research system.

The SHAPR framework is designed for iterative refinement, with each development cycle actively contributing to the enhancement of subsequent ones. Captured within Cycle Review Notes are insights gleaned from completed work – not merely documenting successes, but also detailing challenges encountered and decisions rationalized. These notes aren’t filed away; instead, they are systematically integrated back into the framework itself, directly influencing the planning and execution of future cycles. This closed-loop system ensures that lessons learned are not lost, fostering continuous adaptation and preventing the repetition of past mistakes. The result is a software development process that evolves organically, building upon its own experiences to produce increasingly robust, maintainable, and trustworthy AI-assisted research systems.

This research demonstrates that the SHAPR framework actively supports the cultivation of actionable insights and established best practices within AI-assisted research endeavors. By meticulously documenting development cycles and prioritizing reflective learning, SHAPR enables researchers to not only track the evolution of their projects but also to systematically identify areas for improvement. This process enhances both the traceability of decisions made throughout the research lifecycle and the coherence of the resulting software systems. Consequently, SHAPR fosters a robust environment for continuous adaptation, allowing teams to build more reliable, maintainable, and ultimately, trustworthy AI-assisted research tools and methodologies through consistent, data-driven refinement.

At the heart of the SHAPR framework lies a commitment to reflective learning, fostering an environment where each development iteration actively contributes to future success. This isn’t simply about identifying errors, but a systemic approach to capturing insights from every cycle – detailing not only what went wrong, but why, and crucially, what decisions were made along the way. By prioritizing the documentation of reasoning and rationale, SHAPR cultivates a culture of accountability, ensuring that knowledge isn’t lost as team members change or projects evolve. This emphasis on shared understanding and proactive problem-solving extends beyond individual tasks, creating a feedback loop that enhances the overall robustness and maintainability of the software, and ultimately, builds more trustworthy AI-assisted research systems.

SHAPR’s design fundamentally centers on the belief that software reliability isn’t solely achieved through technical solutions, but also through consistent human oversight and iterative refinement. The framework actively encourages researchers to critically evaluate each development cycle, not just for functional outcomes, but also for the process itself. This emphasis on continuous improvement-documented through ‘Cycle Review Notes’-allows for the identification and correction of subtle biases, flawed assumptions, or inefficient workflows. By consistently prioritizing human judgment alongside automated processes, SHAPR fosters a system where errors are viewed as learning opportunities, ultimately leading to software that is not only more robust and maintainable, but also demonstrably trustworthy due to its transparent and adaptable nature.

“`html

The pursuit of coherence, as demonstrated by the SHAPR framework’s emphasis on a maintained source-of-truth, echoes a fundamental tenet of elegant design. Donald Knuth observes, “Premature optimization is the root of all evil.” This principle extends beyond mere performance; attempting to build a complex system without first establishing a clear, documented foundation-a single source of truth-introduces unnecessary complication. The described implementation of SHAPR prioritizes quick capture and cycle-boundary snapshots not as ends in themselves, but as tools to delay optimization, allowing for iterative refinement grounded in accurate reflection and traceability. This aligns with the idea that clarity-a well-defined system-is the minimum viable kindness.

Beyond the Snapshot

The exercise detailed herein – applying SHAPR to a share trading system – confirms a suspicion long held: that much of software development effort is consumed not by creation, but by archaeological reconstruction. Maintaining a living source-of-truth, even in the face of relentless iteration, isn’t merely ‘good practice’; it’s a fundamental category error to proceed otherwise. The persistent challenge, however, lies not in capturing information, but in resisting the urge to overpopulate the record. The true skill is ruthless pruning, distilling intent to its irreducible form.

Future work must address the impedance mismatch between human intuition and machine legibility. SHAPR provides a structure, but it does not, and cannot, think for the developer. The ideal lies in systems that anticipate the need for documentation, inferring intent from code changes and prompting for clarification – a subtle nudge towards self-evident design. Such systems must prioritize signal over noise, recognizing that a concise, accurate record is infinitely more valuable than a verbose, ambiguous one.

Ultimately, the success of any framework hinges on its ability to fade into the background. The goal isn’t to manage complexity, but to eliminate it. The pursuit of perfect documentation is a paradox; the truly well-understood system requires no external explanation, its logic as transparent and inevitable as gravity.

Original article: https://arxiv.org/pdf/2604.15020.pdf

Contact the author: https://www.linkedin.com/in/avetisyan/

See also:

2026-04-18 14:33