Applying SHAPR in AI-Assisted Research Software Development: Lessons Learnt from Building a Share Trading System

Abstract: Generative AI is changing how research software is developed, but rapid AI-assisted development can weaken continuity, traceability, and methodological clarity. SHAPR (Solo, Human-centred, AI-assisted PRactice) was proposed as a framework for structuring AI-assisted research software development. This paper presents a documented case of applying SHAPR to the development of a modular share trading system. From the outset, the project adopted a SHAPR-informed working configuration that shaped how interaction, implementation, and documentation were organised. Across iterative development cycles, the project generated a structured evidence base including reflection notes, development cycle review notes, source-of-truth documents, contracts, quick captures, workflow notes, and evolving code artefacts. The case showed that continuous documentation updates, supported by quick capture and AI-assisted refinement, helped maintain organised and usable project knowledge throughout development. Five recurring lessons were identified: contracts stabilised AI-assisted coding, a maintained source-of-truth layer improved coherence, cycle-boundary snapshots strengthened continuity, code and documentation co-evolved through quick capture and iterative refinement, and environment setup itself contributed to knowledge generation. The case also illustrates a practical SHAPR operating configuration in which a ChatGPT Project and cycle-specific chats supported interaction, reasoning, summarisation, and coding collaboration, PyCharm supported artefact implementation, and Obsidian supported external working memory, structured documentation, reflection, continuity, and repository-oriented note organisation, while remaining consistent with SHAPR's tool-agnostic principle. The paper contributes practical guidance and good practices for researchers conducting AI-assisted research software development.

• The paper demonstrates how the SHAPR framework integrates AI-assisted coding with continuous evidence capture to maintain code and documentation coherence.
• It details a modular share trading system case study, showing the impact of early contract establishment and systematic snapshot reviews on traceability.
• The study highlights practical guidelines for solo AI-assisted software development, emphasizing modularity, evidence-based cycle reviews, and adaptive workflows.

Applying the SHAPR Framework for AI-Assisted Research Software: Insights from a Modular Share Trading System Case

Introduction

Generative AI has introduced new paradigms in research software engineering, enabling rapid, AI-assisted cycles of code construction, evaluation, and refinement. Yet, accelerated iteration exposes risk vectors including naming drift, documentation fragmentation, and loss of research traceability. "Applying SHAPR in AI-Assisted Research Software Development: Lessons Learnt from Building a Share Trading System" (2604.15020) conducts a formal empirical examination of SHAPR (Solo, Human-centred, AI-assisted PRactice), a framework designed to address these risks through structured, evidence-oriented development grounded in human agency. The study presents a richly documented application of SHAPR to the iterative construction of a modular share trading system, distilling operational lessons, characterizing key artefacts, and providing guidance for practitioners deploying AI in solo research contexts.

SHAPR Framework: Concept and Operationalization

SHAPR asserts a human-centric, tool-agnostic form of AI collaboration, in which the human researcher orchestrates iterative cycles of exploration, implementation, evaluation, and learning. AI is an assistant for reasoned code generation, summarization, and note refinement—never an autonomous decision-maker. Core principles include continuous evidence capture (e.g., source-of-truth notes, contracts, quick captures), structure-preserving cycle review, and the co-evolution of code and documentation. The framework is deliberately compatible with heterogeneous tooling and supports personalised, adaptive solo workflows.

The practical instantiation in this study demonstrates a SHAPR operating configuration involving three linked workspaces: ChatGPT for interaction and summarization, PyCharm for modular code implementation, and Obsidian for structured repository and knowledge capture. This triangulation allows decoupling of interaction, implementation, and persistent documentation.

Figure 1: SHAPR operating configuration used in the case—integrating ChatGPT for collaboration, PyCharm for implementation, and Obsidian for repository and reflection, supporting the recurring loop of Explore, Build, Use, Evaluate, and Learn.

Case Study: Modular Share Trading System Development

