Building LearnMate AI: Engineering Practices for a Full-Stack Educational Platform with Claude Code
Over the past development cycle, our team built the **LearnMate AI** platform. This is a decoupled educational Software as a Service (SaaS) application. In this project, we not only implemented core business logic for both instructors and students, but we also systematically integrated Claude Code (including advanced features like Hooks, Custom Skills, MCP, and Agents) into our Agile development and parallel branching (Git Worktree) workflows.
This article reviews how we utilized AI to improve our development efficiency while building defensive mechanisms to address underlying technical challenges and model instability during the development process.
Architectural Refactoring and Storage Optimization
In the early stages of the project (Sprint 1), we prioritized a review and refactoring of the system architecture. We discovered coupling issues between the frontend routing and the storage layer in the legacy system.
Leveraging AI's code refactoring capabilities, we completed a data model association (cascading updates) from Course to Module at a low cost. We also implemented an environment-adaptive Storage Abstraction layer. This abstraction layer currently uses a local static directory as default storage but leaves interfaces ready for a future migration to AWS S3. Additionally, to resolve conflicts when starting multiple local services, we wrote a dynamic port detection script that enables cross-process port discovery and binding between Vite and FastAPI.
Toolchain Expansion: Deep Integration with Claude Code
A core technical highlight of this project was integrating the `everything-claude-code` plugin ecosystem into our daily workflow and solving a series of underlying configuration issues:
1. Resolving Inter-Process Communication Limitations of Hooks
To strictly enforce Test-Driven Development (TDD) standards in our project, we attempted to configure a `PreToolUse` Hook in `.claude/settings.json` to block any code from being committed if it failed unit tests.
In practice, we found that Claude had limitations in handling standard error codes (like `exit 1`), and Inter-Process Communication (IPC) would sometimes cause the pipeline to hang. Through system-level troubleshooting, we improved the interception strategy. We used `read -t 1` to avoid deadlocks, and we forced the script to return `exit 2` while redirecting output to `stderr` upon test failure. This configuration effectively blocked untested code commits at the process level, ensuring the code quality of our main branch.
2.Local Customization of Plugins and Custom Commands
To achieve deep control over the core components of `everything-claude-code`, we skipped the default online installation. Instead, we extracted the core rules directly and completed a highly customized local deployment. Furthermore, to address the challenge of background scripts being unable to save conversational history across processes, we developed a dedicated `/chat-history-log` custom command. This command standardized the automatic archiving process of chat logs via file reading and writing, perfectly solving the data persistence issue.
3.Automated Collaboration with MCP and Agents
For daily task management, we integrated the **GitHub MCP Server** to fetch and parse Open Issues directly within the terminal. For documentation maintenance, we invoked a locally configured `doc-reviewer` Agent to conduct automated formatting audits and structural checks on the README, which greatly improved the standardization of our documentation.
Ensuring Data Consistency: Handling Structural Errors in Model Outputs
When integrating Large Language Models, maintaining system robustness becomes challenging due to the unpredictable structure of the inputs.
While developing the "quiz generation" API, we encountered a typical data inconsistency issue: the frontend successfully displayed the quiz content, but the backend database failed to save it, causing the data to disappear after a page refresh.
Through full-stack tracing, we identified that the root cause was abnormal JSON formatting generated by the model. When the generated content contained complex Chinese contexts and punctuation, the model would occasionally output unescaped, stringified JSON. This caused the backend Pydantic to throw an HTTP 500 exception during deserialization.
To fix this defect, we optimized the structural constraints in our `SYSTEM_PROMPT` and introduced the `json-repair` library into the Python processing layer for fault-tolerant parsing. Paired with our automated Playwright E2E (End-to-End) test scripts, we effectively ensured the high availability of our quiz and flashcard generation endpoints.
Parallel Development and Version Control: Git Worktree Practices
In Sprint 2, we introduced **Git Worktree**, enabling true parallel development for `feat/33-flashcard-ui` and `feat/24-quiz-ui`. These two independent workspaces handled the construction of complex 3D flip animations (implemented with CSS + SVG) and the state machine of the quiz system, respectively.
During the high-frequency merging process of Agile development, parallel branching inevitably leads to complex version dependencies and Merge Conflicts. For example, when synchronously updating core feature trees, the remote and local commit streams developed complex intersections. By accurately analyzing the topological structure, we decisively used `git reset --hard` to reset the state baseline and used Force Push to overwrite the mixed commit records on the remote end, perfectly maintaining the linearity and cleanliness of the Git history.
Conclusion
Looking back at the development process of LearnMate AI, AI tools significantly accelerated our coding, but they also placed higher demands on our system architecture design and troubleshooting abilities. From handling cross-process hook interception and large model formatting errors to resolving Git branch conflicts and configuring E2E testing environments, we established a more rigorous engineering mindset while utilizing AI. This workflow, which combines automated toolchains with strict testing standards, will serve as an important reference for our future software development practices.
Comments