Selamat datang di tutorial komprehensif untuk pemula! Tutorial ini akan memandu Anda secara mendalam dalam menggunakan Gemini CLI dan Spec-Kit, dua alat revolusioner yang akan mengubah cara Anda membangun perangkat lunak.
Sebelum kita menyelami Spec-Kit, mari kita berkenalan terlebih dahulu dengan Gemini CLI, fondasi yang akan kita gunakan.
Gemini CLI adalah alat bantu alur kerja AI berbasis baris perintah yang canggih. Anggap saja ini sebagai asisten pengkodean pribadi Anda yang berada langsung di terminal Anda. Gemini CLI dapat terhubung ke berbagai alat, memahami basis kode Anda, dan mempercepat alur kerja pengembangan Anda secara signifikan. Beberapa kemampuannya antara lain:
Sebelum menginstal Gemini CLI, pastikan sistem Anda memenuhi persyaratan berikut:
Ada beberapa cara untuk menginstal dan menjalankan Gemini CLI. Metode yang disarankan adalah instalasi standar menggunakan npm (Node Package Manager).
Instalasi Global (Disarankan):
Dengan instalasi global, Anda dapat menjalankan perintah gemini dari direktori mana pun di sistem Anda.
npm install -g @google/gemini-cli
Penggunaan Tanpa Instalasi (via NPX):
Jika Anda hanya ingin mencoba Gemini CLI tanpa menginstalnya secara permanen, Anda bisa menggunakan npx.
npx @google/gemini-cli
Instalasi via Homebrew (macOS dan Linux):
brew install gemini-cli
Setelah terinstal, cukup jalankan perintah berikut di terminal Anda untuk memulai sesi Gemini CLI:
gemini
Anda sekarang siap untuk berinteraksi dengan asisten AI Anda!
Setelah Anda nyaman menggunakan Gemini CLI, saatnya untuk naik ke level berikutnya dengan Spec-Kit dan Spec-Driven Development (SDD).
Dalam pengembangan perangkat lunak tradisional, seringkali terjadi kesenjangan antara apa yang diinginkan oleh pemangku kepentingan (seperti manajer produk) dan apa yang dibuat oleh para pengembang. Kesenjangan ini dapat menyebabkan pengerjaan ulang yang mahal, keterlambatan proyek, dan produk akhir yang tidak memenuhi harapan.
Spec-Kit hadir untuk menjembatani kesenjangan ini. Dengan menggunakan Spec-Kit, Anda memulai proses pengembangan dengan membuat spesifikasi yang jelas dan dapat dieksekusi. Spesifikasi ini menjadi "sumber kebenaran" tunggal yang dipahami oleh semua orang yang terlibat dalam proyek.
Mengadopsi Spec-Kit dan pendekatan SDD memberikan banyak keuntungan, antara lain:
Sebelum memulai dengan Spec-Kit, pastikan Anda telah menginstal:
uv untuk manajemen paket.Untuk menggunakan Spec-Kit, Anda perlu menginstal Specify CLI.
Instalasi Persisten (Disarankan):
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
Setelah instalasi, Anda bisa menginisialisasi proyek baru:
specify init <NAMA_PROYEK>
Atau di proyek yang sudah ada:
specify init . --ai gemini
Untuk memperbarui, gunakan perintah:
uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git
Berikut adalah alur kerja khas menggunakan Spec-Kit di dalam sesi Gemini CLI Anda.
Di terminal Anda, jalankan perintah specify CLI untuk menginisialisasi proyek Anda. Perintah ini akan membuat struktur direktori dasar dan file konfigurasi yang diperlukan.
"Konstitusi" adalah seperangkat aturan dan prinsip tingkat tinggi yang akan memandu pengembangan proyek Anda. Gunakan perintah /speckit.constitution di dalam sesi Gemini CLI Anda untuk menentukannya. Ini memastikan bahwa semua kode yang dihasilkan akan mematuhi standar yang telah Anda tetapkan.
Contoh Penggunaan Konstitusi:
/speckit.constitution 1. **Fokus pada Pengguna (User-Centric):** Setiap fitur harus memberikan nilai yang jelas kepada pengguna akhir. 2. **Modularitas:** Kode harus diorganisir ke dalam modul-modul yang independen dan dapat digunakan kembali. 3. **Kualitas Kode Tinggi:** Menerapkan standar linting, format, dan pengujian otomatis yang ketat. 4. **Keamanan Utama:** Mengutamakan praktik keamanan terbaik dalam setiap lapisan aplikasi. 5. **Performa Optimal:** Membangun aplikasi yang responsif dan efisien.
Dengan konstitusi ini, Anda memberikan pedoman yang jelas kepada agen AI tentang bagaimana proyek Anda harus dikembangkan, membantu menjaga konsistensi dan kualitas.
Ini adalah inti dari proses SDD. Gunakan perintah /speckit.specify di dalam Gemini CLI untuk menjelaskan apa yang ingin Anda bangun dan mengapa. Hindari detail teknis dan fokus pada kebutuhan pengguna.
Contoh yang Lebih Komprehensif:
/speckit.specify Sebagai seorang fotografer profesional, saya ingin membuat sebuah galeri online untuk memamerkan karya-karya saya. **Fitur Utama:** 1. **Halaman Beranda:** Menampilkan koleksi foto unggulan dalam tata letak masonry yang responsif. 2. **Halaman Album:** Pengguna dapat melihat foto berdasarkan album. Setiap album memiliki judul, deskripsi, dan tanggal pembuatan. 3. **Halaman Detail Foto:** Ketika sebuah foto diklik, foto akan terbuka dalam mode layar penuh (lightbox) dengan informasi EXIF (kamera, lensa, shutter speed, dll.) yang ditampilkan. 4. **Halaman Kontak:** Formulir kontak sederhana agar calon klien dapat menghubungi saya. **Tujuan Bisnis:** * Meningkatkan visibilitas online saya. * Menghasilkan prospek klien baru. * Menyediakan platform yang elegan dan profesional untuk menampilkan portofolio saya.
Setelah spesifikasi fungsional disetujui, saatnya untuk merencanakan implementasi teknisnya. Di dalam Gemini CLI, gunakan perintah /speckit.plan untuk menguraikan tumpukan teknologi (misalnya, React, Next.js, Tailwind CSS), arsitektur (misalnya, monolitik, layanan mikro), dan keputusan teknis penting lainnya.
/speckit.plan
Setelah rencana dibuat, gunakan perintah /speckit.tasks untuk secara otomatis memecah rencana tersebut menjadi daftar tugas yang dapat ditindaklanjuti. Perintah ini akan menganalisis plan.md dan dokumen terkait lainnya untuk membuat file tasks.md.
/speckit.tasks
File tasks.md ini akan berisi daftar tugas yang terperinci, lengkap dengan ID tugas, potensi untuk paralelisasi, dan keterkaitan dengan user story tertentu.
Sekarang saatnya untuk mengubah rencana menjadi kode nyata. Gunakan perintah /speckit.implement untuk menjalankan rencana implementasi Anda.
/speckit.implement
Perintah ini secara cerdas akan:
tasks.md dan urutan pengerjaannya.Pastikan semua alat bantu CLI yang diperlukan oleh rencana Anda (misalnya, npm, django-admin) sudah terinstal di sistem Anda.
Setelah /speckit.implement selesai, aplikasi Anda seharusnya sudah terbangun. Namun, pekerjaan belum selesai. Anda perlu menguji aplikasi secara manual untuk menemukan runtime errors (kesalahan saat runtime) yang mungkin tidak terlihat dalam log CLI.
Jika Anda menemukan bug atau ingin menambahkan fitur, Anda dapat mengulangi siklus ini: perbarui spesifikasi Anda (/speckit.specify), regenerasi rencana (/speckit.plan), dan implementasikan lagi (/speckit.implement). Ini adalah proses iteratif yang memungkinkan Anda untuk terus menyempurnakan produk Anda.
Gemini CLI dan Spec-Kit adalah duo yang kuat. Gemini CLI menyediakan platform interaktif berbasis AI, sementara Spec-Kit memberikan kerangka kerja terstruktur untuk mengubah ide menjadi perangkat lunak yang berfungsi. Dengan menguasai kedua alat ini, Anda tidak hanya akan menjadi pengembang yang lebih cepat, tetapi juga arsitek perangkat lunak yang lebih efektif.
Selamat datang di masa depan pengembangan perangkat lunak!
Sekarang saatnya untuk mempraktikkan semua yang telah Anda pelajari dalam sebuah skenario kolaboratif. Dalam latihan ini, kita akan membangun sebuah aplikasi Skor Padel sederhana. Proyek ini akan dibagi menjadi beberapa bagian, di mana setiap orang atau tim dapat mengerjakan satu bagian secara paralel.
Kita akan membangun sebuah Aplikasi Skor Padel sederhana. Setiap tim akan mengambil satu bagian dari spesifikasi di bawah ini dan menjalankannya di dalam sesi Gemini CLI mereka sendiri.
git clone https://github.com/iboen/padel-scoring.git
copy-paste) hanya bagian spesifikasi Anda ke dalam perintah /speckit.specify./speckit.plan, /speckit.tasks, dan /speckit.implement seperti yang telah dipelajari.Di bawah ini adalah spesifikasi lengkapnya. Ingat, setiap tim hanya menyalin bagian yang relevan untuk mereka.
Lakukan secara berurutan sesuai tutorial yang telah dipelajari:
/speckit.specify ..... /speckit.plan /speckit.tasks /speckit.implement
/speckit.specify
# User Story: New User Signup
As a new user, I want to be able to sign up for an account using my email and a password, so that I can start using the Padel Scoring Website to score my matches and track my performance.
## Acceptance Criteria
1. **Given** I am on the Signup page, **when** I fill in my name, email, password, and confirm my password, and all the information is valid, **then** my account should be created successfully.
2. **Given** I have successfully signed up, **then** I should be automatically logged in and redirected to my profile page.
3. **Given** I am on the Signup page, **when** I enter an email that is already registered, **then** I should see an error message indicating that the email is already in use.
4. **Given** I am on the Signup page, **when** I enter a password that does not meet the security requirements, **then** I should see an error message specifying the password policy.
5. **Given** I am on the Signup page, **when** my "confirm password" does not match my password, **then** I should see an error message.
6. **Given** I am on the Signup page, **when** I leave any of the required fields empty, **then** the signup button should be disabled, and I should be prompted to fill in all the required fields.
## UI and Functionality
* The signup form should have the following fields:
* Name (text input)
* Email (email input)
* Password (password input)
* Confirm Password (password input)
* The password field should have a "show/hide" option.
* The password must be at least 8 characters long and contain at least one uppercase letter, one lowercase letter, one number, and one special character.
* The signup button should be disabled until all fields are filled out correctly.
* There should be a link to the Login page for users who already have an account.
## Error Handling
* Display clear and user-friendly error messages for invalid input.
* If the server returns an error during signup, display a generic error message to the user.
/speckit.specify
# User Story: User Login
As an existing user, I want to be able to log in to my account using my email and password, so that I can access my profile, view my match history, and score new matches.
## Acceptance Criteria
1. **Given** I am on the Login page, **when** I enter my correct email and password, **then** I should be logged in successfully.
2. **Given** I have successfully logged in, **then** I should be redirected to my profile page or the main dashboard.
3. **Given** I am on the Login page, **when** I enter an incorrect email or password, **then** I should see an error message indicating that the login credentials are invalid.
4. **Given** I am on the Login page, **when** I leave the email or password field empty, **then** the login button should be disabled, and I should be prompted to fill in both fields.
5. **Given** I have forgotten my password, **when** I click on the "Forgot Password" link, **then** I should be taken to a page where I can reset my password.
## UI and Functionality
* The login form should have the following fields:
* Email (email input)
* Password (password input)
* The password field should have a "show/hide" option.
* The login button should be disabled until both fields are filled out.
* There should be a link to the Signup page for new users.
* There should be a "Forgot Password?" link that directs the user to a password reset flow.
## Error Handling
* Display a clear and user-friendly error message for invalid login credentials.
* Do not specify whether the email or the password was incorrect for security reasons.
* If the server returns an error during login, display a generic error message to the user.
/speckit.specify # User Story: User Logout As a logged-in user, I want to be able to easily log out of my account from anywhere in the application, so that I can ensure my account is secure and my data is private. ## Acceptance Criteria 1. **Given** I am a logged-in user, **when** I click on the "Logout" button, **then** my session should be terminated. 2. **Given** I have successfully logged out, **then** I should be redirected to the public home page or the login page. 3. **Given** I have logged out, **when** I try to access a page that requires authentication (e.g., my profile page) by navigating to its URL, **then** I should be redirected to the login page. ## UI and Functionality * The "Logout" button should be clearly visible and accessible to logged-in users. * A common location for the logout button is in a user dropdown menu in the main navigation bar. * Clicking the "Logout" button should immediately log the user out without requiring a confirmation dialog, unless there is unsaved data. ## Security Considerations * Upon logout, the user's authentication token (e.g., JWT) must be invalidated on the client-side. * The server-side session should also be terminated if applicable.
/speckit.specify # User Story: Create a New Match As a player, I want to be able to set up a new padel match by selecting my partner and our two opponents, so that I can start scoring the game accurately. ## Acceptance Criteria 1. **Given** I am a logged-in user on the "Create Match" page, **when** I select one partner and two opponents from the list of registered users, **then** the "Start Match" button should become active. 2. **Given** I have selected the players for the match, **when** I click the "Start Match" button, **then** a new match should be created in the system with an initial score of 0-0 for both teams. 3. **Given** the match has been created, **then** I should be redirected to the live scoring page for that match. 4. **Given** I am on the "Create Match" page, **when** I try to select the same user as both my partner and an opponent, **then** the system should prevent this and show an error message. 5. **Given** I am on the "Create Match" page, **when** I have not selected all four players, **then** the "Start Match" button should be disabled. ## UI and Functionality * The "Create Match" page will have four player selection slots, grouped into "Team 1" and "Team 2". * "Team 1" will have the logged-in user pre-selected as "Player 1", and a selection for "Player 2" (their partner). * "Team 2" will have selections for "Player 1" and "Player 2" (the opponents). * Each player selection slot should feature a search or dropdown component to find and select from the list of registered users. * As I type a name in the search box, the list of users should be filtered in real-time. * Once all four players are selected, a "Start Match" button will be enabled. * The match format (e.g., best of 3 or 5 sets) can be selected before starting the match. A default will be set to "Best of 3". ## Error Handling * If there is an error creating the match on the server, a user-friendly error message should be displayed. * The system should prevent a user from being selected more than once for the same match.
/speckit.specify # User Story: Live Match Scoring As a player scoring the match, I want a simple and intuitive interface to add points for each team, so that I can accurately keep track of the score without getting distracted from the game. ## Acceptance Criteria 1. **Given** I am on the live scoring page for a match, **when** I click the "+ Point" button for a team, **then** that team's point score should increase according to padel rules (15, 30, 40, Game). 2. **Given** a team has 40 points and they win the next point, **then** they should win the game, their game score should increment by one, and the point score for both teams should reset to 0. 3. **Given** the score is 40-40 (Deuce), **when** a team wins a point, **then** their score should show as "Advantage". 4. **Given** a team has "Advantage" and wins the next point, **then** they should win the game. 5. **Given** a team has "Advantage" and loses the next point, **then** the score should return to Deuce (40-40). 6. **Given** a team wins a game and their game score reaches 6 (and they are leading by at least two games), **then** they should win the set, their set score should increment by one, and the game and point scores for both teams should reset to 0. 7. **Given** the game score is 6-6, **then** a tie-break game should be initiated. 8. **Given** I made a mistake, **when** I click the "Undo" button, **then** the last point entry should be reversed, and the score should revert to its previous state. ## UI and Functionality * The live scoring page will prominently display the names of the players in each team. * The current score will be clearly visible, showing sets, games, and points for each team. * Each team will have a large, easy-to-press "+ Point" button. * An "Undo Last Point" button will be available to correct mistakes. * The interface will clearly indicate which player/team is currently serving. This will alternate after each game. * When a match is finished, a summary screen should appear with the final score and the winners. ## Special Cases (Tie-break) * During a tie-break, points will be scored numerically (1, 2, 3...). * The tie-break ends when a team reaches at least 7 points with a margin of 2 points. * The team that wins the tie-break wins the set with a game score of 7-6.
/speckit.specify
# User Story: View Match History
As a player, I want to be able to view a comprehensive history of all the matches I have played, so that I can review my past performances, analyze my win/loss record, and see my progress over time.
## Acceptance Criteria
1. **Given** I am a logged-in user, **when** I navigate to my "Match History" page, **then** I should see a list of all the matches I have participated in.
2. **Given** I am viewing my match history, **then** each match in the list should display the date of the match, the players on each team, and the final score.
3. **Given** I am viewing my match history, **then** the matches should be listed in reverse chronological order by default (newest first).
4. **Given** I am viewing my match history, **when** I click on a specific match, **then** I should be taken to a detailed view of that match.
5. **Given** I am viewing my match history, **when** I use the filter options, **then** the list of matches should be updated to show only the matches that meet the filter criteria.
## UI and Functionality
* The "Match History" page will display a list of matches.
* Each item in the list will be a "Match Card" component.
* The Match Card will show:
* Date of the match.
* Team 1 players' names vs. Team 2 players' names.
* The final score in sets.
* An indicator showing whether I won or lost the match.
* The page will have filter controls to allow users to filter their match history. Filter options should include:
* Filter by partner.
* Filter by opponent.
* Filter by date range.
* The page will have sorting options to allow users to sort the match history by:
* Date (newest or oldest first).
* Result (wins or losses first).
## Error Handling
* If there is an error fetching the match history, a user-friendly error message should be displayed.
* If there are no matches to display, a message should be shown to the user encouraging them to play their first match.
/speckit.specify
# User Story: View Match Details
As a player, I want to be able to view a detailed summary of a specific past match, so that I can analyze the game, see the score breakdown, and remember the key moments of the game.
## Acceptance Criteria
1. **Given** I am on my "Match History" page, **when** I click on a specific match, **then** I should be navigated to the "Match Details" page for that match.
2. **Given** I am on the "Match Details" page, **then** I should see the names of all four players, grouped by their teams.
3. **Given** I am on the "Match Details" page, **then** I should see the final score of the match, broken down by sets and games.
4. **Given** I am on the "Match Details" page, **then** I should see the date and duration of the match.
5. **(Optional)** **Given** I am on the "Match Details" page, **then** I should see a chart or a timeline that visualizes the score progression throughout the match.
## UI and Functionality
* The "Match Details" page will have a clear and organized layout.
* The top of the page will display the names of the winning team more prominently.
* The page will display the following information:
* **Teams:** The players in each team.
* **Final Score:** The final score in sets (e.g., 6-2, 6-4).
* **Game-by-Game Score:** A table showing the score of each game within each set.
* **Date:** The date the match was played.
* **Duration:** The total duration of the match (e.g., "1 hour 25 minutes").
* A "Back to Match History" button will be present to allow the user to easily navigate back to the list of their matches.
* **(Optional) Score Progression Chart:** A line chart could be used to show how the game scores progressed over the course of each set.
## Error Handling
* If the user tries to view the details of a match that does not exist or they do not have permission to see, a "Match not found" error page should be shown.
* If there is a server error while fetching the match details, a generic error message should be displayed.
/speckit.specify
# User Story: Create a New Tournament
As a tournament organizer, I want to be able to easily create a new padel tournament, specify its details, and generate a bracket, so that I can set up and run a competitive event for players.
## Acceptance Criteria
1. **Given** I am a logged-in user on the "Create Tournament" page, **when** I fill in the tournament name, select the number of teams, and choose the tournament type, **then** the "Create Tournament" button should be enabled.
2. **Given** I have filled in the required tournament details, **when** I click the "Create Tournament" button, **then** a new tournament should be created, and a tournament bracket should be generated.
3. **Given** the tournament has been created, **then** I should be redirected to the tournament's management page, where I can see the empty bracket and an invitation link.
4. **Given** I am on the "Create Tournament" page, **when** I do not provide a name for the tournament, **then** the "Create Tournament" button should be disabled.
## UI and Functionality
* The "Create Tournament" form should include the following fields:
* **Tournament Name:** A text input for the name of the tournament.
* **Number of Teams:** A select dropdown to choose the number of teams (e.g., 4, 8, 16).
* **Tournament Type:** A select dropdown for the tournament format. Initially, this will only support "Single Elimination".
* **Start Date:** An optional date picker for the tournament's start date.
* The "Create Tournament" button will be disabled until all required fields are valid.
* Upon creation, the system will generate a single-elimination bracket structure based on the number of teams selected.
* The newly created tournament will have a "Pending" or "Registration Open" status.
## Tournament Bracket
* The bracket will be visually represented on the tournament page.
* Initially, the bracket slots will be shown as "To be determined" or will be empty placeholders.
* As teams join the tournament, their names will populate the bracket's first-round slots.
## Error Handling
* If there is an error during tournament creation on the server, a user-friendly error message should be displayed.
/speckit.specify # User Story: Invite Players to a Tournament As a tournament organizer, I want to be able to share a unique link with players, so that they can easily join my tournament and their team can be added to the bracket. ## Acceptance Criteria (Organizer) 1. **Given** I am on the management page for a tournament I have created, **then** I should see a unique and shareable invitation link. 2. **Given** I am on the tournament management page, **when** I click a "Copy Link" button, **then** the invitation link should be copied to my clipboard so I can easily share it. ## Acceptance Criteria (Invited Player) 1. **Given** I have received a tournament invitation link, **when** I open the link and I am logged in, **then** I should see the tournament details and an option to "Join Tournament". 2. **Given** I am on the tournament invitation page, **when** I click "Join Tournament", **then** I should be prompted to select my partner for the tournament. 3. **Given** I have selected my partner, **when** our team is successfully added to the tournament, **then** we should be placed in one of the available slots in the tournament bracket. 4. **Given** I try to join a tournament that is already full, **then** I should see a message indicating that the tournament is full and I cannot join. 5. **Given** I try to join a tournament I am already a part of, **then** the "Join Tournament" button should be disabled or I should see a message indicating I am already registered. ## UI and Functionality ### Organizer's View (Tournament Management Page) * A clearly visible section will display the unique invitation link. * A "Copy Link" button will be next to the link. * A list of teams that have already joined will be displayed. ### Invited Player's View (Invitation Page) * The page will show the tournament's name, date, and format. * A "Join Tournament" button will be prominent. * When a player decides to join, they will need to select their partner from the list of registered users (similar to creating a match). The joining player is automatically assigned as Player 1 of their team. * Once a team joins, their team name (e.g., "Player A / Player B") will appear in the tournament bracket. ## Error Handling * If an invalid or expired invitation link is used, a "Tournament Not Found" page should be displayed. * If a player tries to join with a partner who is already in the tournament, an error message should be shown. * If there's a server error when a team tries to join, a user-friendly error message should be displayed.
/speckit.specify # User Story: View Tournament Bracket As a player or a spectator, I want to be able to view the tournament bracket at any time, so that I can track the progress of the tournament, see upcoming matches, and view the results of completed games. ## Acceptance Criteria 1. **Given** I am viewing a tournament page, **then** I should see a visual representation of the single-elimination bracket for the tournament. 2. **Given** the tournament registration is still open, **then** the bracket should show the teams that have joined in the first-round slots. 3. **Given** a match in the tournament has been completed, **when** the score is submitted, **then** the bracket should automatically update to show the winner advancing to the next round. 4. **Given** I am viewing the tournament bracket, **then** I should be able to see the scores of the completed matches directly within the bracket view. 5. **Given** the tournament is complete, **then** the bracket should clearly show the tournament winner. ## UI and Functionality * The tournament page will feature a large, easy-to-read bracket diagram. * The bracket will be organized by rounds (e.g., Round 1, Quarter-finals, Semi-finals, Final). * Each matchup in the bracket will display the teams playing against each other. * For upcoming matches, the teams' names will be shown. * For completed matches, the winning team will be highlighted or moved to the next round's slot, and the final score will be displayed next to the teams' names. * When a user clicks on a completed match in the bracket, they should be navigated to the "Match Details" page for that match. * The entire bracket should be viewable without excessive scrolling, potentially using a zoom-and-pan interface for larger tournaments. ## Bracket Progression * When a tournament starts, the first-round matchups are locked in. * When a match is scored and a winner is declared (via the live scoring feature), the winning team's name automatically populates the appropriate slot in the next round. * This process continues until the final match is played and a tournament champion is crowned. * The champion's slot at the end of the bracket should be visually distinct (e.g., with a trophy icon or a "Winner" label).