The case analyzes five iterative development cycles spanning environment setup, baseline implementation, back-end stabilization, indicator extension, and derived-signal pipeline enhancement. Each cycle is rigorously documented with artefact-layered records (reflection notes, cycle reviews, contracts, quick captures, and transition snapshots). Importantly, documentation is not a post-hoc summary but an actively maintained, low-friction, continuously updated process, facilitated by AI for both capture and later refinement.

The development workflow is explicitly structured around the SHAPR five-phase loop. Quick captures are made during active coding phases and later integrated into more structured evidence through AI-assisted summarization and consolidation—creating a cumulative knowledge base highly aligned with the evolving codebase.

Figure 2: The SHAPR five-phase loop guiding each development cycle, with integrated capture and consolidation updating the code and documentation repositories to achieve cumulative knowledge growth.

Key Lessons and Good Practices

The study surfaces five recurrent lessons from the application of SHAPR:

1. Early Contracts Stabilize AI-assisted Coding: The introduction and progressive refinement of contracts (naming, interfaces, code protocols) curtail structural and semantic drift during AI-mediated implementation. Early investment in explicit contracts improves code coherence and maintainability.
2. A Source-of-Truth Layer Enhances Coherence: A continuously updated source-of-truth note provides project architectural alignment, mitigating ambiguity and guiding development decisions. When neglected, coherence and implementation quality deteriorate.
3. Snapshots and Handoff Artefacts for Continuity: End-of-cycle snapshots and explicit handoff records preserve state and rationale across cycles, ensuring traceability and minimizing knowledge loss at session boundaries.
4. Code and Documentation Co-evolution: Quick capture of emerging observations, when iteratively refined with AI support, synchronizes the evolution of code and evidence. This practice reduces documentation burden without forfeiting traceability or reflective rigor.
5. Environment Setup as Knowledge Generation: The act of structuring workspaces, note hierarchies, and contracts at setup directly enhances downstream coding quality and reflectivity, establishing a foundation for subsequent research evidence.

The aggregate implication is that SHAPR is most effective when implementation control, documentation rhythm, and cycle continuity are deliberately integrated and continuously visible—rather than treated as secondary or administrative operations. The framework's tool-agnostic and personalizable stance is robust: operational efficacy stems from preserving the balance between interaction, evidence, and code rather than from rigid mandates.

Practical Implications and Future Developments

Practically, SHAPR enables solo researchers to construct highly traceable, explainable development histories in AI-assisted environments without imposing prohibitive process overhead. The structure supports effective onboarding of collaborators, post-hoc review, and research reproducibility. The principles extrapolate to more collaborative or extended settings with appropriate adaptation.

Theoretically, SHAPR embodies a model of research software development where iterative cycles are foregrounded as epistemic activities—each artefact, note, and record a component of cumulative scientific evidence. The seamless integration of human judgement with AI assistance in both code and documentation co-evolution points toward a future in which hybrid intelligence, rather than pure automation, is the dominant paradigm in research software engineering.

Looking forward, integrative tooling (e.g., combined chat-history/artefact management platforms, dynamic contract enforcement, meta-repository tooling for SHAPR records) and formal evaluation across broader team setups and domains are natural extensions. Automated support for knowledge extraction during environment setup, cycle closure, and cross-cycle synthesis could further mitigate cognitive overhead for practitioners.

Conclusion

The case study presented in "Applying SHAPR in AI-Assisted Research Software Development" (2604.15020) provides a detailed, operationally grounded analysis of the SHAPR framework, elucidating its value for managing traceability, coherence, and continuity in solo, AI-assisted research software projects. The identified lessons and derived practices offer concrete guidance for researchers seeking both methodological discipline and the velocity of AI-augmented iteration. The evidence indicates that the co-evolution of code and documentation, stabilized by explicit contracts and maintained through continuous, AI-supported documentation rhythms, is essential for high-integrity AI-assisted research software development. SHAPR's adaptability and artefact-centric discipline position it as a robust foundation for future advances in hybrid human-AI research workflows.