refactor(vault): Phase 2 — root directory cleanup and clipper migration
- Remove dead services: .scripts/memory/, compose.yml, initdb/, specs/ - Remove root散件: package-lock.json, install.sh, LICENSE, FIRST_RUN, .failed_images.txt, .upgrade-checklist.md, 未命名*.md, Untitled Kanban.md - Move chinese-to-english-mapping.csv → .scripts/ - Migrate 00_Inbox/Clippings/ → 04_Archive/Inbox-Clippings/ - Fix self-nesting bug: 2024/11/2023/ → 2023/ (73 files relocated) - Fix verifier false-positive on its own regex patterns
This commit is contained in:
windyboy
+83
@@ -0,0 +1,83 @@
|
||||
---
|
||||
title: "AI Agent Systems: Architectures, Applications, and Evaluation"
|
||||
source: "https://arxiv.org/abs/2601.01743v1"
|
||||
author:
|
||||
- "[[Bin Xu]]"
|
||||
published:
|
||||
created: 2026-01-07
|
||||
description: "Abstract page for arXiv paper 2601.01743v1: AI Agent Systems: Architectures, Applications, and Evaluation"
|
||||
tags:
|
||||
- "clippings"
|
||||
- "webclipper"
|
||||
---
|
||||
> [!info] Source
|
||||
> URL: https://arxiv.org/abs/2601.01743v1
|
||||
> Title: AI Agent Systems: Architectures, Applications, and Evaluation
|
||||
> Clipped:
|
||||
|
||||
页面已保存到 Trilium。 [在 Trilium 中打开。](https://arxiv.org/abs/)
|
||||
|
||||
\[Submitted on 5 Jan 2026\]
|
||||
|
||||
## Title:AI Agent Systems: Architectures, Applications, and Evaluation
|
||||
|
||||
Authors:
|
||||
|
||||
[View PDF](https://arxiv.org/pdf/2601.01743v1) [HTML (experimental)](https://arxiv.org/html/2601.01743v1)
|
||||
|
||||
> Abstract:AI agents -- systems that combine foundation models with reasoning, planning, memory, and tool use -- are rapidly becoming a practical interface between natural-language intent and real-world computation. This survey synthesizes the emerging landscape of AI agent architectures across: (i) deliberation and reasoning (e.g., chain-of-thought-style decomposition, self-reflection and verification, and constraint-aware decision making), (ii) planning and control (from reactive policies to hierarchical and multi-step planners), and (iii) tool calling and environment interaction (retrieval, code execution, APIs, and multimodal perception). We organize prior work into a unified taxonomy spanning agent components (policy/LLM core, memory, world models, planners, tool routers, and critics), orchestration patterns (single-agent vs.\\ multi-agent; centralized vs.\\ decentralized coordination), and deployment settings (offline analysis vs.\\ online interactive assistance; safety-critical vs.\\ open-ended tasks). We discuss key design trade-offs -- latency vs.\\ accuracy, autonomy vs.\\ controllability, and capability vs.\\ reliability -- and highlight how evaluation is complicated by non-determinism, long-horizon credit assignment, tool and environment variability, and hidden costs such as retries and context growth. Finally, we summarize measurement and benchmarking practices (task suites, human preference and utility metrics, success under constraints, robustness and security) and identify open challenges including verification and guardrails for tool actions, scalable memory and context management, interpretability of agent decisions, and reproducible evaluation under realistic workloads.
|
||||
|
||||
| Subjects: | Artificial Intelligence (cs.AI) |
|
||||
| --- | --- |
|
||||
| Cite as: | [arXiv:2601.01743](https://arxiv.org/abs/2601.01743) \[cs.AI\] |
|
||||
| | (or [arXiv:2601.01743v1](https://arxiv.org/abs/2601.01743v1) \[cs.AI\] for this version) |
|
||||
| | [https://doi.org/10.48550/arXiv.2601.01743](https://doi.org/10.48550/arXiv.2601.01743) arXiv-issued DOI via DataCite (pending registration) |
|
||||
|
||||
## Submission history
|
||||
|
||||
From: Bin Xu \[[view email](https://arxiv.org/show-email/97a5ff94/2601.01743)\]
|
||||
**\[v1\]** Mon, 5 Jan 2026 02:38:40 UTC (47,415 KB)
|
||||
|
||||
## Bibliographic and Citation Tools
|
||||
|
||||
Bibliographic Explorer *([What is the Explorer?](https://info.arxiv.org/labs/showcase.html#arxiv-bibliographic-explorer))*
|
||||
|
||||
Connected Papers *([What is Connected Papers?](https://www.connectedpapers.com/about))*
|
||||
|
||||
Litmaps *([What is Litmaps?](https://www.litmaps.co/))*
|
||||
|
||||
scite Smart Citations *([What are Smart Citations?](https://www.scite.ai/))*
|
||||
|
||||
## Code, Data and Media Associated with this Article
|
||||
|
||||
alphaXiv *([What is alphaXiv?](https://alphaxiv.org/))*
|
||||
|
||||
CatalyzeX Code Finder for Papers *([What is CatalyzeX?](https://www.catalyzex.com/))*
|
||||
|
||||
DagsHub *([What is DagsHub?](https://dagshub.com/))*
|
||||
|
||||
Gotit.pub *([What is GotitPub?](http://gotit.pub/faq))*
|
||||
|
||||
Hugging Face *([What is Huggingface?](https://huggingface.co/huggingface))*
|
||||
|
||||
Papers with Code *([What is Papers with Code?](https://paperswithcode.com/))*
|
||||
|
||||
ScienceCast *([What is ScienceCast?](https://sciencecast.org/welcome))*
|
||||
|
||||
## Demos
|
||||
|
||||
Replicate *([What is Replicate?](https://replicate.com/docs/arxiv/about))*
|
||||
|
||||
Hugging Face Spaces *([What is Spaces?](https://huggingface.co/docs/hub/spaces))*
|
||||
|
||||
TXYZ.AI *([What is TXYZ.AI?](https://txyz.ai/))*
|
||||
|
||||
## arXivLabs: experimental projects with community collaborators
|
||||
|
||||
arXivLabs is a framework that allows collaborators to develop and share new arXiv features directly on our website.
|
||||
|
||||
Both individuals and organizations that work with arXivLabs have embraced and accepted our values of openness, community, excellence, and user data privacy. arXiv is committed to these values and only works with partners that adhere to them.
|
||||
|
||||
Have an idea for a project that will add value for arXiv's community? [**Learn more about arXivLabs**](https://info.arxiv.org/labs/index.html).
|
||||
|
||||
[Which authors of this paper are endorsers?](https://arxiv.org/auth/show-endorsers/2601.01743) | [Disable MathJax](https://arxiv.org/abs/) ([What is MathJax?](https://info.arxiv.org/help/mathjax.html))
|
||||
@@ -0,0 +1,150 @@
|
||||
---
|
||||
title: "How I use Obsidian"
|
||||
source: "https://stephango.com/vault"
|
||||
author:
|
||||
- "[[Steph Ango]]"
|
||||
published:
|
||||
created: 2026-01-05
|
||||
description: "My personal Obsidian vault template. A bottom-up approach to note-taking and organizing things I am interested in."
|
||||
tags:
|
||||
- "clippings"
|
||||
- "webclipper"
|
||||
---
|
||||
> [!info] Source
|
||||
> URL: https://stephango.com/vault
|
||||
> Title: How I use Obsidian
|
||||
> Clipped:
|
||||
|
||||
I use [Obsidian](https://stephango.com/obsidian) to think, take notes, write essays, and publish this site. This is my bottom-up approach to note-taking and organizing things I am interested in. It embraces chaos and laziness to create emergent structure.
|
||||
|
||||
In Obsidian, a “vault” is simply a folder of files. This is important because it adheres to my [file over app](https://stephango.com/file-over-app) philosophy. If you want to create digital artifacts that last, they must be files you can control, in formats that are easy to retrieve and read. Obsidian gives you that freedom.
|
||||
|
||||
The following is in no way dogmatic, just one example of how you can use Obsidian. Take the parts you like.
|
||||
|
||||
## Vault template
|
||||
|
||||
1. [Download my vault](https://github.com/kepano/kepano-obsidian/archive/refs/heads/main.zip) or clone it from [the Github repo](https://github.com/kepano/kepano-obsidian).
|
||||
2. Unzip the `.zip` file to a folder of your choosing.
|
||||
3. In Obsidian open the folder as a vault.
|
||||
- My theme [Minimal](https://stephango.com/minimal) with the [Flexoki](https://stephango.com/flexoki) color scheme.
|
||||
- [Obsidian Web Clipper](https://stephango.com/obsidian-web-clipper) to save articles and pages from the web, see my [clipper templates](https://github.com/kepano/clipper-templates) for specific sites I clip from.
|
||||
- [Obsidian Sync](https://obsidian.md/sync) to sync notes between my desktop, phone and tablet.
|
||||
- [Obsidian Bases](https://help.obsidian.md/bases) to view notes by category.
|
||||
- [Obsidian Maps](https://help.obsidian.md/bases/views/map) for maps used in some of my templates.
|
||||
|
||||
## Personal rules
|
||||
|
||||
Rules I follow in my personal vault:
|
||||
|
||||
- Avoid splitting content into multiple vaults.
|
||||
- Avoid folders for organization.
|
||||
- Avoid non-standard Markdown.
|
||||
- Always pluralize categories and tags.
|
||||
- Use internal links profusely.
|
||||
- Use `YYYY-MM-DD` dates everywhere.
|
||||
- Use the 7-point scale for ratings.
|
||||
- Keep [a single to-do list](https://stephango.com/todos) per week.
|
||||
|
||||
Having a [consistent style](https://stephango.com/style) collapses hundreds of future decisions into one, and gives me focus. For example, I always pluralize tags so I never have to wonder what to name new tags. Choose rules that feel comfortable to you and write them down. Make your own style guide. You can always change your rules later.
|
||||
|
||||
## Folders and organization
|
||||
|
||||
I use very few folders. I avoid folders because many of my entries belong to more than one area of thought. My system is oriented towards speed and laziness. I don’t want the overhead of having to consider where something should go.
|
||||
|
||||
I do not use nested sub-folders. I do not use the file explorer much for navigation. I mostly navigate using the quick switcher, backlinks, or links within a note.
|
||||
|
||||
My notes are primarily organized using the `categories` property. Categories display an overview of related notes, using the [bases](https://help.obsidian.md/bases) feature in Obsidian.
|
||||
|
||||
**Most of my notes are in the root of the vault**, not a folder. This where I write about my personal world: journal entries, essays, [evergreen](https://stephango.com/evergreen-notes) notes, and other personal notes. If a note is in the root, I know it’s something I wrote, or relates directly to me.
|
||||
|
||||
Two reference folders I use:
|
||||
|
||||
- **References** where I write about things that exist outside my world. Books, movies, places, people, podcasts, etc. Always named using the title e.g. `Book title.md` or `Movie title.md`.
|
||||
- **Clippings** where I save things other people wrote, mostly essays and articles.
|
||||
|
||||
Three admin folders exist so that their contents don’t show up in the file navigation:
|
||||
|
||||
- **Attachments** for images, audio, videos, PDFs, etc.
|
||||
- **Daily** for my daily notes, all named `YYYY-MM-DD.md`. I do not write anything in daily notes, they exist solely to be linked to from other entries.
|
||||
- **Templates** for templates.
|
||||
|
||||
Two folders are present in the downloadable version of my vault for the sake of clarity. In my personal vault, these notes would be in the root, not a folder.
|
||||
|
||||
- **Categories** contains top-level overviews of notes per category (e.g. Books, Movies, Podcasts, etc).
|
||||
- **Notes** contains example notes.
|
||||
|
||||
## Links
|
||||
|
||||
I use internal links profusely throughout my notes. I try to always link the first mention of something. My journal entries are often a stream of consciousness cataloging recent events, finding connections between things. Often the link is *unresolved*, meaning that the note for that link isn’t created yet. Unresolved links are important because they are breadcrumbs for future connections between things.
|
||||
|
||||
A journal entry in the **root** of my vault might look something like this:
|
||||
|
||||
```
|
||||
I went to see the movie [[Perfect Days]] with [[Aisha]] at [[Vidiots]] and had Filipino food at [[Little Ongpin]]. I loved this quote from Perfect Days: [[Next time is next time, now is now]]. It reminds me of the essay ...
|
||||
```
|
||||
|
||||
The movie, movie theater, and restaurant each link to entries in my **References** folder. In these reference notes I capture properties, my rating, and thoughts about that thing. I use [Web Clipper](https://stephango.com/obsidian-web-clipper) to help populate properties from databases like IMDB. The quote was meaningful to me, so it became an [evergreen note](https://stephango.com/evergreen-notes) in my root folder. The essay I mention is in my **Clippings** folder, because I didn’t write it myself.
|
||||
|
||||
This heavy linking style becomes more useful as time goes on, because I can trace how ideas emerged, and the branching paths these ideas created.
|
||||
|
||||
## Fractal journaling and random revisit
|
||||
|
||||
Fractal journaling and randomization are how I tame the wilderness that a knowledge base can grow into.
|
||||
|
||||
Throughout the day I use Obsidian’s *unique note* hotkey to write individual thoughts as they come up. This shortcut automatically creates a note with the prefix `YYYY-MM-DD HHmm` to which I may add a title that describes the idea.
|
||||
|
||||
Every few days I review these journal fragments and compile the salient thoughts. I then review those reviews monthly, and review the monthly reviews yearly (using [this template](https://stephango.com/40-questions)). The result is a fractal web of my life that I can zoom in and out of at varying degrees of detail. I can trace back where individual thoughts came from, and how they bubbled up into bigger themes.
|
||||
|
||||
Every few months I set aside time for a “random revisit”. I use the *random note* hotkey to quickly travel randomly through my vault. I often use the local graph at shallow depth to see related notes. This helps me revisit old ideas, create missing links, and find inspiration in past thoughts. It’s also an opportunity to do maintenance, like fix formatting based on new rules in my personal style guide.
|
||||
|
||||
People have asked me if this could be automated with language models but I do not care to do so. I enjoy this process. Doing this maintenance helps me understand my own patterns. [Don’t delegate understanding](https://stephango.com/understand).
|
||||
|
||||
## Properties and templates
|
||||
|
||||
Almost every note I create starts from a [template](https://github.com/kepano/kepano-obsidian/tree/main/Templates). I use templates heavily because they allow me to lazily add information that will help me find the note later. I have a template for every category with [properties](https://help.obsidian.md/properties) at the top, to capture data such as:
|
||||
|
||||
- **Dates** — created, start, end, published
|
||||
- **People** — author, director, artist, cast, host, guests
|
||||
- **Themes** — grouping by genre, type, topic, related notes
|
||||
- **Locations** — neighborhood, city, coordinates
|
||||
- **Ratings** — more on this below
|
||||
|
||||
A few rules I follow for properties:
|
||||
|
||||
- Property names and values should aim to be reusable across categories. This allows me to find things across categories, e.g. `genre` is shared across all media types, which means I can see an archive of *Sci-fi* books, movies and shows in one place.
|
||||
- Templates should aim to be composable, e.g. *Person* and *Author* are two different templates that can be added to the same note.
|
||||
- Short property names are faster to type, e.g. `start` instead of `start‑date`.
|
||||
- Default to `list` type properties instead of `text` if there is any chance it might contain more than one link or value in the future.
|
||||
|
||||
The [.obsidian/types.json](https://github.com/kepano/kepano-obsidian/blob/main/.obsidian/types.json) file lists which properties are assigned to which types (i.e. `date`, `number`, `text`, etc).
|
||||
|
||||
## Rating system
|
||||
|
||||
Anything with a `rating` uses an integer from 1 to 7:
|
||||
|
||||
- 7 — **Perfect**, must try, life-changing, go out of your way to seek this out
|
||||
- 6 — **Excellent**, worth repeating
|
||||
- 5 — **Good**, don’t go out of your way, but enjoyable
|
||||
- 4 — **Passable**, works in a pinch
|
||||
- 3 — **Bad**, don’t do this if you can
|
||||
- 2 — **Atrocious**, actively avoid, repulsive
|
||||
- 1 — **Evil**, life-changing in a bad way
|
||||
|
||||
Why this scale? I like rating out of 7 better than 4 or 5 because I need more granularity at the top, for the good experiences, and 10 is too granular.
|
||||
|
||||
## Publishing to the web
|
||||
|
||||
This site is written, edited, and published directly from Obsidian. To do this, I break one of my rules listed above — I have a separate vault for my site. I use a *static site generator* called [Jekyll](https://jekyllrb.com/) to automatically compile my notes into a website and convert them from Markdown to HTML.
|
||||
|
||||
My publishing flow is easy to use, but a bit technical to set up. This is because I like to have full control over every aspect of my site’s layout. If you don’t need full control you might consider [Obsidian Publish](https://obsidian.md/publish) which is more user-friendly, and what I use for my [Minimal documentation site](https://minimal.guide/publish/download).
|
||||
|
||||
For this site, I push notes from Obsidian to a GitHub repo using the [Obsidian Git](https://obsidian.md/plugins?id=obsidian-git) plugin. The notes are then automatically compiled using [Jekyll](https://jekyllrb.com/) with my web host [Netlify](https://www.netlify.com/). I also use my [Permalink Opener](https://stephango.com/permalink-opener) plugin to quickly open notes in the browser so I can compare the draft and live versions.
|
||||
|
||||
The color palette is [Flexoki](https://stephango.com/flexoki), which I created for this site. My Jekyll template is not public, but you can get similar results from [this template](https://github.com/maximevaillancourt/digital-garden-jekyll-template) by Maxime Vaillancourt. There are also many alternatives to Jekyll you can use to compile your site such as [Quartz](https://quartz.jzhao.xyz/), [Astro](https://astro.build/), [Eleventy](https://www.11ty.dev/), and [Hugo](https://gohugo.io/).
|
||||
|
||||
- [File over app](https://stephango.com/file-over-app)
|
||||
- [Concise explanations accelerate progress](https://stephango.com/concise)
|
||||
- [Evergreen notes turn ideas into objects that you can manipulate](https://stephango.com/evergreen-notes)
|
||||
- [40 questions to ask yourself every year](https://stephango.com/40-questions)
|
||||
- [40 questions to ask yourself every decade](https://stephango.com/40-questions-decade)
|
||||
- [How I do my to-dos](https://stephango.com/todos)
|
||||
+181
@@ -0,0 +1,181 @@
|
||||
---
|
||||
title: "Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl"
|
||||
source: "https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html"
|
||||
author:
|
||||
- "[[Birgitta BöckelerBirgitta is a Distinguished Engineer and AI-assisted delivery expert at Thoughtworks. She has over 20 years of experience as a software developer]]"
|
||||
- "[[architect and technical leader.]]"
|
||||
published:
|
||||
created: 2026-01-21
|
||||
description: "Notes from my Thoughtworks colleagues on AI-assisted software delivery"
|
||||
tags:
|
||||
- "clippings"
|
||||
- "webclipper"
|
||||
---
|
||||
> [!info] Source
|
||||
> URL: https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html
|
||||
> Title: Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl
|
||||
> Clipped:
|
||||
|
||||
I’ve been trying to understand one of the latest AI coding buzzword: Spec-driven development (SDD). I looked at three of the tools that label themselves as SDD tools and tried to untangle what it means, as of now.
|
||||
|
||||
## Definition
|
||||
|
||||
Like with many emerging terms in this fast-paced space, the definition of “spec-driven development” (SDD) is still in flux. Here’s what I can gather from how I have seen it used so far: Spec-driven development means writing a “spec” before writing code with AI (“documentation first”). The spec becomes the source of truth for the human and the AI.
|
||||
|
||||
[GitHub](https://github.com/github/spec-kit/blob/main/spec-driven.md): “In this new world, *maintaining software means evolving specifications*. \[…\] The lingua franca of development moves to a higher level, and code is the last-mile approach.”
|
||||
|
||||
[Tessl](https://docs.tessl.io/introduction-to-tessl/concepts): “A development approach where *specs — not code — are the primary artifact*. Specs describe intent in structured, testable language, and agents generate code to match them.”
|
||||
|
||||
After looking over the usages of the term, and some of the tools that claim to be implementing SDD, it seems to me that in reality, there are multiple implementation levels to it:
|
||||
|
||||
1. **Spec-first**: A well thought-out spec is written first, and then used in the AI-assisted development workflow for the task at hand.
|
||||
2. **Spec-anchored**: The spec is kept even after the task is complete, to continue using it for evolution and maintenance of the respective feature.
|
||||
3. **Spec-as-source**: The spec is the main source file over time, and only the spec is edited by the human, the human never touches the code.
|
||||
|
||||
All SDD approaches and definitions I’ve found are spec-first, but not all strive to be spec-anchored or spec-as-source. And often it’s left vague or totally open what the spec maintenance strategy over time is meant to be.
|
||||
|
||||
|
||||
|
||||
## What is a spec?
|
||||
|
||||
The key question in terms of definitions of course is: What is a spec? There doesn’t seem to be a general definition, the closest I’ve seen to a consistent definition is the comparison of a spec to a “Product Requirements Document”.
|
||||
|
||||
The term is quite overloaded at the moment, here is my attempt at defining what a spec is:
|
||||
|
||||
A spec is a structured, behavior-oriented artifact - or a set of related artifacts - written in natural language that expresses software functionality and serves as guidance to AI coding agents. Each variant of spec-driven development defines their approach to a spec’s structure, level of detail, and how these artifacts are organized within a project.
|
||||
|
||||
There is a useful difference to be made I think between specs and the more general context documents for a codebase. That general context are things like rules files, or high level descriptions of the product and the codebase. Some tools call this context a [**memory bank**](https://docs.cline.bot/prompting/cline-memory-bank), so that’s what I will use here. These files are relevant across all AI coding sessions in the codebase, whereas specs only relevant to the tasks that actually create or change that particular functionality.
|
||||
|
||||
|
||||
|
||||
## The challenge with evaluating SDD tools
|
||||
|
||||
It turns out to be quite time-consuming to evaluate SDD tools and approaches in a way that gets close to real usage. You would have to try them out with different sizes of problems, greenfield, brownfield, and really take the time to review and revise the intermediate artifacts with more than just a cursory glance. Because as [GitHub’s blog post about spec-kit](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/) says: “Crucially, your role isn’t just to steer. It’s to verify. At each phase, you reflect and refine.”
|
||||
|
||||
For two of the three tools I tried it also seems to be even more work to introduce them into an existing codebase, therefore making it even harder to evaluate their usefulness for brownfield codebases. Until I hear usage reports from people using them for a period of time on a “real” codebase, I still have a lot of open questions about how this works in real life.
|
||||
|
||||
That being said - let’s get into three of these tools. I will share a description of how they work first (or rather how I think they work), and will keep my observations and questions for the end. Note that these tools are very fast evolving, so they might have already changed since I used them in September.
|
||||
|
||||
## Kiro
|
||||
|
||||
[Kiro](https://kiro.dev/) is the simplest (or most lightweight) one of the three I tried. It seems to be mostly spec-first, all the examples I have found use it for a task, or a user story, with no mention of how to use the requirements document in a spec-anchored way over time, across multiple tasks.
|
||||
|
||||
**Workflow:** Requirements → Design → Tasks
|
||||
|
||||
Each workflow step is represented by one markdown document, and Kiro guides you through those 3 workflow steps inside of its VS Code based distribution.
|
||||
|
||||
**Requirements:** Structured as a list of requirements, where each requirement represents a “User Story” (in “As a…” format) with acceptance criteria (in “GIVEN… WHEN… THEN…” format)
|
||||
|
||||
|
||||
|
||||
**Design:** In my attempt, the design document consisted of the sections seen in the screenshot below. I only have the results of one of my attempts still, so I’m not sure if this is a consistent structure, or if it changes depending on the task.
|
||||
|
||||
|
||||
|
||||
**Tasks:** A list of tasks that trace back to the requirement numbers, and that get some extra UI elements to run tasks one by one, and review changes per task.
|
||||
|
||||
|
||||
|
||||
Kiro also has the concept of a memory bank, they call it “steering”. Its contents are flexible, and their workflow doesn’t seem to rely on any specific files being there (I made my usage attempts before I even discovered the steering section). The default topology created by Kiro when you ask it to generate steering documents is product.md, structure.md, tech.md.
|
||||
|
||||
|
||||
|
||||
## Spec-kit
|
||||
|
||||
[Spec-kit](https://github.com/github/spec-kit) is GitHub’s version of SDD. It is distributed as a CLI that can create workspace setups for a wide range of common coding assistants. Once that structure is set up, you interact with spec-kit via slash commands in your coding assistant. Because all of its artifacts are put right into your workspace, this is the most customizable one of the three tools discussed here.
|
||||
|
||||
|
||||
|
||||
**Workflow:** Constitution → 𝄆 Specify → Plan → Tasks 𝄇
|
||||
|
||||
Spec-kit’s memory bank concept is a prerequisite for the spec-driven approach. They call it a [**constitution**](https://github.com/github/spec-kit/blob/main/spec-driven.md#the-constitutional-foundation-enforcing-architectural-discipline). The constitution is supposed to contain the high level principles that are “immutable” and should always be applied, to every change. It’s basically a very powerful rules file that is heavily used by the workflow.
|
||||
|
||||
In each of the workflow steps (specify, plan, tasks), spec-kit instantiates a set of files and prompts with the help of a bash script and some templates. The workflow then makes heavy use of checklists inside of the files, to track necessary user clarifications, constitution violations, research tasks, etc. They are like a “definition of done” for each workflow step (though interpreted by AI, so there is no 100% guarantee that they will be respected).
|
||||
|
||||
|
||||
|
||||
Below is an overview to illustrate the file topology I saw in spec-kit. Note how one spec is made up of many files.
|
||||
|
||||
|
||||
|
||||
At first glance, GitHub seems to be [aspiring to a spec-anchored approach](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/) (“That’s why we’re rethinking specifications — not as static documents, but as living, executable artifacts that evolve with the project. Specs become the shared source of truth. When something doesn’t make sense, you go back to the spec; when a project grows complex, you refine it; when tasks feel too large, you break them down.”) However, spec-kit creates a branch for every spec that gets created, which seems to indicate that they see a spec as a living artifact for the lifetime of a change request, not the lifetime of a feature. [This community discussion](https://github.com/github/spec-kit/discussions/152) is talking about this confusion. It makes me think that spec-kit is still what I would call spec-first only, not spec-anchored over time.
|
||||
|
||||
## Tessl Framework
|
||||
|
||||
*(Still in private beta)*
|
||||
|
||||
Like spec-kit, the [Tessl Framework](https://docs.tessl.io/introduction-to-tessl/quick-start-guide-tessl-framework) is distributed as a CLI that can create all the workspace and config structure for a variety of coding assistants. The CLI command also doubles as an MCP server.
|
||||
|
||||
|
||||
|
||||
Tessl is the only one of these three tools that explicitly aspires to a spec-anchored approach, and is even exploring the spec-as-source level of SDD. A Tessl spec can serve as the main artifact that is being maintained and edited, with the code even marked with a comment at the top saying `// GENERATED FROM SPEC - DO NOT EDIT`. This is currently a 1:1 mapping between spec and code files, i.e. one spec translates into one file in the codebase. But Tessl is still in beta and they are experimenting with different versions of this, so I can imagine that this approach could also be taken on a level where one spec maps to a code component with multiple files. It remains to be seen what the alpha product will support. (The Tessl team themselves see their framework as something that is more in the future than their current public product, the Tessl Registry.)
|
||||
|
||||
Here is an example of a spec that I had the Tessl CLI reverse engineer (`tessl document --code ...js`) from a JavaScript file in an existing codebase:
|
||||
|
||||
|
||||
|
||||
Tags like `@generate` or `@test` seem to tell Tessl what to generate. The API section shows the idea of defining at least the interfaces that get exposed to other parts of the codebase in the spec, presumably to make sure that these more crucial parts of the generated component are fully under the control of the maintainer. Running `tessl build` for this spec generates the corresponding JavaScript code file.
|
||||
|
||||
Putting the specs for spec-as-source at a quite low abstraction level, per code file, probably reduces amount of steps and interpretations the LLM has to do, and therefore the chance of errors. Even at this low abstraction level I have seen the non-determinism in action though, when I generated code multiple times from the same spec. It was an interesting exercise to iterate on the spec and make it more and more specific to increase the repeatability of the code generation. That process reminded me of some of the pitfalls and challenges of writing an unambiguous and complete specification.
|
||||
|
||||
|
||||
|
||||
## Observations and questions
|
||||
|
||||
These three tools are all labelling themselves as implementations of spec-driven development, but they are quite different from each other. So that’s the first thing to keep in mind when talking about SDD, it is not just one thing.
|
||||
|
||||
### One workflow to fit all sizes?
|
||||
|
||||
Kiro and spec-kit provide one opinionated workflow each, but I’m quite sure that neither of them is suitable for the majority of real life coding problems. In particular, it’s not quite clear to me how they would cater to enough different problem sizes to be generally applicable.
|
||||
|
||||
When I asked Kiro to fix a small bug ([it was the same one I used in the past to try Codex](https://martinfowler.com/articles/exploring-gen-ai/autonomous-agents-codex-example.html)), it quickly became clear that the workflow was like using a sledgehammer to crack a nut. The requirements document turned this small bug into 4 “user stories” with a total of 16 acceptance criteria, including gems like “User story: As a developer, I want the transformation function to handle edge cases gracefully, so that the system remains robust when new category formats are introduced.”
|
||||
|
||||
I had a similar challenge when I used spec-kit, I wasn’t quite sure what size of problem to use it for. Available tutorials are usually based on creating an application from scratch, because that’s easiest for a tutorial. One of the use cases I ended up trying was a feature that would be a 3-5 point story on one of my past teams. The feature depended on a lot of code that was already there, it was supposed to build an overview modal that summarised a bunch of data from an existing dashboard. With the amount of steps spec-kit took, and the amount of markdown files it created for me to review, this again felt like overkill for the size of the problem. It was a bigger problem than the one I used with Kiro, but also a much more elaborate workflow. I never even finished the full implementation, but I think in the same time it took me to run and review the spec-kit results I could have implemented the feature with “plain” AI-assisted coding, and I would have felt much more in control.
|
||||
|
||||
An effective SDD tool would at the very least have to provide flexibility for a few different core workflows, for different sizes and types of changes.
|
||||
|
||||
### Reviewing markdown over reviewing code?
|
||||
|
||||
As just mentioned, and as you can see in the description of the tool above, spec-kit created a LOT of markdown files for me to review. They were repetitive, both with each other, and with the code that already existed. Some contained code already. Overall they were just very verbose and tedious to review. In Kiro it was a little easier, as you only get 3 files, and it’s more intuitive to understand the mental model of “requirements > design > tasks”. However, as mentioned, Kiro also was way too verbose for the small bug I was asking it to fix.
|
||||
|
||||
To be honest, I’d rather review code than all these markdown files. An effective SDD tool would have to provide a very good spec review experience.
|
||||
|
||||
### False sense of control?
|
||||
|
||||
Even with all of these files and templates and prompts and workflows and checklists, I frequently saw the agent ultimately not follow all the instructions. Yes, the context windows are now larger, which is often mentioned as one of the enablers of spec-driven development. But just because the windows are larger, doesn’t mean that AI will properly pick up on everything that’s in there.
|
||||
|
||||
For example: Spec-kit has a research step somewhere during planning, and it did a lot of research on the existing code and what’s already there, which was great because I asked it to add a feature that built on top of existing code. But ultimately the agent ignored the notes that these were descriptions of existing classes, it just took them as a new specification and generated them all over again, creating duplicates. But I didn’t only see examples of ignoring instructions, I also saw the agent go way overboard because it was too eagerly following instructions (e.g. one of the constitution articles).
|
||||
|
||||
The past has shown that the best way for us to stay in control of what we’re building are small, iterative steps, so I’m very skeptical that lots of up-front spec design is a good idea, especially when it’s overly verbose. An effective SDD tool would have to cater to an iterative approach, but small work packages almost seem counter to the idea of SDD.
|
||||
|
||||
### How to effectively separate functional from technical spec?
|
||||
|
||||
It is a common idea in SDD to be intentional about the separation between functional spec and technical implementation. The underlying aspiration I guess is that ultimately, we could have AI fill in all the solutioning and details, and switch to different tech stacks with the same spec.
|
||||
|
||||
In reality, when I was trying spec-kit, I frequently got confused when to stay on the functional level, and when it was time to add technical details. The tutorial and documentation also weren’t quite consistent with it, there seem to be different interpretations of what “purely functional” really means. And when I think back on the many, many user stories I’ve read in my career that weren’t properly separating requirements from implementation, I don’t think we have a good track record as a profession to do this well.
|
||||
|
||||
### Who is the target user?
|
||||
|
||||
Many of the demos and tutorials for spec-driven development tools include things like defining product and feature goals, they even incorporate terms like “user story”. The idea here might be to use AI as an enabler for cross-skilling, and have developers participate more heavily in requirements analysis? Or have developers pair with product people when they work on this workflow? None of this is made explicit though, it’s presented as a given that a developer would do all this analysis.
|
||||
|
||||
In which case I would ask myself again, what problem size and type is SDD meant for? Probably not for large features that are still very unclear, as surely that would require more specialist product and requirements skills, and lots of other steps like research and stakeholder involvement?
|
||||
|
||||
|
||||
|
||||
### Spec-anchored and spec-as-source: Are we learning from the past?
|
||||
|
||||
While many people draw analogies between SDD and TDD or BDD, I think another important parallel to look at for spec-as-source in particular is MDD (model-driven development). I worked on a few projects at the beginning of my career that heavily used MDD, and I kept being reminded about that when I was trying out the Tessl Framework. The models in MDD were basically the specs, albeit not in natural language, but expressed in e.g. custom UML or a textual DSL. We built custom code generators to turn those specs into code.
|
||||
|
||||
|
||||
|
||||
Ultimately, MDD never took off for business applications, it sits at an awkward abstraction level and just creates too much overhead and constraints. But LLMs take some of the overhead and constraints of MDD away, so there is a new hope that we can now finally focus on writing specs and just generate code from them. With LLMs, we are not constrained by a predefined and parseable spec language anymore, and we don’t have to build elaborate code generators. The price for that is LLMs’ non-determinism of course. And the parseable structure also had upsides that we’re losing now: We could provide the spec author with a lot of tool support to write valid, complete and consistent specs. I wonder if spec-as-source, and even spec-anchoring, might end up with the downsides of both MDD and LLMs: Inflexibility *and* non-determinism.
|
||||
|
||||
To be clear, I’m not nostalgic about my MDD experience in the past and saying “we might as well bring that back”. But we should look to code-from-spec attempts in the past to learn from them when we explore spec-driven today.
|
||||
|
||||
## Conclusions
|
||||
|
||||
In my personal usage of AI-assisted coding, I also often spend time on carefully crafting some form of spec first to give to the coding agent. So the general principle of spec-first is definitely valuable in many situations, and the different approaches of how to structure that spec are very sought after. They are among the top most frequently asked questions I hear at the moment from practitioners: “How do I structure my memory bank?”, “How do I write a good specification and design document for AI?”.
|
||||
|
||||
But the term “spec-driven development” isn’t very well defined yet, and it’s already [semantically diffused](https://martinfowler.com/bliki/SemanticDiffusion.html). I’ve even recently heard people use “spec” basically as a synonym for “detailed prompt”.
|
||||
|
||||
Regarding the tools I’ve tried, I have listed many of my questions about their real world usefulness here. I wonder if some of them are trying to feed AI agents with our existing workflows too literally, ultimately amplifying existing challenges like review overload and hallucinations. Especially with the more elaborate approaches that create lots of files, I can’t help but think of the German compound word “Verschlimmbesserung”: Are we making something worse in the attempt of making it better?
|
||||
+164
@@ -0,0 +1,164 @@
|
||||
---
|
||||
title: "VectifyAI/PageIndex: 📑 PageIndex: Document Index for Vectorless, Reasoning-based RAG"
|
||||
source: "https://github.com/VectifyAI/PageIndex"
|
||||
author:
|
||||
- "[[rejojer]]"
|
||||
published:
|
||||
created: 2026-01-20
|
||||
description: "📑 PageIndex: Document Index for Vectorless, Reasoning-based RAG - VectifyAI/PageIndex"
|
||||
tags:
|
||||
- "clippings"
|
||||
- "webclipper"
|
||||
---
|
||||
> [!info] Source
|
||||
> URL: https://github.com/VectifyAI/PageIndex
|
||||
> Title: VectifyAI/PageIndex: 📑 PageIndex: Document Index for Vectorless, Reasoning-based RAG
|
||||
> Clipped:
|
||||
|
||||
**[PageIndex](https://github.com/VectifyAI/PageIndex)** Public
|
||||
|
||||
📑 PageIndex: Document Index for Vectorless, Reasoning-based RAG
|
||||
|
||||
[pageindex.ai](https://pageindex.ai/ "https://pageindex.ai")
|
||||
|
||||
[MIT license](https://github.com/VectifyAI/PageIndex/blob/main/LICENSE)
|
||||
|
||||
[Open in github.dev](https://github.dev/) [Open in a new github.dev tab](https://github.dev/) [Open in codespace](https://github.com/codespaces/new/VectifyAI/PageIndex?resume=1)
|
||||
|
||||
[](https://vectify.ai/pageindex)
|
||||
|
||||
|
||||
[](https://trendshift.io/repositories/14736)
|
||||
|
||||
**Reasoning-based RAG ◦ No Vector DB ◦ No Chunking ◦ Human-like Retrieval**
|
||||
|
||||
**🔥 Releases:**
|
||||
|
||||
- [**PageIndex Chat**](https://chat.pageindex.ai/): The first human-like document-analysis agent [platform](https://chat.pageindex.ai/) built for professional long documents. Can also be integrated via [MCP](https://pageindex.ai/mcp) or [API](https://docs.pageindex.ai/quickstart) (beta).
|
||||
|
||||
**📝 Articles:**
|
||||
|
||||
- [**PageIndex Framework**](https://pageindex.ai/blog/pageindex-intro): Introduces the PageIndex framework — an *agentic, in-context* *tree index* that enables LLMs to perform *reasoning-based*, *human-like retrieval* over long documents, without vector DB or chunking.
|
||||
|
||||
**🧪 Cookbooks:**
|
||||
|
||||
- [Vectorless RAG](https://docs.pageindex.ai/cookbook/vectorless-rag-pageindex): A minimal, hands-on example of reasoning-based RAG using PageIndex. No vectors, no chunking, and human-like retrieval.
|
||||
- [Vision-based Vectorless RAG](https://docs.pageindex.ai/cookbook/vision-rag-pageindex): OCR-free, vision-only RAG with PageIndex's reasoning-native retrieval workflow that works directly over PDF page images.
|
||||
|
||||
---
|
||||
|
||||
Are you frustrated with vector database retrieval accuracy for long professional documents? Traditional vector-based RAG relies on semantic *similarity* rather than true *relevance*. But **similarity ≠ relevance** — what we truly need in retrieval is **relevance**, and that requires **reasoning**. When working with professional documents that demand domain expertise and multi-step reasoning, similarity search often falls short.
|
||||
|
||||
Inspired by AlphaGo, we propose **[PageIndex](https://vectify.ai/pageindex)** — a **vectorless**, **reasoning-based RAG** system that builds a **hierarchical tree index** from long documents and uses LLMs to **reason** *over that index* for **agentic, context-aware retrieval**. It simulates how *human experts* navigate and extract knowledge from complex documents through *tree search*, enabling LLMs to *think* and *reason* their way to the most relevant document sections. PageIndex performs retrieval in two steps:
|
||||
|
||||
1. Generate a “Table-of-Contents” **tree structure index** of documents
|
||||
2. Perform reasoning-based retrieval through **tree search**
|
||||
|
||||
[](https://pageindex.ai/blog/pageindex-intro "The PageIndex Framework")
|
||||
|
||||
### 🎯 Features
|
||||
|
||||
Compared to traditional vector-based RAG, **PageIndex** features:
|
||||
|
||||
- **No Vector DB**: Uses document structure and LLM reasoning for retrieval, instead of vector similarity search.
|
||||
- **No Chunking**: Documents are organized into natural sections, not artificial chunks.
|
||||
- **Human-like Retrieval**: Simulates how human experts navigate and extract knowledge from complex documents.
|
||||
- **Better Explainability and Traceability**: Retrieval is based on reasoning — traceable and interpretable, with page and section references. No more opaque, approximate vector search (“vibe retrieval”).
|
||||
|
||||
PageIndex powers a reasoning-based RAG system that achieved **state-of-the-art** [98.7% accuracy](https://github.com/VectifyAI/Mafin2.5-FinanceBench) on FinanceBench, demonstrating superior performance over vector-based RAG solutions in professional document analysis (see our [blog post](https://vectify.ai/blog/Mafin2.5) for details).
|
||||
|
||||
To learn more, please see a detailed introduction of the [PageIndex framework](https://pageindex.ai/blog/pageindex-intro). Check out this GitHub repo for open-source code, and the [cookbooks](https://docs.pageindex.ai/cookbook), [tutorials](https://docs.pageindex.ai/tutorials), and [blog](https://pageindex.ai/blog) for additional usage guides and examples.
|
||||
|
||||
The PageIndex service is available as a ChatGPT-style [chat platform](https://chat.pageindex.ai/), or can be integrated via [MCP](https://pageindex.ai/mcp) or [API](https://docs.pageindex.ai/quickstart).
|
||||
|
||||
- Self-host — run locally with this open-source repo.
|
||||
- Cloud Service — try instantly with our [Chat Platform](https://chat.pageindex.ai/), or integrate with [MCP](https://pageindex.ai/mcp) or [API](https://docs.pageindex.ai/quickstart).
|
||||
- *Enterprise* — private or on-prem deployment. [Contact us](https://ii2abc2jejf.typeform.com/to/tK3AXl8T) or [book a demo](https://calendly.com/pageindex/meet) for more details.
|
||||
- Try the [**Vectorless RAG**](https://github.com/VectifyAI/PageIndex/blob/main/cookbook/pageindex_RAG_simple.ipynb) notebook — a *minimal*, hands-on example of reasoning-based RAG using PageIndex.
|
||||
- Experiment with [*Vision-based Vectorless RAG*](https://github.com/VectifyAI/PageIndex/blob/main/cookbook/vision_RAG_pageindex.ipynb) — no OCR; a minimal, reasoning-native RAG pipeline that works directly over page images.
|
||||
|
||||
---
|
||||
|
||||
PageIndex can transform lengthy PDF documents into a semantic **tree structure**, similar to a *"table of contents"* but optimized for use with Large Language Models (LLMs). It's ideal for: financial reports, regulatory filings, academic textbooks, legal or technical manuals, and any document that exceeds LLM context limits.
|
||||
|
||||
Below is an example PageIndex tree structure. Also see more example [documents](https://github.com/VectifyAI/PageIndex/tree/main/tests/pdfs) and generated [tree structures](https://github.com/VectifyAI/PageIndex/tree/main/tests/results).
|
||||
|
||||
You can generate the PageIndex tree structure with this open-source repo, or use our [API](https://docs.pageindex.ai/quickstart)
|
||||
|
||||
---
|
||||
|
||||
You can follow these steps to generate a PageIndex tree from a PDF document.
|
||||
|
||||
```
|
||||
pip3 install --upgrade -r requirements.txt
|
||||
```
|
||||
|
||||
Create a `.env` file in the root directory and add your API key:
|
||||
|
||||
```
|
||||
CHATGPT_API_KEY=your_openai_key_here
|
||||
```
|
||||
```
|
||||
python3 run_pageindex.py --pdf_path /path/to/your/document.pdf
|
||||
```
|
||||
**Optional parameters**
|
||||
You can customize the processing with additional optional arguments:
|
||||
|
||||
```
|
||||
--model OpenAI model to use (default: gpt-4o-2024-11-20)
|
||||
--toc-check-pages Pages to check for table of contents (default: 20)
|
||||
--max-pages-per-node Max pages per node (default: 10)
|
||||
--max-tokens-per-node Max tokens per node (default: 20000)
|
||||
--if-add-node-id Add node ID (yes/no, default: yes)
|
||||
--if-add-node-summary Add node summary (yes/no, default: yes)
|
||||
--if-add-doc-description Add doc description (yes/no, default: yes)
|
||||
```
|
||||
|
||||
**Markdown support**
|
||||
We also provide markdown support for PageIndex. You can use the \`-md\_path\` flag to generate a tree structure for a markdown file.
|
||||
```
|
||||
python3 run_pageindex.py --md_path /path/to/your/document.md
|
||||
```
|
||||
|
||||
> Note: in this function, we use "#" to determine node heading and their levels. For example, "##" is level 2, "###" is level 3, etc. Make sure your markdown file is formatted correctly. If your Markdown file was converted from a PDF or HTML, we don't recommend using this function, since most existing conversion tools cannot preserve the original hierarchy. Instead, use our [PageIndex OCR](https://pageindex.ai/blog/ocr), which is designed to preserve the original hierarchy, to convert the PDF to a markdown file and then use this function.
|
||||
|
||||
---
|
||||
|
||||
[Mafin 2.5](https://vectify.ai/mafin) is a reasoning-based RAG system for financial document analysis, powered by **PageIndex**. It achieved a state-of-the-art [**98.7% accuracy**](https://vectify.ai/blog/Mafin2.5) on the [FinanceBench](https://arxiv.org/abs/2311.11944) benchmark, significantly outperforming traditional vector-based RAG systems.
|
||||
|
||||
PageIndex's hierarchical indexing and reasoning-driven retrieval enable precise navigation and extraction of relevant context from complex financial reports, such as SEC filings and earnings disclosures.
|
||||
|
||||
Explore the full [benchmark results](https://github.com/VectifyAI/Mafin2.5-FinanceBench) and our [blog post](https://vectify.ai/blog/Mafin2.5) for detailed comparisons and performance metrics.
|
||||
|
||||
[](https://github.com/VectifyAI/Mafin2.5-FinanceBench)
|
||||
|
||||
---
|
||||
|
||||
## 🧭 Resources
|
||||
|
||||
- 🧪 [Cookbooks](https://docs.pageindex.ai/cookbook/vectorless-rag-pageindex): hands-on, runnable examples and advanced use cases.
|
||||
- 📖 [Tutorials](https://docs.pageindex.ai/doc-search): practical guides and strategies, including *Document Search* and *Tree Search*.
|
||||
- 📝 [Blog](https://pageindex.ai/blog): technical articles, research insights, and product updates.
|
||||
- 🔌 [MCP setup](https://pageindex.ai/mcp#quick-setup) & [API docs](https://docs.pageindex.ai/quickstart): integration details and configuration options.
|
||||
|
||||
---
|
||||
|
||||
Leave us a star 🌟 if you like our project. Thank you!
|
||||
|
||||
[](https://private-user-images.githubusercontent.com/13518252/481667856-eae4ff38-48ae-4a7c-b19f-eab81201d794.gif?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3Njg4NzI2MzYsIm5iZiI6MTc2ODg3MjMzNiwicGF0aCI6Ii8xMzUxODI1Mi80ODE2Njc4NTYtZWFlNGZmMzgtNDhhZS00YTdjLWIxOWYtZWFiODEyMDFkNzk0LmdpZj9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNjAxMjAlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjYwMTIwVDAxMjUzNlomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPWEyNzA4ZDQxMmI2MjhiOGVkODU3MTMxOWFhNTE0Mjg4MzdkOWI3N2Q4ZmY4MTY2MDk3NDZlZjE1YzcwNWJlZjkmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0In0.pSfTU0Lp63eIF6U3IbkEbdIwr2_U4ZL708xLqslt8uQ)
|
||||
|
||||
---
|
||||
|
||||
© 2025 [Vectify AI](https://vectify.ai/)
|
||||
|
||||
## Releases
|
||||
|
||||
No releases published
|
||||
|
||||
## Packages
|
||||
|
||||
No packages published
|
||||
|
||||
## Languages
|
||||
|
||||
- [Python 100.0%](https://github.com/VectifyAI/PageIndex/search?l=python)
|
||||
@@ -0,0 +1,124 @@
|
||||
---
|
||||
title: "Welcome to LessWrong! — LessWrong"
|
||||
source: "https://www.lesswrong.com/posts/bJ2haLkcGeLtTWaD5/welcome-to-lesswrong"
|
||||
author:
|
||||
- "[[Ruby]]"
|
||||
published: 2019-06-15
|
||||
created: 2026-01-16
|
||||
description: "The road to wisdom? Well, it's plainand simple to express: • Errand errand err againbut lessand lessand less. • – Piet Hein …"
|
||||
tags:
|
||||
- "clippings"
|
||||
- "webclipper"
|
||||
---
|
||||
> [!info] Source
|
||||
> URL: https://www.lesswrong.com/posts/bJ2haLkcGeLtTWaD5/welcome-to-lesswrong
|
||||
> Title: Welcome to LessWrong! — LessWrong
|
||||
> Clipped:
|
||||
|
||||
| *The road to wisdom? Well, it's plain 通往智慧的道路？好吧，它显而易见* *and simple to express: 且易于表达：* *Err 犯错* *and err 以及犯错的智慧* *and err again 并再次犯错* *but **less** 但更少* *and **less** 越来越少* *and **less**.越少越好* – Piet Hein – 彼得·海恩 |
|
||||
| --- |
|
||||
|
||||
LessWrong is an online forum and community dedicated to improving human reasoning and decision-making. We seek to hold true beliefs and to be effective at accomplishing our goals. Each day, we aim to be less wrong about the world than the day before.
|
||||
LessWrong 是一个致力于提升人类推理与决策能力的在线论坛和社区。我们力求持有正确的信念，并高效实现目标。每一天，我们都努力让自己对世界的认识比前一天更少错误。
|
||||
|
||||
*See also our* [*New User's Guide*](https://www.lesswrong.com/posts/LbbrnRvc9QwjJeics/new-user-s-guide-to-lesswrong)
|
||||
也可参见我们的新用户指南*.*
|
||||
|
||||
## Training Rationality 训练理性
|
||||
|
||||
Rationality has a number of definitions [^1] on LessWrong, but perhaps the most canonical is that the more rational you are, the more likely your reasoning leads you to have accurate beliefs, and by extension, allows you to make decisions that most effectively advance your goals.
|
||||
在 LessWrong 上，理性有多种定义 <sup><span><a href="https://www.lesswrong.com/posts/bJ2haLkcGeLtTWaD5/#fnajdy57uko9d">[1]</a></span></sup> ，但或许最经典的诠释是：你的理性程度越高，你的推理过程就越有可能助你获得准确的信念，进而让你能够做出最有效推动目标达成的决策。
|
||||
|
||||
LessWrong contains a lot of content on this topic. How minds work (both human, artificial, and theoretical ideal), how to reason better, and how to have discussions that are productive. We're very big fans of [Bayes Theorem](https://www.lesswrong.com/w/bayes_rule?l=1zq) and other theories of normatively correct reasoning [^2].
|
||||
LessWrong 包含大量关于此主题的内容，涉及心智如何运作（包括人类心智、人工心智以及理论上的理想心智）、如何更好地推理，以及如何进行富有成效的讨论。我们非常推崇贝叶斯定理和其他规范性正确推理理论。
|
||||
|
||||
To get started improving your Rationality, we recommend reading the background-knowledge text of LessWrong, [Rationality: A-Z](https://www.lesswrong.com/rationality) (aka "The Sequences") or at least [selected highlights](https://www.lesswrong.com/highlights) from it. After that, looking through the Rationality section of the [Concepts Portal](https://www.lesswrong.com/concepts) is a good thing to do.
|
||||
要开始提升你的理性思维，我们建议先阅读 LessWrong 的背景知识文本《理性：从 A 到 Z》（又称“The Sequences”），或者至少阅读其中的精选亮点部分。之后，浏览概念门户的理性部分是很好的下一步。
|
||||
|
||||
## Applying Rationality 运用理性
|
||||
|
||||
You might value Rationality for its own sake, however, many people want to be better reasoners so they can have more accurate beliefs about topics they care about, and make better decisions.
|
||||
您可能因理性本身的价值而珍视它，然而，许多人希望成为更出色的推理者，以便能在他们关心的话题上拥有更准确的信念，并做出更明智的决策。
|
||||
|
||||
Using LessWrong-style reasoning, contributors to LessWrong have written essays on an immense variety of topics on LessWrong, each time approaching the topic with a desire to know what's actually true (not just what's convenient or pleasant to believe), being deliberate about processing the evidence, and avoiding common pitfalls of human reason.
|
||||
在 LessWrong，投稿者运用 LessWrong 风格的推理，针对极其多样的主题撰写了大量文章。每一次探讨主题时，他们都怀有探究真实（而非仅仅相信便捷或令人愉悦的观点）的渴望，审慎地处理证据，并避开人类推理中常见的陷阱。
|
||||
|
||||
Check out the [Concepts Portal](https://www.lesswrong.com/concepts) to find essays on topics such as [artificial intelligence](https://www.lesswrong.com/w/ai), [history](https://www.lesswrong.com/w/history), [philosophy of science](https://www.lesswrong.com/w/practice-and-philosophy-of-science), [language](https://www.lesswrong.com/w/philosophy-of-language), [psychology](https://www.lesswrong.com/w/psychology), [biology](https://www.lesswrong.com/w/biology), [morality](https://www.lesswrong.com/w/ethics-and-morality), [culture](https://www.lesswrong.com/w/social-and-cultural-dynamics), [self-care](https://www.lesswrong.com/w/well-being), [economics](https://www.lesswrong.com/w/economics), [game theory](https://www.lesswrong.com/w/game-theory), [productivity](https://www.lesswrong.com/w/productivity), [art](https://www.lesswrong.com/w/art), [nutrition](https://www.lesswrong.com/w/nutrition), [relationships](https://www.lesswrong.com/w/relationships-interpersonal) and hundreds of other topics broad and narrow.
|
||||
查阅概念门户，探索人工智能、历史、科学哲学、语言、心理学、生物学、道德、文化、自我关怀、经济学、博弈论、生产力、艺术、营养、人际关系以及数百种主题广泛或专精的文章。
|
||||
|
||||
## LessWrong and Artificial Intelligence"少错"社区与人工智能
|
||||
|
||||
For several reasons, LessWrong is a website and community with a strong interest in AI and specifically causing powerful AI systems to be safe and beneficial.
|
||||
出于多种原因，LessWrong 作为一个网站及社群，对人工智能领域抱有浓厚兴趣，尤其关注如何确保强大的人工智能系统安全且有益。
|
||||
|
||||
- AI is a field concerned with how minds and intelligence works, overlapping a lot with rationality.
|
||||
人工智能这一领域探讨意识与智能的运行机制，与理性思维研究存在大量交集。
|
||||
- Historically, LessWrong was seeded by the writings of Eliezer Yudkowsky, an artificial intelligence researcher.
|
||||
回溯历史，LessWrong 最初源自人工智能研究者埃利泽·尤德考斯基的系列著作。
|
||||
- Many members of the LessWrong community are heavily motivated by trying to improve the world as much as possible, and these people were convinced many years ago that AI was a very big deal for the future of humanity. Since then LessWrong has hosted a lot of discussion of AI Alignment/AI Safety, and that's only accelerated recently with further AI capabilities developments.
|
||||
LessWrong 社区中的许多成员都深受改善世界的强烈动机驱动，这些人多年前就已确信人工智能将对人类的未来产生深远影响。自那时起，LessWrong 便承载了大量关于人工智能对齐与安全性的讨论，而随着近期人工智能能力的进一步发展，这一讨论趋势正在加速。
|
||||
- LessWrong is also integrated with the [Alignment Forum](https://www.alignmentforum.org/about)
|
||||
LessWrong 还与 Alignment Forum 紧密集成。
|
||||
- The LessWrong team who maintain and develop the site are predominantly motivated by trying to cause powerful AI outcomes to be good.
|
||||
维护和开发此网站的 LessWrong 团队，主要动力源于努力促使强大的人工智能带来积极成果。
|
||||
|
||||
If you want to see more or less AI content, you can adjust your Frontpage Tag Filters according to taste [^3].
|
||||
若您希望调整人工智能相关内容的显示频率，可根据个人喜好通过首页标签筛选功能进行设置 <sup><span><a href="https://www.lesswrong.com/posts/bJ2haLkcGeLtTWaD5/#fnq85givw8h9">[3]</a></span></sup> 。
|
||||
|
||||
## Getting Started on LessWrong开启 LessWrong 之旅
|
||||
|
||||
The [New User's Guide](https://www.lesswrong.com/posts/LbbrnRvc9QwjJeics/new-user-s-guide-to-lesswrong) is a great place to start.
|
||||
《新手指南》是极佳的入门起点。
|
||||
|
||||
The core background text of LessWrong is the collection of essays, [Rationality: A-Z](https://www.lesswrong.com/rationality) (aka "The Sequences"). Reading these will help you understand the mindset and philosophy that defines the site. Those looking for a quick introduction can start with [The Sequences Highlights](https://www.lesswrong.com/highlights)
|
||||
LessWrong 的核心背景文本是文集《理性：从 A 到 Z》（亦称“序列系列”）。阅读这些文章将帮助您理解定义本网站思维方式与哲学理念。寻求快速入门者可先阅读《序列精选》
|
||||
|
||||
Other top writings include [The Codex](https://www.lesswrong.com/codex) (writings by Scott Alexander) and [Harry Potter & The Methods of Rationality](https://www.lesswrong.com/hpmor). Also see the [Library Page](https://www.lesswrong.com/library) for many curated collections of posts and the [Concepts Portal.](https://www.lesswrong.com/concepts)
|
||||
其他重要作品包括《秘典集》（斯科特·亚历山大文集）与《哈利波特与理性之道》。您亦可通过文库页查阅众多精选文章合集，或浏览概念门户获取系统知识。
|
||||
|
||||
Also, feel free to introduce yourself in the monthly [open and welcome thread](https://www.lesswrong.com/w/open-threads?sortedBy=new)!
|
||||
也欢迎你随时在每月开放欢迎贴中自我介绍！
|
||||
|
||||
Lastly, we do recommend that new contributors (posters or commenters) take time to familiarize themselves with the sites norms and culture to maximize the chances that your contributions are well-received.
|
||||
最后，我们确实建议新贡献者（无论是发布文章还是评论）花时间熟悉本站的规范和文化，这样能最大限度地让你的贡献受到欢迎。
|
||||
|
||||
Thanks for your interest!
|
||||
感谢你的关注！
|
||||
|
||||
\- The LW Team
|
||||
\- LW 团队
|
||||
|
||||
- [**LessWrong FAQ LessWrong 常见问题**](https://www.lesswrong.com/posts/2rWKkWuPrgTMpLRbp/lesswrong-faq)
|
||||
- [**A Brief History of LessWrong
|
||||
LessWrong 简史**](https://www.lesswrong.com/posts/S69ogAGXcc9EQjpcZ/a-brief-history-of-lesswrong)
|
||||
- [**Team 团队**](https://www.lesswrong.com/posts/aG74jJkiPccqdkK3c/the-lesswrong-team-page-under-construction)
|
||||
- [**LessWrong Concepts LessWrong 概念**](https://www.lesswrong.com/concepts)
|
||||
|
||||
x
|
||||
|
||||
[^1]: Definitions of Rationality as used on LessWrong include:
|
||||
LessWrong 中使用的理性定义包括：
|
||||
|
||||
\- Rationality is thinking in ways that systematically arrive at truth.
|
||||
\- 理性是系统性地抵达真理的思维方式。
|
||||
|
||||
\- Rationality is thinking in ways that cause you to systematically achieve your goals.
|
||||
\- 理性是系统性地帮助你达成目标的思维方式。
|
||||
|
||||
\- Rationality is trying to do better on purpose.
|
||||
\- 理性意味着要有意为之，力求做得更好。
|
||||
|
||||
\- Rationality is reasoning well even in the face of massive uncertainty.
|
||||
\- 理性意味着即便面对巨大的不确定性，仍能进行良好的推理。
|
||||
|
||||
\- Rationality is making good decisions even when it’s hard.
|
||||
\- 理性意味着即便在艰难时刻，也能做出明智的决策。
|
||||
|
||||
\-Rationality is being self-aware, understanding how your own mind works, and applying this knowledge to thinking better.
|
||||
\- 理性意味着保持自我觉察，理解自身心智的运作方式，并运用这些知识来更好地思考。
|
||||
|
||||
[^2]: There are in fact laws of thought no less ironclad than the law of physics \[[source](https://www.lesswrong.com/posts/QkX2bAkwG2EpGvNug/the-second-law-of-thermodynamics-and-engines-of-cognition)\].
|
||||
事实上，思维的法则与物理定律同样牢不可破【来源】。
|
||||
|
||||
[^3]: Hover your mouse over the tags to be able to adjust their weighting in your Latest Posts feed.
|
||||
将鼠标悬停在标签上，即可在“最新帖子”动态中调整其权重。
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
title: "YAGNI Principle in Software Development"
|
||||
source: "https://www.geeksforgeeks.org/software-engineering/what-is-yagni-principle-you-arent-gonna-need-it/"
|
||||
author:
|
||||
- "[[GeeksforGeeks]]"
|
||||
published: 2024-02-20
|
||||
created: 2026-01-22
|
||||
description: "Your All-in-One Learning Portal: GeeksforGeeks is a comprehensive educational platform that empowers learners across domains-spanning computer science and programming, school education, upskilling, commerce, software tools, competitive exams, and more."
|
||||
tags:
|
||||
- "clippings"
|
||||
- "webclipper"
|
||||
---
|
||||
> [!info] Source
|
||||
> URL: https://www.geeksforgeeks.org/software-engineering/what-is-yagni-principle-you-arent-gonna-need-it/
|
||||
> Title: YAGNI Principle in Software Development
|
||||
> Clipped:
|
||||
|
||||
页面已保存到 Trilium。 [在 Trilium 中打开。](https://www.geeksforgeeks.org/software-engineering/what-is-yagni-principle-you-arent-gonna-need-it/)
|
||||
|
||||
Last Updated: 27 Aug, 2025
|
||||
|
||||
****"YAGNI"**** stands for ****"You Aren't Gonna Need It".**** It is a principle in software development that suggests developers should only implement features that are necessary for the current requirements and not add any additional functionality that might be needed in the future.
|
||||
|
||||
- This principle is based on the idea that adding unnecessary features can lead to increased complexity, longer development times, and potentially more bugs.
|
||||
- The YAGNI principle is closely related to the ****"**** [****KISS****](https://www.geeksforgeeks.org/software-engineering/kiss-principle-in-software-development/) ****"**** principle ("Keep It Simple, Stupid"), which advocates for simplicity in design and avoiding unnecessary complexity. Both principles encourage developers to focus on delivering the simplest solution that meets current requirements, rather than trying to anticipate and accommodate potential future needs.
|
||||
|
||||
### Why a developer should follow the YAGNI principle?
|
||||
|
||||
The developer should follow YAGNI principles for the following reasons:
|
||||
|
||||
|
||||
- ****Cost of Building:**** The cost of build is the amount of time, effort, and resources spent on creating a feature or solution. It includes everything from planning and coding to testing.
|
||||
- ****Cost of Delay:**** The cost of delay is the missed opportunity or economic impact of not delivering a feature or solution promptly.
|
||||
- ****Cost of Carry:**** When a feature adds complexity, it can make it harder to work on other parts of the software, leading to additional time and effort.
|
||||
- ****Cost of Repair:**** The cost of repair, also known as technical debt, is the ongoing cost associated with fixing mistakes, bugs, or poor choices made during the development of a feature.
|
||||
|
||||
### Steps to follow YAGNI Principle
|
||||
|
||||
To use YAGNI as a developer, it's like having a practical guide to keep your work focused and efficient.
|
||||
|
||||
|
||||
|
||||
YAGNI Principal for Developers
|
||||
|
||||
****1\. Get the Necessary Requirements**** : All the things your project needs and sort them into "must-haves" and "can wait."
|
||||
|
||||
****2\. Discuss with Your Team:**** After that, it's time to talk with your team. Share your plans and goals with them. This makes sure everyone is on the same page and understands what needs to be done.
|
||||
|
||||
****3\. Analyze a Simple Plan for the Solution:**** Now, when it comes to planning the actual work, keep it simple. Break down your big goals into smaller tasks. This helps you avoid getting overwhelmed and ensures you're focusing on what really matters.
|
||||
|
||||
****4\. Refuse If It Doesn't Fit for the Solution:**** Sometimes, your team might come up with new ideas or want to add extra things. While these ideas might be cool, you've got to be ready to say "no" unless it's a tiny improvement. Saying "no" can be tough, but it keeps you from getting off track and missing deadlines.
|
||||
|
||||
****5\. Have a Record of Your Progress:**** Keep a record of what you've done. It's like keeping score in a game. This helps you see how far you've come and if you're heading in the right direction.
|
||||
|
||||
### Advantages of Applying YAGNI
|
||||
|
||||
- ****Reduced Development Time****: By avoiding the development of unused features, teams can focus on current requirements and accelerate the delivery of functional software.
|
||||
- ****Improved Maintainability:**** Simpler, more focused codebases are easier to understand and maintain over time.
|
||||
- ****Increased Flexibility:**** The ability to defer decisions until later provides more clarity and allows for more informed design choices as requirements become clearer.
|
||||
- ****Fewer Bugs:**** Less complex code with fewer speculative features is less prone to bugs, leading to a higher quality product
|
||||
|
||||
Overall, YAGNI complements other software development principles by focusing on delivering the simplest solution that meets the current requirements and avoiding unnecessary functionality.
|
||||
|
||||
Article Tags:
|
||||
+1773
File diff suppressed because it is too large
Load Diff
+151
File diff suppressed because one or more lines are too long
+626
@@ -0,0 +1,626 @@
|
||||
---
|
||||
title: "github/spec-kit: 💫 Toolkit to help you get started with Spec-Driven Development"
|
||||
source: "https://github.com/github/spec-kit"
|
||||
author:
|
||||
- "[[localden]]"
|
||||
published:
|
||||
created: 2026-01-21
|
||||
description: "💫 Toolkit to help you get started with Spec-Driven Development - github/spec-kit"
|
||||
tags:
|
||||
- "clippings"
|
||||
- "webclipper"
|
||||
---
|
||||
> [!info] Source
|
||||
> URL: https://github.com/github/spec-kit
|
||||
> Title: github/spec-kit: 💫 Toolkit to help you get started with Spec-Driven Development
|
||||
> Clipped:
|
||||
|
||||
**[spec-kit](https://github.com/github/spec-kit)** Public
|
||||
|
||||
💫 Toolkit to help you get started with Spec-Driven Development
|
||||
|
||||
[MIT license](https://github.com/github/spec-kit/blob/main/LICENSE)
|
||||
|
||||
[Code of conduct](https://github.com/github/spec-kit/blob/main/CODE_OF_CONDUCT.md)
|
||||
|
||||
[Contributing](https://github.com/github/spec-kit/blob/main/CONTRIBUTING.md)
|
||||
|
||||
[Security policy](https://github.com/github/spec-kit/blob/main/SECURITY.md)
|
||||
|
||||
[63.9k stars](https://github.com/github/spec-kit/stargazers) [5.5k forks](https://github.com/github/spec-kit/forks) [443 watching](https://github.com/github/spec-kit/watchers) [Branches](https://github.com/github/spec-kit/branches) [Tags](https://github.com/github/spec-kit/tags) [Activity](https://github.com/github/spec-kit/activity) [Custom properties](https://github.com/github/spec-kit/custom-properties)
|
||||
|
||||
Public repository
|
||||
|
||||
[Open in github.dev](https://github.dev/) [Open in a new github.dev tab](https://github.dev/) [Open in codespace](https://github.com/codespaces/new/github/spec-kit?resume=1)
|
||||
|
||||
<table><thead><tr><th colspan="2"><span>Name</span></th><th colspan="1"><span>Name</span></th><th><p><span>Last commit message</span></p></th><th colspan="1"><p><span>Last commit date</span></p></th></tr></thead><tbody><tr><td colspan="3"><p><span><a href="https://github.com/github/spec-kit/commit/9111699cd27879e3e6301651a03e502ecb6dd65d">Merge pull request</a> <a href="https://github.com/github/spec-kit/pull/1288">#1288</a> <a href="https://github.com/github/spec-kit/commit/9111699cd27879e3e6301651a03e502ecb6dd65d">from github/localden/updates</a></span></p><p><span><a href="https://github.com/github/spec-kit/commit/9111699cd27879e3e6301651a03e502ecb6dd65d">9111699</a> ·</span></p><p><a href="https://github.com/github/spec-kit/commits/main/"><span><span><span>528 Commits</span></span></span></a></p></td></tr><tr><td colspan="2"><p><a href="https://github.com/github/spec-kit/tree/main/.devcontainer">.devcontainer</a></p></td><td colspan="1"><p><a href="https://github.com/github/spec-kit/tree/main/.devcontainer">.devcontainer</a></p></td><td><p><a href="https://github.com/github/spec-kit/commit/71c2c63d555ea5b86e1498f6e572023bc01ff98d">chore: replace <code>bun</code> by <code>node/npm</code> in the <code>devcontainer</code> (as many CLI…</a></p></td><td></td></tr><tr><td colspan="2"><p><a href="https://github.com/github/spec-kit/tree/main/.github">.github</a></p></td><td colspan="1"><p><a href="https://github.com/github/spec-kit/tree/main/.github">.github</a></p></td><td><p><a href="https://github.com/github/spec-kit/commit/8d552e6d116801a2b3cac203405a0a469257ac2c">feat:qoder agent</a></p></td><td></td></tr><tr><td colspan="2"><p><a href="https://github.com/github/spec-kit/tree/main/docs">docs</a></p></td><td colspan="1"><p><a href="https://github.com/github/spec-kit/tree/main/docs">docs</a></p></td><td><p><a href="https://github.com/github/spec-kit/commit/0049b1cdc2f9ba12def39a042872b0b1b6a09704">Update Markdown formatting</a></p></td><td></td></tr><tr><td colspan="2"><p><a href="https://github.com/github/spec-kit/tree/main/media">media</a></p></td><td colspan="1"><p><a href="https://github.com/github/spec-kit/tree/main/media">media</a></p></td><td><p><a href="https://github.com/github/spec-kit/commit/f892b9e1cb21d3cd971c98cebea3270d7d167d7c">fix: broken media files</a></p></td><td></td></tr><tr><td colspan="2"><p><a href="https://github.com/github/spec-kit/tree/main/memory">memory</a></p></td><td colspan="1"><p><a href="https://github.com/github/spec-kit/tree/main/memory">memory</a></p></td><td><p><a href="https://github.com/github/spec-kit/commit/36ff7e6505ae49eee73a01c2d3dd31752f73ad5d">Update files</a></p></td><td></td></tr><tr><td colspan="2"><p><a href="https://github.com/github/spec-kit/tree/main/scripts">scripts</a></p></td><td colspan="1"><p><a href="https://github.com/github/spec-kit/tree/main/scripts">scripts</a></p></td><td><p><a href="https://github.com/github/spec-kit/commit/6c3d698959bd9a8b50588f93c1bffb517fc6d5a0">Merge pull request</a> <a href="https://github.com/github/spec-kit/pull/1237">#1237</a> <a href="https://github.com/github/spec-kit/commit/6c3d698959bd9a8b50588f93c1bffb517fc6d5a0">from Mearman/fix/branch-number-collision-bug</a></p></td><td></td></tr><tr><td colspan="2"><p><a href="https://github.com/github/spec-kit/tree/main/src/specify_cli"><span>src/</span> <span>specify_cli</span></a></p></td><td colspan="1"><p><a href="https://github.com/github/spec-kit/tree/main/src/specify_cli"><span>src/</span> <span>specify_cli</span></a></p></td><td><p><a href="https://github.com/github/spec-kit/commit/ad3bb1a5fed2f8a8e5a569b9927a784691cee501">resolve confilct and add qoder agent</a></p></td><td></td></tr><tr><td colspan="2"><p><a href="https://github.com/github/spec-kit/tree/main/templates">templates</a></p></td><td colspan="1"><p><a href="https://github.com/github/spec-kit/tree/main/templates">templates</a></p></td><td><p><a href="https://github.com/github/spec-kit/commit/0049b1cdc2f9ba12def39a042872b0b1b6a09704">Update Markdown formatting</a></p></td><td></td></tr><tr><td colspan="2"><p><a href="https://github.com/github/spec-kit/blob/main/.gitattributes">.gitattributes</a></p></td><td colspan="1"><p><a href="https://github.com/github/spec-kit/blob/main/.gitattributes">.gitattributes</a></p></td><td><p><a href="https://github.com/github/spec-kit/commit/36ff7e6505ae49eee73a01c2d3dd31752f73ad5d">Update files</a></p></td><td></td></tr><tr><td colspan="2"><p><a href="https://github.com/github/spec-kit/blob/main/.gitignore">.gitignore</a></p></td><td colspan="1"><p><a href="https://github.com/github/spec-kit/blob/main/.gitignore">.gitignore</a></p></td><td><p><a href="https://github.com/github/spec-kit/commit/392dbf20c4a6589cf2df6b8627e6beac2773e878">docs: Add comprehensive upgrading guide for Spec Kit</a></p></td><td></td></tr><tr><td colspan="3"></td></tr></tbody></table>
|
||||
|
||||
[](https://github.com/github/spec-kit/blob/main/media/logo_large.webp)
|
||||
|
||||
**An open source toolkit that allows you to focus on product scenarios and predictable outcomes instead of vibe coding every piece from scratch.**
|
||||
|
||||
---
|
||||
|
||||
- [🤔 What is Spec-Driven Development?](https://github.com/github/#-what-is-spec-driven-development)
|
||||
- [⚡ Get Started](https://github.com/github/#-get-started)
|
||||
- [📽️ Video Overview](https://github.com/github/#%EF%B8%8F-video-overview)
|
||||
- [🤖 Supported AI Agents](https://github.com/github/#-supported-ai-agents)
|
||||
- [🔧 Specify CLI Reference](https://github.com/github/#-specify-cli-reference)
|
||||
- [📚 Core Philosophy](https://github.com/github/#-core-philosophy)
|
||||
- [🌟 Development Phases](https://github.com/github/#-development-phases)
|
||||
- [🎯 Experimental Goals](https://github.com/github/#-experimental-goals)
|
||||
- [🔧 Prerequisites](https://github.com/github/#-prerequisites)
|
||||
- [📖 Learn More](https://github.com/github/#-learn-more)
|
||||
- [📋 Detailed Process](https://github.com/github/#-detailed-process)
|
||||
- [🔍 Troubleshooting](https://github.com/github/#-troubleshooting)
|
||||
- [👥 Maintainers](https://github.com/github/#-maintainers)
|
||||
- [💬 Support](https://github.com/github/#-support)
|
||||
- [🙏 Acknowledgements](https://github.com/github/#-acknowledgements)
|
||||
- [📄 License](https://github.com/github/#-license)
|
||||
|
||||
Spec-Driven Development **flips the script** on traditional software development. For decades, code has been king — specifications were just scaffolding we built and discarded once the "real work" of coding began. Spec-Driven Development changes this: **specifications become executable**, directly generating working implementations rather than just guiding them.
|
||||
|
||||
Choose your preferred installation method:
|
||||
|
||||
Install once and use everywhere:
|
||||
|
||||
```
|
||||
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
|
||||
```
|
||||
|
||||
Then use the tool directly:
|
||||
|
||||
```
|
||||
# Create new project
|
||||
specify init <PROJECT_NAME>
|
||||
|
||||
# Or initialize in existing project
|
||||
specify init . --ai claude
|
||||
# or
|
||||
specify init --here --ai claude
|
||||
|
||||
# Check installed tools
|
||||
specify check
|
||||
```
|
||||
|
||||
To upgrade Specify, see the [Upgrade Guide](https://github.com/github/spec-kit/blob/main/docs/upgrade.md) for detailed instructions. Quick upgrade:
|
||||
|
||||
```
|
||||
uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git
|
||||
```
|
||||
|
||||
Run directly without installing:
|
||||
|
||||
```
|
||||
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>
|
||||
```
|
||||
|
||||
**Benefits of persistent installation:**
|
||||
|
||||
- Tool stays installed and available in PATH
|
||||
- No need to create shell aliases
|
||||
- Better tool management with `uv tool list`, `uv tool upgrade`, `uv tool uninstall`
|
||||
- Cleaner shell configuration
|
||||
|
||||
Launch your AI assistant in the project directory. The `/speckit.*` commands are available in the assistant.
|
||||
|
||||
Use the **`/speckit.constitution`** command to create your project's governing principles and development guidelines that will guide all subsequent development.
|
||||
|
||||
```
|
||||
/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements
|
||||
```
|
||||
|
||||
Use the **`/speckit.specify`** command to describe what you want to build. Focus on the **what** and **why**, not the tech stack.
|
||||
|
||||
```
|
||||
/speckit.specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page. Albums are never in other nested albums. Within each album, photos are previewed in a tile-like interface.
|
||||
```
|
||||
|
||||
Use the **`/speckit.plan`** command to provide your tech stack and architecture choices.
|
||||
|
||||
```
|
||||
/speckit.plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database.
|
||||
```
|
||||
|
||||
Use **`/speckit.tasks`** to create an actionable task list from your implementation plan.
|
||||
|
||||
```
|
||||
/speckit.tasks
|
||||
```
|
||||
|
||||
Use **`/speckit.implement`** to execute all tasks and build your feature according to the plan.
|
||||
|
||||
```
|
||||
/speckit.implement
|
||||
```
|
||||
|
||||
For detailed step-by-step instructions, see our [comprehensive guide](https://github.com/github/spec-kit/blob/main/spec-driven.md).
|
||||
|
||||
Want to see Spec Kit in action? Watch our [video overview](https://www.youtube.com/watch?v=a9eR1xsfvHg&pp=0gcJCckJAYcqIYzv)!
|
||||
|
||||
[](https://www.youtube.com/watch?v=a9eR1xsfvHg&pp=0gcJCckJAYcqIYzv)
|
||||
|
||||
| Agent | Support | Notes |
|
||||
| --- | --- | --- |
|
||||
| [Qoder CLI](https://qoder.com/cli) | ✅ | |
|
||||
| [Amazon Q Developer CLI](https://aws.amazon.com/developer/learning/q-developer-cli/) | ⚠️ | Amazon Q Developer CLI [does not support](https://github.com/aws/amazon-q-developer-cli/issues/3064) custom arguments for slash commands. |
|
||||
| [Amp](https://ampcode.com/) | ✅ | |
|
||||
| [Auggie CLI](https://docs.augmentcode.com/cli/overview) | ✅ | |
|
||||
| [Claude Code](https://www.anthropic.com/claude-code) | ✅ | |
|
||||
| [CodeBuddy CLI](https://www.codebuddy.ai/cli) | ✅ | |
|
||||
| [Codex CLI](https://github.com/openai/codex) | ✅ | |
|
||||
| [Cursor](https://cursor.sh/) | ✅ | |
|
||||
| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | ✅ | |
|
||||
| [GitHub Copilot](https://code.visualstudio.com/) | ✅ | |
|
||||
| [IBM Bob](https://www.ibm.com/products/bob) | ✅ | IDE-based agent with slash command support |
|
||||
| [Jules](https://jules.google.com/) | ✅ | |
|
||||
| [Kilo Code](https://github.com/Kilo-Org/kilocode) | ✅ | |
|
||||
| [opencode](https://opencode.ai/) | ✅ | |
|
||||
| [Qwen Code](https://github.com/QwenLM/qwen-code) | ✅ | |
|
||||
| [Roo Code](https://roocode.com/) | ✅ | |
|
||||
| [SHAI (OVHcloud)](https://github.com/ovh/shai) | ✅ | |
|
||||
| [Windsurf](https://windsurf.com/) | ✅ | |
|
||||
|
||||
The `specify` command supports the following options:
|
||||
|
||||
### Commands
|
||||
|
||||
| Command | Description |
|
||||
| --- | --- |
|
||||
| `init` | Initialize a new Specify project from the latest template |
|
||||
| `check` | Check for installed tools (`git`, `claude`, `gemini`, `code` / `code-insiders`, `cursor-agent`, `windsurf`, `qwen`, `opencode`, `codex`, `shai`, `qoder`) |
|
||||
|
||||
| Argument/Option | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| `<project-name>` | Argument | Name for your new project directory (optional if using `--here`, or use `.` for current directory) |
|
||||
| `--ai` | Option | AI assistant to use: `claude`, `gemini`, `copilot`, `cursor-agent`, `qwen`, `opencode`, `codex`, `windsurf`, `kilocode`, `auggie`, `roo`, `codebuddy`, `amp`, `shai`, `q`, `bob`, or `qoder` |
|
||||
| `--script` | Option | Script variant to use: `sh` (bash/zsh) or `ps` (PowerShell) |
|
||||
| `--ignore-agent-tools` | Flag | Skip checks for AI agent tools like Claude Code |
|
||||
| `--no-git` | Flag | Skip git repository initialization |
|
||||
| `--here` | Flag | Initialize project in the current directory instead of creating a new one |
|
||||
| `--force` | Flag | Force merge/overwrite when initializing in current directory (skip confirmation) |
|
||||
| `--skip-tls` | Flag | Skip SSL/TLS verification (not recommended) |
|
||||
| `--debug` | Flag | Enable detailed debug output for troubleshooting |
|
||||
| `--github-token` | Option | GitHub token for API requests (or set GH\_TOKEN/GITHUB\_TOKEN env variable) |
|
||||
|
||||
### Examples
|
||||
|
||||
```
|
||||
# Basic project initialization
|
||||
specify init my-project
|
||||
|
||||
# Initialize with specific AI assistant
|
||||
specify init my-project --ai claude
|
||||
|
||||
# Initialize with Cursor support
|
||||
specify init my-project --ai cursor-agent
|
||||
|
||||
# Initialize with Qoder support
|
||||
specify init my-project --ai qoder
|
||||
|
||||
# Initialize with Windsurf support
|
||||
specify init my-project --ai windsurf
|
||||
|
||||
# Initialize with Amp support
|
||||
specify init my-project --ai amp
|
||||
|
||||
# Initialize with SHAI support
|
||||
specify init my-project --ai shai
|
||||
|
||||
# Initialize with IBM Bob support
|
||||
specify init my-project --ai bob
|
||||
|
||||
# Initialize with PowerShell scripts (Windows/cross-platform)
|
||||
specify init my-project --ai copilot --script ps
|
||||
|
||||
# Initialize in current directory
|
||||
specify init . --ai copilot
|
||||
# or use the --here flag
|
||||
specify init --here --ai copilot
|
||||
|
||||
# Force merge into current (non-empty) directory without confirmation
|
||||
specify init . --force --ai copilot
|
||||
# or
|
||||
specify init --here --force --ai copilot
|
||||
|
||||
# Skip git initialization
|
||||
specify init my-project --ai gemini --no-git
|
||||
|
||||
# Enable debug output for troubleshooting
|
||||
specify init my-project --ai claude --debug
|
||||
|
||||
# Use GitHub token for API requests (helpful for corporate environments)
|
||||
specify init my-project --ai claude --github-token ghp_your_token_here
|
||||
|
||||
# Check system requirements
|
||||
specify check
|
||||
```
|
||||
|
||||
After running `specify init`, your AI coding agent will have access to these slash commands for structured development:
|
||||
|
||||
#### Core Commands
|
||||
|
||||
Essential commands for the Spec-Driven Development workflow:
|
||||
|
||||
| Command | Description |
|
||||
| --- | --- |
|
||||
| `/speckit.constitution` | Create or update project governing principles and development guidelines |
|
||||
| `/speckit.specify` | Define what you want to build (requirements and user stories) |
|
||||
| `/speckit.plan` | Create technical implementation plans with your chosen tech stack |
|
||||
| `/speckit.tasks` | Generate actionable task lists for implementation |
|
||||
| `/speckit.implement` | Execute all tasks to build the feature according to the plan |
|
||||
|
||||
#### Optional Commands
|
||||
|
||||
Additional commands for enhanced quality and validation:
|
||||
|
||||
| Command | Description |
|
||||
| --- | --- |
|
||||
| `/speckit.clarify` | Clarify underspecified areas (recommended before `/speckit.plan`; formerly `/quizme`) |
|
||||
| `/speckit.analyze` | Cross-artifact consistency & coverage analysis (run after `/speckit.tasks`, before `/speckit.implement`) |
|
||||
| `/speckit.checklist` | Generate custom quality checklists that validate requirements completeness, clarity, and consistency (like "unit tests for English") |
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Description |
|
||||
| --- | --- |
|
||||
| `SPECIFY_FEATURE` | Override feature detection for non-Git repositories. Set to the feature directory name (e.g., `001-photo-albums`) to work on a specific feature when not using Git branches. \*\*Must be set in the context of the agent you're working with prior to using `/speckit.plan` or follow-up commands. |
|
||||
|
||||
Spec-Driven Development is a structured process that emphasizes:
|
||||
|
||||
- **Intent-driven development** where specifications define the " *what* " before the " *how* "
|
||||
- **Rich specification creation** using guardrails and organizational principles
|
||||
- **Multi-step refinement** rather than one-shot code generation from prompts
|
||||
- **Heavy reliance** on advanced AI model capabilities for specification interpretation
|
||||
|
||||
| Phase | Focus | Key Activities |
|
||||
| --- | --- | --- |
|
||||
| **0-to-1 Development** ("Greenfield") | Generate from scratch | - Start with high-level requirements - Generate specifications - Plan implementation steps - Build production-ready applications |
|
||||
| **Creative Exploration** | Parallel implementations | - Explore diverse solutions - Support multiple technology stacks & architectures - Experiment with UX patterns |
|
||||
| **Iterative Enhancement** ("Brownfield") | Brownfield modernization | - Add features iteratively - Modernize legacy systems - Adapt processes |
|
||||
|
||||
Our research and experimentation focus on:
|
||||
|
||||
### Technology independence
|
||||
|
||||
- Create applications using diverse technology stacks
|
||||
- Validate the hypothesis that Spec-Driven Development is a process not tied to specific technologies, programming languages, or frameworks
|
||||
|
||||
### Enterprise constraints
|
||||
|
||||
- Demonstrate mission-critical application development
|
||||
- Incorporate organizational constraints (cloud providers, tech stacks, engineering practices)
|
||||
- Support enterprise design systems and compliance requirements
|
||||
|
||||
### User-centric development
|
||||
|
||||
- Build applications for different user cohorts and preferences
|
||||
- Support various development approaches (from vibe-coding to AI-native development)
|
||||
- Validate the concept of parallel implementation exploration
|
||||
- Provide robust iterative feature development workflows
|
||||
- Extend processes to handle upgrades and modernization tasks
|
||||
|
||||
## 🔧 Prerequisites
|
||||
|
||||
- **Linux/macOS/Windows**
|
||||
- [Supported](https://github.com/github/#-supported-ai-agents) AI coding agent.
|
||||
- [uv](https://docs.astral.sh/uv/) for package management
|
||||
- [Python 3.11+](https://www.python.org/downloads/)
|
||||
- [Git](https://git-scm.com/downloads)
|
||||
|
||||
If you encounter issues with an agent, please open an issue so we can refine the integration.
|
||||
|
||||
- **[Complete Spec-Driven Development Methodology](https://github.com/github/spec-kit/blob/main/spec-driven.md)** - Deep dive into the full process
|
||||
- **[Detailed Walkthrough](https://github.com/github/#-detailed-process)** - Step-by-step implementation guide
|
||||
|
||||
---
|
||||
|
||||
Click to expand the detailed step-by-step walkthrough
|
||||
|
||||
You can use the Specify CLI to bootstrap your project, which will bring in the required artifacts in your environment. Run:
|
||||
|
||||
```
|
||||
specify init <project_name>
|
||||
```
|
||||
|
||||
Or initialize in the current directory:
|
||||
|
||||
```
|
||||
specify init .
|
||||
# or use the --here flag
|
||||
specify init --here
|
||||
# Skip confirmation when the directory already has files
|
||||
specify init . --force
|
||||
# or
|
||||
specify init --here --force
|
||||
```
|
||||
|
||||
[](https://github.com/github/spec-kit/blob/main/media/specify_cli.gif)
|
||||
|
||||
You will be prompted to select the AI agent you are using. You can also proactively specify it directly in the terminal:
|
||||
|
||||
```
|
||||
specify init <project_name> --ai claude
|
||||
specify init <project_name> --ai gemini
|
||||
specify init <project_name> --ai copilot
|
||||
|
||||
# Or in current directory:
|
||||
specify init . --ai claude
|
||||
specify init . --ai codex
|
||||
|
||||
# or use --here flag
|
||||
specify init --here --ai claude
|
||||
specify init --here --ai codex
|
||||
|
||||
# Force merge into a non-empty current directory
|
||||
specify init . --force --ai claude
|
||||
|
||||
# or
|
||||
specify init --here --force --ai claude
|
||||
```
|
||||
|
||||
The CLI will check if you have Claude Code, Gemini CLI, Cursor CLI, Qwen CLI, opencode, Codex CLI, Qoder CLI, or Amazon Q Developer CLI installed. If you do not, or you prefer to get the templates without checking for the right tools, use `--ignore-agent-tools` with your command:
|
||||
|
||||
```
|
||||
specify init <project_name> --ai claude --ignore-agent-tools
|
||||
```
|
||||
|
||||
Go to the project folder and run your AI agent. In our example, we're using `claude`.
|
||||
|
||||
[](https://github.com/github/spec-kit/blob/main/media/bootstrap-claude-code.gif)
|
||||
|
||||
You will know that things are configured correctly if you see the `/speckit.constitution`, `/speckit.specify`, `/speckit.plan`, `/speckit.tasks`, and `/speckit.implement` commands available.
|
||||
|
||||
The first step should be establishing your project's governing principles using the `/speckit.constitution` command. This helps ensure consistent decision-making throughout all subsequent development phases:
|
||||
|
||||
```
|
||||
/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements. Include governance for how these principles should guide technical decisions and implementation choices.
|
||||
```
|
||||
|
||||
This step creates or updates the `.specify/memory/constitution.md` file with your project's foundational guidelines that the AI agent will reference during specification, planning, and implementation phases.
|
||||
|
||||
With your project principles established, you can now create the functional specifications. Use the `/speckit.specify` command and then provide the concrete requirements for the project you want to develop.
|
||||
|
||||
> \[!IMPORTANT\] Be as explicit as possible about *what* you are trying to build and *why*. **Do not focus on the tech stack at this point**.
|
||||
|
||||
An example prompt:
|
||||
|
||||
```
|
||||
Develop Taskify, a team productivity platform. It should allow users to create projects, add team members,
|
||||
assign tasks, comment and move tasks between boards in Kanban style. In this initial phase for this feature,
|
||||
let's call it "Create Taskify," let's have multiple users but the users will be declared ahead of time, predefined.
|
||||
I want five users in two different categories, one product manager and four engineers. Let's create three
|
||||
different sample projects. Let's have the standard Kanban columns for the status of each task, such as "To Do,"
|
||||
"In Progress," "In Review," and "Done." There will be no login for this application as this is just the very
|
||||
first testing thing to ensure that our basic features are set up. For each task in the UI for a task card,
|
||||
you should be able to change the current status of the task between the different columns in the Kanban work board.
|
||||
You should be able to leave an unlimited number of comments for a particular card. You should be able to, from that task
|
||||
card, assign one of the valid users. When you first launch Taskify, it's going to give you a list of the five users to pick
|
||||
from. There will be no password required. When you click on a user, you go into the main view, which displays the list of
|
||||
projects. When you click on a project, you open the Kanban board for that project. You're going to see the columns.
|
||||
You'll be able to drag and drop cards back and forth between different columns. You will see any cards that are
|
||||
assigned to you, the currently logged in user, in a different color from all the other ones, so you can quickly
|
||||
see yours. You can edit any comments that you make, but you can't edit comments that other people made. You can
|
||||
delete any comments that you made, but you can't delete comments anybody else made.
|
||||
```
|
||||
|
||||
After this prompt is entered, you should see Claude Code kick off the planning and spec drafting process. Claude Code will also trigger some of the built-in scripts to set up the repository.
|
||||
|
||||
Once this step is completed, you should have a new branch created (e.g., `001-create-taskify`), as well as a new specification in the `specs/001-create-taskify` directory.
|
||||
|
||||
The produced specification should contain a set of user stories and functional requirements, as defined in the template.
|
||||
|
||||
At this stage, your project folder contents should resemble the following:
|
||||
|
||||
```
|
||||
└── .specify
|
||||
├── memory
|
||||
│ └── constitution.md
|
||||
├── scripts
|
||||
│ ├── check-prerequisites.sh
|
||||
│ ├── common.sh
|
||||
│ ├── create-new-feature.sh
|
||||
│ ├── setup-plan.sh
|
||||
│ └── update-claude-md.sh
|
||||
├── specs
|
||||
│ └── 001-create-taskify
|
||||
│ └── spec.md
|
||||
└── templates
|
||||
├── plan-template.md
|
||||
├── spec-template.md
|
||||
└── tasks-template.md
|
||||
```
|
||||
|
||||
With the baseline specification created, you can go ahead and clarify any of the requirements that were not captured properly within the first shot attempt.
|
||||
|
||||
You should run the structured clarification workflow **before** creating a technical plan to reduce rework downstream.
|
||||
|
||||
Preferred order:
|
||||
|
||||
1. Use `/speckit.clarify` (structured) – sequential, coverage-based questioning that records answers in a Clarifications section.
|
||||
2. Optionally follow up with ad-hoc free-form refinement if something still feels vague.
|
||||
|
||||
If you intentionally want to skip clarification (e.g., spike or exploratory prototype), explicitly state that so the agent doesn't block on missing clarifications.
|
||||
|
||||
Example free-form refinement prompt (after `/speckit.clarify` if still needed):
|
||||
|
||||
```
|
||||
For each sample project or project that you create there should be a variable number of tasks between 5 and 15
|
||||
tasks for each one randomly distributed into different states of completion. Make sure that there's at least
|
||||
one task in each stage of completion.
|
||||
```
|
||||
|
||||
You should also ask Claude Code to validate the **Review & Acceptance Checklist**, checking off the things that are validated/pass the requirements, and leave the ones that are not unchecked. The following prompt can be used:
|
||||
|
||||
```
|
||||
Read the review and acceptance checklist, and check off each item in the checklist if the feature spec meets the criteria. Leave it empty if it does not.
|
||||
```
|
||||
|
||||
It's important to use the interaction with Claude Code as an opportunity to clarify and ask questions around the specification - **do not treat its first attempt as final**.
|
||||
|
||||
You can now be specific about the tech stack and other technical requirements. You can use the `/speckit.plan` command that is built into the project template with a prompt like this:
|
||||
|
||||
```
|
||||
We are going to generate this using .NET Aspire, using Postgres as the database. The frontend should use
|
||||
Blazor server with drag-and-drop task boards, real-time updates. There should be a REST API created with a projects API,
|
||||
tasks API, and a notifications API.
|
||||
```
|
||||
|
||||
The output of this step will include a number of implementation detail documents, with your directory tree resembling this:
|
||||
|
||||
```
|
||||
.
|
||||
├── CLAUDE.md
|
||||
├── memory
|
||||
│ └── constitution.md
|
||||
├── scripts
|
||||
│ ├── check-prerequisites.sh
|
||||
│ ├── common.sh
|
||||
│ ├── create-new-feature.sh
|
||||
│ ├── setup-plan.sh
|
||||
│ └── update-claude-md.sh
|
||||
├── specs
|
||||
│ └── 001-create-taskify
|
||||
│ ├── contracts
|
||||
│ │ ├── api-spec.json
|
||||
│ │ └── signalr-spec.md
|
||||
│ ├── data-model.md
|
||||
│ ├── plan.md
|
||||
│ ├── quickstart.md
|
||||
│ ├── research.md
|
||||
│ └── spec.md
|
||||
└── templates
|
||||
├── CLAUDE-template.md
|
||||
├── plan-template.md
|
||||
├── spec-template.md
|
||||
└── tasks-template.md
|
||||
```
|
||||
|
||||
Check the `research.md` document to ensure that the right tech stack is used, based on your instructions. You can ask Claude Code to refine it if any of the components stand out, or even have it check the locally-installed version of the platform/framework you want to use (e.g.,.NET).
|
||||
|
||||
Additionally, you might want to ask Claude Code to research details about the chosen tech stack if it's something that is rapidly changing (e.g.,.NET Aspire, JS frameworks), with a prompt like this:
|
||||
|
||||
```
|
||||
I want you to go through the implementation plan and implementation details, looking for areas that could
|
||||
benefit from additional research as .NET Aspire is a rapidly changing library. For those areas that you identify that
|
||||
require further research, I want you to update the research document with additional details about the specific
|
||||
versions that we are going to be using in this Taskify application and spawn parallel research tasks to clarify
|
||||
any details using research from the web.
|
||||
```
|
||||
|
||||
During this process, you might find that Claude Code gets stuck researching the wrong thing - you can help nudge it in the right direction with a prompt like this:
|
||||
|
||||
```
|
||||
I think we need to break this down into a series of steps. First, identify a list of tasks
|
||||
that you would need to do during implementation that you're not sure of or would benefit
|
||||
from further research. Write down a list of those tasks. And then for each one of these tasks,
|
||||
I want you to spin up a separate research task so that the net results is we are researching
|
||||
all of those very specific tasks in parallel. What I saw you doing was it looks like you were
|
||||
researching .NET Aspire in general and I don't think that's gonna do much for us in this case.
|
||||
That's way too untargeted research. The research needs to help you solve a specific targeted question.
|
||||
```
|
||||
|
||||
> \[!NOTE\] Claude Code might be over-eager and add components that you did not ask for. Ask it to clarify the rationale and the source of the change.
|
||||
|
||||
With the plan in place, you should have Claude Code run through it to make sure that there are no missing pieces. You can use a prompt like this:
|
||||
|
||||
```
|
||||
Now I want you to go and audit the implementation plan and the implementation detail files.
|
||||
Read through it with an eye on determining whether or not there is a sequence of tasks that you need
|
||||
to be doing that are obvious from reading this. Because I don't know if there's enough here. For example,
|
||||
when I look at the core implementation, it would be useful to reference the appropriate places in the implementation
|
||||
details where it can find the information as it walks through each step in the core implementation or in the refinement.
|
||||
```
|
||||
|
||||
This helps refine the implementation plan and helps you avoid potential blind spots that Claude Code missed in its planning cycle. Once the initial refinement pass is complete, ask Claude Code to go through the checklist once more before you can get to the implementation.
|
||||
|
||||
You can also ask Claude Code (if you have the [GitHub CLI](https://docs.github.com/en/github-cli/github-cli) installed) to go ahead and create a pull request from your current branch to `main` with a detailed description, to make sure that the effort is properly tracked.
|
||||
|
||||
> \[!NOTE\] Before you have the agent implement it, it's also worth prompting Claude Code to cross-check the details to see if there are any over-engineered pieces (remember - it can be over-eager). If over-engineered components or decisions exist, you can ask Claude Code to resolve them. Ensure that Claude Code follows the [constitution](https://github.com/github/spec-kit/blob/main/base/memory/constitution.md) as the foundational piece that it must adhere to when establishing the plan.
|
||||
|
||||
With the implementation plan validated, you can now break down the plan into specific, actionable tasks that can be executed in the correct order. Use the `/speckit.tasks` command to automatically generate a detailed task breakdown from your implementation plan:
|
||||
|
||||
```
|
||||
/speckit.tasks
|
||||
```
|
||||
|
||||
This step creates a `tasks.md` file in your feature specification directory that contains:
|
||||
|
||||
- **Task breakdown organized by user story** - Each user story becomes a separate implementation phase with its own set of tasks
|
||||
- **Dependency management** - Tasks are ordered to respect dependencies between components (e.g., models before services, services before endpoints)
|
||||
- **Parallel execution markers** - Tasks that can run in parallel are marked with `[P]` to optimize development workflow
|
||||
- **File path specifications** - Each task includes the exact file paths where implementation should occur
|
||||
- **Test-driven development structure** - If tests are requested, test tasks are included and ordered to be written before implementation
|
||||
- **Checkpoint validation** - Each user story phase includes checkpoints to validate independent functionality
|
||||
|
||||
The generated tasks.md provides a clear roadmap for the `/speckit.implement` command, ensuring systematic implementation that maintains code quality and allows for incremental delivery of user stories.
|
||||
|
||||
Once ready, use the `/speckit.implement` command to execute your implementation plan:
|
||||
|
||||
```
|
||||
/speckit.implement
|
||||
```
|
||||
|
||||
The `/speckit.implement` command will:
|
||||
|
||||
- Validate that all prerequisites are in place (constitution, spec, plan, and tasks)
|
||||
- Parse the task breakdown from `tasks.md`
|
||||
- Execute tasks in the correct order, respecting dependencies and parallel execution markers
|
||||
- Follow the TDD approach defined in your task plan
|
||||
- Provide progress updates and handle errors appropriately
|
||||
|
||||
> \[!IMPORTANT\] The AI agent will execute local CLI commands (such as `dotnet`, `npm`, etc.) - make sure you have the required tools installed on your machine.
|
||||
|
||||
Once the implementation is complete, test the application and resolve any runtime errors that may not be visible in CLI logs (e.g., browser console errors). You can copy and paste such errors back to your AI agent for resolution.
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Troubleshooting
|
||||
|
||||
If you're having issues with Git authentication on Linux, you can install Git Credential Manager:
|
||||
|
||||
```
|
||||
#!/usr/bin/env bash
|
||||
set -e
|
||||
echo "Downloading Git Credential Manager v2.6.1..."
|
||||
wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.deb
|
||||
echo "Installing Git Credential Manager..."
|
||||
sudo dpkg -i gcm-linux_amd64.2.6.1.deb
|
||||
echo "Configuring Git to use GCM..."
|
||||
git config --global credential.helper manager
|
||||
echo "Cleaning up..."
|
||||
rm gcm-linux_amd64.2.6.1.deb
|
||||
```
|
||||
|
||||
## 👥 Maintainers
|
||||
|
||||
- Den Delimarsky ([@localden](https://github.com/localden))
|
||||
- John Lam ([@jflam](https://github.com/jflam))
|
||||
|
||||
## 💬 Support
|
||||
|
||||
For support, please open a [GitHub issue](https://github.com/github/spec-kit/issues/new). We welcome bug reports, feature requests, and questions about using Spec-Driven Development.
|
||||
|
||||
## 🙏 Acknowledgements
|
||||
|
||||
This project is heavily influenced by and based on the work and research of [John Lam](https://github.com/jflam).
|
||||
|
||||
## 📄 License
|
||||
|
||||
This project is licensed under the terms of the MIT open source license. Please refer to the [LICENSE](https://github.com/github/spec-kit/blob/main/LICENSE) file for the full terms.
|
||||
|
||||
## Releases 90
|
||||
|
||||
[\+ 89 releases](https://github.com/github/spec-kit/releases)
|
||||
|
||||
## Deployments 14
|
||||
|
||||
- [github-pages](https://github.com/github/spec-kit/deployments/github-pages)
|
||||
|
||||
[\+ 13 deployments](https://github.com/github/spec-kit/deployments)
|
||||
|
||||
## Languages
|
||||
|
||||
- [Python 37.5%](https://github.com/github/spec-kit/search?l=python)
|
||||
- [Shell 34.9%](https://github.com/github/spec-kit/search?l=shell)
|
||||
- [PowerShell 27.6%](https://github.com/github/spec-kit/search?l=powershell)
|
||||
+81
@@ -0,0 +1,81 @@
|
||||
---
|
||||
title: "kepano/obsidian-skills: Claude Skills for Obsidian"
|
||||
source: "https://github.com/kepano/obsidian-skills"
|
||||
author:
|
||||
- "[[kepano]]"
|
||||
published:
|
||||
created: 2026-01-07
|
||||
description: "Claude Skills for Obsidian. Contribute to kepano/obsidian-skills development by creating an account on GitHub."
|
||||
tags:
|
||||
- "clippings"
|
||||
- "webclipper"
|
||||
---
|
||||
> [!info] Source
|
||||
> URL: https://github.com/kepano/obsidian-skills
|
||||
> Title: kepano/obsidian-skills: Claude Skills for Obsidian
|
||||
> Clipped:
|
||||
|
||||
**[obsidian-skills](https://github.com/kepano/obsidian-skills)** Public
|
||||
|
||||
Claude Skills for Obsidian
|
||||
|
||||
[MIT license](https://github.com/kepano/obsidian-skills/blob/main/LICENSE)
|
||||
|
||||
[Open in github.dev](https://github.dev/) [Open in a new github.dev tab](https://github.dev/) [Open in codespace](https://github.com/codespaces/new/kepano/obsidian-skills?resume=1)
|
||||
|
||||
<table><thead><tr><th colspan="2"><span>Name</span></th><th colspan="1"><span>Name</span></th><th><p><span>Last commit message</span></p></th><th colspan="1"><p><span>Last commit date</span></p></th></tr></thead><tbody><tr><td colspan="3"><p><span><a href="https://github.com/kepano/obsidian-skills/commit/2b9846224fa277993e23c8c8eb35c185571e3551">2b98462</a> ·</span></p><p><a href="https://github.com/kepano/obsidian-skills/commits/main/"><span><span><span>13 Commits</span></span></span></a></p></td></tr><tr><td colspan="2"><p><a href="https://github.com/kepano/obsidian-skills/tree/main/.claude-plugin">.claude-plugin</a></p></td><td colspan="1"><p><a href="https://github.com/kepano/obsidian-skills/tree/main/.claude-plugin">.claude-plugin</a></p></td><td><p><a href="https://github.com/kepano/obsidian-skills/commit/2b9846224fa277993e23c8c8eb35c185571e3551">Update plugin.json</a></p></td><td></td></tr><tr><td colspan="2"><p><a href="https://github.com/kepano/obsidian-skills/tree/main/skills">skills</a></p></td><td colspan="1"><p><a href="https://github.com/kepano/obsidian-skills/tree/main/skills">skills</a></p></td><td><p><a href="https://github.com/kepano/obsidian-skills/commit/9eab9ad2bf8e2839b991bb8ef592a7f65ceee4af">feat: convert to Claude Code plugin structure</a></p></td><td></td></tr><tr><td colspan="2"><p><a href="https://github.com/kepano/obsidian-skills/blob/main/LICENSE">LICENSE</a></p></td><td colspan="1"><p><a href="https://github.com/kepano/obsidian-skills/blob/main/LICENSE">LICENSE</a></p></td><td><p><a href="https://github.com/kepano/obsidian-skills/commit/6aa10512d87abb8c5fdf3b5705029854b893d667">license</a></p></td><td></td></tr><tr><td colspan="2"><p><a href="https://github.com/kepano/obsidian-skills/blob/main/README.md">README.md</a></p></td><td colspan="1"><p><a href="https://github.com/kepano/obsidian-skills/blob/main/README.md">README.md</a></p></td><td><p><a href="https://github.com/kepano/obsidian-skills/commit/6d8941875cd9f58431a2f7d47fbacc94ca87f5ea">Update README.md</a></p></td><td></td></tr><tr><td colspan="3"></td></tr></tbody></table>
|
||||
|
||||
Claude Code skills for creating and editing Obsidian vault files.
|
||||
|
||||
## Skills included
|
||||
|
||||
| Skill | Description | File Types |
|
||||
| --- | --- | --- |
|
||||
| [obsidian-markdown](https://github.com/kepano/obsidian-skills/blob/main/skills/obsidian-markdown) | Obsidian Flavored Markdown with wikilinks, embeds, callouts, and properties | `.md` |
|
||||
| [obsidian-bases](https://github.com/kepano/obsidian-skills/blob/main/skills/obsidian-bases) | Database-like views with filters, formulas, and summaries | `.base` |
|
||||
| [json-canvas](https://github.com/kepano/obsidian-skills/blob/main/skills/json-canvas) | Infinite canvas with nodes, edges, and groups | `.canvas` |
|
||||
|
||||
## Installation
|
||||
|
||||
Install directly from the Obsidian marketplace:
|
||||
|
||||
```
|
||||
claude plugin add obsidian@kepano
|
||||
claude plugin install obsidian@kepano
|
||||
```
|
||||
|
||||
### Manual installation
|
||||
|
||||
Clone or copy this repository into your project's `.claude/plugins/` directory:
|
||||
|
||||
```
|
||||
# Option 1: Clone into plugins directory
|
||||
mkdir -p .claude/plugins
|
||||
git clone https://github.com/obsidianmd/obsidian-skills.git .claude/plugins/obsidian
|
||||
|
||||
# Option 2: Add as git submodule
|
||||
git submodule add https://github.com/obsidianmd/obsidian-skills.git .claude/plugins/obsidian
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
Once installed, Claude Code will automatically use these skills when working with Obsidian files. The skills provide:
|
||||
|
||||
- **Syntax guidance** for Obsidian-specific features (wikilinks, callouts, embeds)
|
||||
- **Schema documentation** for `.base` and `.canvas` file formats
|
||||
- **Best practices** for structuring notes and databases
|
||||
- **Complete function references** for Bases formulas
|
||||
|
||||
## Documentation
|
||||
|
||||
- [Obsidian Flavored Markdown](https://help.obsidian.md/obsidian-flavored-markdown)
|
||||
- [Obsidian Bases](https://help.obsidian.md/bases)
|
||||
- [JSON Canvas Spec](https://jsoncanvas.org/)
|
||||
|
||||
## Releases
|
||||
|
||||
No releases published
|
||||
|
||||
## Packages
|
||||
|
||||
No packages published
|
||||
Reference in New Issue
Block a user