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?

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

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.

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.

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:

Did I update
```
main-tasks.md
```
?
Did I save evidence to
```
docs/evidence/
```
?
Did I push the code and create a PR?

Development Guidelines

Development Guidelines

General Best Practices

Project Structure

Documentation Standards

Safety Rules

Testing Standards

Development Workflow

1. Pre-Development Checklist

2. Coding Phase

3. Post-Coding & Review

Related Skills

Markdown Converter

Nano Banana Pro

1password

Development Guidelines

General Best Practices

Project Structure

Documentation Standards

Safety Rules

Testing Standards

Development Workflow

1. Pre-Development Checklist

2. Coding Phase

3. Post-Coding & Review