111 lines
4.9 KiB
Markdown
111 lines
4.9 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`.
|
|
|
|
## 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.
|