Structure AI Projects with Claude Code: A Pre-Coding Workflow

What you’ll get

You’ll get a structured repository template for AI-assisted software development projects, covering pre-coding phases like objectives, user stories, and architecture. This approach ensures AI coding agents have clear context, leading to more efficient and organized development, especially across multiple sessions.

Tools you need

• Claude Code (paid) - An AI assistant for generating and structuring text-based project artifacts.
• GitHub (freemium) - A platform for hosting code repositories and collaborating on projects.

Steps

1. Access the AI SDLC Scaffold repository - Navigate to the GitHub repository provided by the author. The author mentions following instructions in the README to try it out.
   • You should see the repository’s main page with files and a README.md file.
2. Understand the Scaffold’s Purpose - Read the README.md file to grasp the workflow’s goal: to provide structure for AI-assisted software development, especially in pre-coding phases.
   • You should understand that the scaffold organizes project context for AI agents.
3. Initiate Project Structure with Claude Code - The author states the scaffold is designed around Claude Code. To start, you would typically use Claude Code to generate initial project artifacts based on the scaffold’s principles.
   • The author doesn’t share the exact initial prompt for Claude Code. A starting point could be:

   I am starting a new software project using the AI SDLC Scaffold. Please help me define the initial project objectives and high-level user stories based on the following idea: [Briefly describe your project idea here].

   • You should receive text output from Claude Code that outlines objectives and user stories, which you can then refine.
4. Define Project Objectives - Use Claude Code to articulate the main goals of your software project. This involves clearly stating what the software should achieve.
   • The author doesn’t specify the exact prompt. You might ask Claude Code:

   Based on our project idea, list 3-5 clear and measurable project objectives.

   • You should see a list of objectives that are specific and actionable.
5. Develop User Stories - Work with Claude Code to create user stories that describe how different users will interact with the software to achieve their goals.
   • The author doesn’t provide a specific prompt. A good prompt would be:

   For each project objective, generate 2-3 user stories in the format 'As a [type of user], I want [an action] so that [a benefit].'

   • You should get a set of user stories that detail desired functionalities from a user’s perspective.
6. Outline Architecture Decisions - Use Claude Code to document key architectural choices for the project.
   • The author doesn’t share the exact prompt. You could try:

   What are the key architectural decisions needed for a project with these objectives and user stories? Suggest a high-level architecture.

   • You should receive suggestions for architectural components and decisions.
7. Organize Artifacts in the Repository - Save the generated objectives, user stories, and architecture decisions into the appropriate files within your GitHub repository, following the structure suggested by the scaffold.
   • Your repository should now contain organized text files detailing the project’s foundational elements.

Original source

This workflow is based on an open-source repository template created by pangon, shared on Hacker News. The author, with extensive experience in computer science research and software engineering, developed this scaffold to bring structure to the pre-coding phases of AI-assisted software development, making it reusable for others.

Notes & variations

• Cost and free alternative: Claude Code requires a paid Claude plan or API credits. For a free option, the Gemini CLI follows the same steps. GitHub’s free tier is sufficient for hosting the project repository.
• Common Pitfall: Ensure you are specific when describing your project idea to Claude Code. Vague descriptions will lead to generic and less useful outputs.
• Tip for Better Results: Regularly review and refine the generated artifacts. AI is a tool to assist, and human oversight is crucial for ensuring the objectives, user stories, and architecture align with your project’s vision.