noteplace-front/docs/AI_WORKING_STYLE.md

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.