Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion audit-log.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,6 @@ last_updated: 2026-03-29

# Audit Log

Replaced 46 ambiguous phrases with hard constraints and quantified terms.
Replaced 10 ambiguous phrases with hard constraints and quantified terms.

Also explicitly enforced logical conflict resolution: TypeScript 5.x -> prefer 'interface' for structure, 'type' for unions.
11 changes: 6 additions & 5 deletions docs/windsurf-vibe-coding-hints.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ vibe_coding_ready: true
# 🏄 Windsurf Advanced Usage Hints: Mastering Vibe Coding
## 📖 1. Introduction to Windsurf AI Agents

Windsurf is a powerful tool for developers who use AI agents to write code. By understanding how Windsurf works, you can improve your vibe coding workflow. Vibe coding allows you to build software by giving intent-based instructions to an AI agent. This guide provides advanced usage hints to help you get the best results from Windsurf, optimize the context window, and manage memory limits.
Windsurf is a powerful tool for developers who use AI agents to write code. Understanding how Windsurf works is MANDATORY to improve your vibe coding workflow. Vibe coding allows you to build software by giving intent-based instructions to an AI agent. This guide provides advanced usage hints to help you get the best results from Windsurf, optimize the context window, and manage memory limits.
## 🏗️ 2. The Windsurf Vibe Coding Workflow

To get robust, deterministic code from Windsurf, you need a clear process. The AI agent needs the right context window to understand what you want. The following diagram shows the best workflow for sending instructions to the Windsurf AI agent.
Expand All @@ -38,7 +38,8 @@ graph TD
```
## 🧠 3. Managing Memory Limits and Context Size

One of the biggest challenges in vibe coding is managing the AI memory limits. If you give the AI agent too much information, it might forget important details in the context window. If you give it too little, it will make mistakes.
One of the biggest challenges in vibe coding is managing the AI memory limits. > [!IMPORTANT]
> If you give the AI agent too much information, it STRICTLY risks forgetting important details in the context window. If you give it too little, it will make mistakes.

Here is a comparison of different ways to manage the context window and memory limits in Windsurf:

Expand All @@ -49,16 +50,16 @@ Here is a comparison of different ways to manage the context window and memory l
| **Full Folder Search** | When you do not know where a code bug is located. | Low accuracy, high memory usage. |
## 💡 4. Advanced Usage Hints for Prompt Creation

To make Windsurf AI agents generate perfect code, follow these simple rules for vibe coding:
To make Windsurf AI agents generate perfect code, follow these deterministic rules for vibe coding:

1. **Be Specific:** Tell the AI agent exactly which file to change. For example, say "Update the button component in `src/button.tsx`" instead of "Change the button".
2. **Use Clear English:** Write your prompts in simple, direct language. Avoid using complex phrasing.
2. **Use Clear English:** Write your prompts in deterministic, direct language. Avoid using complex phrasing.
3. **Limit the Context Window:** Close unnecessary files to keep the context window small and avoid reaching memory limits.
## ✅ 5. Actionable Checklist for Windsurf Vibe Coding Success

Follow these steps every time you start a new vibe coding session with Windsurf:

- [ ] Write a clear and simple prompt that states your exact goal for the AI agent.
- [ ] Write a deterministic and structured prompt that states your exact goal for the AI agent.
- [ ] Open only the files that the AI agent needs to read in the context window.
- [ ] Add a `.windsurfrules` file to your project to set global constraints.
- [ ] Check the generated code for errors before accepting the changes.
Expand Down
3 changes: 2 additions & 1 deletion frontend/angular/components-signals.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,8 @@ Boilerplate code that is easy to break if you make a mistake in naming the `Chan
value = model<string>();
```
### 🚀 Solution
Use `model()`. This creates a Signal that can be both read and written to, automatically synchronizing its state with the parent.
> [!IMPORTANT]
> STRICTLY use `model()`. This creates a Signal with read and write capabilities, automatically synchronizing its state with the parent.
---


Expand Down
6 changes: 4 additions & 2 deletions frontend/typescript/objects-functions.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,8 @@ The index signature syntax is more verbose, harder to read, and less semanticall
const prices: Record<string, number> = { apple: 1 };
```
### 🚀 Solution
Use the `Record<K, V>` utility type for key-value maps. It provides a deterministic, clean, and declarative syntax that AI agents and engineers can parse instantly.
> [!IMPORTANT]
> Use the `Record<K, V>` utility type for key-value maps. It provides a deterministic, structured, and declarative syntax that AI agents and engineers MUST parse instantly.
## 🚨 22. Excess property checks and object spreading
> [!NOTE]
> **Context:** Passing objects to functions.
Expand Down Expand Up @@ -83,7 +84,8 @@ Manually unwrapping promises via custom conditional types is unnecessarily compl
type Result = Awaited<ReturnType<typeof apiCall>>;
```
### 🚀 Solution
Always use the built-in `Awaited<T>` utility type (TS 4.5+) for deterministic and clean promise resolution.
> [!IMPORTANT]
> Always use the built-in `Awaited<T>` utility type (TS 4.5+) for deterministic and structured promise resolution.
## 🚨 25. `this` typing in functions
> [!NOTE]
> **Context:** Ensuring correct context in callback-heavy code.
Expand Down
1 change: 1 addition & 0 deletions frontend/typescript/readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,7 @@ type Status = "active" | "inactive";
```
### 🚀 Solution
> [!IMPORTANT]
> > [!IMPORTANT]
> Prefer `interface` for structure, `type` for unions. Interfaces provide better error messages and performance for structural types in TypeScript 5.x.
>
> **Logical Conflict Resolution:** To enforce the repo standard, NEVER use `type` for defining object structures, and NEVER use `interface` for unions.
Expand Down
1 change: 1 addition & 0 deletions frontend/typescript/types-interfaces.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,7 @@ type Status = "active" | "inactive";
```
### 🚀 Solution
> [!IMPORTANT]
> > [!IMPORTANT]
> Prefer `interface` for structure, `type` for unions. Interfaces provide better error messages and performance for structural types in TypeScript 5.x.
---

Expand Down
Loading