Development Guidelines

General Best Practices

• Code Quality: Write clean, readable, and maintainable code. Use meaningful variable and function names.
• Consistency: Follow the existing coding style and conventions of the project.
• Documentation: Comment complex logic and properties. Keep documentation up-to-date.
• Error Handling: Implement robust error handling. Don't simply suppress errors; log or handle them gracefully.
• Modularity: Keep functions and components small and focused on a single responsibility (SRP).
• Version Control: Write clear and descriptive commit messages.
• Other: Each file line of code not more than 1,000 line of codes. If more than 1,000 line of codes, split it into multiple files.

Project Structure

• Root Directory: The root workspace should only contain configuration files (e.g., README.md, .gitignore, AGENTS.md) and documentation.
• Application Source: All application source code must be contained within a dedicated subdirectory named after the application (e.g., my-app/, app-assistant/). Do not place source code files directly in the root workspace.
• Separation of Concerns: For projects with distinct frontend and backend components, organize them into dedicated subdirectories within the main application folder (e.g., app-name/frontend and app-name/backend) to maintain clear boundaries.

Documentation Standards

• Comprehensive Docs: Maintain detailed documentation for every stage of development. This includes:
  • Tasks: Clearly defined atomic units of work.
  • Analysis & Research: Notes on technical decisions, alternatives considered, and architectural rationale.
  • Acceptance Criteria: Verifiable conditions that must be met for a task to be complete.
  • Implementation Plan: A sequenced list of steps to execute the solution.
  • Lessons Learned: Insights gained during the process to prevent future issues.
  • Retrospectives: Periodic reviews of the workflow to identify improvements.
• Continuous Updates: Documentation is a living artifact. Updates must happen synchronously with work. If a task is done, check it off immediately. If a design decision changes, update the requirements immediately.
• Working Logs: Maintain a dev_log.md or session log that records chronological actions, decisions, and outcomes for the current work session. This is different from a Retrospective (which is better for feelings/process improvement).
• Directory Structure: Organize documentation within a docs/ directory in the application folder (e.g., app-name/docs/). Recommended structure:
  • tasks/: Task tracking and checklists.
  • analysis/: Research, requirements, and design analysis.
  • plans/: Implementation plans and execution steps.
  • retrospectives/: Lessons learned and retrospective logs.
  • logs/: Chronological development working logs.
  • evidence/: Screenshots, logs, and test results verifying functionality.

Safety Rules

• No Dangerous Commands: Do not use commands that can cause irreversible data loss or system instability (e.g., rm -rf /, formatting drives) without explicit, confirmed user authorization.
• No Force Operations: Avoid using --force or hard reset commands in git unless specifically instructed and the consequences are fully understood.
• Merge Request/Pull Request Protocol: Never auto-approve merge requests or pull requests. All code changes must be reviewed and approved by the user before merging.

Testing Standards

• Build Integrity: Always ensure that the application builds successfully after any changes.
• Runtime Verification: Verify that the application can run and start up correctly. Do not assume code works just because it compiles.
• Evidence Collection: Gather and save visual evidence (screenshots), test cases, and test results in the project workspace (in docs/evidence/). This ensures verifiable proof of functionality.

Development Workflow

1. Pre-Development Checklist

Do not start coding immediately. Ensure the following checklist is complete before writing any code:

• Requirements: Clear understanding of what needs to be built.
• Analysis & Research: Investigation of identifying potential solutions, libraries, or architectural decisions.
• Tasks Breakdown: Detailed list of specific tasks to complete.
• Acceptance Criteria: Definition of done for each task.
• Plan: A step-by-step implementation plan.

2. Coding Phase

• User Initiation: Do not start the actual coding process automatically. Wait for a specific user command or action to begin implementation.
• Step-by-Step Implementation: Follow the plan created in the pre-development phase.

3. Post-Coding & Review

• Immediate Delivery: Upon completing the coding phase and local verification, immediately push the branch and create a Pull Request (PR). Do not wait for the user to ask "Where is the PR?".
• Manual Review: Do not auto-accept or merge the PR. The user must strictly review the code and manually manage the approval and merge process.
• Exit Criteria: Before ending a turn or turn series, verify:
  1. Did I update main-tasks.md?
  2. Did I save evidence to docs/evidence/?
  3. Did I push the code and create a PR?