Codebase Concerns【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-doneAnalysis Date:[YYYY-MM-DD]Tech DebtKnown BugsSecurity ConsiderationsPerformance BottlenecksFragile AreasScaling LimitsDependencies at RiskMissing Critical FeaturesTest Coverage Gaps各板块字段定义如下写作时必须逐项填全 | 板块 | 必填字段 | 字段语义 | |------|---------|---------| | Tech Debt | Issue / Why / Impact / Fix approach | 走捷径做了什么、为何如此、破坏了什么、如何正确修复 | | Known Bugs | Symptoms / Trigger / Workaround / Root cause / Blocked by | 现象、复现步骤、临时缓解、根因、是否被阻塞 | | Security Considerations | Risk / Current mitigation / Recommendations | 可能出什么错、现状防护、还应补什么 | | Performance Bottlenecks | Problem / Measurement / Cause / Improvement path | 什么慢、真实数值、为何慢、如何提速 | | Fragile Areas | Why fragile / Common failures / Safe modification / Test coverage | 为何易碎、典型故障、安全改法、测试覆盖 | | Scaling Limits | Current capacity / Limit / Symptoms at limit / Scaling path | 当前容量、何处崩溃、极限时表现、扩容路径 | | Dependencies at Risk | Risk / Impact / Migration plan | 废弃/无人维护/破坏性变更、失败影响、迁移方案 | | Missing Critical Features | Problem / Current workaround / Blocks / Implementation complexity | 缺什么、用户如何凑合、阻塞了什么、工作量量级 | | Test Coverage Gaps | Whats not tested / Risk / Priority / Difficulty to test | 未测功能、潜在破坏、优先级、为何未测 | 文件尾部以审计日期收尾并声明其动态属性 markdown --- *Concerns audit: [date]* *Update as issues are fixed or new ones discovered*2.1 源码侧的同构模板gsd-codebase-mapper 代理 内部维护了一份 CONCERNS.md 的 concerns 焦点变体字段略有精简如 Tech Debt 用Files而非Why字段但板块划分与主模板完全一致。这印证了模板在该系统中的双重存在既供人工阅读也作为 Agent 的直接产出格式。三、完整填写示例从占位符到真实条目模板内置的 good_examples 段落 用一份虚构 SaaS 项目展示了每个板块的正确写法。以下提取关键条目作为范式参考原文为英文此处直译保留结构Tech Debt 示例## Tech Debt **Database queries in React components:** - Issue: Direct Supabase queries in 15 page components instead of server actions - Files: app/dashboard/page.tsx, app/profile/page.tsx, ... - Why: Rapid prototyping during MVP phase - Impact: Cant implement RLS properly, exposes DB structure to client - Fix approach: Move all queries to server actions in app/actions/, add proper RLS policiesKnown Bugs 示例必须含复现路径**Race condition in subscription updates:** - Symptoms: User shows as free tier for 5-10 seconds after successful payment - Trigger: Fast navigation after Stripe checkout redirect, before webhook processes - Files: app/checkout/success/page.tsx, app/api/webhooks/stripe/route.ts - Workaround: Stripe webhook eventually updates status (self-heals) - Root cause: Webhook processing slower than user navigation, no optimistic UI updatePerformance Bottlenecks 示例强调真实测量值**/api/courses endpoint:** - Problem: Fetching all courses with nested lessons and authors - File: app/api/courses/route.ts - Measurement: 1.2s p95 response time with 50 courses - Cause: N1 query pattern (separate query per course for lessons) - Improvement path: Use Prisma include to eager-load lessons, add Redis cachingScaling Limits 示例给出硬数字**Supabase Free Tier:** - Current capacity: 500MB database, 1GB file storage, 2GB bandwidth/month - Limit: ~5000 users estimated before hitting limits - Symptoms at limit: 429 rate limit errors, DB writes fail - Scaling path: Upgrade to Pro ($25/mo) extends to 8GB DB, 100GB storageDependencies at Risk 示例**react-hot-toast:** - Risk: Unmaintained (last update 18 months ago), React 19 compatibility unknown - Impact: Toast notifications break, no graceful degradation - Migration plan: Switch to sonner (actively maintained, similar API)这些示例的价值在于展示了统一的信息颗粒度每条目都包含文件路径、可量化的测量值、具体的修复方向绝不停留在情绪化评价。四、填写指南该放什么、不该放什么模板末尾的 guidelines 段落 是最重要的写作纪律直接决定文档质量。4.1 应该收纳的内容What belongs有明确影响与修复方案的技术债带复现步骤的已知 Bug安全缺口与缓解建议带测量数据的性能瓶颈容易改坏的脆弱代码带数字的扩展上限需要关注的依赖阻塞工作流的缺失功能测试覆盖缺口。4.2 严禁收纳的内容What does NOT belong无证据的观点如 code is messy只抱怨不给方案的诉苦如 auth sucks未来功能想法归产品规划普通 TODO留在代码注释运行良好的架构决策细微的代码风格问题。4.3 填写纪律When filling this templateAlways include file paths—— 没有定位的担忧无法执行路径用反引号包裹如src/file.tsBe specific with measurements—— 写 500ms p95 而非 slow每个 Bug 都要写复现步骤只提问题不行要给出修复方向Suggest fix approaches, not just problems聚焦可执行条目按风险/影响排序问题解决后及时更新发现新问题随时追加。4.4 语气规范Tone guidelines模板给出四组正反对照核心是专业、面向解决、聚焦风险、基于事实专业而非情绪化N1 query pattern 而非 terrible queries面向解决Fix: add index 而非 needs fixing聚焦风险Could expose user data 而非 security is bad基于事实3.5s load time 而非 really slow。4.5 何时对阶段规划有用Useful for phase planning when决定下一步做什么估算改动风险理解哪些地方要格外小心排定改进优先级为新 Claude 会话做上下文交接onboarding规划重构工作。这份风险即规划输入的设计正是 CONCERNS.md 与 GSD 规划流程衔接的关键接口。五、这份文档如何被生成源码级调用链CONCERNS.md 不是手写孤本而是 GSD 代码库测绘流水线的正式产物。理解其生成路径有助于你在新项目中复刻这套实践。5.1 触发入口map-codebase 与 scanmap-codebase 工作流 会并行派出 4 个gsd-codebase-mapper子代理其中 Agent 4 的焦点为concerns明确指示Analyze this codebase for technical debt, known issues, and areas of concern并写入 CONCERNS.mdTech debt, bugs, security, performance, fragile areasscan 工作流 提供轻量路径通过--focus concerns只派出单个 mapper 生成 CONCERNS.md用于快速评估若运行时不支持Agent工具map-codebase 会回退到顺序执行 4 轮内联测绘sequential mapping产出同样 7 份文档见 map-codebase。5.2 concerns 焦点的探索命令gsd-codebase-mapper 代理 为 concerns 焦点提供了三个侦察命令模板可直接用于任何代码库# 1. 扫描 TODO/FIXME/HACK/XXX 标记 grep -rn TODO\|FIXME\|HACK\|XXX src/ --include*.ts --include*.tsx 2/dev/null | head -50 # 2. 按行数找出超大体量文件潜在复杂度热点 find src/ -name *.ts -o -name *.tsx | xargs wc -l 2/dev/null | sort -rn | head -20 # 3. 定位空返回值与桩代码 grep -rn return null\|return \[\]\|return {} src/ --include*.ts --include*.tsx 2/dev/null | head -30【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考