From 0d8e0366c6f074b17abb31015610c9e033943f71 Mon Sep 17 00:00:00 2001
From: curo1305 <curo1305@proton.me>
Date: Tue, 21 Apr 2026 11:48:22 +0200
Subject: [PATCH] docs: always use port 5173 for feature stacks (no per-branch
 ports)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Update feature branch workflow: stop main stack before starting feature
stack, always use :5173. Simplify feat override template — no port
remapping needed.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CLAUDE.md | 21 +++++++++------------
 1 file changed, 9 insertions(+), 12 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 0d879e0..2501c82 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -329,23 +329,18 @@ git checkout -b feat/<descriptive-title>   # e.g. feat/user-profile-avatar-uploa
 ```
 
 #### 2 — Spin up an isolated Docker stack for the feature
-A dedicated compose stack runs alongside the main dev stack so both can be tested independently.
+The feature stack always uses port `5173` (same as the main dev stack). Stop the main stack before starting a feature stack, and restart it when done.
 
-**Find the next free port** (main dev stack owns 5173):
+**Stop the main dev stack first:**
 ```bash
-for port in $(seq 5174 5200); do
-  lsof -iTCP:$port -sTCP:LISTEN -t &>/dev/null || { echo "$port"; break; }
-done
+docker compose -f docker-compose.yml -f docker-compose.dev.yml down
 ```
-Use the first free port returned (call it `$PORT`).
 
 **Create a per-feature override file** at `docker-compose.feat-<slug>.yml` (gitignored):
 ```yaml
 # docker-compose.feat-<slug>.yml  — feature test stack, never committed to main
 services:
   frontend:
-    ports:
-      - "$PORT:8080"        # e.g. 5174:8080
     container_name: frontend-<slug>
   backend:
     container_name: backend-<slug>
@@ -371,8 +366,7 @@ docker compose -f docker-compose.yml \
   --project-name <slug> up --build
 ```
 
-The feature frontend is now reachable at `http://localhost:$PORT`.
-The main dev stack continues running unaffected on `:5173`.
+The feature frontend is now reachable at `http://localhost:5173`.
 
 #### 3 — Develop on the feature branch
 All code changes happen on `feat/<slug>`. Commit and push normally:
@@ -383,7 +377,7 @@ git push -u origin feat/<slug>
 ```
 
 #### 4 — Confirm functionality
-Before merging, verify all of the following on `http://localhost:$PORT`:
+Before merging, verify all of the following on `http://localhost:5173`:
 - [ ] Login and registration work end-to-end
 - [ ] The specific feature works as intended
 - [ ] No regressions visible in the UI
@@ -400,13 +394,16 @@ git branch -d feat/<slug>
 git push origin --delete feat/<slug>
 ```
 
-#### 6 — Tear down the feature stack
+#### 6 — Tear down the feature stack and restart main dev stack
 ```bash
 docker compose -f docker-compose.yml \
                -f docker-compose.dev.yml \
                -f docker-compose.feat-<slug>.yml \
   --project-name <slug> down --volumes --remove-orphans
 rm docker-compose.feat-<slug>.yml
+
+# Restart the main dev stack on :5173
+docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build -d
 ```
 
 ---