Skip to content

Instantly share code, notes, and snippets.

@ali-aka-ahmed

ali-aka-ahmed/WORKFLOW.md

Created November 10, 2025 22:42
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save ali-aka-ahmed/81383a284b02b53d29765371c4b68110 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save ali-aka-ahmed/81383a284b02b53d29765371c4b68110 to your computer and use it in GitHub Desktop.
Download ZIP

Revisions

  1. ali-aka-ahmed created this gist Nov 10, 2025.
    55 changes: 55 additions & 0 deletions WORKFLOW.md
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,55 @@
    # WORKFLOW - READ BEFORE EVERY CODE CHANGE

    ## 🛑 STOP: Before Modifying ANY Code

    **Two-tier documentation system - Read BOTH types:**

    1. **Read folder-level docs (detailed architecture)**
    2. **Read function-level docs (concise: 1-3 sentences)**

    **Examples:**

    - Modifying `internal/api/router.go`?
    1. Read `docs/internal/api-docs.md` (folder-level: detailed)
    2. Read `docs/internal/api/router.md` (function-level: concise)

    - Adding `internal/api/handlers/user.go`?
    1. Read `docs/internal/api-docs.md` + `docs/internal/api/handlers-docs.md` (folder-level)
    2. Read existing handler docs in `docs/internal/api/handlers/` (function-level)

    ## 🛑 STOP: After Writing ANY Code

    **Run this ONE command (all must pass):**

    ```bash
    go build ./... && go test ./... && go test -race ./... && golangci-lint run ./...
    ```

    **If ANY command fails: FIX BEFORE PROCEEDING. NO EXCEPTIONS.**

    ## 🛑 STOP: Before Committing

    1. **All commands above passed?** ✅
    2. **Updated function-level docs in `docs/**/*.md`?** (concise: 1-3 sentences) ✅
    3. **Updated folder-level docs if architecture changed?** (detailed) ✅
    4. **All code files under 250 lines?** ✅

    ## Quick Reference

    **Two-Tier Documentation:**

    **Folder-Level (Detailed):**
    - `docs/internal/api-docs.md` → Architecture for `internal/api/`
    - `docs/internal/api/handlers-docs.md` → Architecture for `internal/api/handlers/`

    **Function-Level (Concise: 1-3 sentences):**
    - `cmd/api/main.go` → `docs/cmd/api/main.md`
    - `internal/api/router.go` → `docs/internal/api/router.md`
    - `internal/api/handlers/health.go` → `docs/internal/api/handlers/health.md`

    **250 Line Limit:**

    - If file exceeds 250 lines, split immediately
    - Update both doc types to reflect new structure

    **No Exceptions. No Shortcuts.**