diff --git a/AI_MEMORY.md b/ai-memory.md similarity index 99% rename from AI_MEMORY.md rename to ai-memory.md index 82798ac..76cac28 100644 --- a/AI_MEMORY.md +++ b/ai-memory.md @@ -1,4 +1,4 @@ -# AI_MEMORY.md +# ai-memory.md # ReplWorks Memory diff --git a/docs/ideas.md b/docs/ideas.md new file mode 100644 index 0000000..0aa4c55 --- /dev/null +++ b/docs/ideas.md @@ -0,0 +1,165 @@ +# ideas.md + +# ReplWorks Documents + +AI 에이전트 기반 개발을 위한 문서 템플릿 저장소 + +--- + +## 배경 + +최근 AI 코딩 도구들은 코드 생성 능력 자체는 충분히 발전했다. + +하지만 실제 프로젝트에서는 다음과 같은 문제들이 반복적으로 발생한다. + +- 잘못된 위치에 파일 생성 +- 새로운 폴더 구조 생성 +- 프로젝트 규칙을 무시한 코드 작성 +- 예상하지 못한 라이브러리 추가 +- 중복 기능 구현 +- 기존 아키텍처와 충돌하는 코드 생성 + +이러한 문제는 AI가 개발 기술을 몰라서 발생하는 것이 아니다. + +대부분 프로젝트별 규칙과 제약조건을 충분히 전달받지 못해서 발생한다. + +--- + +## 목표 + +이 저장소의 목적은 사람을 위한 문서가 아니다. + +AI가 프로젝트를 이해하고 일관된 방식으로 개발할 수 있도록 하는 문서 템플릿을 제공하는 것이다. + +프로젝트를 시작할 때 필요한 문서를 복사하여 사용함으로써 AI에게 동일한 품질의 컨텍스트를 제공할 수 있다. + +--- + +## 핵심 아이디어 + +AI는 일반적인 개발 지식보다 현재 프로젝트의 규칙을 더 필요로 한다. + +예를 들어 AI는 React를 알고 있다. + +하지만 다음과 같은 정보는 알지 못한다. + +- 이 프로젝트가 Zustand를 사용하는지 +- Redux를 금지하는지 +- 컴포넌트를 어디에 생성해야 하는지 +- 어떤 Import 규칙을 사용하는지 +- 어떤 폴더 구조를 유지해야 하는지 + +이 저장소는 이러한 규칙을 템플릿 형태로 제공한다. + +--- + +## 설계 원칙 + +### 1. AI First + +문서는 사람이 아니라 AI를 위해 작성한다. + +가독성보다 명확성을 우선한다. + +필요한 규칙은 중복되더라도 명시적으로 작성한다. + +--- + +### 2. Framework First + +프로젝트마다 사용하는 기술 스택은 다르다. + +따라서 프레임워크별 규칙을 별도 문서로 관리한다. + +예시: + +```text +frameworks/ + ├─ REACT_VITE.md + ├─ NEXTJS.md + ├─ LARAVEL.md + ├─ FASTAPI.md + └─ DJANGO.md +``` + +각 문서는 다음 내용을 포함한다. + +- 기술 스택 +- 폴더 구조 +- 네이밍 규칙 +- Import 규칙 +- 금지 사항 +- 개발 제약 조건 + +--- + +### 3. Template Based + +새 프로젝트 생성 시 필요한 문서를 복사하여 사용한다. + +프로젝트 특성에 맞게 수정할 수 있으며 원본 템플릿은 독립적으로 유지한다. + +--- + +### 4. 추측보다 규칙 + +AI는 추측하지 않는다. + +문서에 정의된 규칙을 따른다. + +규칙이 없는 경우에는 새로운 구조를 만들어내기보다 질문하거나 TODO를 남기는 것을 우선한다. + +--- + +## 기본 문서 구성 + +프로젝트에는 다음 문서 구성을 권장한다. + +```text +AGENTS.md +architecture.md +tasks.md +AI_MEMORY.md + +framework.md +``` + +### AGENTS.md + +AI 에이전트의 행동 규칙 + +### architecture.md + +시스템 구조 및 설계 + +### tasks.md + +현재 작업 목록 + +### AI_MEMORY.md + +제품 비전 및 장기 컨텍스트 + +### framework.md + +현재 프로젝트의 기술 스택 및 개발 규칙 + +--- + +## 기대 효과 + +이 저장소를 통해 다음을 기대한다. + +- AI의 파일 생성 오류 감소 +- 프로젝트 구조 일관성 유지 +- 불필요한 라이브러리 추가 방지 +- 아키텍처 위반 감소 +- 여러 AI 도구 간 동일한 개발 경험 제공 + +--- + +## 장기 비전 + +프로젝트마다 AI 사용 방식이 달라지는 것이 아니라, + +어떤 AI를 사용하더라도 동일한 문서 구조와 규칙을 통해 안정적으로 개발할 수 있는 표준 문서 체계를 만드는 것을 목표로 한다. diff --git a/frameworks/astro.md b/frameworks/astro.md new file mode 100644 index 0000000..e0fe749 --- /dev/null +++ b/frameworks/astro.md @@ -0,0 +1,302 @@ +# astro.md + +## STACK + +REQUIRED + +- Astro 6.x +- JavaScript + +OPTIONAL + +- TailwindCSS 4.x +- React 19.x +- MDX + +USE_DECLARED_STACK_ONLY + +DO_NOT_INTRODUCE_NEW_LIBRARIES_UNLESS_EXPLICITLY_REQUESTED + +--- + +## VERSION_POLICY + +PACKAGE_JSON_IS_SOURCE_OF_TRUTH + +FRAMEWORK_MD_IS_FALLBACK + +USE_DECLARED_VERSIONS_ONLY + +DO_NOT_ASSUME_LIBRARY_VERSIONS + +DO_NOT_ASSUME_ASTRO_VERSION + +DO_NOT_GENERATE_CODE_FOR_OTHER_VERSIONS + +WHEN_VERSION_CONFLICT_EXISTS + +FOLLOW_PACKAGE_JSON + +--- + +## PROJECT_STRUCTURE + +```text +src/ +├── components/ +├── layouts/ +├── pages/ +├── content/ +├── images/ +├── data/ +├── utils/ +└── styles/ + +public/ + +astro.config.mjs +content.config.ts +``` + +THIS_STRUCTURE_IS_AUTHORITATIVE + +DO_NOT_CREATE_NEW_TOP_LEVEL_DIRECTORIES + +PREFER_EXISTING_DIRECTORIES_OVER_NEW_ONES + +FOLLOW_EXISTING_STRUCTURE_BEFORE_CREATING_NEW_STRUCTURE + +--- + +## FILE_PLACEMENT + +pages -> src/pages + +layouts -> src/layouts + +components -> src/components + +content -> src/content + +images -> src/images + +data -> src/data + +utilities -> src/utils + +styles -> src/styles + +static_assets -> public + +content_configuration -> content.config.ts + +astro_configuration -> astro.config.mjs + +DO_NOT_CREATE_COMPONENTS_OUTSIDE_DEFINED_LOCATIONS + +--- + +## ROUTING_RULES + +USE_FILE_BASED_ROUTING + +ROUTES_BELONG_IN_SRC_PAGES + +DO_NOT_CREATE_CUSTOM_ROUTING_SYSTEM + +FOLLOW_ASTRO_ROUTING_CONVENTIONS + +--- + +## COMPONENT_RULES + +USE_ASTRO_COMPONENTS_BY_DEFAULT + +PREFER_ASTRO_OVER_REACT + +USE_REACT_ONLY_WHEN_REQUIRED + +ONE_COMPONENT_PER_FILE + +DO_NOT_EXPORT_MULTIPLE_COMPONENTS_FROM_SAME_FILE + +PREFER_SMALL_COMPOSABLE_COMPONENTS + +--- + +## CONTENT_RULES + +CONTENT_BELONGS_IN_SRC_CONTENT + +USE_CONTENT_COLLECTIONS + +CONTENT_CONFIG_IS_SOURCE_OF_TRUTH + +DO_NOT_STORE_CONTENT_IN_COMPONENTS + +DO_NOT_STORE_LARGE_CONTENT_BLOCKS_IN_PAGES + +SEPARATE_CONTENT_FROM_PRESENTATION + +--- + +## DATA_RULES + +STATIC_DATA_BELONGS_IN_SRC_DATA + +NAVIGATION_DATA_BELONGS_IN_SRC_DATA + +FAQ_DATA_BELONGS_IN_SRC_DATA + +CONFIGURATION_DATA_BELONGS_IN_SRC_DATA + +DO_NOT_STORE_DATA_IN_COMPONENTS + +SEPARATE_DATA_FROM_PRESENTATION + +--- + +## IMAGE_RULES + +PROJECT_IMAGES_BELONG_IN_SRC_IMAGES + +PUBLIC_ASSETS_BELONG_IN_PUBLIC + +USE_ASTRO_IMAGE_OPTIMIZATION_WHEN_AVAILABLE + +DO_NOT_STORE_IMAGES_IN_COMPONENT_DIRECTORIES + +--- + +## STYLING_RULES + +USE_PROJECT_DEFINED_STYLING_SOLUTION + +IF_TAILWIND_IS_INSTALLED + +USE_TAILWINDCSS_ONLY + +DO_NOT_MIX_MULTIPLE_STYLING_APPROACHES + +PREFER_GLOBAL_STYLES_IN_SRC_STYLES + +--- + +## PERFORMANCE_RULES + +PREFER_STATIC_GENERATION + +MINIMIZE_CLIENT_SIDE_JAVASCRIPT + +MINIMIZE_HYDRATION + +LOAD_ONLY_REQUIRED_CLIENT_CODE + +AVOID_UNNECESSARY_REACT_COMPONENTS + +--- + +## ISLAND_RULES + +USE_ISLANDS_ARCHITECTURE + +DEFAULT_TO_SERVER_RENDERED_CONTENT + +HYDRATE_ONLY_WHEN_NECESSARY + +DO_NOT_HYDRATE_STATIC_CONTENT + +USE_CLIENT_DIRECTIVES_ONLY_WHEN_REQUIRED + +--- + +## NAMING_RULES + +COMPONENT_FILES -> PascalCase + +LAYOUT_FILES -> PascalCase + +UTILITY_FILES -> camelCase + +DATA_FILES -> camelCase + +CONTENT_FILES -> kebab-case + +IMAGE_FILES -> kebab-case + +EXAMPLES + +- Header.astro + +- HeroSection.astro + +- PostLayout.astro + +- navigationData.js + +- faqData.js + +- getting-started.md + +- first-blog-post.md + +--- + +## ROOT_DIRECTORY_POLICY + +DO_NOT_CREATE_FILES_IN_REPOSITORY_ROOT + +UNLESS_REQUIRED_BY_ASTRO + +ALLOWED_ROOT_FILES + +- astro.config.mjs +- content.config.ts +- package.json +- README.md +- tsconfig.json + +--- + +## GENERATION_POLICY + +BEFORE_CREATING_ANY_FILE + +1. CHECK_EXISTING_STRUCTURE +2. CHECK_EXISTING_COMPONENTS +3. CHECK_EXISTING_CONTENT +4. CHECK_EXISTING_DATA +5. CHECK_EXISTING_PATTERNS +6. REUSE_BEFORE_CREATING + +PREFER_MODIFICATION_OVER_NEW_FILES + +PREFER_EXISTING_PATTERNS_OVER_NEW_PATTERNS + +DO_NOT_INVENT_NEW_ARCHITECTURE + +DO_NOT_DUPLICATE_EXISTING_FUNCTIONALITY + +WHEN_UNCERTAIN + +FOLLOW_EXISTING_CODEBASE + +PACKAGE_JSON_OVERRIDES_VERSION_ASSUMPTIONS + +DO_NOT_GUESS + +--- + +## ASTRO_PRINCIPLES + +STATIC_FIRST + +CONTENT_FIRST + +SERVER_FIRST + +USE_ISLANDS_ARCHITECTURE + +MINIMIZE_JAVASCRIPT + +HYDRATE_ONLY_WHEN_NECESSARY diff --git a/frameworks/fastapi.md b/frameworks/fastapi.md new file mode 100644 index 0000000..bc098af --- /dev/null +++ b/frameworks/fastapi.md @@ -0,0 +1,259 @@ +# fastapi.md + +## STACK + +REQUIRED + +- Python 3.13+ +- FastAPI +- Pydantic 2.x +- Uvicorn + +OPTIONAL + +- SQLAlchemy +- Alembic +- PostgreSQL + +USE_DECLARED_STACK_ONLY + +DO_NOT_INTRODUCE_NEW_LIBRARIES_UNLESS_EXPLICITLY_REQUESTED + +--- + +## VERSION_POLICY + +PYPROJECT_TOML_IS_SOURCE_OF_TRUTH + +REQUIREMENTS_TXT_IS_FALLBACK + +USE_DECLARED_VERSIONS_ONLY + +DO_NOT_ASSUME_LIBRARY_VERSIONS + +DO_NOT_GENERATE_DEPRECATED_PATTERNS + +WHEN_VERSION_CONFLICT_EXISTS + +FOLLOW_PROJECT_CONFIGURATION + +--- + +## PROJECT_STRUCTURE + +```text +app/ +├── api/ +├── schemas/ +├── dependencies/ +├── core/ +└── main.py + +tests/ + +pyproject.toml +``` + +THIS_STRUCTURE_IS_AUTHORITATIVE + +DO_NOT_CREATE_SRC_DIRECTORY + +DO_NOT_CREATE_SERVICES_DIRECTORY + +DO_NOT_CREATE_REPOSITORIES_DIRECTORY + +DO_NOT_CREATE_CONTROLLERS_DIRECTORY + +DO_NOT_CREATE_ADDITIONAL_TOP_LEVEL_DIRECTORIES + +PREFER_EXISTING_DIRECTORIES_OVER_NEW_ONES + +--- + +## FILE_PLACEMENT + +api_routes -> app/api + +request_schemas -> app/schemas + +response_schemas -> app/schemas + +shared_dependencies -> app/dependencies + +application_configuration -> app/core + +application_entry -> app/main.py + +tests -> tests + +--- + +## API_RULES + +USE_APIRouter + +GROUP_RELATED_ENDPOINTS + +KEEP_ROUTE_MODULES_SMALL + +KEEP_ENDPOINTS_FOCUSED + +FOLLOW_FASTAPI_CONVENTIONS + +ROUTES_BELONG_IN_APP_API + +--- + +## SCHEMA_RULES + +USE_PYDANTIC_MODELS + +REQUEST_MODELS_ARE_REQUIRED + +RESPONSE_MODELS_ARE_REQUIRED + +SEPARATE_REQUEST_AND_RESPONSE_MODELS_WHEN_NEEDED + +DO_NOT_USE_RAW_DICTIONARIES_FOR_PUBLIC_APIS + +--- + +## DEPENDENCY_RULES + +USE_FASTAPI_DEPENDENCY_INJECTION + +SHARED_DEPENDENCIES_BELONG_IN_APP_DEPENDENCIES + +AVOID_GLOBAL_STATE + +PREFER_EXPLICIT_DEPENDENCIES + +--- + +## CONFIGURATION_RULES + +APPLICATION_CONFIGURATION_BELONGS_IN_APP_CORE + +USE_ENVIRONMENT_VARIABLES_FOR_CONFIGURATION + +DO_NOT_HARDCODE_SECRETS + +DO_NOT_HARDCODE_CREDENTIALS + +DO_NOT_HARDCODE_API_KEYS + +--- + +## DATABASE_RULES + +DATABASE_INTEGRATION_IS_OPTIONAL + +DO_NOT_ASSUME_DATABASE_USAGE + +DO_NOT_ASSUME_DATABASE_ENGINE + +FOLLOW_DECLARED_PROJECT_DEPENDENCIES + +--- + +## TESTING_RULES + +TESTS_BELONG_IN_TESTS_DIRECTORY + +USE_PYTEST + +TEST_API_ENDPOINTS + +TEST_CORE_BUSINESS_BEHAVIOR + +--- + +## ARCHITECTURE_RULES + +DO_NOT_CREATE_SERVICES_DIRECTORY + +DO_NOT_CREATE_REPOSITORIES_DIRECTORY + +DO_NOT_CREATE_CUSTOM_ARCHITECTURE + +DO_NOT_INTRODUCE_PATTERNS_NOT_DEFINED_IN_ARCHITECTURE_MD + +DO_NOT_CREATE_ABSTRACTIONS_WITHOUT_JUSTIFICATION + +PREFER_SIMPLE_OVER_COMPLEX + +--- + +## FORBIDDEN_DIRECTORIES + +- src +- services +- repositories +- controllers + +DO_NOT_CREATE_FORBIDDEN_DIRECTORIES + +UNLESS_EXPLICITLY_REQUESTED + +--- + +## ROOT_DIRECTORY_POLICY + +ALLOWED_ROOT_DIRECTORIES + +- app +- tests + +ALLOWED_ROOT_FILES + +- pyproject.toml +- README.md +- .env.example + +DO_NOT_CREATE_UNDEFINED_ROOT_DIRECTORIES + +--- + +## GENERATION_POLICY + +BEFORE_CREATING_ANY_FILE + +1. CHECK_EXISTING_STRUCTURE +2. CHECK_EXISTING_PATTERNS +3. REUSE_BEFORE_CREATING + +PREFER_MODIFICATION_OVER_CREATION + +DO_NOT_INVENT_ARCHITECTURE + +DO_NOT_DUPLICATE_EXISTING_FUNCTIONALITY + +PYPROJECT_TOML_OVERRIDES_VERSION_ASSUMPTIONS + +WHEN_UNCERTAIN + +FOLLOW_EXISTING_CODEBASE + +DO_NOT_GUESS + +--- + +## FASTAPI_PRINCIPLES + +LATEST_STABLE_ONLY + +NEW_PROJECTS_ONLY + +API_FIRST + +MINIMAL_STRUCTURE + +SCHEMAS_ARE_REQUIRED + +DEPENDENCY_INJECTION_OVER_GLOBAL_STATE + +NO_ARCHITECTURAL_GUESSING + +REUSE_BEFORE_CREATING + +KEEP_IT_SIMPLE diff --git a/frameworks/nextjs.md b/frameworks/nextjs.md new file mode 100644 index 0000000..11c6a48 --- /dev/null +++ b/frameworks/nextjs.md @@ -0,0 +1,329 @@ +# nextjs.md + +## STACK + +REQUIRED + +- Next.js 16.x +- React 19.x +- JavaScript + +OPTIONAL + +- TailwindCSS 4.x +- TypeScript +- next-intl + +USE_DECLARED_STACK_ONLY + +DO_NOT_INTRODUCE_NEW_LIBRARIES_UNLESS_EXPLICITLY_REQUESTED + +--- + +## VERSION_POLICY + +PACKAGE_JSON_IS_SOURCE_OF_TRUTH + +FRAMEWORK_MD_IS_FALLBACK + +USE_DECLARED_VERSIONS_ONLY + +DO_NOT_ASSUME_LIBRARY_VERSIONS + +DO_NOT_ASSUME_NEXTJS_VERSION + +DO_NOT_GENERATE_DEPRECATED_PATTERNS + +WHEN_VERSION_CONFLICT_EXISTS + +FOLLOW_PACKAGE_JSON + +--- + +## PROJECT_STRUCTURE + +```text +app/ + +components/ +├── layout/ +├── sections/ +└── ui/ + +data/ +hooks/ +utils/ +styles/ +images/ + +public/ + +next.config.mjs +``` + +THIS_STRUCTURE_IS_AUTHORITATIVE + +DO_NOT_CREATE_SRC_DIRECTORY + +DO_NOT_CREATE_SRC_APP + +DO_NOT_CREATE_NEW_TOP_LEVEL_DIRECTORIES + +PREFER_EXISTING_DIRECTORIES_OVER_NEW_ONES + +--- + +## FILE_PLACEMENT + +routes -> app + +layout_components -> components/layout + +section_components -> components/sections + +reusable_ui_components -> components/ui + +static_content -> data + +navigation_data -> data + +custom_hooks -> hooks + +utility_functions -> utils + +global_styles -> styles + +project_images -> images + +public_assets -> public + +--- + +## ROUTING_RULES + +USE_APP_ROUTER_ONLY + +APP_ROUTER_IS_ROOT_LEVEL + +DO_NOT_USE_PAGES_ROUTER + +DO_NOT_CREATE_PAGES_DIRECTORY + +FOLLOW_NEXTJS_FILE_CONVENTIONS + +USE_ROUTE_GROUPS_WHEN_APPROPRIATE + +USE_PRIVATE_FOLDERS_FOR_ROUTE_SPECIFIC_CODE + +PRIVATE_FOLDERS_START_WITH_UNDERSCORE + +--- + +## COLOCATION_RULES + +ALLOW_ROUTE_LOCAL_COMPONENTS + +ALLOW_ROUTE_LOCAL_UTILITIES + +ALLOW_ROUTE_LOCAL_DATA + +USE_PRIVATE_FOLDERS_FOR_ROUTE_SPECIFIC_FILES + +PREFER_ROUTE_LOCAL_CODE_WHEN_NOT_SHARED + +USE_SHARED_DIRECTORIES_ONLY_FOR_REUSABLE_CODE + +--- + +## COMPONENT_RULES + +USE_SERVER_COMPONENTS_BY_DEFAULT + +ADD_USE_CLIENT_ONLY_WHEN_REQUIRED + +MINIMIZE_CLIENT_COMPONENTS + +PREFER_SERVER_RENDERING + +ONE_COMPONENT_PER_FILE + +DO_NOT_EXPORT_MULTIPLE_COMPONENTS_FROM_SAME_FILE + +PREFER_SMALL_COMPOSABLE_COMPONENTS + +--- + +## DATA_FETCHING_RULES + +FETCH_DATA_IN_SERVER_COMPONENTS_WHEN_POSSIBLE + +PREFER_ASYNC_SERVER_COMPONENTS + +AVOID_CLIENT_SIDE_FETCHING_UNLESS_REQUIRED + +DO_NOT_MOVE_SERVER_FETCHING_TO_CLIENT_COMPONENTS + +--- + +## API_RULES + +API_ROUTES_BELONG_IN_APP_API + +USE_ROUTE_HANDLERS + +FOLLOW_NEXTJS_API_CONVENTIONS + +DO_NOT_CREATE_CUSTOM_API_ARCHITECTURE + +--- + +## IMAGE_RULES + +USE_NEXT_IMAGE_WHEN_POSSIBLE + +PROJECT_IMAGES_BELONG_IN_IMAGES + +PUBLIC_ASSETS_BELONG_IN_PUBLIC + +OPTIMIZE_IMAGES + +--- + +## STYLING_RULES + +USE_PROJECT_DEFINED_STYLING_SOLUTION + +IF_TAILWIND_IS_INSTALLED + +USE_TAILWINDCSS_ONLY + +DO_NOT_MIX_MULTIPLE_STYLING_APPROACHES + +--- + +## RESPONSIVE_RULES + +MOBILE_FIRST + +RESPONSIVENESS_IS_REQUIRED + +REQUIRE_RESPONSIVE_LAYOUTS + +REQUIRE_RESPONSIVE_TYPOGRAPHY + +REQUIRE_RESPONSIVE_IMAGES + +REQUIRE_FLEXIBLE_LAYOUTS + +AVOID_FIXED_WIDTH_LAYOUTS + +AVOID_HORIZONTAL_SCROLLING + +--- + +## ACCESSIBILITY_RULES + +ACCESSIBILITY_IS_REQUIRED + +REQUIRE_PROPER_HEADING_HIERARCHY + +REQUIRE_ALT_TEXT + +REQUIRE_KEYBOARD_ACCESSIBILITY + +REQUIRE_SUFFICIENT_COLOR_CONTRAST + +ACCESSIBILITY_OVERRIDES_VISUAL_PREFERENCES + +--- + +## FORBIDDEN_DIRECTORIES + +- pages +- src +- features +- shared +- widgets +- modules +- views + +DO_NOT_CREATE_FORBIDDEN_DIRECTORIES + +UNLESS_EXPLICITLY_REQUESTED + +--- + +## ROOT_DIRECTORY_POLICY + +ALLOWED_ROOT_DIRECTORIES + +- app +- components +- data +- hooks +- utils +- styles +- images +- public + +ALLOWED_ROOT_FILES + +- package.json +- next.config.js +- next.config.mjs +- README.md +- jsconfig.json +- tsconfig.json + +DO_NOT_CREATE_UNDEFINED_ROOT_DIRECTORIES + +--- + +## GENERATION_POLICY + +BEFORE_CREATING_ANY_FILE + +1. CHECK_EXISTING_STRUCTURE +2. CHECK_EXISTING_COMPONENTS +3. CHECK_EXISTING_PATTERNS +4. REUSE_BEFORE_CREATING + +PREFER_MODIFICATION_OVER_CREATION + +PREFER_EXISTING_PATTERNS_OVER_NEW_PATTERNS + +DO_NOT_INVENT_NEW_ARCHITECTURE + +DO_NOT_DUPLICATE_EXISTING_FUNCTIONALITY + +PACKAGE_JSON_OVERRIDES_VERSION_ASSUMPTIONS + +WHEN_UNCERTAIN + +FOLLOW_EXISTING_CODEBASE + +DO_NOT_GUESS + +--- + +## NEXTJS_PRINCIPLES + +LATEST_STABLE_ONLY + +NEW_PROJECTS_ONLY + +APP_ROUTER_ONLY + +SERVER_FIRST + +SERVER_COMPONENTS_BY_DEFAULT + +MINIMIZE_USE_CLIENT + +MINIMIZE_CLIENT_SIDE_JAVASCRIPT + +RESPONSIVE_BY_DEFAULT + +ACCESSIBLE_BY_DEFAULT + +REUSE_BEFORE_CREATING diff --git a/frameworks/vanilla.md b/frameworks/vanilla.md new file mode 100644 index 0000000..dd65051 --- /dev/null +++ b/frameworks/vanilla.md @@ -0,0 +1,261 @@ +# vanilla.md + +## STACK + +REQUIRED + +- HTML5 +- CSS3 +- JavaScript ES2024 + +USE_DECLARED_STACK_ONLY + +DO_NOT_INTRODUCE_FRAMEWORKS + +DO_NOT_INTRODUCE_BUILD_TOOLS + +DO_NOT_INTRODUCE_PACKAGE_MANAGERS + +--- + +## PROJECT_STRUCTURE + +```text +/ +├── index.html +├── css/ +│ └── styles.css +├── js/ +│ └── main.js +├── images/ +└── assets/ +``` + +THIS_STRUCTURE_IS_AUTHORITATIVE + +DO_NOT_CREATE_ADDITIONAL_TOP_LEVEL_DIRECTORIES + +PREFER_EXISTING_DIRECTORIES_OVER_NEW_ONES + +--- + +## FILE_PLACEMENT + +html_pages -> repository_root + +stylesheets -> css + +javascript -> js + +images -> images + +static_assets -> assets + +DO_NOT_CREATE_SRC_DIRECTORY + +DO_NOT_CREATE_COMPONENT_DIRECTORIES + +DO_NOT_CREATE_BUILD_DIRECTORIES + +--- + +## HTML_RULES + +USE_SEMANTIC_HTML + +PREFER_NATIVE_HTML_ELEMENTS + +USE_PROPER_HEADING_HIERARCHY + +REQUIRE_ALT_TEXT_FOR_IMAGES + +AVOID_UNNECESSARY_DIV_ELEMENTS + +--- + +## CSS_RULES + +USE_PLAIN_CSS + +STORE_GLOBAL_STYLES_IN_CSS_STYLES_CSS + +DO_NOT_USE_SCSS + +DO_NOT_USE_SASS + +DO_NOT_USE_LESS + +DO_NOT_USE_CSS_MODULES + +DO_NOT_USE_CSS_IN_JS + +DO_NOT_INTRODUCE_STYLING_FRAMEWORKS + +--- + +## JAVASCRIPT_RULES + +USE_VANILLA_JAVASCRIPT + +USE_ES_MODULES_WHEN_NEEDED + +PREFER_MODERN_BROWSER_APIS + +DO_NOT_USE_JQUERY + +DO_NOT_USE_REACT + +DO_NOT_USE_VUE + +DO_NOT_USE_ANGULAR + +DO_NOT_USE_SVELTE + +DO_NOT_USE_ALPINE + +DO_NOT_USE_HTMX + +--- + +## ASSET_RULES + +IMAGES_BELONG_IN_IMAGES + +FONTS_BELONG_IN_ASSETS + +ICONS_BELONG_IN_ASSETS + +DOWNLOADABLE_FILES_BELONG_IN_ASSETS + +DO_NOT_STORE_ASSETS_IN_CSS_OR_JS_DIRECTORIES + +--- + +## RESPONSIVE_RULES + +MOBILE_FIRST + +RESPONSIVENESS_IS_REQUIRED + +REQUIRE_RESPONSIVE_LAYOUTS + +REQUIRE_RESPONSIVE_TYPOGRAPHY + +REQUIRE_RESPONSIVE_IMAGES + +REQUIRE_FLEXIBLE_LAYOUTS + +AVOID_FIXED_WIDTH_LAYOUTS + +AVOID_HORIZONTAL_SCROLLING + +TEST_COMMON_VIEWPORT_SIZES + +RESPONSIVE_BEHAVIOR_OVERRIDES_DESKTOP_PREFERENCES + +--- + +## ACCESSIBILITY_RULES + +ACCESSIBILITY_IS_REQUIRED + +REQUIRE_PROPER_HEADING_HIERARCHY + +REQUIRE_ALT_TEXT + +REQUIRE_KEYBOARD_ACCESSIBILITY + +REQUIRE_SUFFICIENT_COLOR_CONTRAST + +ACCESSIBILITY_OVERRIDES_VISUAL_PREFERENCES + +--- + +## PERFORMANCE_RULES + +MINIMIZE_JAVASCRIPT + +MINIMIZE_DEPENDENCIES + +OPTIMIZE_IMAGES + +PREFER_NATIVE_BROWSER_FEATURES + +AVOID_UNNECESSARY_ABSTRACTIONS + +--- + +## FORBIDDEN_TOOLS + +- React +- Vue +- Angular +- Svelte +- Next.js +- Nuxt +- Astro +- Vite +- Webpack +- Parcel +- Rollup +- jQuery + +DO_NOT_INTRODUCE_FORBIDDEN_TOOLS + +UNLESS_EXPLICITLY_REQUESTED + +--- + +## ROOT_DIRECTORY_POLICY + +ROOT_HTML_FILES_ARE_ALLOWED + +DO_NOT_CREATE_CONFIGURATION_FILES + +DO_NOT_CREATE_PACKAGE_JSON + +DO_NOT_CREATE_NODE_MODULES + +DO_NOT_CREATE_BUILD_CONFIGURATIONS + +--- + +## GENERATION_POLICY + +BEFORE_CREATING_ANY_FILE + +1. CHECK_EXISTING_STRUCTURE +2. CHECK_EXISTING_PATTERNS +3. REUSE_BEFORE_CREATING + +PREFER_MODIFICATION_OVER_CREATION + +DO_NOT_INVENT_ARCHITECTURE + +DO_NOT_INTRODUCE_FRAMEWORKS + +WHEN_UNCERTAIN + +FOLLOW_EXISTING_CODEBASE + +--- + +## VANILLA_PRINCIPLES + +HTML_FIRST + +CSS_SECOND + +JAVASCRIPT_WHEN_NEEDED + +USE_NATIVE_BROWSER_FEATURES + +MOBILE_FIRST + +RESPONSIVE_BY_DEFAULT + +KEEP_IT_SIMPLE + +AVOID_DEPENDENCIES + +DO_NOT_INTRODUCE_FRAMEWORKS