35 lines
3.0 KiB
Markdown
35 lines
3.0 KiB
Markdown
# AI Collaboration Guide for the Noteplace Project
|
|
|
|
This document outlines the preferred working style and conventions for AI collaboration on this project, based on initial interactions and feedback.
|
|
|
|
## 1. Core Philosophy: Incremental, Verifiable Milestones
|
|
|
|
- **Break It Down**: Do not attempt to implement large, complex features in a single step. Decompose work into the smallest possible, verifiable milestones.
|
|
- **No Mocks in Milestones**: A milestone is only considered "done" when its features are fully functional and integrated with the live backend API. Mocked implementations are only acceptable as a temporary step *within* a milestone, not as the final deliverable for one.
|
|
- **Test Before Moving On**: After a feature is implemented, it must be tested and verified before starting the next task.
|
|
|
|
## 2. The "Polish Phase"
|
|
|
|
After a functional milestone is complete, a dedicated "polish phase" is required. This is a critical step and should not be skipped. This phase includes:
|
|
|
|
- **Documentation**: Update the `README.md`, `docs/WORKLOG.md`, and any other relevant documentation.
|
|
- **Testing**: Add unit or integration tests for the new functionality. The preferred framework for the frontend is `vitest`.
|
|
- **Code Quality**: Clean up any temporary or "useless" code. Refactor to improve clarity and maintainability.
|
|
- **Production Readiness**: Remove hardcoded values (e.g., URLs, tokens) and replace them with environment variables.
|
|
- **Repository Health**: Ensure the repository is well-structured. This includes adding or updating files like `.gitignore` and CI/CD workflows.
|
|
|
|
## 3. Backend & Environment Interaction
|
|
|
|
- **Backend is Truth**: The Go backend is the source of truth. Before implementing a frontend feature, verify that the required backend endpoint exists and functions as expected.
|
|
- **Identify Backend Gaps**: If a required backend feature is missing (e.g., a web auth endpoint for a web app), the AI must:
|
|
1. Clearly identify and explain the gap.
|
|
2. Propose the correct, standard solution.
|
|
3. Offer to implement the necessary changes in the backend code.
|
|
- **Handle Environment Constraints**: The development environment may have limitations (e.g., shell commands like `npm` failing). The AI should not get stuck. It should diagnose the issue, and if it cannot be resolved, propose a manual workaround (like editing `package.json` directly) and clearly ask the user for help with running the required commands (e.g., `npm install`).
|
|
|
|
## 4. Project-Specific Conventions
|
|
|
|
- **CI/CD**: The project uses both **GitHub Actions** and **Gitea**. When adding a CI/CD workflow, create configuration files for both systems (`.github/workflows/` and `.gitea/workflows/`).
|
|
- **Backend Logging**: When modifying backend code, add meaningful logs using the existing `zap` logger to trace the execution flow.
|
|
- **User-AI Interaction**: The user prefers clear, step-by-step explanations, especially for complex topics (like OAuth2). The AI should be proactive in its explanations and planning.
|