136 lines
7.0 KiB
Markdown
136 lines
7.0 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
|
|
This repository is currently a clean workspace with no application source tree checked in. Keep new code organized by responsibility:
|
|
|
|
- `src/` for application code and reusable modules.
|
|
- `tests/` for automated tests that mirror the `src/` layout.
|
|
- `assets/` for static images, fonts, fixtures, or other non-code resources.
|
|
- `docs/` for architecture notes, setup guides, and operational runbooks.
|
|
|
|
Prefer small, focused modules. Place shared helpers near the code that uses them first; promote them to a common module only when multiple features need them.
|
|
|
|
## Build, Test, and Development Commands
|
|
|
|
No build system or package manifest is currently present. When tooling is added, document the canonical commands in the README and keep them stable. Recommended command names:
|
|
|
|
- `npm run dev`, `pnpm dev`, or equivalent: start the local development server.
|
|
- `npm test`, `pnpm test`, or equivalent: run the full test suite.
|
|
- `npm run lint` / `npm run format`: check and format code style.
|
|
- `npm run build`: produce a production-ready build.
|
|
|
|
Avoid adding ad hoc scripts that only work on one machine. Prefer cross-platform commands or document platform-specific requirements clearly.
|
|
|
|
## Coding Style & Naming Conventions
|
|
|
|
Follow the formatter and linter configured by the first language/toolchain added to the project. Until then, use 2-space indentation for web projects, 4-space indentation for Python, and meaningful names over abbreviations.
|
|
|
|
Use clear file names that describe purpose, for example `user-service.ts`, `map-view.tsx`, or `test_user_service.py`. Keep public APIs explicit and avoid large catch-all utility files.
|
|
|
|
## Testing Guidelines
|
|
|
|
Add tests alongside each new feature or bug fix. Test files should mirror the implementation name, such as `user-service.test.ts` for `src/user-service.ts` or `test_user_service.py` for `src/user_service.py`.
|
|
|
|
Prefer fast unit tests for business logic and a smaller number of integration tests for workflows. Include regression tests for any fixed bug.
|
|
|
|
## Commit & Pull Request Guidelines
|
|
|
|
Git history is not available in this workspace, so use a simple imperative commit style: `Add project scaffold`, `Fix login validation`, `Update map assets`.
|
|
|
|
Pull requests should include a short summary, testing performed, linked issues when applicable, and screenshots or screen recordings for user-facing UI changes. Keep PRs focused; split unrelated changes into separate submissions.
|
|
|
|
## Security & Configuration Tips
|
|
|
|
Do not commit secrets, local credentials, generated build output, or machine-specific configuration. Store required environment variables in an ignored `.env` file and document safe example values in `.env.example`.
|
|
|
|
## Standard architektoniczny: routing (obowiązkowy)
|
|
|
|
Każdy nowy widok, ekran, zakładka lub podstrona **musi mieć własny, jednoznaczny adres URL** i być obsługiwana przez React Router. To twardy standard całego projektu, nie sugestia.
|
|
|
|
Zasady:
|
|
|
|
- **Nie buduj nawigacji na stanie.** Zakazane jako mechanizm przełączania stron: `useState('view')`, `setView`, `activeView`, `selectedPage`, `selectedTab` i pochodne.
|
|
- **Nie przełączaj całych stron warunkowym renderowaniem** bez zmiany adresu (`{view === 'x' && <Page />}`).
|
|
- **Do nawigacji używaj** `Link`, `NavLink`, `useNavigate` oraz tras zadeklarowanych w `Routes`.
|
|
- **Identyfikatory obiektów trzymaj w parametrach URL**: `/oferta/:id`, `/profil/:id`, `/wiadomosci/:conversationId` - nie w stanie Reacta.
|
|
- **Filtry, sortowanie, wyszukiwanie i paginację zapisuj w query string** wszędzie tam, gdzie użytkownik powinien móc skopiować lub odświeżyć widok.
|
|
- **Zakładki paneli twórz jako trasy zagnieżdżone**: `/konto/ustawienia`, `/admin/uzytkownicy`.
|
|
- **Trasy wymagające logowania zabezpieczaj `ProtectedRoute`** (`frontend/src/ProtectedRoute.tsx`). Pamiętaj, że to zabezpieczenie interfejsu - autoryzację egzekwuje backend.
|
|
- **Nie używaj `href="#"`** ani przycisków imitujących linki.
|
|
- **Każdy link musi działać** po odświeżeniu (F5), przy bezpośrednim wejściu z adresu, po użyciu Wstecz/Dalej i po otwarciu w nowej karcie.
|
|
|
|
Gdzie co leży:
|
|
|
|
- `frontend/src/routes.ts` - centralna mapa adresów (`ROUTES`) i helpery (`listingPath`, `mapPath`, `adminTabPath`). Nowy widok zaczynaj od wpisu tutaj, nie od literału ścieżki w JSX.
|
|
- `frontend/src/ProtectedRoute.tsx` - bramka autoryzacji, obsługuje stan `loading` z `AuthProvider`.
|
|
- `frontend/src/App.tsx` - deklaracja `<Routes>`.
|
|
- `nginx/default.conf` - `try_files $uri $uri/ /index.html` (SPA fallback, już skonfigurowany).
|
|
|
|
Przed zakończeniem każdego zadania sprawdź, czy dodane widoki mają trasy i czy adres zmienia się podczas nawigacji. Jeżeli istniejący kod łamie ten standard, nie powielaj starego rozwiązania - dostosuj go do React Routera.
|
|
|
|
## Behavioral Guidelines To Reduce Common LLM Coding Mistakes
|
|
|
|
Tradeoff: These guidelines bias toward caution over speed. For trivial tasks, use judgment.
|
|
|
|
### 1. Think Before Coding
|
|
|
|
Don't assume. Don't hide confusion. Surface tradeoffs.
|
|
|
|
Before implementing:
|
|
|
|
- State assumptions explicitly. If uncertain, ask.
|
|
- If multiple interpretations exist, present them instead of choosing silently.
|
|
- If a simpler approach exists, say so. Push back when warranted.
|
|
- If something is unclear, stop, name what is confusing, and ask.
|
|
|
|
### 2. Simplicity First
|
|
|
|
Minimum code that solves the problem. Nothing speculative.
|
|
|
|
- No features beyond what was asked.
|
|
- No abstractions for single-use code.
|
|
- No flexibility or configurability that was not requested.
|
|
- No error handling for impossible scenarios.
|
|
- If code is much longer than needed, rewrite it to be simpler.
|
|
|
|
Ask: Would a senior engineer say this is overcomplicated? If yes, simplify.
|
|
|
|
### 3. Surgical Changes
|
|
|
|
Touch only what you must. Clean up only your own mess.
|
|
|
|
When editing existing code:
|
|
|
|
- Do not improve adjacent code, comments, or formatting unless needed for the task.
|
|
- Do not refactor code that is not broken.
|
|
- Match existing style, even if you would do it differently.
|
|
- If unrelated dead code is noticed, mention it but do not delete it.
|
|
|
|
When changes create orphans:
|
|
|
|
- Remove imports, variables, or functions made unused by your own changes.
|
|
- Do not remove pre-existing dead code unless asked.
|
|
|
|
Test: Every changed line should trace directly to the request.
|
|
|
|
### 4. Goal-Driven Execution
|
|
|
|
Define success criteria. Loop until verified.
|
|
|
|
Transform tasks into verifiable goals:
|
|
|
|
- Add validation -> write tests for invalid inputs, then make them pass.
|
|
- Fix a bug -> write a test that reproduces it, then make it pass.
|
|
- Refactor X -> ensure tests pass before and after.
|
|
|
|
For multi-step tasks, state a brief plan:
|
|
|
|
1. [Step] -> verify: [check]
|
|
2. [Step] -> verify: [check]
|
|
3. [Step] -> verify: [check]
|
|
|
|
Strong success criteria enable independent execution. Weak criteria require frequent clarification.
|
|
|
|
These guidelines are working if there are fewer unnecessary diff changes, fewer rewrites caused by overcomplication, and clarifying questions appear before implementation mistakes.
|